feat(icons): add brand icon picker from dashboard-icons

Add a second tab in the node Icon picker to choose from the ~2250 brand
icons hosted by homarr-labs/dashboard-icons (Plex, Sonarr, Home
Assistant, etc.) served via jsDelivr CDN. The Generic tab keeps the
existing lucide picker unchanged.

Storage uses a 'brand:<slug>' prefix on custom_icon, so existing nodes
referencing lucide keys keep working with zero migration. A new
resolveCustomIcon helper returns a discriminated union (lucide | brand)
and a NodeIcon component centralizes rendering for both kinds.

Includes a manifest fetch script (scripts/fetch-dashboard-icons.mjs)
and a checked-in dashboardIcons.json snapshot.

.env.example

@@ -1,6 +1,7 @@
 # Backend - server-side only (NEVER commit .env)
 SECRET_KEY=change_me_in_production
 SQLITE_PATH=./data/homelab.db
+# Set this to the URL(s) you use to access Homelable in your browser.
 CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
 
 # Auth — default credentials: admin / admin
@@ -15,3 +16,15 @@ SCANNER_RANGES=["192.168.1.0/24"]
 
 # Status checker interval in seconds
 STATUS_CHECKER_INTERVAL=60
+
+# MCP server — used by the mcp service (port 8001)
+# MCP_API_KEY: authenticates AI clients (Claude Code, etc.) → MCP server
+# MCP_SERVICE_KEY: authenticates MCP server → backend (never exposed externally)
+# Generate keys: python3 -c "import secrets; print(secrets.token_hex(32))"
+MCP_API_KEY=mcp_sk_changeme
+MCP_SERVICE_KEY=svc_changeme
+
+# Live view — read-only public canvas at /view?key=<value>
+# Off by default. Set to a random secret to enable.
+# Generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+# LIVEVIEW_KEY=

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: pouzor
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/docker-ci.yml

@@ -0,0 +1,83 @@
+name: Docker CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke-and-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── Write a minimal .env required by env_file: .env in docker-compose.yml ─
+      # AUTH_PASSWORD_HASH is NOT set here — it's injected via docker-compose.ci.yml
+      # environment section using $$ escaping to avoid docker-compose $VAR expansion.
+      - name: Write .env
+        run: |
+          {
+            echo "SECRET_KEY=ci-only-secret-key-not-for-production"
+            echo "SQLITE_PATH=/app/data/homelab.db"
+            echo 'CORS_ORIGINS=["http://localhost:3000"]'
+            echo 'SCANNER_RANGES=["127.0.0.1/32"]'
+            echo "STATUS_CHECKER_INTERVAL=300"
+            echo "MCP_API_KEY=ci-mcp-key"
+            echo "MCP_SERVICE_KEY=ci-svc-key"
+          } > .env
+
+      # ── Build + start backend and frontend (skip mcp) ─────────────────────────
+      # docker-compose.ci.yml: exposes port 8000 + injects AUTH_* env vars
+      - name: Build images
+        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml build backend frontend
+
+      - name: Start stack
+        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d backend frontend
+
+      # ── Wait for backend to be healthy (max 60 s) ─────────────────────────────
+      - name: Wait for backend health
+        run: |
+          echo "Waiting for backend..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8000/api/v1/health > /dev/null 2>&1; then
+              echo "Backend is up after ${i}s"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Backend did not become healthy in time" >&2
+          docker compose -f docker-compose.yml -f docker-compose.ci.yml logs backend
+          exit 1
+
+      # ── Smoke: frontend serves HTML ───────────────────────────────────────────
+      - name: Smoke — frontend returns 200
+        run: |
+          STATUS=$(curl -so /dev/null -w "%{http_code}" http://localhost:3000/)
+          [ "$STATUS" = "200" ] || { echo "Frontend returned $STATUS"; exit 1; }
+
+      # ── Tier 3: integration tests against the live stack ──────────────────────
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install backend test deps
+        run: pip install --quiet -r backend/requirements.txt
+
+      - name: Run integration tests
+        env:
+          INTEGRATION_BASE_URL: http://localhost:8000
+          INTEGRATION_USERNAME: admin
+          INTEGRATION_PASSWORD: admin
+        run: |
+          cd backend
+          pytest tests/test_integration.py -v
+
+      # ── Teardown ──────────────────────────────────────────────────────────────
+      - name: Dump logs on failure
+        if: failure()
+        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml logs
+
+      - name: Stop stack
+        if: always()
+        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml down -v

.github/workflows/quality.yml

@@ -7,6 +7,25 @@ on:
     branches: [main]
 
 jobs:
+  lint-scripts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: ShellCheck — lxc-install.sh
+        uses: ludeeus/action-shellcheck@2.0.0
+        with:
+          scandir: './scripts'
+      - name: Hadolint — Dockerfile.backend
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile.backend
+          ignore: DL3008
+      - name: Hadolint — Dockerfile.frontend
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile.frontend
+          ignore: DL3008
+
   frontend:
     runs-on: ubuntu-latest
     defaults:

.gitignore

@@ -45,6 +45,8 @@ htmlcov/
 *.db
 *.db-shm
 *.db-wal
+*.db.back
 
 # Docker
 .docker/
+Ideas.md

.hadolint.yaml

@@ -0,0 +1,4 @@
+# DL3008: pinning apt package versions is impractical for system tools (nmap, iputils-ping)
+# that have version numbers tied to specific Debian releases.
+ignore:
+  - DL3008

CONTRIBUTING.md

@@ -0,0 +1,276 @@
+# Contributing to Homelable
+
+Thanks for taking the time to contribute! This document covers everything you need to get started.
+
+---
+
+## Table of Contents
+
+- [Ways to Contribute](#ways-to-contribute)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [Commit Message Format](#commit-message-format)
+
+---
+
+## Ways to Contribute
+
+- Report bugs or unexpected behavior
+- Suggest new features or improvements
+- Fix open issues (check the [issue tracker](https://github.com/Pouzor/homelable/issues))
+- Improve documentation
+- Add service signatures to `service_signatures.json`
+
+---
+
+## Reporting Bugs
+
+Before opening an issue, search existing ones to avoid duplicates.
+
+When filing a bug, include:
+
+- **Homelable version** (visible in the sidebar bottom-left)
+- **Deployment method** (Docker Compose, Proxmox LXC, source)
+- **Steps to reproduce**
+- **Expected vs actual behavior**
+- **Relevant logs** (`docker compose logs backend` / `docker compose logs frontend`)
+- **Browser console errors** if it's a UI issue
+
+---
+
+## Suggesting Features
+
+Open an issue with the `enhancement` label. Describe:
+
+- The problem you're trying to solve
+- Your proposed solution
+- Any alternatives you considered
+
+For large changes, discuss first before writing code — it avoids wasted effort.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js 20+** and **npm**
+- **Python 3.11–3.13** (3.14 not yet supported by all dependencies)
+- **nmap** installed on your system (required for scanner)
+- **Docker + Docker Compose** (optional, for full-stack testing)
+
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/Pouzor/homelable.git
+cd homelable
+```
+
+### 2. Backend
+
+```bash
+cd backend
+python3.13 -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+
+# Copy and configure environment
+cp .env.example .env             # edit AUTH_PASSWORD_HASH, SECRET_KEY, etc.
+
+# Start the backend (auto-reloads on change)
+uvicorn app.main:app --reload --port 8000
+```
+
+API docs available at `http://localhost:8000/docs`.
+
+### 3. Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev                      # http://localhost:5173
+```
+
+Vite proxies `/api` to `localhost:8000` — the backend must be running.
+
+### 4. Verify tooling
+
+```bash
+./scripts/verify-tooling.sh
+```
+
+---
+
+## Project Structure
+
+```
+homelable/
+├── frontend/src/
+│   ├── components/
+│   │   ├── canvas/          # React Flow canvas, custom nodes & edges
+│   │   ├── panels/          # Sidebar, detail panel, toolbar
+│   │   ├── modals/          # Add/edit node, scan config, pending devices
+│   │   └── ui/              # Shadcn/ui base components
+│   ├── stores/              # Zustand state (canvas, auth, scan)
+│   ├── hooks/               # Custom React hooks
+│   ├── types/               # TypeScript interfaces & enums
+│   ├── api/                 # Axios client & typed endpoints
+│   └── utils/               # Layout, export, color helpers
+│
+├── backend/app/
+│   ├── api/routes/          # FastAPI route handlers
+│   ├── services/            # Scanner, status checker, canvas service
+│   ├── db/                  # SQLAlchemy models, Alembic migrations
+│   ├── schemas/             # Pydantic request/response schemas
+│   └── core/                # Config, JWT, scheduler
+│
+├── docker/                  # Nginx configs
+├── scripts/                 # LXC bootstrap, dev helpers
+└── mcp/                     # MCP server (AI integration)
+```
+
+---
+
+## Coding Standards
+
+### General
+
+- No untested code merged — every feature or fix must include tests
+- Keep changes focused — one concern per PR
+
+### Frontend (TypeScript + React)
+
+- Strict TypeScript — no `any`, no type assertions unless truly necessary
+- React Flow node domain fields go in `node.data`, never on the node root
+- State management via Zustand stores — no prop drilling beyond 2 levels
+- Styling via TailwindCSS utility classes — follow the existing [design system](#design-system)
+- Run before committing:
+  ```bash
+  cd frontend
+  npm run lint
+  npm run typecheck
+  npm test
+  ```
+
+### Backend (Python + FastAPI)
+
+- Python 3.11+ syntax
+- Pydantic v2 schemas for all request/response types
+- SQLAlchemy async sessions — never block the event loop
+- Scanner logic runs in a background thread — never in an async route directly
+- All schema changes via Alembic migrations — never modify tables directly
+- Run before committing:
+  ```bash
+  cd backend
+  source .venv/bin/activate
+  ruff check .
+  pytest
+  ```
+
+### Design System
+
+| Token | Value |
+|---|---|
+| Background | `#0d1117` |
+| Surface | `#161b22` |
+| Card | `#21262d` |
+| Accent cyan | `#00d4ff` |
+| Online | `#39d353` |
+| Offline | `#f85149` |
+| Pending | `#e3b341` |
+| Font (UI) | Inter |
+| Font (IPs/ports) | JetBrains Mono |
+
+---
+
+## Testing
+
+Tests run automatically via a pre-commit hook when frontend or backend files are staged.
+
+### Frontend
+
+```bash
+cd frontend
+npm test                  # run all tests
+npm run test:coverage     # with coverage report
+```
+
+Test files live in `__tests__/` next to their module, named `*.test.ts(x)`.
+
+**What to test:** Zustand store actions, utility functions, non-trivial component logic.
+
+### Backend
+
+```bash
+cd backend
+source .venv/bin/activate
+pytest                    # run all tests
+pytest -v tests/test_nodes.py   # single file
+```
+
+Test files live in `backend/tests/test_*.py`.
+
+**What to test:** all API routes (happy path + error cases), auth flows, service logic.
+
+Use the `client` and `headers` fixtures from `conftest.py` — they provide an in-memory SQLite database so tests are isolated and fast.
+
+---
+
+## Submitting a Pull Request
+
+1. **Fork** the repo and create a branch from `main`:
+   ```bash
+   git checkout -b feat/my-feature
+   ```
+
+2. **Make your changes** — include tests.
+
+3. **Run the full test suite** (frontend + backend) and make sure everything passes.
+
+4. **Open a PR** against `main`:
+   - Use a clear title (see commit format below)
+   - Describe what changed and why
+   - Reference any related issues (`Closes #123`)
+   - Include screenshots for UI changes
+
+5. Keep the PR focused — one feature or fix per PR. Large refactors should be discussed in an issue first.
+
+---
+
+## Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>: <short description>
+
+[optional body]
+```
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code change with no behavior change |
+| `test` | Adding or fixing tests |
+| `chore` | Build, deps, tooling |
+
+**Examples:**
+```
+feat: add logout button to sidebar
+fix: stop click propagation on pending device checkbox
+docs: add CONTRIBUTING.md
+```
+
+
+---
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/Pouzor/homelable/discussions) or drop a comment on a relevant issue.

Dockerfile.backend

@@ -2,13 +2,14 @@ FROM python:3.13-slim
 
 WORKDIR /app
 
-# Install nmap for network scanning
-RUN apt-get update && apt-get install -y --no-install-recommends nmap && rm -rf /var/lib/apt/lists/*
+# Install nmap for network scanning + iputils-ping for ping-based status checks + curl for the health check
+RUN apt-get update && apt-get install -y --no-install-recommends nmap iputils-ping curl && rm -rf /var/lib/apt/lists/*
 
 COPY backend/requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
 COPY backend/ .
+COPY VERSION /app/VERSION
 
 # Create data directory (volume mount point)
 RUN mkdir -p /app/data

Dockerfile.frontend

@@ -1,5 +1,8 @@
 # Stage 1: build
-FROM node:20-alpine AS builder
+# Use the native build platform so npm ci never runs under QEMU emulation.
+# The build output (static HTML/JS/CSS) is platform-independent.
+# node:20-slim (Debian/glibc) avoids lightningcss musl binary resolution issues on Alpine.
+FROM --platform=$BUILDPLATFORM node:20-slim AS builder
 
 ARG VITE_STANDALONE=false
 ENV VITE_STANDALONE=$VITE_STANDALONE
@@ -9,6 +12,7 @@ COPY frontend/package*.json ./
 RUN npm ci
 
 COPY frontend/ .
+COPY VERSION ../VERSION
 RUN npm run build
 
 # Stage 2: serve

INSTALLATION.md

@@ -0,0 +1,105 @@
+# Homelable — Installation
+
+## Quick Start — Docker
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
+cd homelable && docker compose up -d
+```
+
+Open **http://localhost:3000** — login with `admin` / `admin`.
+
+> Change the password before exposing to a network: edit `.env` and update `AUTH_USERNAME` / `AUTH_PASSWORD_HASH`.
+>
+Generate a new hash: 
+```bash 
+docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"
+```
+
+
+⚠️ **bcrypt hashes contain `$` characters** — how to handle them depends on where you set the value:
+ - **`.env` file** (recommended): wrap the hash in single quotes → `AUTH_PASSWORD_HASH='$2b$12$...'`
+ - **`docker-compose.yml` `environment:` block**: escape every `$` as `$$` — use this command to generate a pre-escaped hash:
+   ```bash
+   docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword').replace('\$', '\$\$'))"
+   ```
+
+## Quick Start — Frontend only
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash -s -- --standalone
+cd homelable && docker compose up -d
+```
+
+## Update (Docker)
+
+Re-run the install script — it detects an existing install and only updates `docker-compose.yml`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
+cd homelable && docker compose pull && docker compose up -d
+```
+
+## Build from source
+
+```bash
+git clone https://github.com/Pouzor/homelable.git
+cd homelable
+cp .env.example .env
+docker compose up -d
+```
+
+---
+
+## Proxmox LXC Install
+
+You can now install Homelable with community-scripts (proxmox-VE) : 
+
+`https://community-scripts.org/scripts/homelable`
+
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homelable.sh)"
+```
+
+---
+
+## Configuration
+
+All configuration is done via `.env` (copied from `.env.example`):
+
+```env
+SECRET_KEY=change_me_in_production
+
+# Auth — default: admin / admin
+AUTH_USERNAME=admin
+AUTH_PASSWORD_HASH='$2b$12$...'   # bcrypt hash — keep single quotes
+
+# CIDR ranges to scan
+SCANNER_RANGES=["192.168.1.0/24"]
+
+# How often to check node status (seconds)
+STATUS_CHECKER_INTERVAL=60
+```
+
+All settings are also editable in-app via the **Scan Network** button.
+
+---
+
+## Development Mode
+
+**Backend (Python 3.13):**
+```bash
+cd backend
+python3.13 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp ../.env.example .env       # edit SECRET_KEY and review defaults
+uvicorn app.main:app --reload --port 8000
+```
+
+**Frontend:**
+```bash
+cd frontend
+npm install
+npm run dev   # http://localhost:5173
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remy Jardinet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -4,95 +4,27 @@ Homelable is a self-hosted infrastructure visualization solution. It provides a
 
 Homelable also offers a healthcheck system (WIP) through multiple methods (ping/TCP, /health API, etc.) to get a global overview of online/offline services.
 
+You can also select some pre-built design styles, or personalize each device in your diagram.
+
 If you just like the design, you can only run the frontend and export your design as PNG.
 
 
 ---
 
-## Quick Start — Docker
+## Screenshots
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
-cd homelable && docker compose up -d
-```
-
-Open **http://localhost:3000** — login with `admin` / `admin`.
-
-> Change the password before exposing to a network: edit `.env` and update `AUTH_USERNAME` / `AUTH_PASSWORD_HASH`.
->
-> Generate a new hash: `docker compose exec backend python -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('yourpassword'))"`
->
-> ⚠️ Keep the single quotes around the hash value in `.env` — bcrypt hashes contain `$` characters that Docker Compose would otherwise misinterpret.
-
-## Quick Start - Front only
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash -s -- --standalone
-cd homelable && docker compose up -d
-```
-
-### Update
-
-Re-run the install script — it detects an existing install and only updates `docker-compose.yml`:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/install.sh | bash
-cd homelable && docker compose pull && docker compose up -d
-```
-
-### Build from source
-
-```bash
-git clone https://github.com/Pouzor/homelable.git
-cd homelable
-cp .env.example .env
-docker compose up -d
-```
+<p align="center">
+  <img src="docs/homelable1.png" alt="Homelable canvas overview" width="100%" />
+  <img src="docs/homelable2.png" alt="Homelable node detail" width="100%" />
+  <img src="docs/homelable3.png" alt="Homelable sidebar and scan" width="48%" />
+  <img src="docs/homelable4.png" alt="Homelable edit pannel" width="48%" />
+</p>
 
 ---
 
-## Proxmox LXC Install
+## Installation
 
-Run this **on the Proxmox host** — it creates a Debian 12 LXC container and installs Homelable inside automatically:
-
-```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/scripts/install-proxmox.sh)
-```
-
-Default container settings: 2 cores, 1 GB RAM, 8 GB disk, DHCP on `vmbr0`. Override before running:
-
-```bash
-CTID=150 RAM=2048 STORAGE=local-zfs bash <(curl -fsSL .../install-proxmox.sh)
-```
-
-The backend runs as a systemd service, the frontend is served via nginx on port 80.
-
-> To install manually inside an existing Debian/Ubuntu machine or LXC:
-> ```bash
-> bash <(curl -fsSL https://raw.githubusercontent.com/Pouzor/homelable/main/scripts/lxc-install.sh)
-> ```
-
----
-
-## Configuration
-
-All configuration is done via `.env` (copied from `.env.example`):
-
-```env
-SECRET_KEY=change_me_in_production
-
-# Auth — default: admin / admin
-AUTH_USERNAME=admin
-AUTH_PASSWORD_HASH='$2b$12$...'   # bcrypt hash — keep single quotes
-
-# CIDR ranges to scan
-SCANNER_RANGES=["192.168.1.0/24"]
-
-# How often to check node status (seconds)
-STATUS_CHECKER_INTERVAL=60
-```
-
-All settings are also editable in-app via the **Scan Network** button.
+Docker, Proxmox LXC, build from source, configuration, and development setup are all covered in **[INSTALLATION.md](./INSTALLATION.md)**.
 
 ---
 
@@ -102,7 +34,8 @@ The scanner runs `nmap -sV --open` on your configured CIDR ranges and populates
 
 ### Triggering a scan
 
-Click **Scan Network** in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes. Errors are shown inline and as a toast notification.
+To save you time when mapping your infrastructure, Homlable can scan your network and report all the services it detects. It can also identify them, saving you even more time.
+Click **Scan Network** in the sidebar. The Scan History tab opens automatically and refreshes every 3 seconds until the scan completes.
 
 ### macOS / root privileges
 
@@ -125,19 +58,10 @@ Results are written directly to the database and appear as Pending Devices in th
 
 ---
 
-## Proxmox Nested Nodes
-
-Proxmox nodes render as a resizable group container. VM and LXC nodes can be placed inside:
-
-1. Add a **Proxmox VE** node to the canvas
-2. Add a **VM** or **LXC** node — select the Proxmox node in the **Parent Proxmox** dropdown
-3. The child node appears inside the group and moves with it
-4. Select the Proxmox node to reveal resize handles (drag corners to expand)
-
----
-
 ## Node Check Methods
 
+Homelable continuously monitors your nodes and displays their live status (online / offline / unknown) directly on the canvas. Each node can be configured with an independent check method suited to the service it runs.
+
 | Method | Description |
 |--------|-------------|
 | `ping` | ICMP ping |
@@ -150,23 +74,147 @@ Proxmox nodes render as a resizable group container. VM and LXC nodes can be pla
 
 ---
 
-## Development Mode
+## Zigbee2MQTT Import
 
-**Backend (Python 3.13):**
-```bash
-cd backend
-python3.13 -m venv .venv && source .venv/bin/activate
-pip install -r requirements.txt
-cp ../.env.example .env       # edit SECRET_KEY and review defaults
-uvicorn app.main:app --reload --port 8000
-```
+Homelable can connect directly to your MQTT broker and import your Zigbee network topology from **Zigbee2MQTT**, placing each device on the canvas as a typed node.
 
-**Frontend:**
-```bash
-cd frontend
-npm install
-npm run dev   # http://localhost:5173
-```
+### Prerequisites
 
+- A running **MQTT broker** (e.g. Mosquitto) accessible from the Homelable host
+- **Zigbee2MQTT** connected to the broker with at least one device paired
+
+### Usage
+
+1. Click **Zigbee Import** in the left sidebar (below "Scan Network")
+2. Enter your broker host, port (default `1883`), optional credentials, and base topic (default `zigbee2mqtt`)
+3. Click **Test Connection** to verify reachability, then **Fetch Devices**
+4. Select the devices you want from the grouped list (Coordinator / Router / End Device)
+5. Click **Add N to Canvas** — devices are placed in a grid with IoT edges
+
+### Node Types
+
+| Type | Z2M Device | Icon |
+|------|-----------|------|
+| `zigbee_coordinator` | Coordinator | Network hub |
+| `zigbee_router` | Router (mains-powered) | Radio |
+| `zigbee_enddevice` | End Device (battery) | Antenna |
+
+Hierarchy is set automatically: coordinator → routers → end devices (`parent_id`).
+LQI (Link Quality Indicator) is stored as a node property.
+
+> **Full documentation:** [docs/zigbee-import.md](./docs/zigbee-import.md)
+
+---
+
+## Live View (read-only public canvas)
+
+Live View lets you share a read-only snapshot of your canvas with anyone on your network — no login required. It is disabled by default.
+
+### Activation
+
+Add LIVEVIEW_KEY to your .env:
+
+`LIVEVIEW_KEY=your-secret-key`
+
+
+Then restart the backend:
+
+`docker compose restart backend`
+
+### Usage
+
+Use this URL to view your canvas:
+
+http://<your-homelab-ip>/view?key=your-secret-key
+
+The page shows your canvas in pan/zoom-only mode — no editing, no credentials needed. Clicking a node that has an IP opens it in a new tab.
+
+---
+
+## MCP Server (AI Integration) (optional)
+
+Homelable can exposes a [Model Context Protocol](https://modelcontextprotocol.io) server so any MCP-compatible AI client (Claude Code, Claude Desktop, Open WebUI…) can read your homelab topology and act on it.
+
+### What the AI can do
+
+| | Action |
+|---|---|
+| **Read** | List all nodes, edges, full canvas, pending devices, scan history |
+| **Write** | Add / update / delete nodes and edges, trigger a network scan, approve or hide discovered devices |
+
+### Setup
+
+**1. Add the keys to your `.env`:**
+
+```env
+# Authenticates AI clients (Claude Code, etc.) → MCP server
+MCP_API_KEY=mcp_sk_changeme
+
+# Authenticates MCP server → backend (internal Docker network only, never exposed)
+MCP_SERVICE_KEY=svc_changeme
+
+# Generate both with:
+# python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+No plain-text passwords involved — `AUTH_PASSWORD_HASH` is only used for the web UI login.
+
+**2. Start the MCP service:**
+
+```bash
+docker compose up -d mcp
+# MCP server is now listening on http://<your-homelab-ip>:8001
+```
+
+**3. Configure your AI client:**
+
+**Claude Code** — run this command in your terminal:
+```bash
+claude mcp add --transport sse homelable http://<your-homelab-ip>:8001/mcp \
+  --header "X-API-Key: mcp_sk_yourkey"
+```
+
+Or add it manually to `~/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "homelable": {
+      "type": "sse",
+      "url": "http://<your-homelab-ip>:8001/mcp",
+      "headers": {
+        "X-API-Key": "mcp_sk_yourkey"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "homelable": {
+      "type": "sse",
+      "url": "http://<your-homelab-ip>:8001/mcp",
+      "headers": {
+        "X-API-Key": "mcp_sk_yourkey"
+      }
+    }
+  }
+}
+```
+
+### Example prompts
+
+- *"What nodes are currently offline?"*
+- *"Add a new LXC container named `pihole` at 192.168.1.5, connected to my switch."*
+- *"Trigger a network scan on 192.168.1.0/24 and show me the pending devices."*
+- *"Show me the full canvas topology."*
+
+### Security
+
+- The MCP server is **not** intended to be exposed to the internet — keep port 8001 firewalled to your LAN.
+- Rotate the key any time by updating `MCP_API_KEY` in `.env` and restarting: `docker compose restart mcp`.
+- The MCP server communicates with the backend over the internal Docker network — the backend API is never directly exposed to MCP clients.
 
 ---

VERSION

@@ -0,0 +1 @@
+2.0.1

backend/app/api/deps.py

@@ -1,12 +1,30 @@
-from fastapi import Depends, HTTPException, status
+import hmac
+
+from fastapi import Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
+from app.core.config import settings
 from app.core.security import decode_token
 
-bearer = HTTPBearer()
+bearer = HTTPBearer(auto_error=False)
 
 
-def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(bearer)) -> str:
+def get_current_user(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer),
+    x_mcp_service_key: str | None = Header(default=None),
+) -> str:
+    # 1. MCP service key (Docker-internal only — backend port is not externally exposed)
+    if x_mcp_service_key is not None:
+        if not settings.mcp_service_key:
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="MCP service key not configured")
+        if not hmac.compare_digest(x_mcp_service_key.encode(), settings.mcp_service_key.encode()):
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid MCP service key")
+        return "__mcp_service__"
+
+    # 2. Standard JWT bearer token
+    if credentials is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
     username = decode_token(credentials.credentials)
     if not username:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")

backend/app/api/routes/canvas.py

@@ -25,6 +25,7 @@ async def load_canvas(db: AsyncSession = Depends(get_db), _: str = Depends(get_c
         nodes=[NodeResponse.model_validate(n) for n in nodes],
         edges=[EdgeResponse.model_validate(e) for e in edges],
         viewport=viewport,
+        custom_style=state.custom_style if state else None,
     )
 
 
@@ -67,13 +68,14 @@ async def save_canvas(
         else:
             db.add(Edge(**edge_data.model_dump()))
 
-    # Upsert viewport
+    # Upsert viewport + custom style
     state = await db.get(CanvasState, 1)
     if state:
         state.viewport = body.viewport
+        state.custom_style = body.custom_style
         state.saved_at = datetime.now(timezone.utc)
     else:
-        db.add(CanvasState(id=1, viewport=body.viewport))
+        db.add(CanvasState(id=1, viewport=body.viewport, custom_style=body.custom_style))
 
     await db.commit()
     return {"saved": True}

backend/app/api/routes/liveview.py

@@ -0,0 +1,41 @@
+import hmac
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import settings
+from app.db.database import get_db
+from app.db.models import CanvasState, Edge, Node
+from app.schemas.canvas import CanvasStateResponse
+from app.schemas.edges import EdgeResponse
+from app.schemas.nodes import NodeResponse
+
+router = APIRouter()
+
+
+@router.get("", response_model=CanvasStateResponse)
+async def liveview_canvas(
+    key: str | None = Query(default=None),
+    db: AsyncSession = Depends(get_db),
+) -> CanvasStateResponse:
+    """Read-only public canvas endpoint.
+
+    Disabled by default — requires LIVEVIEW_KEY to be set in .env.
+    Always returns 403 when disabled, regardless of the key provided.
+    """
+    if not settings.liveview_key:
+        raise HTTPException(status_code=403, detail="Live view is disabled")
+    if not key or not hmac.compare_digest(key, settings.liveview_key):
+        raise HTTPException(status_code=403, detail="Invalid live view key")
+
+    nodes = (await db.execute(select(Node))).scalars().all()
+    edges = (await db.execute(select(Edge))).scalars().all()
+    state = await db.get(CanvasState, 1)
+    viewport: dict[str, Any] = state.viewport if state else {"x": 0, "y": 0, "zoom": 1}
+    return CanvasStateResponse(
+        nodes=[NodeResponse.model_validate(n) for n in nodes],
+        edges=[EdgeResponse.model_validate(e) for e in edges],
+        viewport=viewport,
+    )

backend/app/api/routes/scan.py

@@ -1,23 +1,38 @@
+import ipaddress
 import logging
+import uuid
 from typing import Any
 
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
 from app.core.config import settings
 from app.db.database import AsyncSessionLocal, get_db
-from app.db.models import Node, PendingDevice, ScanRun
+from app.db.models import Edge, Node, PendingDevice, PendingDeviceLink, ScanRun
 from app.schemas.nodes import NodeCreate
 from app.schemas.scan import PendingDeviceResponse, ScanRunResponse
-from app.services.scanner import run_scan
+from app.services.scanner import request_cancel, run_scan
+
+
+class BulkActionRequest(BaseModel):
+    device_ids: list[str]
 
 
 class ScanConfig(BaseModel):
     ranges: list[str]
-    interval_seconds: int
+
+    @field_validator("ranges")
+    @classmethod
+    def validate_cidr(cls, v: list[str]) -> list[str]:
+        for r in v:
+            try:
+                ipaddress.ip_network(r, strict=False)
+            except ValueError as exc:
+                raise ValueError(f"Invalid CIDR range: {r!r}") from exc
+        return v
 
 
 logger = logging.getLogger(__name__)
@@ -26,7 +41,15 @@ router = APIRouter()
 
 async def _background_scan(run_id: str, ranges: list[str]) -> None:
     async with AsyncSessionLocal() as db:
-        await run_scan(ranges, db, run_id)
+        try:
+            await run_scan(ranges, db, run_id)
+        except Exception:
+            logger.exception("Scan run %s failed unexpectedly", run_id)
+            await db.rollback()
+            run = await db.get(ScanRun, run_id)
+            if run and run.status == "running":
+                run.status = "failed"
+                await db.commit()
 
 
 @router.post("/trigger", response_model=ScanRunResponse)
@@ -44,18 +67,151 @@ async def trigger_scan(
     return run
 
 
+@router.post("/{run_id}/stop", response_model=dict)
+async def stop_scan(
+    run_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, bool]:
+    try:
+        uuid.UUID(run_id)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="Invalid run_id format") from None
+    run = await db.get(ScanRun, run_id)
+    if not run:
+        raise HTTPException(status_code=404, detail="Scan run not found")
+    if run.status != "running":
+        raise HTTPException(status_code=409, detail="Scan is not running")
+    request_cancel(run_id)
+    return {"stopping": True}
+
+
 @router.get("/pending", response_model=list[PendingDeviceResponse])
 async def list_pending(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[PendingDevice]:
     result = await db.execute(select(PendingDevice).where(PendingDevice.status == "pending"))
     return list(result.scalars().all())
 
 
+@router.delete("/pending", response_model=dict)
+async def clear_pending(
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, int]:
+    from sqlalchemy import delete as sa_delete
+    result = await db.execute(sa_delete(PendingDevice).where(PendingDevice.status == "pending"))
+    await db.commit()
+    return {"deleted": result.rowcount}
+
+
 @router.get("/hidden", response_model=list[PendingDeviceResponse])
 async def list_hidden(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[PendingDevice]:
     result = await db.execute(select(PendingDevice).where(PendingDevice.status == "hidden"))
     return list(result.scalars().all())
 
 
+@router.post("/pending/bulk-approve", response_model=dict)
+async def bulk_approve_devices(
+    payload: BulkActionRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, Any]:
+    result = await db.execute(
+        select(PendingDevice).where(
+            PendingDevice.id.in_(payload.device_ids),
+            PendingDevice.status == "pending",
+        )
+    )
+    devices = result.scalars().all()
+    created_nodes: list[Node] = []
+    for device in devices:
+        device.status = "approved"
+        node = Node(
+            label=device.hostname or device.friendly_name or device.ip or "device",
+            type=device.suggested_type or "generic",
+            ip=device.ip,
+            hostname=device.hostname,
+            status="unknown",
+            services=device.services or [],
+            ieee_address=device.ieee_address,
+            # Default to ping so the status checker actually polls the new node.
+            # Without this the scheduler skips it (check_method NULL → no check).
+            check_method="ping" if device.ip else None,
+        )
+        db.add(node)
+        created_nodes.append(node)
+    await db.flush()  # populates node.id from Python-side default before reading
+    node_ids = [n.id for n in created_nodes]
+    approved_device_ids = [d.id for d in devices]
+
+    all_edges: list[dict[str, str]] = []
+    for device in devices:
+        all_edges.extend(await _resolve_pending_links_for_ieee(db, device.ieee_address))
+
+    await db.commit()
+    return {
+        "approved": len(node_ids),
+        "node_ids": node_ids,
+        "device_ids": approved_device_ids,
+        "edges_created": len(all_edges),
+        "edges": all_edges,
+        "skipped": len(payload.device_ids) - len(node_ids),
+    }
+
+
+@router.post("/pending/bulk-hide", response_model=dict)
+async def bulk_hide_devices(
+    payload: BulkActionRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, Any]:
+    result = await db.execute(
+        select(PendingDevice).where(
+            PendingDevice.id.in_(payload.device_ids),
+            PendingDevice.status == "pending",
+        )
+    )
+    devices = result.scalars().all()
+    for device in devices:
+        device.status = "hidden"
+    await db.commit()
+    return {"hidden": len(devices), "skipped": len(payload.device_ids) - len(devices)}
+
+
+@router.post("/pending/{device_id}/restore", response_model=dict)
+async def restore_device(
+    device_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, Any]:
+    device = await db.get(PendingDevice, device_id)
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    if device.status != "hidden":
+        raise HTTPException(status_code=409, detail="Device is not hidden")
+    device.status = "pending"
+    await db.commit()
+    return {"restored": True, "device_id": device_id}
+
+
+@router.post("/pending/bulk-restore", response_model=dict)
+async def bulk_restore_devices(
+    payload: BulkActionRequest,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> dict[str, Any]:
+    result = await db.execute(
+        select(PendingDevice).where(
+            PendingDevice.id.in_(payload.device_ids),
+            PendingDevice.status == "hidden",
+        )
+    )
+    devices = result.scalars().all()
+    for device in devices:
+        device.status = "pending"
+    await db.commit()
+    return {"restored": len(devices), "skipped": len(payload.device_ids) - len(devices)}
+
+
 @router.post("/pending/{device_id}/approve", response_model=dict)
 async def approve_device(
     device_id: str,
@@ -64,13 +220,118 @@ async def approve_device(
     _: str = Depends(get_current_user),
 ) -> dict[str, Any]:
     device = await db.get(PendingDevice, device_id)
-    if device:
-        device.status = "approved"
-        node = Node(**node_data.model_dump())
-        db.add(node)
-        await db.commit()
-        return {"approved": True, "node_id": node.id}
-    return {"approved": False}
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    if device.status != "pending":
+        raise HTTPException(status_code=409, detail="Device already processed")
+    device.status = "approved"
+    node = Node(
+        label=node_data.label,
+        type=node_data.type,
+        ip=node_data.ip,
+        hostname=node_data.hostname,
+        status=node_data.status,
+        services=node_data.services or [],
+        ieee_address=device.ieee_address,
+        # Honour caller-supplied check_method, else default to ping when an IP exists
+        # so the scheduler doesn't silently skip the new node.
+        check_method=node_data.check_method or ("ping" if node_data.ip else None),
+        check_target=node_data.check_target,
+    )
+    db.add(node)
+    await db.flush()
+    node_id = node.id
+
+    edges = await _resolve_pending_links_for_ieee(db, device.ieee_address)
+
+    await db.commit()
+    return {
+        "approved": True,
+        "node_id": node_id,
+        "edges_created": len(edges),
+        "edges": edges,
+    }
+
+
+async def _resolve_pending_links_for_ieee(
+    db: AsyncSession, ieee: str | None
+) -> list[dict[str, str]]:
+    """Materialize edges for any pending_device_links involving ``ieee``.
+
+    For each link where the other endpoint already exists as a canvas Node
+    (matched by ``Node.ieee_address``), create the Edge and drop the link
+    row. Links where the other endpoint is still pending are kept so they
+    can resolve when that endpoint is approved later.
+    """
+    if not ieee:
+        return []
+
+    links_q = await db.execute(
+        select(PendingDeviceLink).where(
+            (PendingDeviceLink.source_ieee == ieee)
+            | (PendingDeviceLink.target_ieee == ieee)
+        )
+    )
+    links = list(links_q.scalars().all())
+    if not links:
+        return []
+
+    # Map every relevant ieee → Node (single query).
+    other_ieees = {
+        link.target_ieee if link.source_ieee == ieee else link.source_ieee
+        for link in links
+    }
+    other_ieees.add(ieee)
+    nodes_q = await db.execute(
+        select(Node).where(Node.ieee_address.in_(other_ieees))
+    )
+    by_ieee = {n.ieee_address: n for n in nodes_q.scalars().all() if n.ieee_address}
+
+    self_node = by_ieee.get(ieee)
+    if self_node is None:
+        return []
+
+    # Pre-fetch existing edges between these node ids so we don't create dups
+    # if the user re-approves a device or had drawn the link manually.
+    candidate_node_ids = [n.id for n in by_ieee.values()]
+    existing_q = await db.execute(
+        select(Edge).where(
+            Edge.source.in_(candidate_node_ids),
+            Edge.target.in_(candidate_node_ids),
+        )
+    )
+    existing_pairs = {(e.source, e.target) for e in existing_q.scalars().all()}
+
+    created: list[dict[str, str]] = []
+    for link in links:
+        other_ieee = (
+            link.target_ieee if link.source_ieee == ieee else link.source_ieee
+        )
+        other_node = by_ieee.get(other_ieee)
+        if other_node is None:
+            continue
+        if link.source_ieee == ieee:
+            src_id, tgt_id = self_node.id, other_node.id
+        else:
+            src_id, tgt_id = other_node.id, self_node.id
+        # Skip if either direction already exists.
+        if (src_id, tgt_id) in existing_pairs or (tgt_id, src_id) in existing_pairs:
+            await db.delete(link)
+            continue
+        edge = Edge(
+            source=src_id,
+            target=tgt_id,
+            type="iot",
+            source_handle="bottom",
+            target_handle="top-t",
+        )
+        db.add(edge)
+        await db.flush()
+        existing_pairs.add((src_id, tgt_id))
+        created.append({"id": edge.id, "source": src_id, "target": tgt_id})
+        await db.delete(link)
+
+    return created
 
 
 @router.post("/pending/{device_id}/hide")
@@ -78,9 +339,10 @@ async def hide_device(
     device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
 ) -> dict[str, bool]:
     device = await db.get(PendingDevice, device_id)
-    if device:
-        device.status = "hidden"
-        await db.commit()
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    device.status = "hidden"
+    await db.commit()
     return {"hidden": True}
 
 
@@ -89,9 +351,10 @@ async def ignore_device(
     device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
 ) -> dict[str, bool]:
     device = await db.get(PendingDevice, device_id)
-    if device:
-        await db.delete(device)
-        await db.commit()
+    if not device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    await db.delete(device)
+    await db.commit()
     return {"ignored": True}
 
 
@@ -103,18 +366,17 @@ async def list_runs(db: AsyncSession = Depends(get_db), _: str = Depends(get_cur
 
 @router.get("/config", response_model=ScanConfig)
 async def get_scan_config(_: str = Depends(get_current_user)) -> ScanConfig:
-    return ScanConfig(
-        ranges=settings.scanner_ranges,
-        interval_seconds=settings.status_checker_interval,
-    )
+    return ScanConfig(ranges=settings.scanner_ranges)
 
 
 @router.post("/config", response_model=ScanConfig)
 async def update_scan_config(payload: ScanConfig, _: str = Depends(get_current_user)) -> ScanConfig:
+    previous = settings.scanner_ranges
+    settings.scanner_ranges = payload.ranges
     try:
-        settings.scanner_ranges = payload.ranges
-        settings.status_checker_interval = payload.interval_seconds
         settings.save_overrides()
         return payload
     except Exception as exc:
-        raise HTTPException(status_code=500, detail=str(exc)) from exc
+        settings.scanner_ranges = previous
+        logger.error("Failed to save scan config: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to save scan config") from exc

backend/app/api/routes/settings.py

@@ -0,0 +1,29 @@
+"""App-level settings (status checker interval, etc.)."""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from app.api.deps import get_current_user
+from app.core.config import settings
+
+router = APIRouter()
+
+
+class AppSettings(BaseModel):
+    interval_seconds: int
+
+
+@router.get("", response_model=AppSettings)
+async def get_settings(_: str = Depends(get_current_user)) -> AppSettings:
+    return AppSettings(interval_seconds=settings.status_checker_interval)
+
+
+@router.post("", response_model=AppSettings)
+async def update_settings(
+    payload: AppSettings, _: str = Depends(get_current_user)
+) -> AppSettings:
+    try:
+        settings.status_checker_interval = payload.interval_seconds
+        settings.save_overrides()
+        return payload
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc

backend/app/api/routes/status.py

@@ -11,11 +11,23 @@ _connections: list[WebSocket] = []
 
 
 @router.websocket("/ws/status")
-async def ws_status(websocket: WebSocket, token: str | None = None) -> None:
-    if not token or not decode_token(token):
-        await websocket.close(code=1008)  # Policy Violation
-        return
+async def ws_status(websocket: WebSocket) -> None:
+    # Accept first so we can send a close frame with a reason code
     await websocket.accept()
+    try:
+        # Expect the first message to be a JSON auth payload: {"token": "<jwt>"}
+        raw = await websocket.receive_text()
+        try:
+            payload = json.loads(raw)
+            token = payload.get("token", "")
+        except (json.JSONDecodeError, AttributeError):
+            token = ""
+        if not token or not decode_token(token):
+            await websocket.close(code=1008)  # Policy Violation
+            return
+    except WebSocketDisconnect:
+        return
+
     _connections.append(websocket)
     try:
         while True:

backend/app/api/routes/zigbee.py

@@ -0,0 +1,260 @@
+"""FastAPI router for Zigbee2MQTT import."""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from sqlalchemy import delete as sa_delete
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_user
+from app.db.database import AsyncSessionLocal, get_db
+from app.db.models import Node, PendingDevice, PendingDeviceLink, ScanRun
+from app.schemas.scan import ScanRunResponse
+from app.schemas.zigbee import (
+    ZigbeeCoordinatorOut,
+    ZigbeeEdgeOut,
+    ZigbeeImportPendingResponse,
+    ZigbeeImportRequest,
+    ZigbeeImportResponse,
+    ZigbeeNodeOut,
+    ZigbeeTestConnectionRequest,
+    ZigbeeTestConnectionResponse,
+)
+from app.services.zigbee_service import fetch_networkmap, test_mqtt_connection
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+@router.post("/import", response_model=ZigbeeImportResponse)
+async def import_zigbee_network(
+    payload: ZigbeeImportRequest,
+    _: str = Depends(get_current_user),
+) -> ZigbeeImportResponse:
+    """Fetch the Zigbee2MQTT network map and return nodes + edges ready for canvas drop.
+
+    Connects to the specified MQTT broker, publishes a networkmap request to
+    ``<base_topic>/bridge/request/networkmap``, and waits up to 60 s for the
+    response (large meshes can take 30 s+).  The devices are returned as typed homelable nodes with a
+    coordinator → router → end-device hierarchy.
+    """
+    try:
+        nodes_raw, edges_raw = await fetch_networkmap(
+            mqtt_host=payload.mqtt_host,
+            mqtt_port=payload.mqtt_port,
+            base_topic=payload.base_topic,
+            username=payload.mqtt_username,
+            password=payload.mqtt_password,
+            tls=payload.mqtt_tls,
+            tls_insecure=payload.mqtt_tls_insecure,
+        )
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    except ConnectionError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    except TimeoutError as exc:
+        raise HTTPException(status_code=504, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("Unexpected error during Zigbee import")
+        raise HTTPException(status_code=500, detail="Unexpected error during Zigbee import") from exc
+
+    nodes = [ZigbeeNodeOut(**n) for n in nodes_raw]
+    edges = [ZigbeeEdgeOut(**e) for e in edges_raw]
+    return ZigbeeImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))
+
+
+@router.post("/import-pending", response_model=ScanRunResponse)
+async def import_zigbee_to_pending(
+    payload: ZigbeeImportRequest,
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+    _: str = Depends(get_current_user),
+) -> ScanRun:
+    """Queue a Zigbee2MQTT pending import as a background scan run.
+
+    Returns the ScanRun row immediately so the UI can close the import
+    modal and surface progress under Scan History (kind=zigbee). The
+    actual MQTT fetch + pending upsert happens in the background.
+    """
+    run = ScanRun(
+        status="running",
+        kind="zigbee",
+        ranges=[f"{payload.mqtt_host}:{payload.mqtt_port}"],
+    )
+    db.add(run)
+    await db.commit()
+    await db.refresh(run)
+    background_tasks.add_task(_background_zigbee_import, run.id, payload)
+    return run
+
+
+async def _background_zigbee_import(run_id: str, payload: ZigbeeImportRequest) -> None:
+    async with AsyncSessionLocal() as db:
+        try:
+            nodes_raw, edges_raw = await fetch_networkmap(
+                mqtt_host=payload.mqtt_host,
+                mqtt_port=payload.mqtt_port,
+                base_topic=payload.base_topic,
+                username=payload.mqtt_username,
+                password=payload.mqtt_password,
+                tls=payload.mqtt_tls,
+                tls_insecure=payload.mqtt_tls_insecure,
+            )
+            result = await _persist_pending_import(db, nodes_raw, edges_raw)
+            run = await db.get(ScanRun, run_id)
+            if run:
+                run.status = "done"
+                run.devices_found = result.device_count
+                run.finished_at = datetime.now(timezone.utc)
+                await db.commit()
+        except Exception as exc:
+            logger.exception("Zigbee import %s failed", run_id)
+            await db.rollback()
+            run = await db.get(ScanRun, run_id)
+            if run:
+                run.status = "error"
+                run.error = str(exc)[:500]
+                run.finished_at = datetime.now(timezone.utc)
+                await db.commit()
+
+
+async def _persist_pending_import(
+    db: AsyncSession,
+    nodes_raw: list[dict[str, Any]],
+    edges_raw: list[dict[str, Any]],
+) -> ZigbeeImportPendingResponse:
+    """Upsert nodes/edges into pending_devices + pending_device_links.
+
+    Coordinator auto-approves to a canvas Node. Other devices upsert by IEEE.
+    All zigbee-source links are wiped and re-inserted from the new map.
+    """
+    coordinator_out: ZigbeeCoordinatorOut | None = None
+    coordinator_existed = False
+    pending_created = 0
+    pending_updated = 0
+
+    for n in nodes_raw:
+        ieee = n.get("ieee_address")
+        if not ieee:
+            continue
+        if n.get("device_type") == "Coordinator":
+            existing = await db.execute(select(Node).where(Node.ieee_address == ieee))
+            existing_node = existing.scalar_one_or_none()
+            if existing_node:
+                coordinator_out = ZigbeeCoordinatorOut(
+                    id=existing_node.id,
+                    label=existing_node.label,
+                    ieee_address=ieee,
+                )
+                coordinator_existed = True
+                continue
+            label = n.get("friendly_name") or ieee
+            node = Node(
+                label=label,
+                type=n.get("type") or "zigbee_coordinator",
+                status="unknown",
+                ieee_address=ieee,
+                services=[],
+            )
+            db.add(node)
+            await db.flush()
+            coordinator_out = ZigbeeCoordinatorOut(
+                id=node.id, label=label, ieee_address=ieee
+            )
+            continue
+
+        result = await db.execute(
+            select(PendingDevice).where(PendingDevice.ieee_address == ieee)
+        )
+        pending = result.scalar_one_or_none()
+        if pending is None:
+            db.add(
+                PendingDevice(
+                    ieee_address=ieee,
+                    friendly_name=n.get("friendly_name"),
+                    hostname=n.get("friendly_name"),
+                    suggested_type=n.get("type"),
+                    device_subtype=n.get("device_type"),
+                    model=n.get("model"),
+                    vendor=n.get("vendor"),
+                    lqi=n.get("lqi"),
+                    status="pending",
+                    discovery_source="zigbee",
+                )
+            )
+            pending_created += 1
+        else:
+            pending.friendly_name = n.get("friendly_name") or pending.friendly_name
+            pending.suggested_type = n.get("type") or pending.suggested_type
+            pending.device_subtype = n.get("device_type") or pending.device_subtype
+            pending.model = n.get("model") or pending.model
+            pending.vendor = n.get("vendor") or pending.vendor
+            if n.get("lqi") is not None:
+                pending.lqi = n.get("lqi")
+            if pending.status == "hidden":
+                # Re-imported a hidden device → leave it hidden, just refresh fields.
+                pass
+            pending_updated += 1
+
+    # Replace all zigbee-source links with the freshly discovered set.
+    await db.execute(
+        sa_delete(PendingDeviceLink).where(PendingDeviceLink.discovery_source == "zigbee")
+    )
+
+    links_recorded = 0
+    seen: set[tuple[str, str]] = set()
+    for e in edges_raw:
+        src = e.get("source")
+        tgt = e.get("target")
+        if not src or not tgt or (src, tgt) in seen:
+            continue
+        seen.add((src, tgt))
+        db.add(
+            PendingDeviceLink(
+                source_ieee=src,
+                target_ieee=tgt,
+                discovery_source="zigbee",
+            )
+        )
+        links_recorded += 1
+
+    await db.commit()
+
+    return ZigbeeImportPendingResponse(
+        pending_created=pending_created,
+        pending_updated=pending_updated,
+        coordinator=coordinator_out,
+        coordinator_already_existed=coordinator_existed,
+        links_recorded=links_recorded,
+        device_count=len(nodes_raw),
+    )
+
+
+@router.post("/test-connection", response_model=ZigbeeTestConnectionResponse)
+async def test_zigbee_connection(
+    payload: ZigbeeTestConnectionRequest,
+    _: str = Depends(get_current_user),
+) -> ZigbeeTestConnectionResponse:
+    """Quick MQTT ping to validate broker connection before importing."""
+    try:
+        await test_mqtt_connection(
+            mqtt_host=payload.mqtt_host,
+            mqtt_port=payload.mqtt_port,
+            username=payload.mqtt_username,
+            password=payload.mqtt_password,
+            tls=payload.mqtt_tls,
+            tls_insecure=payload.mqtt_tls_insecure,
+        )
+        return ZigbeeTestConnectionResponse(connected=True, message="Connection successful")
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    except (ConnectionError, TimeoutError) as exc:
+        return ZigbeeTestConnectionResponse(connected=False, message=str(exc))
+    except Exception:
+        logger.exception("Unexpected error during connection test")
+        return ZigbeeTestConnectionResponse(connected=False, message="Unexpected error")

backend/app/core/config.py

@@ -1,8 +1,23 @@
 import json
+import logging
 from pathlib import Path
 
+from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+logger = logging.getLogger(__name__)
+
+def _read_version() -> str:
+    for candidate in [
+        Path(__file__).parent.parent.parent.parent / "VERSION",  # repo root (dev)
+        Path("/app/VERSION"),                                      # Docker image
+    ]:
+        if candidate.exists():
+            return candidate.read_text().strip()
+    return "unknown"
+
+APP_VERSION = _read_version()
+
 
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
@@ -19,12 +34,33 @@ class Settings(BaseSettings):
     auth_username: str = "admin"
     auth_password_hash: str = ""
 
+    @model_validator(mode="after")
+    def check_password_hash(self) -> "Settings":
+        h = self.auth_password_hash
+        if h and not h.startswith("$2"):
+            logger.error(
+                "AUTH_PASSWORD_HASH looks invalid (does not start with '$2b$'). "
+                "bcrypt hashes contain '$' signs — wrap the value in single quotes "
+                "in your .env file: AUTH_PASSWORD_HASH='$2b$12$...'"
+            )
+        return self
+
     # Scanner
     scanner_ranges: list[str] = ["192.168.1.0/24"]
 
     # Status checker
     status_checker_interval: int = 60
 
+    # MCP service key — set MCP_SERVICE_KEY in .env
+    # Used by the MCP server to authenticate against the backend without a user password.
+    # Leave empty to disable MCP service key auth.
+    mcp_service_key: str = ""
+
+    # Live view — optional read-only public canvas endpoint.
+    # Set to a random secret string to enable /api/v1/liveview?key=<value>.
+    # Leave unset (or empty) to keep the feature disabled (default).
+    liveview_key: str | None = None
+
     def _override_path(self) -> Path:
         return Path(self.sqlite_path).parent / "scan_config.json"
 

backend/app/core/scheduler.py

@@ -1,4 +1,5 @@
 """APScheduler setup for background scan and status check jobs."""
+import asyncio
 import logging
 from datetime import datetime, timezone
 
@@ -15,43 +16,94 @@ logger = logging.getLogger(__name__)
 scheduler: AsyncIOScheduler = AsyncIOScheduler()
 
 
-async def _run_status_checks() -> None:
-    """Check all nodes and broadcast results via WebSocket."""
+async def _check_single_node(
+    node_id: str,
+    check_method: str,
+    check_target: str | None,
+    ip: str | None,
+) -> tuple[str, dict[str, object] | None]:
+    """Run a single node check; returns (node_id, result_or_None).
+
+    Accepts plain scalars — not an ORM object — so there is no risk of
+    DetachedInstanceError when the originating session has already closed.
+    """
     from app.api.routes.status import broadcast_status  # avoid circular import
 
+    try:
+        check_result = await check_node(check_method, check_target, ip)
+        now = datetime.now(timezone.utc)
+        async with AsyncSessionLocal() as db:
+            n = await db.get(Node, node_id)
+            if n:
+                n.status = check_result["status"]
+                n.response_time_ms = check_result["response_time_ms"]
+                if check_result["status"] == "online":
+                    n.last_seen = now
+                await db.commit()
+        await broadcast_status(
+            node_id=node_id,
+            status=check_result["status"],
+            checked_at=now.isoformat(),
+            response_time_ms=check_result["response_time_ms"],
+        )
+        return node_id, check_result
+    except Exception as exc:
+        logger.error("Status check failed for node %s: %s", node_id, exc)
+        return node_id, None
+
+
+async def _run_status_checks() -> None:
+    """Check all nodes concurrently and broadcast results via WebSocket."""
     async with AsyncSessionLocal() as db:
         result = await db.execute(select(Node))
         nodes = result.scalars().all()
+        # Extract scalars while the session is open to avoid DetachedInstanceError
+        checkable = [
+            (n.id, n.check_method, n.check_target, n.ip)
+            for n in nodes
+            if n.check_method
+        ]
 
-    for node in nodes:
-        if not node.check_method:
-            continue
-        try:
-            check_result = await check_node(node.check_method, node.check_target, node.ip)
-            async with AsyncSessionLocal() as db:
-                n = await db.get(Node, node.id)
-                if n:
-                    n.status = check_result["status"]
-                    n.response_time_ms = check_result["response_time_ms"]
-                    n.last_seen = datetime.now(timezone.utc) if check_result["status"] == "online" else n.last_seen
-                    await db.commit()
-            await broadcast_status(
-                node_id=node.id,
-                status=check_result["status"],
-                checked_at=datetime.now(timezone.utc).isoformat(),
-                response_time_ms=check_result["response_time_ms"],
-            )
-        except Exception as exc:
-            logger.error("Status check failed for node %s: %s", node.id, exc)
+    if not checkable:
+        return
+
+    await asyncio.gather(*[
+        _check_single_node(node_id, method, target, ip)
+        for node_id, method, target, ip in checkable
+    ])
 
 
 def start_scheduler() -> None:
     global scheduler
+    if scheduler.running:
+        try:
+            scheduler.shutdown(wait=False)
+        except Exception as exc:
+            logger.warning("Failed to shut down previous scheduler instance: %s", exc)
     scheduler = AsyncIOScheduler()
-    scheduler.add_job(_run_status_checks, "interval", seconds=settings.status_checker_interval, id="status_checks")
+    scheduler.add_job(
+        _run_status_checks,
+        "interval",
+        seconds=settings.status_checker_interval,
+        id="status_checks",
+        max_instances=1,
+        coalesce=True,
+    )
     scheduler.start()
     logger.info("Scheduler started — status checks every %ds", settings.status_checker_interval)
 
 
+def reschedule_status_checks(interval_seconds: int) -> None:
+    """Update the status check interval on the running scheduler."""
+    if interval_seconds < 10:
+        raise ValueError(f"interval_seconds must be >= 10, got {interval_seconds}")
+    if not scheduler.running:
+        logger.warning("Scheduler not running, skipping reschedule")
+        return
+    scheduler.reschedule_job("status_checks", trigger="interval", seconds=interval_seconds)
+    logger.info("Status checks rescheduled to every %ds", interval_seconds)
+
+
 def stop_scheduler() -> None:
-    scheduler.shutdown(wait=False)
+    if scheduler.running:
+        scheduler.shutdown(wait=False)

backend/app/core/security.py

@@ -9,7 +9,10 @@ pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
 
 
 def verify_password(plain: str, hashed: str) -> bool:
-    return bool(pwd_context.verify(plain, hashed))
+    try:
+        return bool(pwd_context.verify(plain, hashed))
+    except ValueError:
+        return False
 
 
 def hash_password(password: str) -> str:

backend/app/db/database.py

@@ -1,11 +1,33 @@
+import logging
+import shutil
 from collections.abc import AsyncGenerator
 from contextlib import suppress
 from pathlib import Path
 
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.exc import OperationalError
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase
 
-from app.core.config import settings
+from app.core.config import APP_VERSION, settings
+
+logger = logging.getLogger(__name__)
+
+
+async def _try_migrate(conn: AsyncConnection, sql: str, *, label: str) -> None:
+    """Run an idempotent migration statement, logging any error.
+
+    Distinguishes 'already applied' errors (debug) from genuine failures
+    (warning) so silent corruption is avoided. Used for new in-commit
+    migrations; existing legacy ALTERs above remain wrapped in suppress.
+    """
+    try:
+        await conn.exec_driver_sql(sql)
+    except OperationalError as exc:
+        msg = str(exc).lower()
+        if "duplicate column" in msg or "already exists" in msg:
+            logger.debug("Migration %s skipped (already applied): %s", label, exc)
+        else:
+            logger.warning("Migration %s failed: %s", label, exc)
 
 # Ensure the data directory exists before SQLite tries to open the file
 Path(settings.sqlite_path).parent.mkdir(parents=True, exist_ok=True)
@@ -22,24 +44,165 @@ class Base(DeclarativeBase):
     pass
 
 
+def _backup_db() -> None:
+    db_path = Path(settings.sqlite_path)
+    if not db_path.exists():
+        return
+    backup_path = db_path.with_suffix(f".db.back-{APP_VERSION}")
+    if backup_path.exists():
+        return
+    try:
+        shutil.copy2(db_path, backup_path)
+        logger.info("DB backup created: %s", backup_path.name)
+    except OSError:
+        logger.warning("Could not create DB backup at %s", backup_path)
+
+
 async def init_db() -> None:
+    _backup_db()
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
         # Add columns introduced after initial schema (idempotent)
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN container_mode BOOLEAN NOT NULL DEFAULT 0")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN custom_colors JSON")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN custom_color TEXT")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN path_style TEXT")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN custom_icon TEXT")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN source_handle TEXT")
-        with suppress(Exception):
+        with suppress(OperationalError):
             await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN target_handle TEXT")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN animated BOOLEAN NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN cpu_count INTEGER")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN cpu_model TEXT")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN ram_gb REAL")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN disk_gb REAL")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN show_hardware BOOLEAN NOT NULL DEFAULT 0")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN width REAL")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN height REAL")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN bottom_handles INTEGER NOT NULL DEFAULT 1")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE pending_devices ADD COLUMN discovery_source TEXT")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE scan_runs ADD COLUMN kind TEXT NOT NULL DEFAULT 'ip'")
+        # --- Zigbee schema migrations (logged variant per CLAUDE.md feedback) ---
+        zigbee_migrations: list[tuple[str, str]] = [
+            ("nodes.ieee_address", "ALTER TABLE nodes ADD COLUMN ieee_address TEXT"),
+            (
+                "nodes.ieee_address.index",
+                "CREATE INDEX IF NOT EXISTS ix_nodes_ieee_address ON nodes(ieee_address)",
+            ),
+            ("pending_devices.ieee_address", "ALTER TABLE pending_devices ADD COLUMN ieee_address TEXT"),
+            (
+                "pending_devices.ieee_address.index",
+                "CREATE INDEX IF NOT EXISTS ix_pending_devices_ieee_address "
+                "ON pending_devices(ieee_address)",
+            ),
+            ("pending_devices.friendly_name", "ALTER TABLE pending_devices ADD COLUMN friendly_name TEXT"),
+            ("pending_devices.device_subtype", "ALTER TABLE pending_devices ADD COLUMN device_subtype TEXT"),
+            ("pending_devices.model", "ALTER TABLE pending_devices ADD COLUMN model TEXT"),
+            ("pending_devices.vendor", "ALTER TABLE pending_devices ADD COLUMN vendor TEXT"),
+            ("pending_devices.lqi", "ALTER TABLE pending_devices ADD COLUMN lqi INTEGER"),
+        ]
+        for label, sql in zigbee_migrations:
+            await _try_migrate(conn, sql, label=label)
+        # Drop NOT NULL on pending_devices.ip (Zigbee devices have no IP).
+        # SQLite can't ALTER column nullability — rebuild the table if needed.
+        try:
+            info = await conn.exec_driver_sql("PRAGMA table_info(pending_devices)")
+            cols = info.fetchall()
+            ip_col = next((c for c in cols if c[1] == "ip"), None)
+            # PRAGMA table_info row layout: (cid, name, type, notnull, dflt, pk)
+            if ip_col and ip_col[3] == 1:
+                logger.info("Migrating pending_devices: dropping NOT NULL on ip column")
+                await conn.exec_driver_sql("PRAGMA foreign_keys = OFF")
+                await conn.exec_driver_sql(
+                    "CREATE TABLE pending_devices_new ("
+                    "id VARCHAR PRIMARY KEY,"
+                    "ip VARCHAR,"
+                    "mac VARCHAR, hostname VARCHAR, os VARCHAR, services JSON,"
+                    "suggested_type VARCHAR,"
+                    "status VARCHAR,"
+                    "discovery_source VARCHAR,"
+                    "ieee_address VARCHAR,"
+                    "friendly_name VARCHAR,"
+                    "device_subtype VARCHAR,"
+                    "model VARCHAR,"
+                    "vendor VARCHAR,"
+                    "lqi INTEGER,"
+                    "discovered_at DATETIME"
+                    ")"
+                )
+                await conn.exec_driver_sql(
+                    "INSERT INTO pending_devices_new "
+                    "(id, ip, mac, hostname, os, services, suggested_type, status, "
+                    "discovery_source, ieee_address, friendly_name, device_subtype, "
+                    "model, vendor, lqi, discovered_at) "
+                    "SELECT id, ip, mac, hostname, os, services, suggested_type, status, "
+                    "discovery_source, ieee_address, friendly_name, device_subtype, "
+                    "model, vendor, lqi, discovered_at FROM pending_devices"
+                )
+                await conn.exec_driver_sql("DROP TABLE pending_devices")
+                await conn.exec_driver_sql(
+                    "ALTER TABLE pending_devices_new RENAME TO pending_devices"
+                )
+                await conn.exec_driver_sql(
+                    "CREATE INDEX IF NOT EXISTS ix_pending_devices_ieee_address "
+                    "ON pending_devices(ieee_address)"
+                )
+                await conn.exec_driver_sql("PRAGMA foreign_keys = ON")
+        except OperationalError as exc:
+            logger.warning("pending_devices ip-nullable rebuild failed: %s", exc)
+        # --- end Zigbee schema migrations -------------------------------------
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE edges ADD COLUMN waypoints JSON")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE nodes ADD COLUMN properties JSON")
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("ALTER TABLE canvas_state ADD COLUMN custom_style JSON")
+        # Migrate hardware columns → properties JSON (idempotent: only runs on nodes where properties IS NULL)
+        with suppress(OperationalError):
+            rows = await conn.exec_driver_sql(
+                "SELECT id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware "
+                "FROM nodes WHERE properties IS NULL"
+            )
+            for row in rows.fetchall():
+                node_id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware = row
+                props = []
+                visible = bool(show_hardware)
+                if cpu_model:
+                    props.append({"key": "CPU Model", "value": str(cpu_model), "icon": "Cpu", "visible": visible})
+                if cpu_count is not None:
+                    props.append({"key": "CPU Cores", "value": str(cpu_count), "icon": "Cpu", "visible": visible})
+                if ram_gb is not None:
+                    props.append({"key": "RAM", "value": f"{ram_gb} GB", "icon": "MemoryStick", "visible": visible})
+                if disk_gb is not None:
+                    props.append({"key": "Disk", "value": f"{disk_gb} GB", "icon": "HardDrive", "visible": visible})
+                import json as _json
+                await conn.exec_driver_sql(
+                    "UPDATE nodes SET properties = ? WHERE id = ?",
+                    (_json.dumps(props), node_id),
+                )
+        # Migrate animated column from boolean (0/1) to string ('none'/'snake')
+        with suppress(OperationalError):
+            await conn.exec_driver_sql("UPDATE edges SET animated = 'snake' WHERE animated = '1' OR animated = 1")
+        with suppress(OperationalError):
+            sql = "UPDATE edges SET animated = 'none' WHERE animated = '0' OR animated = 0 OR animated IS NULL"
+            await conn.exec_driver_sql(sql)
 
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:

backend/app/db/models.py

@@ -33,15 +33,24 @@ class Node(Base):
     notes: Mapped[str | None] = mapped_column(Text)
     pos_x: Mapped[float] = mapped_column(Float, default=0)
     pos_y: Mapped[float] = mapped_column(Float, default=0)
-    parent_id: Mapped[str | None] = mapped_column(String, ForeignKey("nodes.id"))
+    parent_id: Mapped[str | None] = mapped_column(String, ForeignKey("nodes.id", ondelete="CASCADE"))
     container_mode: Mapped[bool] = mapped_column(Boolean, default=False)
     custom_colors: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     custom_icon: Mapped[str | None] = mapped_column(String, nullable=True)
+    cpu_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    cpu_model: Mapped[str | None] = mapped_column(String, nullable=True)
+    ram_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
+    disk_gb: Mapped[float | None] = mapped_column(Float, nullable=True)
+    show_hardware: Mapped[bool] = mapped_column(Boolean, default=False)
+    properties: Mapped[list[Any]] = mapped_column(JSON, default=list)
+    width: Mapped[float | None] = mapped_column(Float, nullable=True)
+    height: Mapped[float | None] = mapped_column(Float, nullable=True)
+    bottom_handles: Mapped[int] = mapped_column(Integer, default=1)
+    ieee_address: Mapped[str | None] = mapped_column(String, index=True, nullable=True)
     last_seen: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     response_time_ms: Mapped[int | None] = mapped_column(Integer)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now, onupdate=_now)
-
     children: Mapped[list["Node"]] = relationship("Node", back_populates="parent")
     parent: Mapped["Node | None"] = relationship("Node", back_populates="children", remote_side=[id])
 
@@ -58,8 +67,10 @@ class Edge(Base):
     speed: Mapped[str | None] = mapped_column(String)
     custom_color: Mapped[str | None] = mapped_column(String)
     path_style: Mapped[str | None] = mapped_column(String)
+    animated: Mapped[str] = mapped_column(String, nullable=False, default='none')
     source_handle: Mapped[str | None] = mapped_column(String)
     target_handle: Mapped[str | None] = mapped_column(String)
+    waypoints: Mapped[list[dict[str, float]] | None] = mapped_column(JSON, nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
 
@@ -68,6 +79,7 @@ class CanvasState(Base):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)
     viewport: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
+    custom_style: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     saved_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
 
@@ -75,13 +87,39 @@ class PendingDevice(Base):
     __tablename__ = "pending_devices"
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
-    ip: Mapped[str] = mapped_column(String, nullable=False)
+    ip: Mapped[str | None] = mapped_column(String, nullable=True)
     mac: Mapped[str | None] = mapped_column(String)
     hostname: Mapped[str | None] = mapped_column(String)
     os: Mapped[str | None] = mapped_column(String)
     services: Mapped[list[Any]] = mapped_column(JSON, default=list)
     suggested_type: Mapped[str | None] = mapped_column(String)
     status: Mapped[str] = mapped_column(String, default="pending")
+    discovery_source: Mapped[str | None] = mapped_column(String)
+    ieee_address: Mapped[str | None] = mapped_column(String, index=True, nullable=True, unique=True)
+    friendly_name: Mapped[str | None] = mapped_column(String, nullable=True)
+    device_subtype: Mapped[str | None] = mapped_column(String, nullable=True)
+    model: Mapped[str | None] = mapped_column(String, nullable=True)
+    vendor: Mapped[str | None] = mapped_column(String, nullable=True)
+    lqi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    discovered_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+
+
+class PendingDeviceLink(Base):
+    """Link between two Zigbee endpoints discovered during import.
+
+    Endpoints are addressed by IEEE (stable across re-imports). Either side may
+    already exist as a canvas Node (resolved via Node.ieee_address) or still be
+    a PendingDevice. On approval, the matching Edge is auto-created when both
+    endpoints exist as canvas Nodes.
+    """
+
+    __tablename__ = "pending_device_links"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
+    source_ieee: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    target_ieee: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    lqi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    discovery_source: Mapped[str] = mapped_column(String, nullable=False, default="zigbee")
     discovered_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
 
@@ -90,6 +128,7 @@ class ScanRun(Base):
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     status: Mapped[str] = mapped_column(String, default="running")
+    kind: Mapped[str] = mapped_column(String, default="ip", server_default="ip")
     ranges: Mapped[list[str]] = mapped_column(JSON, default=list)
     devices_found: Mapped[int] = mapped_column(Integer, default=0)
     started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)

backend/app/main.py

@@ -1,3 +1,5 @@
+import logging
+import logging.config
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from typing import Any
@@ -5,7 +7,8 @@ from typing import Any
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
-from app.api.routes import auth, canvas, edges, nodes, scan, status
+from app.api.routes import auth, canvas, edges, liveview, nodes, scan, status, zigbee
+from app.api.routes import settings as settings_routes
 from app.core.config import settings
 from app.core.scheduler import start_scheduler, stop_scheduler
 from app.db.database import init_db
@@ -13,6 +16,16 @@ from app.db.database import init_db
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    # Ensure app logs are visible: attach a handler to the root logger if none
+    # exists (uvicorn only installs handlers on its own loggers, not the root).
+    root_logger = logging.getLogger()
+    if not root_logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s:%(name)s:%(message)s"))
+        root_logger.addHandler(handler)
+    root_logger.setLevel(logging.INFO)
+    logging.getLogger("app").setLevel(logging.INFO)
+    logging.getLogger("app.services.scanner").setLevel(logging.INFO)
     await init_db()
     settings.load_overrides()
     start_scheduler()
@@ -22,7 +35,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 
 app = FastAPI(
     title="Homelable API",
-    version="1.0.0",
+    version="1.9.0",
     lifespan=lifespan,
 )
 
@@ -30,8 +43,8 @@ app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.cors_origins,
     allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
+    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+    allow_headers=["Authorization", "Content-Type"],
 )
 
 app.include_router(auth.router, prefix="/api/v1/auth", tags=["auth"])
@@ -40,6 +53,9 @@ app.include_router(edges.router, prefix="/api/v1/edges", tags=["edges"])
 app.include_router(canvas.router, prefix="/api/v1/canvas", tags=["canvas"])
 app.include_router(scan.router, prefix="/api/v1/scan", tags=["scan"])
 app.include_router(status.router, prefix="/api/v1/status", tags=["status"])
+app.include_router(settings_routes.router, prefix="/api/v1/settings", tags=["settings"])
+app.include_router(liveview.router, prefix="/api/v1/liveview", tags=["liveview"])
+app.include_router(zigbee.router, prefix="/api/v1/zigbee", tags=["zigbee"])
 
 
 @app.get("/api/v1/health")

backend/app/schemas/canvas.py

@@ -1,9 +1,10 @@
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from app.schemas.edges import EdgeResponse
 from app.schemas.nodes import NodeResponse
+from app.schemas.utils import normalize_animated
 
 
 class NodeSave(BaseModel):
@@ -23,6 +24,15 @@ class NodeSave(BaseModel):
     container_mode: bool = False
     custom_colors: dict[str, Any] | None = None
     custom_icon: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool = False
+    properties: list[Any] = []
+    width: float | None = None
+    height: float | None = None
+    bottom_handles: int = 1
     pos_x: float = 0
     pos_y: float = 0
 
@@ -37,17 +47,26 @@ class EdgeSave(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    animated: str = 'none'
     source_handle: str | None = None
     target_handle: str | None = None
+    waypoints: list[dict[str, float]] | None = None
+
+    @field_validator('animated', mode='before')
+    @classmethod
+    def validate_animated(cls, v: object) -> str:
+        return normalize_animated(v)
 
 
 class CanvasSaveRequest(BaseModel):
     nodes: list[NodeSave] = []
     edges: list[EdgeSave] = []
     viewport: dict[str, Any] = {}
+    custom_style: dict[str, Any] | None = None
 
 
 class CanvasStateResponse(BaseModel):
     nodes: list[NodeResponse]
     edges: list[EdgeResponse]
     viewport: dict[str, Any]
+    custom_style: dict[str, Any] | None = None

backend/app/schemas/edges.py

@@ -1,6 +1,8 @@
 from datetime import datetime
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
+
+from app.schemas.utils import normalize_animated
 
 
 class EdgeBase(BaseModel):
@@ -12,8 +14,15 @@ class EdgeBase(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    animated: str = 'none'
     source_handle: str | None = None
     target_handle: str | None = None
+    waypoints: list[dict[str, float]] | None = None
+
+    @field_validator('animated', mode='before')
+    @classmethod
+    def validate_animated(cls, v: object) -> str:
+        return normalize_animated(v)
 
 
 class EdgeCreate(EdgeBase):
@@ -27,8 +36,17 @@ class EdgeUpdate(BaseModel):
     speed: str | None = None
     custom_color: str | None = None
     path_style: str | None = None
+    animated: str | None = None
     source_handle: str | None = None
     target_handle: str | None = None
+    waypoints: list[dict[str, float]] | None = None
+
+    @field_validator('animated', mode='before')
+    @classmethod
+    def validate_animated(cls, v: object) -> str | None:
+        if v is None:
+            return None
+        return normalize_animated(v)
 
 
 class EdgeResponse(EdgeBase):

backend/app/schemas/nodes.py

@@ -22,6 +22,15 @@ class NodeBase(BaseModel):
     container_mode: bool = False
     custom_colors: dict[str, Any] | None = None
     custom_icon: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool = False
+    properties: list[dict[str, Any]] = []
+    width: float | None = None
+    height: float | None = None
+    bottom_handles: int = 1
 
 
 class NodeCreate(NodeBase):
@@ -42,9 +51,19 @@ class NodeUpdate(BaseModel):
     notes: str | None = None
     pos_x: float | None = None
     pos_y: float | None = None
+    parent_id: str | None = None
     container_mode: bool | None = None
     custom_colors: dict[str, Any] | None = None
     custom_icon: str | None = None
+    cpu_count: int | None = None
+    cpu_model: str | None = None
+    ram_gb: float | None = None
+    disk_gb: float | None = None
+    show_hardware: bool | None = None
+    properties: list[dict[str, Any]] | None = None
+    width: float | None = None
+    height: float | None = None
+    bottom_handles: int | None = None
 
 
 class NodeResponse(NodeBase):

backend/app/schemas/scan.py

@@ -6,13 +6,20 @@ from pydantic import BaseModel
 
 class PendingDeviceResponse(BaseModel):
     id: str
-    ip: str
+    ip: str | None
     mac: str | None
     hostname: str | None
     os: str | None
     services: list[Any]
     suggested_type: str | None
     status: str
+    discovery_source: str | None
+    ieee_address: str | None = None
+    friendly_name: str | None = None
+    device_subtype: str | None = None
+    model: str | None = None
+    vendor: str | None = None
+    lqi: int | None = None
     discovered_at: datetime
 
     model_config = {"from_attributes": True}
@@ -21,6 +28,7 @@ class PendingDeviceResponse(BaseModel):
 class ScanRunResponse(BaseModel):
     id: str
     status: str
+    kind: str = "ip"
     ranges: list[str]
     devices_found: int
     started_at: datetime

backend/app/schemas/utils.py

@@ -0,0 +1,9 @@
+def normalize_animated(v: object) -> str:
+    """Normalize legacy bool/int animated values to string mode ('none'/'snake'/'flow')."""
+    if v is True or v == 1 or v == '1':
+        return 'snake'
+    if v is False or v == 0 or v == '0' or v is None or v == 'none':
+        return 'none'
+    if v in ('snake', 'flow', 'basic'):
+        return str(v)
+    return 'none'

backend/app/schemas/zigbee.py

@@ -0,0 +1,95 @@
+"""Pydantic v2 schemas for Zigbee2MQTT import."""
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class ZigbeeImportRequest(BaseModel):
+    mqtt_host: str = Field(..., description="MQTT broker hostname or IP address")
+    mqtt_port: int = Field(1883, ge=1, le=65535, description="MQTT broker port")
+    mqtt_username: str | None = Field(None, description="MQTT username (optional)")
+    mqtt_password: str | None = Field(None, description="MQTT password (optional)")
+    base_topic: str = Field("zigbee2mqtt", description="Zigbee2MQTT base topic")
+    mqtt_tls: bool = Field(False, description="Enable TLS (typically port 8883)")
+    mqtt_tls_insecure: bool = Field(
+        False, description="Skip TLS certificate verification (self-signed only)"
+    )
+
+    @model_validator(mode="after")
+    def _insecure_requires_tls(self) -> "ZigbeeImportRequest":
+        if self.mqtt_tls_insecure and not self.mqtt_tls:
+            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
+        return self
+
+
+class ZigbeeTestConnectionRequest(BaseModel):
+    mqtt_host: str
+    mqtt_port: int = Field(1883, ge=1, le=65535)
+    mqtt_username: str | None = None
+    mqtt_password: str | None = None
+    mqtt_tls: bool = False
+    mqtt_tls_insecure: bool = False
+
+    @model_validator(mode="after")
+    def _insecure_requires_tls(self) -> "ZigbeeTestConnectionRequest":
+        if self.mqtt_tls_insecure and not self.mqtt_tls:
+            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
+        return self
+
+
+class ZigbeeDeviceData(BaseModel):
+    ieee_address: str
+    friendly_name: str
+    device_type: str  # Coordinator, Router, EndDevice
+    model: str | None = None
+    vendor: str | None = None
+    description: str | None = None
+    lqi: int | None = None
+    last_seen: str | None = None
+
+
+class ZigbeeNodeOut(BaseModel):
+    """A homelable-ready node representation of a Zigbee device."""
+
+    id: str
+    label: str
+    type: str  # zigbee_coordinator | zigbee_router | zigbee_enddevice
+    ieee_address: str
+    friendly_name: str
+    device_type: str
+    model: str | None = None
+    vendor: str | None = None
+    lqi: int | None = None
+    parent_id: str | None = None
+
+
+class ZigbeeEdgeOut(BaseModel):
+    source: str
+    target: str
+
+
+class ZigbeeImportResponse(BaseModel):
+    nodes: list[ZigbeeNodeOut]
+    edges: list[ZigbeeEdgeOut]
+    device_count: int
+
+
+class ZigbeeTestConnectionResponse(BaseModel):
+    connected: bool
+    message: str
+
+
+class ZigbeeCoordinatorOut(BaseModel):
+    id: str
+    label: str
+    ieee_address: str
+
+
+class ZigbeeImportPendingResponse(BaseModel):
+    """Result of importing a Z2M network into the pending section."""
+
+    pending_created: int
+    pending_updated: int
+    coordinator: ZigbeeCoordinatorOut | None = None
+    coordinator_already_existed: bool = False
+    links_recorded: int
+    device_count: int

backend/app/services/fingerprint.py

@@ -1,18 +1,28 @@
 """Match nmap scan results against service_signatures.json."""
 import json
 import re
+import threading
 from pathlib import Path
 from typing import Any
 
 _SIGNATURES: list[dict[str, Any]] | None = None
+_LOCK = threading.Lock()
 
 
 def _load() -> list[dict[str, Any]]:
     global _SIGNATURES
     if _SIGNATURES is None:
-        path = Path(__file__).parent.parent.parent / "data" / "service_signatures.json"
-        with open(path) as f:
-            _SIGNATURES = json.load(f)
+        with _LOCK:
+            if _SIGNATURES is None:
+                path = Path(__file__).parent.parent / "data" / "service_signatures.json"
+                try:
+                    with open(path) as f:
+                        _SIGNATURES = json.load(f)
+                except FileNotFoundError as err:
+                    raise FileNotFoundError(
+                        f"service_signatures.json not found at {path}. "
+                        "This file should be bundled with the application."
+                    ) from err
     return _SIGNATURES
 
 
@@ -55,14 +65,46 @@ def fingerprint_ports(open_ports: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return results
 
 
-# Known OUI prefixes for virtual machines / hypervisors (lowercase, colon-separated)
+# Known OUI prefixes — lowercase, colon-separated, first 3 octets
 _MAC_OUI_TYPES: dict[str, str] = {
-    "52:54:00": "vm",    # QEMU/KVM (used by Proxmox VMs)
-    "bc:24:11": "vm",    # Proxmox official OUI (VMs and LXC, Proxmox 7.3+)
+    # Hypervisors / VMs
+    "52:54:00": "vm",    # QEMU/KVM (Proxmox VMs)
+    "bc:24:11": "vm",    # Proxmox official OUI (VMs and LXC, 7.3+)
     "00:50:56": "vm",    # VMware
     "00:0c:29": "vm",    # VMware Workstation / Fusion
     "08:00:27": "vm",    # VirtualBox
     "00:15:5d": "vm",    # Hyper-V
+    # Shelly
+    "34:94:54": "iot",
+    "84:f3:eb": "iot",
+    "ec:fa:bc": "iot",
+    "30:c6:f7": "iot",
+    # Espressif (ESP8266 / ESP32 — used by Sonoff, many DIY IoT)
+    "a0:20:a6": "iot",
+    "24:62:ab": "iot",
+    "30:ae:a4": "iot",
+    "cc:50:e3": "iot",
+    "ac:67:b2": "iot",
+    "b4:e6:2d": "iot",
+    "3c:71:bf": "iot",
+    "8c:aa:b5": "iot",
+    # Sonoff / ITEAD
+    "dc:4f:22": "iot",
+    "e8:db:84": "iot",
+    # Tapo / TP-Link smart home
+    "b0:a7:b9": "iot",
+    "50:c7:bf": "iot",
+    "1c:3b:f3": "iot",
+    "10:27:f5": "iot",
+    # Philips Hue
+    "00:17:88": "iot",
+    "ec:b5:fa": "iot",
+    # IKEA Tradfri
+    "34:13:e8": "iot",
+    "00:21:2e": "iot",
+    # Tuya / Smart Life (widely used chip in many brands)
+    "d8:f1:5b": "iot",
+    "68:57:2d": "iot",
 }
 
 
@@ -91,10 +133,13 @@ _PORT_TYPE_HINTS: dict[int, str] = {
     37777: "camera",   # Dahua
     34567: "camera",   # Amcrest
     2020: "camera",    # Tapo
-    # Smart-home / MQTT → iot
+    # Smart-home / MQTT / CoAP → iot
     1883: "iot",
     8883: "iot",
-    6052: "iot",    # ESPHome
+    6052: "iot",    # ESPHome dashboard
+    4915: "iot",    # Shelly CoIoT
+    5683: "iot",    # CoAP (Shelly Gen1, many IoT devices)
+    5684: "iot",    # CoAP DTLS
     # AP / wireless
     8880: "ap",     # UniFi HTTP
     8443: "ap",     # UniFi HTTPS
@@ -105,8 +150,13 @@ _PORT_TYPE_HINTS: dict[int, str] = {
 
 
 def suggest_node_type(open_ports: list[dict[str, Any]], mac: str | None = None) -> str:
-    """Suggest a node type based on matched signatures and MAC OUI."""
-    priority = ["proxmox", "nas", "router", "lxc", "vm", "server", "ap", "camera", "iot", "switch"]
+    """Suggest a node type based on matched signatures, port hints, and MAC OUI."""
+    # IoT vendor MACs are a strong, unambiguous signal — don't let generic HTTP ports override
+    mac_type = suggest_type_from_mac(mac)
+    if mac_type == "iot":
+        return "iot"
+
+    priority = ["proxmox", "nas", "router", "lxc", "vm", "ap", "camera", "iot", "server", "switch"]
     found: set[str] = set()
     for p in open_ports:
         port = p["port"]
@@ -116,10 +166,10 @@ def suggest_node_type(open_ports: list[dict[str, Any]], mac: str | None = None)
             found.add(sig["suggested_node_type"])
         if port in _PORT_TYPE_HINTS:
             found.add(_PORT_TYPE_HINTS[port])
-    # MAC OUI is a lower-priority hint — only used if ports give no better answer
-    mac_type = suggest_type_from_mac(mac)
+
     if mac_type:
         found.add(mac_type)
+
     for t in priority:
         if t in found:
             return t

backend/app/services/scanner.py

@@ -1,17 +1,48 @@
-"""Network scanner: ARP sweep + nmap service detection."""
+"""Network scanner: ARP sweep + nmap service detection + mDNS discovery."""
 import asyncio
+import ipaddress
 import logging
+import os
+import re
 import socket
+import subprocess
+import threading
 from datetime import datetime, timezone
 from typing import Any
 
+from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import PendingDevice, ScanRun
+from app.db.models import Node, PendingDevice, ScanRun
 from app.services.fingerprint import fingerprint_ports, suggest_node_type
 
 logger = logging.getLogger(__name__)
 
+# Run IDs that have been requested to cancel (thread-safe via lock)
+_cancelled_runs: set[str] = set()
+_cancelled_lock = threading.Lock()
+
+# Port list for service detection (Phase 2)
+_EXTRA_PORTS = (
+    "80,443,22,21,23,25,53,110,143,161,162,179,389,445,548,"
+    "554,636,873,1883,1880,1935,2020,2375,2376,3000,3001,3306,"
+    "3389,4711,4915,5000,5001,5432,5601,5683,5684,5900,5984,"
+    "6052,6379,6432,6443,6767,6789,6800,7878,8000,8006,8080,"
+    "8081,8086,8088,8090,8096,8112,8123,8200,8291,8428,8443,"
+    "8554,8686,8789,8843,8880,8883,8971,8989,9000,9001,9090,"
+    "9091,9092,9093,9100,9117,9200,9300,9411,9443,9696,10051,"
+    "16686,34567,37777,51413,64738"
+)
+
+_MDNS_SERVICE_TYPES = [
+    "_http._tcp.local.",
+    "_shelly._tcp.local.",
+    "_esphomelib._tcp.local.",
+    "_hap._tcp.local.",        # HomeKit Accessory Protocol
+    "_mqtt._tcp.local.",
+    "_device-info._tcp.local.",
+]
+
 try:
     import nmap
     _NMAP_AVAILABLE = True
@@ -19,50 +50,24 @@ except ImportError:
     _NMAP_AVAILABLE = False
     logger.warning("python-nmap not available — scanner will run in mock mode")
 
+try:
+    from zeroconf import ServiceStateChange
+    from zeroconf.asyncio import AsyncServiceBrowser, AsyncServiceInfo, AsyncZeroconf
+    _ZEROCONF_AVAILABLE = True
+except ImportError:
+    _ZEROCONF_AVAILABLE = False
+    logger.warning("zeroconf not available — mDNS discovery disabled")
 
-def _nmap_scan(target: str) -> list[dict[str, Any]]:
-    """Run nmap -sV --open on target, return list of host dicts."""
-    if not _NMAP_AVAILABLE:
-        return _mock_scan(target)
 
-    nm = nmap.PortScanner()
-    try:
-        # Home lab port range: standard top-1000 + common self-hosted service ports
-        extra_ports = (
-            "80,443,22,21,23,25,53,110,143,161,162,179,389,445,548,"
-            "554,636,873,1883,1880,1935,2020,2375,2376,3000,3001,3306,"
-            "3389,4711,5000,5001,5432,5601,5900,5984,6052,6379,6432,6443,"
-            "6767,6789,6800,7878,8000,8006,8080,8081,8086,8088,8090,8096,"
-            "8112,8123,8200,8291,8428,8443,8554,8686,8789,8843,8880,8883,"
-            "8971,8989,9000,9001,9090,9091,9092,9093,9100,9117,9200,9300,"
-            "9411,9443,9696,10051,16686,34567,37777,51413,64738"
-        )
-        nm.scan(hosts=target, arguments=f"-sV --open -T4 --host-timeout 120s -p {extra_ports}")
-    except Exception as exc:
-        logger.error("nmap scan failed: %s", exc)
-        raise RuntimeError(str(exc)) from exc
+def request_cancel(run_id: str) -> None:
+    """Signal a running scan to stop early."""
+    with _cancelled_lock:
+        _cancelled_runs.add(run_id)
 
-    hosts = []
-    for host in nm.all_hosts():
-        if nm[host].state() != "up":
-            continue
-        open_ports = []
-        for proto in nm[host].all_protocols():
-            for port, info in nm[host][proto].items():
-                if info["state"] == "open":
-                    open_ports.append({
-                        "port": port,
-                        "protocol": proto,
-                        "banner": info.get("product", "") + " " + info.get("version", ""),
-                    })
-        hosts.append({
-            "ip": host,
-            "hostname": _resolve_hostname(host),
-            "mac": nm[host].get("addresses", {}).get("mac"),
-            "os": _extract_os(nm, host),
-            "open_ports": open_ports,
-        })
-    return hosts
+
+def _is_cancelled(run_id: str) -> bool:
+    with _cancelled_lock:
+        return run_id in _cancelled_runs
 
 
 def _resolve_hostname(ip: str) -> str | None:
@@ -82,6 +87,278 @@ def _extract_os(nm: object, host: str) -> str | None:
     return None
 
 
+def _arp_table_hosts(network: str) -> dict[str, dict[str, Any]]:
+    """
+    Read the OS ARP cache for recently-seen hosts in the target network.
+    Works without root on both Linux (/proc/net/arp) and macOS (arp -a).
+    Supplements nmap discovery — catches IoT and devices with all ports filtered.
+    """
+    try:
+        net = ipaddress.ip_network(network, strict=False)
+        found: dict[str, dict[str, Any]] = {}
+
+        # Linux: parse /proc/net/arp — present on any Linux kernel (including Docker)
+        proc_arp = "/proc/net/arp"
+        try:
+            with open(proc_arp) as f:
+                for line in f.readlines()[1:]:  # skip header row
+                    parts = line.split()
+                    if len(parts) >= 4:
+                        ip, mac = parts[0], parts[3]
+                        if mac == "00:00:00:00:00:00":
+                            continue
+                        try:
+                            if ipaddress.ip_address(ip) in net:
+                                found[ip] = {
+                                    "ip": ip, "mac": mac,
+                                    "hostname": _resolve_hostname(ip),
+                                    "os": None, "open_ports": [],
+                                }
+                        except ValueError:
+                            pass
+            # /proc/net/arp opened successfully — return whatever we found (may be empty)
+            # Don't fall through to `arp -a` since we're on Linux
+            return found
+        except FileNotFoundError:
+            pass  # Not Linux — fall through to macOS `arp -a`
+
+        # macOS: parse `arp -a` output
+        result = subprocess.run(["arp", "-a"], capture_output=True, text=True, timeout=5)
+        for line in result.stdout.splitlines():
+            m = re.search(r"\((\d+\.\d+\.\d+\.\d+)\)\s+at\s+([0-9a-f:]+)", line)
+            if not m:
+                continue
+            ip, mac = m.group(1), m.group(2)
+            if mac in ("(incomplete)", "ff:ff:ff:ff:ff:ff"):
+                continue
+            try:
+                if ipaddress.ip_address(ip) in net:
+                    found[ip] = {"ip": ip, "mac": mac, "hostname": _resolve_hostname(ip), "os": None, "open_ports": []}
+            except ValueError:
+                pass
+        return found
+    except Exception as exc:
+        logger.warning("[Phase 1] ARP cache lookup failed: %s", exc)
+        return {}
+
+
+async def _ping_sweep(target: str) -> dict[str, dict[str, Any]]:
+    """
+    Phase 1: Concurrent ICMP ping sweep + ARP cache.
+    Pings all IPs in the CIDR in parallel (up to 50 at once, 1s timeout each).
+    Supplements with the OS ARP cache to catch devices that block ICMP.
+    Works in Docker with CAP_NET_RAW — no nmap, no false positives.
+    """
+    net = ipaddress.ip_network(target, strict=False)
+    all_ips = [str(ip) for ip in net.hosts()]
+    logger.info("[Phase 1] Pinging %d hosts in %s ...", len(all_ips), target)
+
+    sem = asyncio.Semaphore(50)
+
+    async def _ping(ip: str) -> str | None:
+        async with sem:
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    "ping", "-c", "1", "-W", "1", ip,
+                    stdout=asyncio.subprocess.DEVNULL,
+                    stderr=asyncio.subprocess.DEVNULL,
+                )
+                await proc.wait()
+                return ip if proc.returncode == 0 else None
+            except Exception:
+                return None
+
+    ping_results = await asyncio.gather(*[_ping(ip) for ip in all_ips])
+    alive_ips: set[str] = {ip for ip in ping_results if ip is not None}
+    logger.info("[Phase 1] %d/%d hosts responded to ping", len(alive_ips), len(all_ips))
+
+    # ARP cache: catch devices that block ICMP but were recently active,
+    # and enrich ping-alive hosts with their MAC addresses.
+    arp_cache = await asyncio.to_thread(_arp_table_hosts, target)
+
+    alive: dict[str, dict[str, Any]] = {}
+
+    for ip in alive_ips:
+        mac = arp_cache.get(ip, {}).get("mac")
+        hostname = await asyncio.to_thread(_resolve_hostname, ip)
+        logger.info("[Phase 1] %s  mac=%s  hostname=%s  (ping)", ip, mac or "n/a", hostname or "n/a")
+        alive[ip] = {"ip": ip, "mac": mac, "hostname": hostname, "os": None, "open_ports": []}
+
+    for ip, host in arp_cache.items():
+        if ip not in alive:
+            logger.info(
+                "[Phase 1] %s  mac=%s  hostname=%s  (ARP cache only)",
+                ip, host.get("mac") or "n/a", host.get("hostname") or "n/a",
+            )
+            alive[ip] = host
+
+    return alive
+
+
+def _nmap_scan_single(host_dict: dict[str, Any]) -> dict[str, Any]:
+    """
+    Phase 2 — single-IP port scan with service detection.
+    Runs in a thread (blocking). Returns the host dict enriched with open_ports.
+    """
+    ip = host_dict["ip"]
+    logger.info("[Phase 2] Scanning %s ...", ip)
+
+    if not _NMAP_AVAILABLE:
+        logger.warning("[Phase 2] nmap not available, skipping %s", ip)
+        return host_dict
+
+    is_root = os.geteuid() == 0
+    if is_root:
+        # SYN scan + version detection (fastest, most accurate)
+        scan_args = f"-sS -sV --open -T4 -Pn --host-timeout 60s -p {_EXTRA_PORTS}"
+    else:
+        # TCP connect scan (-sT) — no raw sockets needed, works without root.
+        # nmap auto-selects -sT without root but being explicit avoids edge cases.
+        scan_args = f"-sT -sV --open -T4 -Pn --host-timeout 60s -p {_EXTRA_PORTS}"
+
+    logger.debug("[Phase 2] %s args: %s", ip, scan_args)
+    nm = nmap.PortScanner()
+    try:
+        nm.scan(hosts=ip, arguments=scan_args)
+    except Exception as exc:
+        logger.warning("[Phase 2] nmap FAILED for %s (%s: %s) — skipping port scan", ip, type(exc).__name__, exc)
+        return host_dict
+
+    all_scanned = nm.all_hosts()
+    logger.debug("[Phase 2] %s — nmap returned %d host(s) in results", ip, len(all_scanned))
+    if ip not in all_scanned:
+        logger.info("[Phase 2] %s — no open ports found (all closed/filtered or nmap had no results)", ip)
+        return host_dict
+
+    open_ports = []
+    for proto in nm[ip].all_protocols():
+        for port, info in nm[ip][proto].items():
+            if info["state"] == "open":
+                banner = (info.get("product", "") + " " + info.get("version", "")).strip()
+                open_ports.append({"port": port, "protocol": proto, "banner": banner})
+
+    if open_ports:
+        port_summary = ", ".join(
+            f"{p['port']}/{p['protocol']} ({p['banner'] or 'unknown'})" for p in open_ports
+        )
+        logger.info("[Phase 2] %s — %d open port(s): %s", ip, len(open_ports), port_summary)
+    else:
+        logger.info("[Phase 2] %s — 0 open ports detected", ip)
+
+    host_dict["open_ports"] = open_ports
+    if not host_dict["mac"]:
+        host_dict["mac"] = nm[ip].get("addresses", {}).get("mac")
+    host_dict["os"] = _extract_os(nm, ip)
+    return host_dict
+
+
+async def _nmap_port_scan(alive: dict[str, dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Phase 2: Per-IP service detection with bounded concurrency.
+    Each host is scanned independently in a thread — no inter-host timeout interference.
+    Up to 10 hosts scanned concurrently.
+    """
+    if not alive:
+        return []
+
+    logger.info("[Phase 2] Starting per-IP port scan for %d host(s)", len(alive))
+    semaphore = asyncio.Semaphore(10)
+
+    async def _scan_with_sem(host_dict: dict[str, Any]) -> dict[str, Any]:
+        async with semaphore:
+            return await asyncio.to_thread(_nmap_scan_single, host_dict)
+
+    raw = await asyncio.gather(*[_scan_with_sem(h) for h in alive.values()], return_exceptions=True)
+    results = []
+    for item in raw:
+        if isinstance(item, BaseException):
+            logger.warning("[Phase 2] Unexpected error in gather: %s", item)
+        else:
+            results.append(item)
+    logger.info("[Phase 2] Completed — %d/%d host(s) scanned", len(results), len(alive))
+    return results
+
+
+async def _nmap_scan(target: str) -> list[dict[str, Any]]:
+    """
+    Two-phase scan for a CIDR range.
+    Phase 1: Concurrent ping sweep to find alive hosts (fast, no false positives).
+    Phase 2: Per-IP nmap port scan with service detection (bounded concurrency, 10 at a time).
+    """
+    logger.info("[Scan] Starting scan for %s — nmap available: %s", target, _NMAP_AVAILABLE)
+    if not _NMAP_AVAILABLE:
+        logger.warning("[Scan] nmap not available — returning mock data")
+        return _mock_scan(target)
+    try:
+        alive = await _ping_sweep(target)
+        logger.info("[Phase 1] Found %d alive host(s) in %s: %s",
+                    len(alive), target, ", ".join(sorted(alive.keys())))
+    except Exception as exc:
+        logger.error("Phase 1 ping sweep failed: %s", exc)
+        raise RuntimeError(str(exc)) from exc
+    return await _nmap_port_scan(alive)
+
+
+async def _mdns_discover(timeout: float = 4.0) -> list[dict[str, Any]]:
+    """
+    Passive mDNS/Bonjour sweep.
+    Returns devices advertising on _shelly._tcp, _esphomelib._tcp, _hap._tcp, etc.
+    Runs for `timeout` seconds then returns what it found.
+    """
+    if not _ZEROCONF_AVAILABLE:
+        return []
+
+    import ipaddress
+
+    found_services: list[tuple[str, str]] = []
+
+    def _on_change(
+        zeroconf: Any,
+        service_type: str,
+        name: str,
+        state_change: Any,
+    ) -> None:
+        if state_change == ServiceStateChange.Added:
+            found_services.append((service_type, name))
+
+    discovered: dict[str, dict[str, Any]] = {}
+
+    try:
+        async with AsyncZeroconf() as azc:
+            browser = AsyncServiceBrowser(
+                azc.zeroconf, _MDNS_SERVICE_TYPES, handlers=[_on_change]
+            )
+            await asyncio.sleep(timeout)
+            await browser.async_cancel()
+
+            for service_type, name in found_services:
+                try:
+                    info = AsyncServiceInfo(service_type, name)
+                    await info.async_request(azc.zeroconf, 3000)
+                    if not info.addresses:
+                        continue
+                    ip = str(ipaddress.IPv4Address(info.addresses[0]))
+                    if ip in discovered:
+                        continue
+                    discovered[ip] = {
+                        "ip": ip,
+                        "hostname": info.server,
+                        "mac": None,
+                        "os": None,
+                        "open_ports": (
+                            [{"port": info.port, "protocol": "tcp", "banner": ""}]
+                            if info.port else []
+                        ),
+                    }
+                except Exception as exc:
+                    logger.debug("mDNS resolution failed for %s: %s", name, exc)
+    except Exception as exc:
+        logger.warning("mDNS discovery error: %s", exc)
+
+    logger.info("mDNS discovery found %d device(s)", len(discovered))
+    return list(discovered.values())
+
+
 def _mock_scan(target: str) -> list[dict[str, Any]]:
     """Return fake results for dev/test environments without nmap."""
     return [
@@ -100,73 +377,136 @@ def _mock_scan(target: str) -> list[dict[str, Any]]:
 
 async def run_scan(ranges: list[str], db: AsyncSession, run_id: str) -> None:
     """Execute scan for given CIDR ranges and populate pending_devices."""
-    # Avoid circular import
-    from sqlalchemy import select
-
     from app.api.routes.status import broadcast_scan_update
 
     devices_found = 0
+    mdns_task: asyncio.Task[list[dict[str, Any]]] | None = None
     try:
-        for cidr in ranges:
-            # Run nmap in a thread pool — does not block the event loop
-            hosts = await asyncio.to_thread(_nmap_scan, cidr)
+        # Validate all ranges are valid CIDRs before passing anything to nmap
+        for r in ranges:
+            try:
+                ipaddress.ip_network(r, strict=False)
+            except ValueError:
+                raise ValueError(f"Invalid CIDR range: {r!r}") from None
 
-            for host in hosts:
-                services = fingerprint_ports(host["open_ports"])
-                suggested_type = suggest_node_type(host["open_ports"], host.get("mac"))
+        # Pre-fetch canvas IPs and hidden IPs once — avoids N+1 queries per host
+        canvas_ips_result = await db.execute(select(Node.ip).where(Node.ip.isnot(None)))
+        canvas_ips: set[str] = {row[0] for row in canvas_ips_result.fetchall()}
 
-                # Update existing pending device or create a new one
-                existing_result = await db.execute(
-                    select(PendingDevice).where(
-                        PendingDevice.ip == host["ip"],
-                        PendingDevice.status == "pending",
-                    )
+        hidden_ips_result = await db.execute(
+            select(PendingDevice.ip).where(PendingDevice.status == "hidden")
+        )
+        hidden_ips: set[str] = {row[0] for row in hidden_ips_result.fetchall()}
+
+        # Clean up stale pending devices whose IPs are already in the canvas
+        if canvas_ips:
+            from sqlalchemy import delete as sa_delete
+            await db.execute(
+                sa_delete(PendingDevice).where(
+                    PendingDevice.status == "pending",
+                    PendingDevice.ip.in_(canvas_ips),
                 )
-                existing = existing_result.scalar_one_or_none()
-                if existing:
-                    existing.mac = host.get("mac") or existing.mac
-                    existing.hostname = host.get("hostname") or existing.hostname
-                    existing.os = host.get("os") or existing.os
-                    existing.services = services
-                    existing.suggested_type = suggested_type
-                else:
-                    device = PendingDevice(
-                        ip=host["ip"],
-                        mac=host.get("mac"),
-                        hostname=host.get("hostname"),
-                        os=host.get("os"),
-                        services=services,
-                        suggested_type=suggested_type,
-                        status="pending",
-                    )
-                    db.add(device)
-                    devices_found += 1
+            )
+            await db.commit()
 
-                # Commit immediately so the device is visible right away
-                await db.commit()
+        # Start mDNS discovery in the background while nmap scans run
+        mdns_task = asyncio.create_task(_mdns_discover())
 
-                # Update running count on the scan run record
-                run = await db.get(ScanRun, run_id)
-                if run:
-                    run.devices_found = devices_found
-                    await db.commit()
+        # Track IPs found by nmap so mDNS doesn't duplicate them
+        nmap_ips: set[str] = set()
 
-                # Push WS event so the frontend refreshes pending panel
-                await broadcast_scan_update(run_id=run_id, devices_found=devices_found)
+        async def _process_host(host: dict[str, Any], discovery_source: str = "arp") -> None:
+            nonlocal devices_found
+            ip = host["ip"]
 
-        # Mark scan as done
+            # Skip canvas nodes and user-hidden devices (sets pre-fetched before loop)
+            if ip in canvas_ips:
+                logger.debug("Skipping %s — already in canvas", ip)
+                return
+            if ip in hidden_ips:
+                logger.debug("Skipping %s — hidden by user", ip)
+                return
+
+            services = fingerprint_ports(host["open_ports"])
+            suggested_type = suggest_node_type(host["open_ports"], host.get("mac"))
+
+            existing_result = await db.execute(
+                select(PendingDevice).where(
+                    PendingDevice.ip == ip,
+                    PendingDevice.status == "pending",
+                )
+            )
+            existing = existing_result.scalar_one_or_none()
+            if existing:
+                existing.mac = host.get("mac") or existing.mac
+                existing.hostname = host.get("hostname") or existing.hostname
+                existing.os = host.get("os") or existing.os
+                existing.services = services
+                existing.suggested_type = suggested_type
+            else:
+                db.add(PendingDevice(
+                    ip=ip,
+                    mac=host.get("mac"),
+                    hostname=host.get("hostname"),
+                    os=host.get("os"),
+                    services=services,
+                    suggested_type=suggested_type,
+                    status="pending",
+                    discovery_source=discovery_source,
+                ))
+                devices_found += 1
+
+            await db.commit()
+            await broadcast_scan_update(run_id=run_id, devices_found=devices_found)
+
+        # nmap scan per CIDR — results stream in progressively
+        for cidr in ranges:
+            if _is_cancelled(run_id):
+                break
+            hosts = await _nmap_scan(cidr)
+            for host in hosts:
+                if _is_cancelled(run_id):
+                    break
+                nmap_ips.add(host["ip"])
+                await _process_host(host)
+
+        # Update ScanRun count once after all CIDR ranges
         run = await db.get(ScanRun, run_id)
         if run:
-            run.status = "done"
+            run.devices_found = devices_found
+            await db.commit()
+
+        # Collect mDNS results — task already has its own 4s internal timeout
+        if not _is_cancelled(run_id):
+            mdns_hosts = await mdns_task
+
+            for host in mdns_hosts:
+                if _is_cancelled(run_id):
+                    break
+                if host["ip"] in nmap_ips:
+                    continue  # already processed with richer nmap data
+                await _process_host(host, discovery_source="mdns")
+        else:
+            mdns_task.cancel()
+
+        # Mark scan as done or cancelled
+        run = await db.get(ScanRun, run_id)
+        if run:
+            run.status = "cancelled" if _is_cancelled(run_id) else "done"
             run.devices_found = devices_found
             run.finished_at = datetime.now(timezone.utc)
             await db.commit()
 
     except Exception as exc:
         logger.error("Scan failed: %s", exc)
+        if mdns_task is not None and not mdns_task.done():
+            mdns_task.cancel()
         run = await db.get(ScanRun, run_id)
         if run:
             run.status = "error"
             run.error = str(exc)
             run.finished_at = datetime.now(timezone.utc)
             await db.commit()
+    finally:
+        with _cancelled_lock:
+            _cancelled_runs.discard(run_id)

backend/app/services/status_checker.py

@@ -2,6 +2,7 @@
 import asyncio
 import logging
 import socket
+import sys
 import time
 from typing import Any
 
@@ -18,7 +19,9 @@ async def check_node(check_method: str, target: str | None, ip: str | None) -> d
     if check_method == "none":
         return {"status": "online", "response_time_ms": None}
 
-    host = target or ip
+    # Use only the first IP when the field contains comma-separated addresses
+    raw_ip = ip.split(",")[0].strip() if ip else None
+    host = target or raw_ip
     if not host:
         return {"status": "unknown", "response_time_ms": None}
 
@@ -57,8 +60,18 @@ async def check_node(check_method: str, target: str | None, ip: str | None) -> d
 
 
 async def _ping(host: str) -> bool:
+    # ping(8) -W flag units differ by OS:
+    #   Linux:   seconds        (-W 1   = 1s)
+    #   macOS:   milliseconds   (-W 1   = 1ms — fails for any RTT >1ms)
+    #   Windows: -w in ms       (-w 1000 = 1s)
+    if sys.platform == "win32":
+        args = ["ping", "-n", "1", "-w", "1000", host]
+    elif sys.platform == "darwin":
+        args = ["ping", "-c", "1", "-W", "1000", host]
+    else:
+        args = ["ping", "-c", "1", "-W", "1", host]
     proc = await asyncio.create_subprocess_exec(
-        "ping", "-c", "1", "-W", "1", host,
+        *args,
         stdout=asyncio.subprocess.DEVNULL,
         stderr=asyncio.subprocess.DEVNULL,
     )

backend/app/services/zigbee_service.py

@@ -0,0 +1,326 @@
+"""Zigbee2MQTT service: connects to MQTT broker and fetches the network map."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import ssl
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+try:
+    import aiomqtt
+except ImportError:  # pragma: no cover
+    aiomqtt = None  # type: ignore[assignment]
+
+_NETWORKMAP_REQUEST_TOPIC = "{base_topic}/bridge/request/networkmap"
+_NETWORKMAP_RESPONSE_TOPIC = "{base_topic}/bridge/response/networkmap"
+_CONNECTION_TIMEOUT = 5.0   # seconds to verify broker reachability
+_NETWORKMAP_TIMEOUT = 300.0  # seconds to wait for the networkmap response (large meshes can be slow)
+
+
+def _sanitize_mqtt_error(exc: BaseException) -> str:
+    """Return a generic, credential-free message for an MQTT error.
+
+    The raw aiomqtt/paho error string can include the broker URI with
+    embedded credentials (e.g. ``mqtt://user:pass@host``) or auth-related
+    detail that should not leak to API clients. Map known patterns to
+    coarse categories; default to a generic failure message. The original
+    exception is logged at WARNING level for operator debugging.
+    """
+    logger.warning("MQTT error (sanitized for client): %r", exc)
+    raw = str(exc).lower()
+    if "not authoriz" in raw or "bad user" in raw or "bad username" in raw:
+        return "Authentication failed"
+    if "refused" in raw:
+        return "Connection refused by broker"
+    if "name or service not known" in raw or "getaddrinfo" in raw or "nodename nor servname" in raw:
+        return "Broker hostname could not be resolved"
+    if "ssl" in raw or "tls" in raw or "certificate" in raw:
+        return "TLS handshake failed"
+    if "timed out" in raw or "timeout" in raw:
+        return "Connection to broker timed out"
+    return "MQTT connection failed"
+
+
+def _build_tls_context(insecure: bool) -> ssl.SSLContext:
+    """Build an SSL context for MQTT TLS. If insecure, skip verification."""
+    ctx = ssl.create_default_context()
+    if insecure:
+        logger.warning(
+            "MQTT TLS certificate verification is DISABLED — "
+            "use only with self-signed brokers on trusted networks."
+        )
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+def _z2m_type_to_homelable(device_type: str) -> str:
+    """Map a Z2M device type string to a homelable node type."""
+    mapping = {
+        "Coordinator": "zigbee_coordinator",
+        "Router": "zigbee_router",
+        "EndDevice": "zigbee_enddevice",
+    }
+    return mapping.get(device_type, "zigbee_enddevice")
+
+
+def _node_from_z2m(raw: dict[str, Any]) -> dict[str, Any] | None:
+    """Build a homelable node dict from a Z2M raw networkmap node entry."""
+    ieee: str = raw.get("ieeeAddr") or raw.get("ieee_address") or ""
+    if not ieee:
+        return None
+    device_type: str = raw.get("type") or "EndDevice"
+    friendly_name: str = (
+        raw.get("friendlyName") or raw.get("friendly_name") or ieee
+    )
+    definition: dict[str, Any] = raw.get("definition") or {}
+    model: str | None = (
+        raw.get("modelID")
+        or raw.get("model")
+        or definition.get("model")
+        or None
+    )
+    vendor: str | None = raw.get("vendor") or definition.get("vendor") or None
+    return {
+        "id": ieee,
+        "label": friendly_name,
+        "type": _z2m_type_to_homelable(device_type),
+        "ieee_address": ieee,
+        "friendly_name": friendly_name,
+        "device_type": device_type,
+        "model": model,
+        "vendor": vendor,
+        "lqi": None,
+        "parent_id": None,
+    }
+
+
+def parse_networkmap(
+    payload: dict[str, Any],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Parse a Z2M ``bridge/response/networkmap`` payload into node + edge lists.
+
+    Z2M raw response shape::
+
+        {
+          "data": {
+            "type": "raw",
+            "routes": false,
+            "value": {
+              "nodes": [{"ieeeAddr": ..., "type": "Coordinator|Router|EndDevice",
+                         "friendlyName": ..., "definition": {"model": ..., "vendor": ...}}],
+              "links": [{"source": {"ieeeAddr": ...}, "target": {"ieeeAddr": ...},
+                         "lqi": 200, "depth": 1}]
+            }
+          },
+          "status": "ok"
+        }
+
+    Older or alternate shapes may put nodes/links directly under ``data``.
+    Both are accepted.
+    """
+    data: dict[str, Any] = payload.get("data") or {}
+    value = data.get("value")
+    container: dict[str, Any] = value if isinstance(value, dict) else data
+
+    raw_nodes: list[dict[str, Any]] = container.get("nodes") or []
+    raw_links: list[dict[str, Any]] = container.get("links") or []
+
+    if not isinstance(raw_nodes, list):
+        raise ValueError("Malformed networkmap: 'nodes' is not a list")
+    if not isinstance(raw_links, list):
+        raise ValueError("Malformed networkmap: 'links' is not a list")
+
+    nodes_list: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    coordinator_id: str | None = None
+
+    for entry in raw_nodes:
+        if not isinstance(entry, dict):
+            continue
+        node = _node_from_z2m(entry)
+        if node is None or node["id"] in seen_ids:
+            continue
+        seen_ids.add(node["id"])
+        nodes_list.append(node)
+        if node["device_type"] == "Coordinator":
+            coordinator_id = node["id"]
+
+    # Z2M `links` is bidirectional/mesh: every pair appears twice and routers
+    # carry sibling-mesh paths. Walk it only to extract LQI per device and to
+    # resolve which router an end device hangs off; do NOT emit edges directly
+    # from links. The final edge set is the strict parent→child tree built
+    # from parent_id below — that avoids duplicate edges and keeps the visual
+    # flow consistent (parent bottom → child top).
+    raw_edges: list[dict[str, Any]] = []
+    lqi_by_id: dict[str, int] = {}
+
+    for link in raw_links:
+        if not isinstance(link, dict):
+            continue
+        src_obj = link.get("source") or {}
+        tgt_obj = link.get("target") or {}
+        src = src_obj.get("ieeeAddr") if isinstance(src_obj, dict) else None
+        tgt = tgt_obj.get("ieeeAddr") if isinstance(tgt_obj, dict) else None
+        if not src or not tgt:
+            continue
+        if src not in seen_ids or tgt not in seen_ids:
+            continue
+        raw_edges.append({"source": src, "target": tgt})
+        lqi = link.get("lqi") or link.get("linkquality")
+        if isinstance(lqi, int) and tgt not in lqi_by_id:
+            lqi_by_id[tgt] = lqi
+
+    for node in nodes_list:
+        if node["id"] in lqi_by_id:
+            node["lqi"] = lqi_by_id[node["id"]]
+
+    # Build parent_id hierarchy: coordinator → routers → end devices
+    if coordinator_id:
+        router_ids = {n["id"] for n in nodes_list if n["device_type"] == "Router"}
+        for node in nodes_list:
+            if node["device_type"] == "Router":
+                node["parent_id"] = coordinator_id
+            elif node["device_type"] == "EndDevice":
+                parent = _find_parent_router(node["id"], router_ids, raw_edges)
+                node["parent_id"] = parent or coordinator_id
+
+    # Final edges = strict parent → child tree (one edge per non-coordinator)
+    edges_list: list[dict[str, Any]] = [
+        {"source": node["parent_id"], "target": node["id"]}
+        for node in nodes_list
+        if node.get("parent_id")
+    ]
+
+    return nodes_list, edges_list
+
+
+def _find_parent_router(
+    device_id: str,
+    router_ids: set[str],
+    edges: list[dict[str, Any]],
+) -> str | None:
+    """Return the first router that has a direct edge to device_id."""
+    for edge in edges:
+        src: str = edge["source"]
+        tgt: str = edge["target"]
+        if tgt == device_id and src in router_ids:
+            return src
+        if src == device_id and tgt in router_ids:
+            return tgt
+    return None
+
+
+async def fetch_networkmap(
+    mqtt_host: str,
+    mqtt_port: int,
+    base_topic: str,
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Connect to the MQTT broker, request the Z2M networkmap, and return (nodes, edges).
+
+    Raises:
+        TimeoutError: if the broker does not respond in time.
+        ConnectionError: if the broker cannot be reached.
+        ValueError: if the response payload is malformed.
+    """
+    if aiomqtt is None:  # pragma: no cover
+        raise ImportError(
+            "aiomqtt is required for Zigbee import. "
+            "Install it with: pip install aiomqtt"
+        )
+
+    request_topic = _NETWORKMAP_REQUEST_TOPIC.format(base_topic=base_topic)
+    response_topic = _NETWORKMAP_RESPONSE_TOPIC.format(base_topic=base_topic)
+
+    response_payload: dict[str, Any] = {}
+
+    tls_context = _build_tls_context(tls_insecure) if tls else None
+
+    try:
+        async with aiomqtt.Client(
+            hostname=mqtt_host,
+            port=mqtt_port,
+            username=username,
+            password=password,
+            timeout=_CONNECTION_TIMEOUT,
+            tls_context=tls_context,
+        ) as client:
+            await client.subscribe(response_topic)
+            # Give the broker a brief window to register the subscription
+            # before we publish the request. Without this, brokers that
+            # race SUBACK with our PUBLISH may deliver the response before
+            # the subscription is active and we'd hang until timeout.
+            await asyncio.sleep(0.1)
+            await client.publish(
+                request_topic,
+                json.dumps({"type": "raw", "routes": False}),
+            )
+
+            async def _wait_for_response() -> None:
+                async for message in client.messages:
+                    if str(message.topic) != response_topic:
+                        continue
+                    raw = message.payload
+                    try:
+                        payload_str = (
+                            raw.decode() if isinstance(raw, bytes | bytearray) else str(raw)
+                        )
+                        response_payload.update(json.loads(payload_str))
+                    except (json.JSONDecodeError, TypeError) as exc:
+                        raise ValueError(
+                            f"Malformed networkmap response: {exc}"
+                        ) from exc
+                    return
+
+            await asyncio.wait_for(_wait_for_response(), timeout=_NETWORKMAP_TIMEOUT)
+
+    except aiomqtt.MqttError as exc:
+        raise ConnectionError(_sanitize_mqtt_error(exc)) from exc
+    except asyncio.TimeoutError as exc:
+        raise TimeoutError("Timed out waiting for networkmap response") from exc
+
+    if not response_payload:
+        raise ValueError("Empty networkmap response received")
+
+    return parse_networkmap(response_payload)
+
+
+async def test_mqtt_connection(
+    mqtt_host: str,
+    mqtt_port: int,
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool = False,
+    tls_insecure: bool = False,
+) -> bool:
+    """Attempt a quick MQTT connection to verify broker reachability.
+
+    Returns True on success, raises ConnectionError on failure.
+    """
+    if aiomqtt is None:  # pragma: no cover
+        raise ImportError("aiomqtt is required")
+
+    tls_context = _build_tls_context(tls_insecure) if tls else None
+
+    try:
+        async with aiomqtt.Client(
+            hostname=mqtt_host,
+            port=mqtt_port,
+            username=username,
+            password=password,
+            timeout=_CONNECTION_TIMEOUT,
+            tls_context=tls_context,
+        ):
+            return True
+    except aiomqtt.MqttError as exc:
+        raise ConnectionError(_sanitize_mqtt_error(exc)) from exc
+    except asyncio.TimeoutError as exc:
+        raise TimeoutError("Connection to broker timed out") from exc

backend/data/.gitignore

@@ -2,3 +2,4 @@
 *.db-shm
 *.db-wal
 scan_config.json
+homelab.db.*

backend/pyproject.toml

@@ -25,6 +25,8 @@ addopts = "--tb=short -q"
 [tool.coverage.run]
 source = ["app"]
 omit = ["*/migrations/*", "*/tests/*"]
+concurrency = ["thread"]
+core = "sysmon"
 
 [tool.coverage.report]
 skip_empty = true

backend/requirements.txt

@@ -9,17 +9,19 @@ pydantic-settings==2.5.2
 python-jose[cryptography]==3.5.0
 passlib[bcrypt]==1.7.4
 bcrypt==4.0.1
-python-multipart==0.0.22
+python-multipart==0.0.27
 apscheduler==3.10.4
 python-nmap==0.7.1
 pyyaml==6.0.2
 types-PyYAML==6.0.12.20240917
 websockets==13.1
 httpx==0.27.2
+zeroconf==0.131.0
+aiomqtt==2.3.0
 
 # Dev
 ruff==0.6.9
 mypy==1.11.2
-pytest==8.3.3
-pytest-asyncio==0.24.0
+pytest==9.0.3
+pytest-asyncio==1.3.0
 pytest-cov==5.0.0

backend/tests/test_auth.py

@@ -1,3 +1,4 @@
+import pytest
 from httpx import AsyncClient
 
 
@@ -28,3 +29,42 @@ async def test_health_is_public(client: AsyncClient):
     res = await client.get("/api/v1/health")
     assert res.status_code == 200
     assert res.json() == {"status": "ok"}
+
+
+# --- MCP service key auth ---
+
+@pytest.fixture
+def with_service_key():
+    from app.core.config import settings
+    settings.mcp_service_key = "test-service-key"
+    yield "test-service-key"
+    settings.mcp_service_key = ""
+
+
+async def test_service_key_grants_access(client: AsyncClient, with_service_key):
+    res = await client.get("/api/v1/nodes", headers={"X-MCP-Service-Key": with_service_key})
+    assert res.status_code == 200
+
+
+async def test_service_key_wrong_value(client: AsyncClient, with_service_key):
+    res = await client.get("/api/v1/nodes", headers={"X-MCP-Service-Key": "wrong-key"})
+    assert res.status_code == 401
+
+
+async def test_service_key_disabled_when_not_configured(client: AsyncClient):
+    from app.core.config import settings
+    settings.mcp_service_key = ""
+    res = await client.get("/api/v1/nodes", headers={"X-MCP-Service-Key": "any-key"})
+    assert res.status_code == 401
+
+
+async def test_login_with_malformed_hash_returns_401_not_500(client: AsyncClient):
+    """Malformed hash (e.g. $ stripped by shell) must not crash with 500."""
+    from app.core.config import settings
+    original = settings.auth_password_hash
+    settings.auth_password_hash = "2b12RtMbyw17l4N5UGzeXMNAWu"  # $ signs stripped
+    try:
+        res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+        assert res.status_code == 401
+    finally:
+        settings.auth_password_hash = original

backend/tests/test_canvas.py

@@ -104,6 +104,25 @@ async def test_save_canvas_persists_custom_colors(client: AsyncClient, headers:
     assert canvas["nodes"][0]["custom_colors"] == {"border": "#ff0000", "icon": "#00ff00"}
 
 
+async def test_save_canvas_persists_zone_label_position_and_text_size(client: AsyncClient, headers: dict):
+    """label_position and text_size are stored in custom_colors and returned unchanged."""
+    n1 = node_payload(custom_colors={
+        "border": "#00d4ff",
+        "border_style": "solid",
+        "border_width": 3,
+        "label_position": "outside",
+        "text_size": 16,
+        "text_color": "#e6edf3",
+    })
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    cc = canvas["nodes"][0]["custom_colors"]
+    assert cc["label_position"] == "outside"
+    assert cc["text_size"] == 16
+    assert cc["border_width"] == 3
+
+
 async def test_save_canvas_persists_edge_custom_color_and_path_style(client: AsyncClient, headers: dict):
     n1 = node_payload()
     n2 = node_payload()
@@ -138,3 +157,442 @@ async def test_save_canvas_custom_icon_cleared_when_null(client: AsyncClient, he
 async def test_save_canvas_requires_auth(client: AsyncClient):
     res = await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}})
     assert res.status_code == 401
+
+
+async def test_save_canvas_persists_hardware_fields(client: AsyncClient, headers: dict):
+    n1 = node_payload(cpu_count=8, cpu_model="Intel i7-12700K", ram_gb=32.0, disk_gb=500.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["cpu_count"] == 8
+    assert node["cpu_model"] == "Intel i7-12700K"
+    assert node["ram_gb"] == 32.0
+    assert node["disk_gb"] == 500.0
+
+
+async def test_save_canvas_hardware_fields_nullable(client: AsyncClient, headers: dict):
+    n1 = node_payload(cpu_count=4, ram_gb=16.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["cpu_count"] == 4
+    assert node["ram_gb"] == 16.0
+    assert node["cpu_model"] is None
+    assert node["disk_gb"] is None
+
+
+async def test_save_canvas_persists_show_hardware(client: AsyncClient, headers: dict):
+    n1 = node_payload(show_hardware=True, cpu_count=4, ram_gb=16.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["show_hardware"] is True
+
+
+async def test_save_canvas_show_hardware_defaults_false(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["show_hardware"] is False
+
+
+async def test_save_canvas_hardware_fields_cleared_on_update(client: AsyncClient, headers: dict):
+    n1 = node_payload(cpu_count=8, ram_gb=32.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    n1_cleared = {**n1, "cpu_count": None, "ram_gb": None}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1_cleared], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["cpu_count"] is None
+    assert node["ram_gb"] is None
+
+
+# ── node width / height (resizable nodes) ─────────────────────────────────────
+
+async def test_save_canvas_persists_node_dimensions(client: AsyncClient, headers: dict):
+    n1 = node_payload(width=320.0, height=180.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["width"] == 320.0
+    assert node["height"] == 180.0
+
+
+async def test_save_canvas_dimensions_default_null(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["width"] is None
+    assert canvas["nodes"][0]["height"] is None
+
+
+async def test_save_canvas_dimensions_updated_on_resize(client: AsyncClient, headers: dict):
+    n1 = node_payload(width=140.0, height=50.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    n1_resized = {**n1, "width": 280.0, "height": 120.0}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1_resized], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["width"] == 280.0
+    assert node["height"] == 120.0
+
+
+async def test_save_canvas_dimensions_cleared_when_null(client: AsyncClient, headers: dict):
+    n1 = node_payload(width=300.0, height=200.0)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    n1_cleared = {**n1, "width": None, "height": None}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1_cleared], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["width"] is None
+    assert canvas["nodes"][0]["height"] is None
+
+
+# ── properties ────────────────────────────────────────────────────────────────
+
+async def test_save_canvas_properties_default_empty(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["properties"] == []
+
+
+async def test_save_canvas_persists_properties(client: AsyncClient, headers: dict):
+    props = [
+        {"key": "RAM", "value": "32 GB", "icon": "MemoryStick", "visible": True},
+        {"key": "CPU", "value": "Intel i9", "icon": "Cpu", "visible": False},
+    ]
+    n1 = node_payload(properties=props)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    returned = canvas["nodes"][0]["properties"]
+    assert len(returned) == 2
+    assert returned[0] == {"key": "RAM", "value": "32 GB", "icon": "MemoryStick", "visible": True}
+    assert returned[1] == {"key": "CPU", "value": "Intel i9", "icon": "Cpu", "visible": False}
+
+
+async def test_save_canvas_properties_updated_on_second_save(client: AsyncClient, headers: dict):
+    n1 = node_payload(properties=[{"key": "RAM", "value": "16 GB", "icon": None, "visible": True}])
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    n1_updated = {**n1, "properties": [
+        {"key": "RAM", "value": "64 GB", "icon": "MemoryStick", "visible": True},
+        {"key": "Disk", "value": "2 TB", "icon": "HardDrive", "visible": True},
+    ]}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1_updated], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    props = canvas["nodes"][0]["properties"]
+    assert len(props) == 2
+    assert props[0]["value"] == "64 GB"
+    assert props[1]["key"] == "Disk"
+
+
+async def test_save_canvas_properties_with_null_icon(client: AsyncClient, headers: dict):
+    props = [{"key": "Note", "value": "custom rack", "icon": None, "visible": True}]
+    n1 = node_payload(properties=props)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["properties"][0]["icon"] is None
+
+
+async def test_save_canvas_properties_cleared_to_empty(client: AsyncClient, headers: dict):
+    n1 = node_payload(properties=[{"key": "RAM", "value": "32 GB", "icon": None, "visible": True}])
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    n1_cleared = {**n1, "properties": []}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1_cleared], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["properties"] == []
+
+
+# ── edge waypoints & handles ──────────────────────────────────────────────────
+
+async def test_save_canvas_edge_waypoints_default_null(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"])
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["edges"][0]["waypoints"] is None
+
+
+async def test_save_canvas_persists_waypoints_on_edge(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    waypoints = [{"x": 100.0, "y": 200.0}, {"x": 300.0, "y": 150.0}]
+    e1 = edge_payload(n1["id"], n2["id"], waypoints=waypoints)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    returned = canvas["edges"][0]["waypoints"]
+    assert returned == [{"x": 100.0, "y": 200.0}, {"x": 300.0, "y": 150.0}]
+
+
+async def test_save_canvas_waypoints_updated_on_second_save(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], waypoints=[{"x": 10.0, "y": 20.0}])
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    e1_updated = {**e1, "waypoints": [{"x": 50.0, "y": 60.0}, {"x": 70.0, "y": 80.0}]}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1_updated], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["edges"][0]["waypoints"] == [{"x": 50.0, "y": 60.0}, {"x": 70.0, "y": 80.0}]
+
+
+async def test_save_canvas_persists_edge_handles(client: AsyncClient, headers: dict):
+    n1 = node_payload(bottom_handles=3)
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], source_handle="bottom-1", target_handle="top")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    edge = canvas["edges"][0]
+    assert edge["source_handle"] == "bottom-1"
+    assert edge["target_handle"] == "top"
+
+
+async def test_save_canvas_persists_animated_edge(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], animated="snake")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["edges"][0]["animated"] == "snake"
+
+
+async def test_save_canvas_persists_animated_basic(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], animated="basic")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["edges"][0]["animated"] == "basic"
+
+
+# ── node fields ───────────────────────────────────────────────────────────────
+
+async def test_save_canvas_persists_all_node_fields(client: AsyncClient, headers: dict):
+    n1 = node_payload(
+        type="server",
+        label="Main Server",
+        hostname="server.local",
+        ip="192.168.1.10",
+        mac="aa:bb:cc:dd:ee:ff",
+        os="Ubuntu 22.04",
+        status="online",
+        check_method="http",
+        check_target="http://192.168.1.10",
+        services=[{"name": "nginx", "port": 80}],
+        notes="Primary web server",
+        pos_x=150.0,
+        pos_y=250.0,
+        bottom_handles=2,
+    )
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["hostname"] == "server.local"
+    assert node["ip"] == "192.168.1.10"
+    assert node["mac"] == "aa:bb:cc:dd:ee:ff"
+    assert node["os"] == "Ubuntu 22.04"
+    assert node["status"] == "online"
+    assert node["check_method"] == "http"
+    assert node["check_target"] == "http://192.168.1.10"
+    assert node["services"] == [{"name": "nginx", "port": 80}]
+    assert node["notes"] == "Primary web server"
+    assert node["pos_x"] == 150.0
+    assert node["pos_y"] == 250.0
+    assert node["bottom_handles"] == 2
+
+
+async def test_save_canvas_persists_bottom_handles(client: AsyncClient, headers: dict):
+    n1 = node_payload(bottom_handles=4)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["bottom_handles"] == 4
+
+
+async def test_save_canvas_bottom_handles_defaults_one(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["bottom_handles"] == 1
+
+
+async def test_save_canvas_persists_services_and_notes(client: AsyncClient, headers: dict):
+    services = [{"name": "ssh", "port": 22}, {"name": "http", "port": 80}]
+    n1 = node_payload(services=services, notes="My NAS device")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["services"] == services
+    assert node["notes"] == "My NAS device"
+
+
+async def test_save_canvas_persists_service_paths(client: AsyncClient, headers: dict):
+    services = [{"service_name": "Grafana", "protocol": "tcp", "port": 3000, "path": "/login"}]
+    n1 = node_payload(ip="192.168.1.50:8080", services=services)
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"][0]["services"] == services
+
+
+async def test_save_canvas_persists_check_fields(client: AsyncClient, headers: dict):
+    n1 = node_payload(check_method="ping", check_target="192.168.1.1")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node = canvas["nodes"][0]
+    assert node["check_method"] == "ping"
+    assert node["check_target"] == "192.168.1.1"
+
+
+# ── parent/child nodes ────────────────────────────────────────────────────────
+
+async def test_save_canvas_persists_parent_child_nodes(client: AsyncClient, headers: dict):
+    parent = node_payload(type="proxmox", label="PVE Host")
+    child = node_payload(type="vm", label="VM-100", parent_id=parent["id"])
+    await client.post("/api/v1/canvas/save", json={"nodes": [parent, child], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node_map = {n["id"]: n for n in canvas["nodes"]}
+    assert node_map[child["id"]]["parent_id"] == parent["id"]
+    assert node_map[parent["id"]]["parent_id"] is None
+
+
+async def test_save_canvas_child_removed_with_parent(client: AsyncClient, headers: dict):
+    parent = node_payload(type="proxmox", label="PVE Host")
+    child = node_payload(type="lxc", label="LXC-101", parent_id=parent["id"])
+    await client.post("/api/v1/canvas/save", json={"nodes": [parent, child], "edges": [], "viewport": {}}, headers=headers)
+
+    # Remove both parent and child
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["nodes"] == []
+
+
+# ── groupRect / group node ────────────────────────────────────────────────────
+
+async def test_save_canvas_persists_group_node(client: AsyncClient, headers: dict):
+    group = node_payload(type="group", label="Network Zone", width=400.0, height=300.0)
+    member = node_payload(type="server", label="Member", parent_id=group["id"])
+    await client.post("/api/v1/canvas/save", json={"nodes": [group, member], "edges": [], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    node_map = {n["id"]: n for n in canvas["nodes"]}
+    assert node_map[group["id"]]["type"] == "group"
+    assert node_map[group["id"]]["width"] == 400.0
+    assert node_map[group["id"]]["height"] == 300.0
+    assert node_map[member["id"]]["parent_id"] == group["id"]
+
+
+# ── viewport ──────────────────────────────────────────────────────────────────
+
+async def test_load_canvas_returns_default_viewport_when_no_state(client: AsyncClient, headers: dict):
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["viewport"] == {"x": 0, "y": 0, "zoom": 1}
+
+
+async def test_save_canvas_updates_existing_canvas_state(client: AsyncClient, headers: dict):
+    """Second save updates the existing CanvasState row (exercises the state.viewport branch)."""
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {"x": 1, "y": 2, "zoom": 1}}, headers=headers)
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {"x": 99, "y": 88, "zoom": 0.75}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["viewport"] == {"x": 99, "y": 88, "zoom": 0.75}
+
+
+# ── edge types ────────────────────────────────────────────────────────────────
+
+async def test_save_canvas_persists_edge_type_vlan(client: AsyncClient, headers: dict):
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], type="vlan", vlan_id=10, label="VLAN 10")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    edge = canvas["edges"][0]
+    assert edge["type"] == "vlan"
+    assert edge["vlan_id"] == 10
+    assert edge["label"] == "VLAN 10"
+
+
+async def test_save_canvas_edge_update_existing(client: AsyncClient, headers: dict):
+    """Second save updates an existing edge (exercises the db_edge branch)."""
+    n1 = node_payload()
+    n2 = node_payload()
+    e1 = edge_payload(n1["id"], n2["id"], label="original")
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1], "viewport": {}}, headers=headers)
+
+    e1_updated = {**e1, "label": "updated", "custom_color": "#ff0000"}
+    await client.post("/api/v1/canvas/save", json={"nodes": [n1, n2], "edges": [e1_updated], "viewport": {}}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    edge = canvas["edges"][0]
+    assert edge["label"] == "updated"
+    assert edge["custom_color"] == "#ff0000"
+
+
+# ── custom_style ──────────────────────────────────────────────────────────────
+
+async def test_save_and_load_custom_style(client: AsyncClient, headers: dict):
+    custom_style = {
+        "nodes": {
+            "server": {"borderColor": "#ff0000", "borderOpacity": 0.8, "bgColor": "#000000", "bgOpacity": 1, "iconColor": "#ff0000", "iconOpacity": 1, "width": 200, "height": 80},
+        },
+        "edges": {
+            "ethernet": {"color": "#00ff00", "opacity": 1, "pathStyle": "bezier", "animated": "none"},
+        },
+    }
+    payload = {"nodes": [], "edges": [], "viewport": {"theme_id": "custom"}, "custom_style": custom_style}
+    res = await client.post("/api/v1/canvas/save", json=payload, headers=headers)
+    assert res.status_code == 200
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert canvas["custom_style"] is not None
+    assert canvas["custom_style"]["nodes"]["server"]["borderColor"] == "#ff0000"
+    assert canvas["custom_style"]["edges"]["ethernet"]["color"] == "#00ff00"
+
+
+async def test_load_canvas_custom_style_null_by_default(client: AsyncClient, headers: dict):
+    res = await client.get("/api/v1/canvas", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["custom_style"] is None
+
+
+async def test_save_canvas_custom_style_overwrite(client: AsyncClient, headers: dict):
+    style_v1 = {"nodes": {"server": {"borderColor": "#aabbcc", "borderOpacity": 1, "bgColor": "#000000", "bgOpacity": 1, "iconColor": "#aabbcc", "iconOpacity": 1, "width": 0, "height": 0}}, "edges": {}}
+    style_v2 = {"nodes": {"proxmox": {"borderColor": "#ff6e00", "borderOpacity": 1, "bgColor": "#111111", "bgOpacity": 1, "iconColor": "#ff6e00", "iconOpacity": 1, "width": 0, "height": 0}}, "edges": {}}
+
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}, "custom_style": style_v1}, headers=headers)
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}, "custom_style": style_v2}, headers=headers)
+
+    canvas = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert "proxmox" in canvas["custom_style"]["nodes"]
+    assert "server" not in canvas["custom_style"]["nodes"]

backend/tests/test_db_backup.py

@@ -0,0 +1,57 @@
+"""
+Tests for automatic DB backup before migrations.
+"""
+import os
+
+os.environ.setdefault("SECRET_KEY", "test-only-secret-key-not-for-production")
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from app.db.database import _backup_db
+
+
+@pytest.fixture()
+def tmp_db(tmp_path: Path):
+    db = tmp_path / "homelab.db"
+    db.write_bytes(b"SQLite placeholder")
+    return db
+
+
+def test_backup_created_when_db_exists(tmp_db: Path):
+    with patch("app.db.database.settings") as mock_settings, \
+         patch("app.db.database.APP_VERSION", "1.9"):
+        mock_settings.sqlite_path = str(tmp_db)
+        _backup_db()
+        backup = tmp_db.parent / "homelab.db.back-1.9"
+        assert backup.exists()
+        assert backup.read_bytes() == b"SQLite placeholder"
+
+
+def test_backup_skipped_when_db_missing(tmp_path: Path):
+    with patch("app.db.database.settings") as mock_settings, \
+         patch("app.db.database.APP_VERSION", "1.9"):
+        mock_settings.sqlite_path = str(tmp_path / "nonexistent.db")
+        _backup_db()
+        assert not any(tmp_path.glob("*.back-*"))
+
+
+def test_backup_idempotent_second_call_no_overwrite(tmp_db: Path):
+    with patch("app.db.database.settings") as mock_settings, \
+         patch("app.db.database.APP_VERSION", "1.9"):
+        mock_settings.sqlite_path = str(tmp_db)
+        _backup_db()
+        backup = tmp_db.parent / "homelab.db.back-1.9"
+        backup.write_bytes(b"original backup")
+        _backup_db()
+        assert backup.read_bytes() == b"original backup"
+
+
+def test_backup_version_in_filename(tmp_db: Path):
+    with patch("app.db.database.settings") as mock_settings, \
+         patch("app.db.database.APP_VERSION", "2.0"):
+        mock_settings.sqlite_path = str(tmp_db)
+        _backup_db()
+        assert (tmp_db.parent / "homelab.db.back-2.0").exists()

backend/tests/test_fingerprint.py

@@ -131,3 +131,45 @@ def test_suggest_node_type_camera_from_signature():
     ]):
         result = suggest_node_type([{"port": 554, "protocol": "tcp"}])
         assert result == "camera"
+
+
+# ── IoT detection ─────────────────────────────────────────────────────────────
+
+def test_suggest_node_type_iot_from_mqtt_port():
+    result = suggest_node_type([{"port": 1883, "protocol": "tcp"}])
+    assert result == "iot"
+
+
+def test_suggest_node_type_iot_from_coap_port():
+    result = suggest_node_type([{"port": 5683, "protocol": "tcp"}])
+    assert result == "iot"
+
+
+def test_suggest_node_type_iot_from_esphome_port():
+    result = suggest_node_type([{"port": 6052, "protocol": "tcp"}])
+    assert result == "iot"
+
+
+def test_suggest_node_type_shelly_mac_overrides_http_port():
+    # Shelly exposes port 80 (would suggest "server") but MAC identifies it as IoT
+    result = suggest_node_type([{"port": 80, "protocol": "tcp"}], mac="34:94:54:aa:bb:cc")
+    assert result == "iot"
+
+
+def test_suggest_node_type_espressif_mac_returns_iot():
+    result = suggest_node_type([], mac="a0:20:a6:11:22:33")
+    assert result == "iot"
+
+
+def test_suggest_node_type_tuya_mac_returns_iot():
+    result = suggest_node_type([{"port": 80, "protocol": "tcp"}], mac="d8:f1:5b:aa:bb:cc")
+    assert result == "iot"
+
+
+def test_suggest_node_type_iot_wins_over_server_when_mqtt_present():
+    # MQTT port + HTTP port → iot wins (iot is higher priority than server now)
+    result = suggest_node_type([
+        {"port": 80, "protocol": "tcp"},
+        {"port": 1883, "protocol": "tcp"},
+    ])
+    assert result == "iot"

backend/tests/test_integration.py

@@ -0,0 +1,185 @@
+"""
+Integration tests — run against a live Docker stack.
+
+Skipped unless INTEGRATION_BASE_URL is set (done automatically in docker-ci.yml).
+
+Usage (local):
+    INTEGRATION_BASE_URL=http://localhost:8000 \
+    INTEGRATION_USERNAME=admin \
+    INTEGRATION_PASSWORD=your-password \
+    pytest backend/tests/test_integration.py -v
+"""
+
+import os
+
+import httpx
+import pytest
+
+BASE_URL = os.environ.get("INTEGRATION_BASE_URL", "")
+USERNAME = os.environ.get("INTEGRATION_USERNAME", "admin")
+_PASSWORD_RAW = os.environ.get("INTEGRATION_PASSWORD", "")
+
+pytestmark = pytest.mark.skipif(
+    not BASE_URL,
+    reason="INTEGRATION_BASE_URL not set — skipping live-stack tests",
+)
+
+
+def _require_password() -> str:
+    if not _PASSWORD_RAW:
+        pytest.fail("INTEGRATION_PASSWORD env var is required for live-stack tests")
+    return _PASSWORD_RAW
+
+
+PASSWORD = _PASSWORD_RAW  # resolved at call time via _require_password() in fixture
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="module")
+def token() -> str:
+    pw = _require_password()
+    res = httpx.post(
+        f"{BASE_URL}/api/v1/auth/login",
+        json={"username": USERNAME, "password": pw},
+        timeout=10,
+    )
+    assert res.status_code == 200, f"Login failed ({res.status_code}): {res.text}"
+    return res.json()["access_token"]
+
+
+@pytest.fixture(scope="module")
+def auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.fixture()
+def restored_canvas(auth):
+    """Save the current canvas before the test and restore it afterward."""
+    before = httpx.get(f"{BASE_URL}/api/v1/canvas", headers=auth, timeout=10).json()
+    yield
+    httpx.post(f"{BASE_URL}/api/v1/canvas/save", json=before, headers=auth, timeout=10)
+
+
+def _save_canvas(auth, nodes, edges=None):
+    payload = {
+        "nodes": nodes,
+        "edges": edges or [],
+        "viewport": {"x": 0, "y": 0, "zoom": 1},
+    }
+    res = httpx.post(f"{BASE_URL}/api/v1/canvas/save", json=payload, headers=auth, timeout=10)
+    assert res.status_code == 200, f"Canvas save failed ({res.status_code}): {res.text}"
+    return res
+
+
+def _node(node_id: str, label: str, node_type: str = "server", **extra) -> dict:
+    """Build a NodeSave-compatible dict (flat API format, not React Flow format)."""
+    return {
+        "id": node_id,
+        "type": node_type,
+        "label": label,
+        "status": "unknown",
+        "services": [],
+        "pos_x": extra.pop("pos_x", 0),
+        "pos_y": extra.pop("pos_y", 0),
+        **extra,
+    }
+
+
+# ── Health ────────────────────────────────────────────────────────────────────
+
+def test_health_endpoint():
+    res = httpx.get(f"{BASE_URL}/api/v1/health", timeout=10)
+    assert res.status_code == 200
+
+
+# ── Auth ──────────────────────────────────────────────────────────────────────
+
+def test_login_returns_token():
+    pw = _require_password()
+    res = httpx.post(
+        f"{BASE_URL}/api/v1/auth/login",
+        json={"username": USERNAME, "password": pw},
+        timeout=10,
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert "access_token" in data
+    assert data["token_type"] == "bearer"
+
+
+def test_login_bad_credentials():
+    res = httpx.post(
+        f"{BASE_URL}/api/v1/auth/login",
+        json={"username": USERNAME, "password": "definitely-wrong"},
+        timeout=10,
+    )
+    assert res.status_code == 401
+
+
+def test_protected_route_without_token():
+    res = httpx.get(f"{BASE_URL}/api/v1/canvas", timeout=10)
+    assert res.status_code == 401
+
+
+# ── Canvas round-trip ─────────────────────────────────────────────────────────
+
+def test_canvas_load_returns_valid_structure(auth):
+    res = httpx.get(f"{BASE_URL}/api/v1/canvas", headers=auth, timeout=10)
+    assert res.status_code == 200
+    data = res.json()
+    assert "nodes" in data
+    assert "edges" in data
+    assert isinstance(data["nodes"], list)
+    assert isinstance(data["edges"], list)
+
+
+def test_canvas_save_and_reload(auth, restored_canvas):
+    _save_canvas(auth, [_node("integ-node-1", "CI Server", pos_x=100, pos_y=200)])
+
+    data = httpx.get(f"{BASE_URL}/api/v1/canvas", headers=auth, timeout=10).json()
+    assert len(data["nodes"]) == 1
+
+    node = data["nodes"][0]
+    assert node["id"] == "integ-node-1"
+    assert node["label"] == "CI Server"
+    assert node["type"] == "server"
+    assert node["pos_x"] == 100
+    assert node["pos_y"] == 200
+
+
+def test_canvas_save_preserves_node_dimensions(auth, restored_canvas):
+    """Width/height survive a save→reload cycle through the real DB."""
+    _save_canvas(auth, [
+        _node("resized-node", "Big Router", node_type="router", width=320.0, height=150.0)
+    ])
+
+    nodes = httpx.get(f"{BASE_URL}/api/v1/canvas", headers=auth, timeout=10).json()["nodes"]
+    node = next((n for n in nodes if n["id"] == "resized-node"), None)
+    assert node is not None
+    assert node["width"] == 320.0
+    assert node["height"] == 150.0
+
+
+def test_canvas_save_with_edge(auth, restored_canvas):
+    _save_canvas(
+        auth,
+        nodes=[
+            _node("n-src", "Router", node_type="router"),
+            _node("n-dst", "Server", node_type="server", pos_x=200),
+        ],
+        edges=[{
+            "id": "e-eth",
+            "source": "n-src",
+            "target": "n-dst",
+            "type": "ethernet",
+        }],
+    )
+
+    data = httpx.get(f"{BASE_URL}/api/v1/canvas", headers=auth, timeout=10).json()
+    assert len(data["edges"]) == 1
+    edge = data["edges"][0]
+    # EdgeResponse uses source/target (not source_id/target_id)
+    assert edge["source"] == "n-src"
+    assert edge["target"] == "n-dst"
+    assert edge["type"] == "ethernet"

backend/tests/test_liveview.py

@@ -0,0 +1,126 @@
+"""
+Tests for the /api/v1/liveview read-only canvas endpoint.
+
+The endpoint is:
+  - Disabled by default (LIVEVIEW_KEY not set) → 403
+  - Returns 403 for missing or wrong key even when enabled
+  - Returns canvas data for a valid key (no JWT required)
+"""
+
+import pytest
+from httpx import AsyncClient
+
+from app.core.config import settings
+
+
+@pytest.fixture(autouse=True)
+def reset_liveview_key():
+    """Restore liveview_key after each test so tests are isolated."""
+    original = settings.liveview_key
+    yield
+    settings.liveview_key = original
+
+
+# ── Disabled (no key configured) ─────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_liveview_disabled_by_default(client: AsyncClient):
+    settings.liveview_key = None
+    res = await client.get("/api/v1/liveview?key=anything")
+    assert res.status_code == 403
+    assert res.json()["detail"] == "Live view is disabled"
+
+
+@pytest.mark.asyncio
+async def test_liveview_disabled_when_key_empty(client: AsyncClient):
+    settings.liveview_key = ""
+    res = await client.get("/api/v1/liveview?key=anything")
+    assert res.status_code == 403
+    assert res.json()["detail"] == "Live view is disabled"
+
+
+# ── Enabled but wrong / missing key ──────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_liveview_wrong_key(client: AsyncClient):
+    settings.liveview_key = "correct-secret"
+    res = await client.get("/api/v1/liveview?key=wrong-key")
+    assert res.status_code == 403
+    assert res.json()["detail"] == "Invalid live view key"
+
+
+@pytest.mark.asyncio
+async def test_liveview_missing_key_param(client: AsyncClient):
+    settings.liveview_key = "correct-secret"
+    res = await client.get("/api/v1/liveview")
+    assert res.status_code == 403
+    assert res.json()["detail"] == "Invalid live view key"
+
+
+# ── Valid key — no JWT needed ────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_liveview_valid_key_returns_canvas(client: AsyncClient):
+    settings.liveview_key = "my-secret-key"
+    res = await client.get("/api/v1/liveview?key=my-secret-key")
+    assert res.status_code == 200
+    data = res.json()
+    assert "nodes" in data
+    assert "edges" in data
+    assert "viewport" in data
+    assert isinstance(data["nodes"], list)
+    assert isinstance(data["edges"], list)
+
+
+@pytest.mark.asyncio
+async def test_liveview_does_not_require_jwt(client: AsyncClient):
+    """Accessing without Authorization header must work when key is correct."""
+    settings.liveview_key = "open-sesame"
+    # client has no auth headers set here
+    res = await client.get("/api/v1/liveview?key=open-sesame")
+    assert res.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_liveview_returns_saved_canvas(client: AsyncClient, auth_headers):
+    """Canvas saved via POST /canvas/save appears in liveview response."""
+    settings.liveview_key = "test-key"
+    headers = await auth_headers()
+
+    # Save a canvas with one node
+    payload = {
+        "nodes": [{
+            "id": "lv-node-1",
+            "type": "server",
+            "label": "Live Node",
+            "status": "online",
+            "services": [],
+            "pos_x": 10,
+            "pos_y": 20,
+        }],
+        "edges": [],
+        "viewport": {"x": 0, "y": 0, "zoom": 1},
+    }
+    await client.post("/api/v1/canvas/save", json=payload, headers=headers)
+
+    # Liveview should return the same node
+    res = await client.get("/api/v1/liveview?key=test-key")
+    assert res.status_code == 200
+    nodes = res.json()["nodes"]
+    assert len(nodes) == 1
+    assert nodes[0]["id"] == "lv-node-1"
+    assert nodes[0]["label"] == "Live Node"
+
+
+# ── Re-disable after enabling ─────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_liveview_disabled_after_key_cleared(client: AsyncClient):
+    settings.liveview_key = "was-enabled"
+    res = await client.get("/api/v1/liveview?key=was-enabled")
+    assert res.status_code == 200
+
+    settings.liveview_key = None
+    res = await client.get("/api/v1/liveview?key=was-enabled")
+    assert res.status_code == 403
+    assert res.json()["detail"] == "Live view is disabled"

backend/tests/test_nodes.py

@@ -102,6 +102,110 @@ async def test_update_node_container_mode(client: AsyncClient, headers: dict):
     assert res.json()["container_mode"] is True
 
 
+async def test_update_node_parent_id(client: AsyncClient, headers: dict):
+    parent = await client.post("/api/v1/nodes", json={"type": "proxmox", "label": "PVE", "status": "unknown"}, headers=headers)
+    parent_id = parent.json()["id"]
+    child = await client.post("/api/v1/nodes", json={"type": "lxc", "label": "Child", "status": "unknown"}, headers=headers)
+    child_id = child.json()["id"]
+    res = await client.patch(f"/api/v1/nodes/{child_id}", json={"parent_id": parent_id}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["parent_id"] == parent_id
+
+
 async def test_create_node_requires_auth(client: AsyncClient):
     res = await client.post("/api/v1/nodes", json={"type": "server", "label": "N", "status": "unknown"})
     assert res.status_code == 401
+
+
+# --- Properties tests ---
+
+async def test_create_node_default_properties_empty(client: AsyncClient, headers: dict):
+    """New node has an empty properties list by default."""
+    res = await client.post("/api/v1/nodes", json={"type": "server", "label": "Srv", "status": "unknown"}, headers=headers)
+    assert res.status_code == 201
+    assert res.json()["properties"] == []
+
+
+async def test_create_node_with_properties(client: AsyncClient, headers: dict):
+    """Node created with properties round-trips correctly."""
+    props = [
+        {"key": "CPU Model", "value": "i7-12700K", "icon": "Cpu", "visible": True},
+        {"key": "RAM", "value": "32 GB", "icon": "MemoryStick", "visible": False},
+    ]
+    res = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "Srv", "status": "unknown", "properties": props},
+        headers=headers,
+    )
+    assert res.status_code == 201
+    assert res.json()["properties"] == props
+
+
+async def test_patch_node_properties(client: AsyncClient, headers: dict):
+    """PATCH with properties replaces the full properties array."""
+    create = await client.post("/api/v1/nodes", json={"type": "server", "label": "Srv", "status": "unknown"}, headers=headers)
+    node_id = create.json()["id"]
+
+    props = [{"key": "Disk", "value": "2 TB", "icon": "HardDrive", "visible": True}]
+    res = await client.patch(f"/api/v1/nodes/{node_id}", json={"properties": props}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["properties"] == props
+
+
+async def test_patch_node_without_properties_does_not_wipe(client: AsyncClient, headers: dict):
+    """PATCH that omits properties leaves existing properties untouched."""
+    props = [{"key": "GPU", "value": "RTX 4090", "icon": "Monitor", "visible": True}]
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "Srv", "status": "unknown", "properties": props},
+        headers=headers,
+    )
+    node_id = create.json()["id"]
+
+    # PATCH only the label — properties must survive
+    res = await client.patch(f"/api/v1/nodes/{node_id}", json={"label": "Updated"}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["properties"] == props
+    assert res.json()["label"] == "Updated"
+
+
+async def test_patch_node_clears_properties_with_empty_array(client: AsyncClient, headers: dict):
+    """PATCH with properties=[] explicitly clears all properties."""
+    props = [{"key": "CPU Model", "value": "i5", "icon": "Cpu", "visible": True}]
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "Srv", "status": "unknown", "properties": props},
+        headers=headers,
+    )
+    node_id = create.json()["id"]
+
+    res = await client.patch(f"/api/v1/nodes/{node_id}", json={"properties": []}, headers=headers)
+    assert res.status_code == 200
+    assert res.json()["properties"] == []
+
+
+async def test_get_node_returns_properties(client: AsyncClient, headers: dict):
+    """GET /nodes/:id returns the properties field."""
+    props = [{"key": "OS", "value": "Debian 12", "icon": "Server", "visible": True}]
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "server", "label": "Srv", "status": "unknown", "properties": props},
+        headers=headers,
+    )
+    node_id = create.json()["id"]
+
+    res = await client.get(f"/api/v1/nodes/{node_id}", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["properties"] == props
+
+
+async def test_properties_icon_can_be_null(client: AsyncClient, headers: dict):
+    """A property with icon=null is valid and round-trips correctly."""
+    props = [{"key": "Notes", "value": "custom value", "icon": None, "visible": False}]
+    create = await client.post(
+        "/api/v1/nodes",
+        json={"type": "generic", "label": "G", "status": "unknown", "properties": props},
+        headers=headers,
+    )
+    assert create.status_code == 201
+    assert create.json()["properties"] == props

backend/tests/test_properties_migration.py

@@ -0,0 +1,176 @@
+"""
+Tests for the hardware → properties migration logic.
+
+We test the migration function directly against an in-memory SQLite database
+so we can set up legacy rows (with hardware columns, NULL properties) and
+verify the migration produces the expected properties JSON.
+"""
+import json
+import os
+
+os.environ.setdefault("SECRET_KEY", "test-only-secret-key-not-for-production")
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+TEST_DB_URL = "sqlite+aiosqlite:///:memory:"
+
+
+async def _setup_legacy_table(conn):
+    """Create a minimal nodes table that mimics the pre-migration schema."""
+    await conn.exec_driver_sql("""
+        CREATE TABLE IF NOT EXISTS nodes (
+            id TEXT PRIMARY KEY,
+            type TEXT NOT NULL DEFAULT 'generic',
+            label TEXT NOT NULL DEFAULT '',
+            cpu_model TEXT,
+            cpu_count INTEGER,
+            ram_gb REAL,
+            disk_gb REAL,
+            show_hardware BOOLEAN NOT NULL DEFAULT 0,
+            properties JSON
+        )
+    """)
+
+
+async def _run_migration(conn):
+    """Run only the properties migration portion (extracted from init_db)."""
+    rows = await conn.exec_driver_sql(
+        "SELECT id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware "
+        "FROM nodes WHERE properties IS NULL"
+    )
+    for row in rows.fetchall():
+        node_id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware = row
+        props = []
+        visible = bool(show_hardware)
+        if cpu_model:
+            props.append({"key": "CPU Model", "value": str(cpu_model), "icon": "Cpu", "visible": visible})
+        if cpu_count is not None:
+            props.append({"key": "CPU Cores", "value": str(cpu_count), "icon": "Cpu", "visible": visible})
+        if ram_gb is not None:
+            props.append({"key": "RAM", "value": f"{ram_gb} GB", "icon": "MemoryStick", "visible": visible})
+        if disk_gb is not None:
+            props.append({"key": "Disk", "value": f"{disk_gb} GB", "icon": "HardDrive", "visible": visible})
+        await conn.exec_driver_sql(
+            "UPDATE nodes SET properties = ? WHERE id = ?",
+            (json.dumps(props), node_id),
+        )
+
+
+async def _get_properties(conn, node_id: str) -> list:
+    rows = await conn.exec_driver_sql("SELECT properties FROM nodes WHERE id = ?", (node_id,))
+    raw = rows.fetchone()[0]
+    return json.loads(raw) if raw else []
+
+
+@pytest.mark.asyncio
+async def test_migration_full_hardware():
+    """Node with all 4 hardware fields → 4 property entries with correct icons."""
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, cpu_model, cpu_count, ram_gb, disk_gb, show_hardware) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            ("node-1", "i7-12700K", 12, 32.0, 2000.0, 1),
+        )
+        await _run_migration(conn)
+        props = await _get_properties(conn, "node-1")
+
+    assert len(props) == 4
+    assert props[0] == {"key": "CPU Model", "value": "i7-12700K", "icon": "Cpu", "visible": True}
+    assert props[1] == {"key": "CPU Cores", "value": "12", "icon": "Cpu", "visible": True}
+    assert props[2] == {"key": "RAM", "value": "32.0 GB", "icon": "MemoryStick", "visible": True}
+    assert props[3] == {"key": "Disk", "value": "2000.0 GB", "icon": "HardDrive", "visible": True}
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_migration_partial_hardware():
+    """Node with only cpu_model and ram_gb → 2 property entries."""
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, cpu_model, ram_gb, show_hardware) VALUES (?, ?, ?, ?)",
+            ("node-2", "Ryzen 5 5600", 16.0, 0),
+        )
+        await _run_migration(conn)
+        props = await _get_properties(conn, "node-2")
+
+    assert len(props) == 2
+    assert props[0]["key"] == "CPU Model"
+    assert props[0]["visible"] is False
+    assert props[1]["key"] == "RAM"
+    assert props[1]["icon"] == "MemoryStick"
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_migration_no_hardware():
+    """Node with no hardware fields → empty properties array."""
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id) VALUES (?)",
+            ("node-3",),
+        )
+        await _run_migration(conn)
+        props = await _get_properties(conn, "node-3")
+
+    assert props == []
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_migration_idempotent():
+    """Running migration twice does not duplicate properties."""
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, cpu_model, show_hardware) VALUES (?, ?, ?)",
+            ("node-4", "Core i5", 1),
+        )
+        await _run_migration(conn)
+        await _run_migration(conn)  # second pass — node already has properties, should be skipped
+        props = await _get_properties(conn, "node-4")
+
+    assert len(props) == 1
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_migration_show_hardware_false_sets_visible_false():
+    """show_hardware=0 means all migrated properties have visible=False."""
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, cpu_model, ram_gb, show_hardware) VALUES (?, ?, ?, ?)",
+            ("node-5", "ARM Cortex-A72", 4.0, 0),
+        )
+        await _run_migration(conn)
+        props = await _get_properties(conn, "node-5")
+
+    assert all(p["visible"] is False for p in props)
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_migration_already_migrated_node_not_touched():
+    """Node that already has properties is skipped — existing properties preserved."""
+    existing = [{"key": "GPU", "value": "RTX 4090", "icon": "Monitor", "visible": True}]
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await _setup_legacy_table(conn)
+        await conn.exec_driver_sql(
+            "INSERT INTO nodes (id, cpu_model, ram_gb, show_hardware, properties) VALUES (?, ?, ?, ?, ?)",
+            ("node-6", "i9-13900K", 64.0, 1, json.dumps(existing)),
+        )
+        await _run_migration(conn)
+        props = await _get_properties(conn, "node-6")
+
+    assert props == existing
+    await engine.dispose()

backend/tests/test_scan.py

@@ -1,4 +1,4 @@
-"""Tests for scan routes: trigger, pending devices, approve/hide/ignore."""
+"""Tests for scan routes: trigger, pending devices, approve/hide/ignore, stop."""
 import uuid
 from unittest.mock import AsyncMock, patch
 
@@ -7,8 +7,8 @@ from httpx import AsyncClient
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import PendingDevice, ScanRun
-from app.services.scanner import run_scan
+from app.db.models import Node, PendingDevice, ScanRun
+from app.services.scanner import _cancelled_runs, request_cancel, run_scan
 
 
 @pytest.fixture
@@ -120,8 +120,7 @@ async def test_approve_nonexistent_device(client: AsyncClient, headers):
         json=node_payload,
         headers=headers,
     )
-    assert res.status_code == 200
-    assert res.json()["approved"] is False
+    assert res.status_code == 404
 
 
 # --- Hide device ---
@@ -141,6 +140,49 @@ async def test_hide_device(client: AsyncClient, headers, pending_device):
     assert len(hidden_res.json()) == 1
 
 
+# --- Restore hidden device ---
+
+@pytest.mark.asyncio
+async def test_restore_device(client: AsyncClient, headers, pending_device):
+    # Hide first
+    await client.post(f"/api/v1/scan/pending/{pending_device.id}/hide", headers=headers)
+
+    # Restore
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/restore", headers=headers)
+    assert res.status_code == 200
+    assert res.json()["restored"] is True
+
+    # Now back in pending, gone from hidden
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert len(pending_res.json()) == 1
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert hidden_res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_restore_device_rejects_non_hidden(client: AsyncClient, headers, pending_device):
+    res = await client.post(f"/api/v1/scan/pending/{pending_device.id}/restore", headers=headers)
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_bulk_restore_devices(client: AsyncClient, headers, pending_device):
+    # Hide
+    await client.post(f"/api/v1/scan/pending/{pending_device.id}/hide", headers=headers)
+
+    res = await client.post(
+        "/api/v1/scan/pending/bulk-restore",
+        headers=headers,
+        json={"device_ids": [pending_device.id]},
+    )
+    assert res.status_code == 200
+    assert res.json()["restored"] == 1
+    assert res.json()["skipped"] == 0
+
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert len(pending_res.json()) == 1
+
+
 # --- Ignore device ---
 
 @pytest.mark.asyncio
@@ -199,6 +241,213 @@ async def test_run_scan_creates_new_pending_device(db_session: AsyncSession):
     assert device.suggested_type == "server"
 
 
+@pytest.mark.asyncio
+async def test_run_scan_purges_stale_pending_for_canvas_nodes(db_session: AsyncSession):
+    """Pending devices that were already in canvas before scan starts must be removed."""
+    node = Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        ip="192.168.1.50",
+        status="online",
+        services=[],
+        pos_x=0.0,
+        pos_y=0.0,
+    )
+    stale = PendingDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.50",
+        mac=None,
+        hostname=None,
+        os=None,
+        services=[],
+        suggested_type="generic",
+        status="pending",
+    )
+    db_session.add(node)
+    db_session.add(stale)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(PendingDevice).where(PendingDevice.ip == "192.168.1.50")
+    )
+    assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_ip_already_in_canvas(db_session: AsyncSession):
+    """Devices whose IP already exists as a canvas Node must not appear in pending."""
+    node = Node(
+        id=str(uuid.uuid4()),
+        label="Existing Server",
+        type="server",
+        ip="192.168.1.50",
+        status="online",
+        services=[],
+        pos_x=0.0,
+        pos_y=0.0,
+    )
+    db_session.add(node)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(PendingDevice).where(PendingDevice.ip == "192.168.1.50")
+    )
+    assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_hidden_device(db_session: AsyncSession):
+    """Devices previously hidden by the user must not re-appear in pending on re-scan."""
+    hidden = PendingDevice(
+        id=str(uuid.uuid4()),
+        ip="192.168.1.50",
+        mac=None,
+        hostname=None,
+        os=None,
+        services=[],
+        suggested_type="generic",
+        status="hidden",
+    )
+    db_session.add(hidden)
+    await db_session.commit()
+
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+
+    result = await db_session.execute(
+        select(PendingDevice).where(
+            PendingDevice.ip == "192.168.1.50",
+            PendingDevice.status == "pending",
+        )
+    )
+    assert result.scalar_one_or_none() is None
+
+
+# --- Stop scan ---
+
+@pytest.mark.asyncio
+async def test_stop_scan_requires_auth(client: AsyncClient):
+    res = await client.post("/api/v1/scan/fake-id/stop")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_not_found(client: AsyncClient, headers):
+    import uuid as _uuid
+    res = await client.post(f"/api/v1/scan/{_uuid.uuid4()}/stop", headers=headers)
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_not_running(client: AsyncClient, headers, db_session: AsyncSession):
+    run = ScanRun(id=str(uuid.uuid4()), status="done", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/{run.id}/stop", headers=headers)
+    assert res.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_stop_scan_success(client: AsyncClient, headers, db_session: AsyncSession):
+    run = ScanRun(id=str(uuid.uuid4()), status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    res = await client.post(f"/api/v1/scan/{run.id}/stop", headers=headers)
+    assert res.status_code == 200
+    assert res.json() == {"stopping": True}
+    # run_id added to cancel set
+    assert run.id in _cancelled_runs
+    # cleanup for other tests
+    _cancelled_runs.discard(run.id)
+
+
+# --- run_scan cancellation ---
+
+@pytest.mark.asyncio
+async def test_run_scan_cancelled_marks_status(db_session: AsyncSession):
+    """When cancel is requested before the scan starts, status becomes 'cancelled'."""
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    request_cancel(run_id)
+
+    with (
+        patch("app.services.scanner._nmap_scan", return_value=[MOCK_HOST]) as mock_nmap,
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["192.168.1.0/24"], db_session, run_id)
+        # nmap should not have been called — cancelled before first range
+        mock_nmap.assert_not_called()
+
+    await db_session.refresh(run)
+    assert run.status == "cancelled"
+    assert run.finished_at is not None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_cancelled_mid_scan_skips_remaining_cidrs(db_session: AsyncSession):
+    """Cancel flag set after first CIDR is started prevents processing of the second CIDR."""
+    run_id = str(uuid.uuid4())
+    run = ScanRun(id=run_id, status="running", ranges=["10.0.0.0/24", "10.0.1.0/24"])
+    db_session.add(run)
+    await db_session.commit()
+
+    call_count = 0
+
+    def nmap_side_effect(target: str):
+        nonlocal call_count
+        call_count += 1
+        # Signal cancellation after the first CIDR scan completes
+        if call_count == 1:
+            request_cancel(run_id)
+        return []
+
+    with (
+        patch("app.services.scanner._nmap_scan", side_effect=nmap_side_effect),
+        patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock),
+    ):
+        await run_scan(["10.0.0.0/24", "10.0.1.0/24"], db_session, run_id)
+
+    assert call_count == 1  # second CIDR was skipped
+    await db_session.refresh(run)
+    assert run.status == "cancelled"
+
+
 @pytest.mark.asyncio
 async def test_run_scan_updates_existing_pending_device(db_session: AsyncSession):
     """Re-scanning the same IP updates services instead of creating a duplicate."""
@@ -237,3 +486,331 @@ async def test_run_scan_updates_existing_pending_device(db_session: AsyncSession
     # Services and hostname should be updated
     assert device.hostname == "myhost.lan"
     assert any(s["port"] == 8096 for s in device.services)
+
+
+# --- Bulk approve ---
+
+@pytest.fixture
+async def two_pending_devices(db_session):
+    devices = []
+    for i in range(2):
+        d = PendingDevice(
+            id=str(uuid.uuid4()),
+            ip=f"192.168.1.{10 + i}",
+            mac=None,
+            hostname=f"host-{i}",
+            os=None,
+            services=[],
+            suggested_type="generic",
+            status="pending",
+        )
+        db_session.add(d)
+        devices.append(d)
+    await db_session.commit()
+    for d in devices:
+        await db_session.refresh(d)
+    return devices
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_approves_devices(client: AsyncClient, headers, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] == 2
+    assert len(data["node_ids"]) == 2
+    assert all(nid is not None for nid in data["node_ids"]), "node_ids must be non-null UUIDs"
+    assert len(data["device_ids"]) == 2
+    assert data["skipped"] == 0
+    # Pending list should now be empty
+    pending_res = await client.get("/api/v1/scan/pending", headers=headers)
+    assert pending_res.json() == []
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_sets_default_check_method(client: AsyncClient, headers, two_pending_devices, db_session):
+    """Approved devices with an IP must default to ping; otherwise scheduler skips them."""
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    ids = [d.id for d in two_pending_devices]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    nodes = (await db_session.execute(select(NodeModel))).scalars().all()
+    for n in nodes:
+        if n.ip:
+            assert n.check_method == "ping", f"node {n.id} created without check_method"
+
+
+@pytest.mark.asyncio
+async def test_approve_device_sets_default_check_method(client: AsyncClient, headers, pending_device, db_session):
+    from sqlalchemy import select
+
+    from app.db.models import Node as NodeModel
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending_device.id}/approve",
+        json={"label": "h", "type": "generic", "ip": "192.168.1.10", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    assert res.status_code == 200
+    node = (await db_session.execute(select(NodeModel))).scalars().first()
+    assert node is not None
+    assert node.check_method == "ping"
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_skips_already_approved(client: AsyncClient, headers, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    # Approve first device individually first
+    await client.post(
+        f"/api/v1/scan/pending/{ids[0]}/approve",
+        json={"label": "h", "type": "generic", "ip": "192.168.1.10", "status": "unknown", "services": []},
+        headers=headers,
+    )
+    # Bulk approve both — first one is already approved (not pending), should be skipped
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] == 1
+    assert data["skipped"] == 1
+
+
+@pytest.mark.asyncio
+async def test_bulk_approve_requires_auth(client: AsyncClient, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    res = await client.post("/api/v1/scan/pending/bulk-approve", json={"device_ids": ids})
+    assert res.status_code == 401
+
+
+# --- Bulk hide ---
+
+@pytest.mark.asyncio
+async def test_bulk_hide_hides_devices(client: AsyncClient, headers, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["hidden"] == 2
+    assert data["skipped"] == 0
+    # Should appear in hidden list
+    hidden_res = await client.get("/api/v1/scan/hidden", headers=headers)
+    assert len(hidden_res.json()) == 2
+
+
+@pytest.mark.asyncio
+async def test_bulk_hide_skips_non_pending(client: AsyncClient, headers, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    # Hide first device individually first
+    await client.post(f"/api/v1/scan/pending/{ids[0]}/hide", headers=headers)
+    # Bulk hide both — first is already hidden (not pending anymore)
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids}, headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert data["hidden"] == 1
+    assert data["skipped"] == 1
+
+
+@pytest.mark.asyncio
+async def test_bulk_hide_requires_auth(client: AsyncClient, two_pending_devices):
+    ids = [d.id for d in two_pending_devices]
+    res = await client.post("/api/v1/scan/pending/bulk-hide", json={"device_ids": ids})
+    assert res.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Approve auto-creates Edges from pending_device_links (Zigbee flow)
+# ---------------------------------------------------------------------------
+
+
+async def _seed_zigbee_pending_pair(db_session):
+    """Create a coordinator Node + a pending device + a link between them."""
+    from app.db.models import Node, PendingDevice, PendingDeviceLink
+
+    coord = Node(
+        label="Coordinator",
+        type="zigbee_coordinator",
+        status="unknown",
+        ieee_address="0xCOORD",
+    )
+    db_session.add(coord)
+
+    pending = PendingDevice(
+        ieee_address="0xR1",
+        friendly_name="router_1",
+        suggested_type="zigbee_router",
+        device_subtype="Router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(pending)
+
+    db_session.add(
+        PendingDeviceLink(
+            source_ieee="0xCOORD",
+            target_ieee="0xR1",
+            discovery_source="zigbee",
+        )
+    )
+    await db_session.commit()
+    return coord, pending
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_creates_edge_when_other_endpoint_is_node(
+    client: AsyncClient, headers, db_session
+):
+    from sqlalchemy import select
+
+    from app.db.models import Edge
+
+    coord, pending = await _seed_zigbee_pending_pair(db_session)
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{pending.id}/approve",
+        json={
+            "label": "router_1",
+            "type": "zigbee_router",
+            "ip": None,
+            "status": "unknown",
+            "services": [],
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["approved"] is True
+    assert data["edges_created"] == 1
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 1
+    assert edges[0].source == coord.id
+    assert edges[0].target == data["node_id"]
+    assert edges[0].source_handle == "bottom"
+    assert edges[0].target_handle == "top-t"
+    assert edges[0].type == "iot"
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_skips_duplicate_edge(
+    client: AsyncClient, headers, db_session
+):
+    """Re-running the resolution does not create a second edge for the same pair."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, PendingDevice, PendingDeviceLink
+
+    coord, pending = await _seed_zigbee_pending_pair(db_session)
+    body = {"label": "router_1", "type": "zigbee_router", "ip": None, "status": "unknown", "services": []}
+    await client.post(f"/api/v1/scan/pending/{pending.id}/approve", json=body, headers=headers)
+
+    # Simulate a second pending row + link between same coord and a new device,
+    # but keep an existing edge in place to verify dedupe also handles
+    # the swapped-direction case.
+    new_pending = PendingDevice(
+        ieee_address="0xR1B",
+        friendly_name="r1b",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add(new_pending)
+    db_session.add(
+        PendingDeviceLink(source_ieee="0xCOORD", target_ieee="0xR1B", discovery_source="zigbee")
+    )
+    await db_session.commit()
+    res = await client.post(
+        f"/api/v1/scan/pending/{new_pending.id}/approve", json=body, headers=headers
+    )
+    assert res.json()["edges_created"] == 1  # only the new pair
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 2  # original + new, no duplicate
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_skips_when_other_endpoint_still_pending(
+    client: AsyncClient, headers, db_session
+):
+    """Both endpoints pending → no edge yet, link row preserved for later."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, PendingDevice, PendingDeviceLink
+
+    a = PendingDevice(
+        ieee_address="0xA",
+        friendly_name="a",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    b = PendingDevice(
+        ieee_address="0xB",
+        friendly_name="b",
+        suggested_type="zigbee_enddevice",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add_all([a, b])
+    db_session.add(
+        PendingDeviceLink(source_ieee="0xA", target_ieee="0xB", discovery_source="zigbee")
+    )
+    await db_session.commit()
+
+    res = await client.post(
+        f"/api/v1/scan/pending/{a.id}/approve",
+        json={
+            "label": "a",
+            "type": "zigbee_router",
+            "ip": None,
+            "status": "unknown",
+            "services": [],
+        },
+        headers=headers,
+    )
+    assert res.status_code == 200
+    assert res.json()["edges_created"] == 0
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert edges == []
+    links = (await db_session.execute(select(PendingDeviceLink))).scalars().all()
+    assert len(links) == 1  # preserved for later resolution
+
+
+@pytest.mark.asyncio
+async def test_approve_zigbee_resolves_link_after_second_approval(
+    client: AsyncClient, headers, db_session
+):
+    """First approval keeps link; second approval creates the edge."""
+    from sqlalchemy import select
+
+    from app.db.models import Edge, PendingDevice, PendingDeviceLink
+
+    a = PendingDevice(
+        ieee_address="0xA",
+        friendly_name="a",
+        suggested_type="zigbee_router",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    b = PendingDevice(
+        ieee_address="0xB",
+        friendly_name="b",
+        suggested_type="zigbee_enddevice",
+        status="pending",
+        discovery_source="zigbee",
+    )
+    db_session.add_all([a, b])
+    db_session.add(
+        PendingDeviceLink(source_ieee="0xA", target_ieee="0xB", discovery_source="zigbee")
+    )
+    await db_session.commit()
+
+    body = {"label": "x", "type": "zigbee_router", "ip": None, "status": "unknown", "services": []}
+    await client.post(f"/api/v1/scan/pending/{a.id}/approve", json=body, headers=headers)
+    res = await client.post(f"/api/v1/scan/pending/{b.id}/approve", json=body, headers=headers)
+    assert res.json()["edges_created"] == 1
+
+    edges = (await db_session.execute(select(Edge))).scalars().all()
+    assert len(edges) == 1
+    links = (await db_session.execute(select(PendingDeviceLink))).scalars().all()
+    assert links == []  # consumed

backend/tests/test_scanner.py

@@ -0,0 +1,535 @@
+"""Tests for scanner: two-phase nmap, mDNS discovery, run_scan integration."""
+import uuid
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from sqlalchemy import select as sa_select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import StaticPool
+
+from app.db.database import Base
+from app.db.models import Node, PendingDevice, ScanRun
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_run_id() -> str:
+    return str(uuid.uuid4())
+
+
+@pytest.fixture
+async def mem_db():
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    yield factory
+    await engine.dispose()
+
+
+def _make_scan_run(run_id: str) -> ScanRun:
+    return ScanRun(id=run_id, status="running", ranges=["192.168.1.0/24"])
+
+
+# ---------------------------------------------------------------------------
+# _ping_sweep
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_ping_sweep_returns_alive_hosts():
+    from app.services.scanner import _ping_sweep
+
+    async def fake_ping(ip: str) -> str | None:
+        return ip if ip in {"192.168.1.1", "192.168.1.2"} else None
+
+    with patch("app.services.scanner._ping_sweep", wraps=None):
+        pass  # just ensure import is fine
+
+    # Patch asyncio.create_subprocess_exec to simulate ping responses
+    responding = {"192.168.1.1", "192.168.1.2"}
+
+    async def mock_subprocess(*args, **kwargs):
+        ip = args[-1]
+        proc = MagicMock()
+        proc.returncode = 0 if ip in responding else 1
+        proc.wait = AsyncMock(return_value=proc.returncode)
+        return proc
+
+    with patch("asyncio.create_subprocess_exec", side_effect=mock_subprocess), \
+         patch("app.services.scanner._arp_table_hosts", return_value={}), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = await _ping_sweep("192.168.1.0/30")  # .1 .2 only in /30
+
+    assert "192.168.1.1" in result
+    assert "192.168.1.2" in result
+    for host in result.values():
+        assert host["open_ports"] == []
+
+
+@pytest.mark.asyncio
+async def test_ping_sweep_excludes_non_responding():
+    from app.services.scanner import _ping_sweep
+
+    async def mock_subprocess(*args, **kwargs):
+        ip = args[-1]
+        proc = MagicMock()
+        proc.returncode = 0 if ip == "192.168.1.1" else 1
+        proc.wait = AsyncMock(return_value=proc.returncode)
+        return proc
+
+    with patch("asyncio.create_subprocess_exec", side_effect=mock_subprocess), \
+         patch("app.services.scanner._arp_table_hosts", return_value={}), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = await _ping_sweep("192.168.1.0/30")
+
+    assert "192.168.1.1" in result
+    assert "192.168.1.2" not in result
+
+
+@pytest.mark.asyncio
+async def test_ping_sweep_supplements_with_arp_cache():
+    """Devices that block ICMP but appear in ARP cache should still be discovered."""
+    from app.services.scanner import _ping_sweep
+
+    async def mock_subprocess(*args, **kwargs):
+        proc = MagicMock()
+        proc.returncode = 1  # all pings fail
+        proc.wait = AsyncMock(return_value=1)
+        return proc
+
+    arp_extra = {
+        "192.168.1.10": {"ip": "192.168.1.10", "mac": "aa:bb:cc:dd:ee:10", "hostname": None, "os": None, "open_ports": []},
+    }
+
+    with patch("asyncio.create_subprocess_exec", side_effect=mock_subprocess), \
+         patch("app.services.scanner._arp_table_hosts", return_value=arp_extra), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = await _ping_sweep("192.168.1.0/24")
+
+    assert "192.168.1.10" in result
+    assert result["192.168.1.10"]["mac"] == "aa:bb:cc:dd:ee:10"
+
+
+@pytest.mark.asyncio
+async def test_ping_sweep_enriches_mac_from_arp_cache():
+    """Ping-alive hosts with no ARP entry get their MAC from the ARP cache."""
+    from app.services.scanner import _ping_sweep
+
+    async def mock_subprocess(*args, **kwargs):
+        ip = args[-1]
+        proc = MagicMock()
+        proc.returncode = 0 if ip == "192.168.1.1" else 1
+        proc.wait = AsyncMock(return_value=proc.returncode)
+        return proc
+
+    arp_extra = {
+        "192.168.1.1": {"ip": "192.168.1.1", "mac": "de:ad:be:ef:00:01", "hostname": None, "os": None, "open_ports": []},
+    }
+
+    with patch("asyncio.create_subprocess_exec", side_effect=mock_subprocess), \
+         patch("app.services.scanner._arp_table_hosts", return_value=arp_extra), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = await _ping_sweep("192.168.1.0/30")
+
+    assert result["192.168.1.1"]["mac"] == "de:ad:be:ef:00:01"
+
+
+# ---------------------------------------------------------------------------
+# _arp_table_hosts
+# ---------------------------------------------------------------------------
+
+def test_arp_table_hosts_parses_proc_net_arp():
+    import io  # noqa: PLC0415
+
+    from app.services.scanner import _arp_table_hosts
+
+    arp_content = (
+        "IP address       HW type     Flags       HW address            Mask     Device\n"
+        "192.168.1.1      0x1         0x2         aa:bb:cc:dd:ee:01     *        eth0\n"
+        "192.168.1.50     0x1         0x2         aa:bb:cc:dd:ee:02     *        eth0\n"
+        "10.0.0.1         0x1         0x2         aa:bb:cc:dd:ee:03     *        eth0\n"  # outside subnet
+        "192.168.1.99     0x1         0x2         00:00:00:00:00:00     *        eth0\n"  # incomplete
+    )
+
+    mock_file = MagicMock()
+    mock_file.__enter__ = MagicMock(return_value=io.StringIO(arp_content))
+    mock_file.__exit__ = MagicMock(return_value=False)
+
+    with patch("builtins.open", return_value=mock_file), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = _arp_table_hosts("192.168.1.0/24")
+
+    assert "192.168.1.1" in result
+    assert "192.168.1.50" in result
+    assert "10.0.0.1" not in result   # outside target subnet
+    assert "192.168.1.99" not in result  # zero MAC skipped
+
+
+def test_arp_table_hosts_parses_macos_arp_output():
+    from app.services.scanner import _arp_table_hosts
+
+    arp_output = (
+        "router.lan (192.168.1.1) at aa:bb:cc:dd:ee:01 on en0 ifscope [ethernet]\n"
+        "device.lan (192.168.1.20) at aa:bb:cc:dd:ee:02 on en0 ifscope [ethernet]\n"
+        "? (192.168.1.99) at (incomplete) on en0 ifscope [ethernet]\n"
+        "? (10.0.0.1) at aa:bb:cc:dd:ee:04 on en0 ifscope [ethernet]\n"  # outside subnet
+    )
+
+    mock_result = MagicMock()
+    mock_result.stdout = arp_output
+
+    with patch("builtins.open", side_effect=FileNotFoundError), \
+         patch("subprocess.run", return_value=mock_result), \
+         patch("app.services.scanner._resolve_hostname", return_value=None):
+        result = _arp_table_hosts("192.168.1.0/24")
+
+    assert "192.168.1.1" in result
+    assert "192.168.1.20" in result
+    assert "192.168.1.99" not in result   # incomplete MAC
+    assert "10.0.0.1" not in result       # outside subnet
+
+
+# ---------------------------------------------------------------------------
+# _nmap_scan_single (Phase 2 per-IP worker)
+# ---------------------------------------------------------------------------
+
+def test_nmap_scan_single_detects_open_ports():
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.10", "hostname": None, "mac": None, "os": None, "open_ports": []}
+
+    # Build a realistic host entry: protocols → ports → port info
+    port_info = {80: {"state": "open", "product": "nginx", "version": "1.24"}}
+    mock_host = MagicMock()
+    mock_host.all_protocols.return_value = ["tcp"]
+    mock_host.__getitem__ = MagicMock(return_value=port_info)
+    mock_host.get.return_value = {}
+
+    mock_nm = MagicMock()
+    mock_nm.all_hosts.return_value = ["192.168.1.10"]
+    mock_nm.__getitem__ = MagicMock(return_value=mock_host)
+
+    with patch("app.services.scanner.nmap.PortScanner", return_value=mock_nm), \
+         patch("app.services.scanner._extract_os", return_value=None):
+        result = _nmap_scan_single(host)
+
+    assert len(result["open_ports"]) == 1
+    assert result["open_ports"][0]["port"] == 80
+    assert result["open_ports"][0]["banner"] == "nginx 1.24"
+
+
+def test_nmap_scan_single_returns_host_unchanged_on_error():
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.20", "hostname": None, "mac": None, "os": None, "open_ports": []}
+    mock_nm = MagicMock()
+    mock_nm.scan.side_effect = Exception("nmap error")
+
+    with patch("app.services.scanner.nmap.PortScanner", return_value=mock_nm):
+        result = _nmap_scan_single(host)
+
+    assert result["ip"] == "192.168.1.20"
+    assert result["open_ports"] == []
+
+
+def test_nmap_scan_single_returns_host_unchanged_when_no_results():
+    """Host confirmed alive in Phase 1 but all ports filtered — keep it with empty ports."""
+    from app.services.scanner import _nmap_scan_single
+
+    host = {"ip": "192.168.1.30", "hostname": "shelly1.lan", "mac": "34:94:54:aa:bb:cc", "os": None, "open_ports": []}
+    mock_nm = MagicMock()
+    mock_nm.all_hosts.return_value = []  # no results
+
+    with patch("app.services.scanner.nmap.PortScanner", return_value=mock_nm):
+        result = _nmap_scan_single(host)
+
+    assert result["ip"] == "192.168.1.30"
+    assert result["open_ports"] == []
+    assert result["mac"] == "34:94:54:aa:bb:cc"  # preserved from Phase 1
+
+
+# ---------------------------------------------------------------------------
+# _nmap_scan
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_nmap_scan_uses_mock_when_nmap_unavailable():
+    from app.services.scanner import _nmap_scan
+
+    with patch("app.services.scanner._NMAP_AVAILABLE", False):
+        result = await _nmap_scan("192.168.1.0/24")
+
+    assert len(result) == 1
+    assert result[0]["ip"] == "192.168.1.99"
+
+
+@pytest.mark.asyncio
+async def test_nmap_scan_raises_on_sweep_error():
+    from app.services.scanner import _nmap_scan
+
+    with patch("app.services.scanner._ping_sweep", side_effect=Exception("ping sweep failed")), \
+         pytest.raises(RuntimeError, match="ping sweep failed"):
+        await _nmap_scan("192.168.1.0/24")
+
+
+# ---------------------------------------------------------------------------
+# _mdns_discover
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_mdns_discover_returns_empty_when_zeroconf_unavailable():
+    from app.services.scanner import _mdns_discover
+
+    with patch("app.services.scanner._ZEROCONF_AVAILABLE", False):
+        result = await _mdns_discover()
+
+    assert result == []
+
+
+@pytest.mark.asyncio
+async def test_mdns_discover_returns_devices():
+    from app.services.scanner import _mdns_discover
+
+    mock_info = MagicMock()
+    mock_info.addresses = [b"\xc0\xa8\x01\x50"]  # 192.168.1.80
+    mock_info.server = "shelly1.local."
+    mock_info.port = 80
+    mock_info.async_request = AsyncMock(return_value=True)
+
+    mock_browser = AsyncMock()
+    mock_browser.async_cancel = AsyncMock()
+
+    # Simulate a service being found during the sleep
+    captured_handler: list = []
+
+    def fake_browser(zc, types, handlers):
+        captured_handler.extend(handlers)
+        return mock_browser
+
+    from zeroconf import ServiceStateChange
+
+    async def fake_sleep(t):
+        # Fire the handler as if a device was discovered
+        for h in captured_handler:
+            h(None, "_shelly._tcp.local.", "Shelly1._shelly._tcp.local.", ServiceStateChange.Added)
+
+    mock_azc = AsyncMock()
+    mock_azc.__aenter__ = AsyncMock(return_value=mock_azc)
+    mock_azc.__aexit__ = AsyncMock(return_value=None)
+    mock_azc.zeroconf = MagicMock()
+
+    with patch("app.services.scanner._ZEROCONF_AVAILABLE", True), \
+         patch("app.services.scanner.AsyncZeroconf", return_value=mock_azc), \
+         patch("app.services.scanner.AsyncServiceBrowser", side_effect=fake_browser), \
+         patch("app.services.scanner.AsyncServiceInfo", return_value=mock_info), \
+         patch("asyncio.sleep", side_effect=fake_sleep):
+        result = await _mdns_discover(timeout=0.01)
+
+    assert len(result) == 1
+    assert result[0]["ip"] == "192.168.1.80"
+    assert result[0]["hostname"] == "shelly1.local."
+
+
+# ---------------------------------------------------------------------------
+# _nmap_port_scan (Phase 2 concurrency)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_nmap_port_scan_returns_empty_when_no_alive_hosts():
+    from app.services.scanner import _nmap_port_scan
+
+    result = await _nmap_port_scan({})
+    assert result == []
+
+
+@pytest.mark.asyncio
+async def test_nmap_port_scan_tolerates_single_host_exception():
+    """A single per-host failure should not abort the entire Phase 2 gather."""
+    from app.services.scanner import _nmap_port_scan
+
+    hosts = {
+        "192.168.1.1": {"ip": "192.168.1.1", "hostname": None, "mac": None, "os": None, "open_ports": []},
+        "192.168.1.2": {"ip": "192.168.1.2", "hostname": None, "mac": None, "os": None, "open_ports": []},
+    }
+
+    call_count = 0
+
+    def _flaky_scan(host_dict):
+        nonlocal call_count
+        call_count += 1
+        if host_dict["ip"] == "192.168.1.1":
+            raise RuntimeError("simulated nmap crash")
+        return host_dict
+
+    with patch("app.services.scanner._nmap_scan_single", side_effect=_flaky_scan), \
+         patch("app.services.scanner._NMAP_AVAILABLE", True):
+        result = await _nmap_port_scan(hosts)
+
+    assert call_count == 2
+    # The crashing host is dropped; the healthy one survives
+    assert len(result) == 1
+    assert result[0]["ip"] == "192.168.1.2"
+
+
+# ---------------------------------------------------------------------------
+# run_scan integration
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_run_scan_adds_nmap_devices_as_pending(mem_db):
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        await session.commit()
+
+    nmap_hosts = [{"ip": "192.168.1.5", "hostname": "device.lan", "mac": None, "os": None, "open_ports": []}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=nmap_hosts), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        result = await session.execute(sa_select(PendingDevice))
+        devices = result.scalars().all()
+
+    assert any(d.ip == "192.168.1.5" for d in devices)
+
+
+@pytest.mark.asyncio
+async def test_run_scan_mdns_only_device_added(mem_db):
+    """Devices found only by mDNS (not nmap) should appear in pending_devices."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        await session.commit()
+
+    mdns_hosts = [{"ip": "192.168.1.80", "hostname": "shelly1.local.", "mac": None, "os": None, "open_ports": [{"port": 80, "protocol": "tcp", "banner": ""}]}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=[]), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=mdns_hosts), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.80"))
+        device = result.scalar_one_or_none()
+
+    assert device is not None
+    assert device.status == "pending"
+    assert device.discovery_source == "mdns"
+
+
+@pytest.mark.asyncio
+async def test_run_scan_mdns_skipped_if_already_in_nmap(mem_db):
+    """If nmap and mDNS both find the same IP, it should not be double-counted."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        await session.commit()
+
+    shared_host = {"ip": "192.168.1.10", "hostname": "device.lan", "mac": None, "os": None, "open_ports": []}
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=[shared_host]), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[shared_host]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.10"))
+        devices = result.scalars().all()
+
+    assert len(devices) == 1  # not duplicated
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_canvas_nodes(mem_db):
+    """Hosts already approved onto the canvas must be skipped."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        canvas_node = Node(
+            id=str(uuid.uuid4()), label="PVE", type="proxmox",
+            ip="192.168.1.100", status="online",
+        )
+        session.add(canvas_node)
+        await session.commit()
+
+    nmap_hosts = [{"ip": "192.168.1.100", "hostname": "pve.lan", "mac": None, "os": None, "open_ports": []}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=nmap_hosts), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        result = await session.execute(sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.100"))
+        assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_skips_hidden_devices(mem_db):
+    """Hosts hidden by the user must not re-appear in pending."""
+    from app.services.scanner import run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        hidden = PendingDevice(ip="192.168.1.55", status="hidden")
+        session.add(hidden)
+        await session.commit()
+
+    nmap_hosts = [{"ip": "192.168.1.55", "hostname": None, "mac": None, "os": None, "open_ports": []}]
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=nmap_hosts), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        result = await session.execute(
+            sa_select(PendingDevice).where(PendingDevice.ip == "192.168.1.55", PendingDevice.status == "pending")
+        )
+        assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+async def test_run_scan_cancelled_marks_status_cancelled(mem_db):
+    """Cancelling a running scan sets the ScanRun status to 'cancelled'."""
+    from app.services.scanner import request_cancel, run_scan
+
+    run_id = _make_run_id()
+    async with mem_db() as session:
+        session.add(_make_scan_run(run_id))
+        await session.commit()
+
+    request_cancel(run_id)
+
+    async with mem_db() as session:
+        with patch("app.services.scanner._nmap_scan", return_value=[]), \
+             patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+             patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+            await run_scan(["192.168.1.0/24"], session, run_id)
+
+    async with mem_db() as session:
+        run = await session.get(ScanRun, run_id)
+        assert run is not None
+        assert run.status == "cancelled"

backend/tests/test_settings.py

@@ -0,0 +1,47 @@
+"""Tests for GET/POST /api/v1/settings."""
+from unittest.mock import patch
+
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.fixture
+async def headers(client: AsyncClient):
+    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+    token = res.json()["access_token"]
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.mark.asyncio
+async def test_get_settings_requires_auth(client: AsyncClient):
+    res = await client.get("/api/v1/settings")
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_settings_returns_interval(client: AsyncClient, headers):
+    res = await client.get("/api/v1/settings", headers=headers)
+    assert res.status_code == 200
+    data = res.json()
+    assert "interval_seconds" in data
+    assert isinstance(data["interval_seconds"], int)
+
+
+@pytest.mark.asyncio
+async def test_update_settings_saves_interval(client: AsyncClient, headers):
+    with patch("app.api.routes.settings.settings") as mock_settings:
+        mock_settings.status_checker_interval = 60
+        mock_settings.save_overrides = lambda: None
+        res = await client.post(
+            "/api/v1/settings",
+            json={"interval_seconds": 120},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    assert res.json()["interval_seconds"] == 120
+
+
+@pytest.mark.asyncio
+async def test_update_settings_requires_auth(client: AsyncClient):
+    res = await client.post("/api/v1/settings", json={"interval_seconds": 30})
+    assert res.status_code == 401

backend/tests/test_status.py

@@ -22,24 +22,33 @@ def _make_token() -> str:
 # ---------------------------------------------------------------------------
 
 def test_websocket_rejected_without_token():
-    """Connection with no token must be closed before being accepted."""
-    with TestClient(app) as client, pytest.raises(WebSocketDisconnect), client.websocket_connect("/api/v1/status/ws/status"):
-        pass
+    """Connection that sends no token field must be closed with 1008."""
+    with TestClient(app) as client, pytest.raises(WebSocketDisconnect), client.websocket_connect("/api/v1/status/ws/status") as ws:
+        ws.send_text(json.dumps({}))  # missing token field
+        ws.receive_text()  # triggers WebSocketDisconnect from server close
 
 
 def test_websocket_rejected_with_invalid_token():
-    """Connection with a garbage token must be closed."""
-    with TestClient(app) as client, pytest.raises(WebSocketDisconnect), client.websocket_connect("/api/v1/status/ws/status?token=not-a-valid-jwt"):
-        pass
+    """Connection that sends a garbage token must be closed."""
+    with TestClient(app) as client, pytest.raises(WebSocketDisconnect), client.websocket_connect("/api/v1/status/ws/status") as ws:
+        ws.send_text(json.dumps({"token": "not-a-valid-jwt"}))
+        ws.receive_text()
+
+
+def test_websocket_rejected_with_malformed_json():
+    """Connection that sends non-JSON as auth must be closed."""
+    with TestClient(app) as client, pytest.raises(WebSocketDisconnect), client.websocket_connect("/api/v1/status/ws/status") as ws:
+        ws.send_text("not-json")
+        ws.receive_text()
 
 
 def test_websocket_accepted_with_valid_token():
-    """Connection with a valid JWT must be accepted and kept open."""
+    """Connection that sends a valid JWT as first message must be accepted."""
     token = _make_token()
-    with TestClient(app) as client, client.websocket_connect(f"/api/v1/status/ws/status?token={token}") as ws:
-        # Connection is open — we can send a ping and it should not raise
+    with TestClient(app) as client, client.websocket_connect("/api/v1/status/ws/status") as ws:
+        ws.send_text(json.dumps({"token": token}))
+        # Connection is open — subsequent messages should not raise
         ws.send_text("ping")
-            # Server keeps the connection open (no disconnect expected)
 
 
 # ---------------------------------------------------------------------------

backend/tests/test_status_checker.py

@@ -3,7 +3,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from app.services.status_checker import _tcp_connect, check_node
+from app.services.status_checker import _ping, _tcp_connect, check_node
 
 # --- check_node dispatcher ---
 
@@ -149,6 +149,73 @@ async def test_check_node_exception_returns_offline():
     assert result["response_time_ms"] is None
 
 
+# --- _ping platform args ---
+
+@pytest.mark.asyncio
+async def test_ping_uses_unix_args_on_non_windows():
+    captured = {}
+
+    async def fake_exec(*args, **kwargs):
+        captured["args"] = args
+        proc = MagicMock()
+        proc.returncode = 0
+        proc.wait = AsyncMock()
+        return proc
+
+    with patch("app.services.status_checker.sys.platform", "linux"), \
+         patch("asyncio.create_subprocess_exec", side_effect=fake_exec):
+        await _ping("192.168.1.1")
+
+    assert "-c" in captured["args"]
+    assert "-W" in captured["args"]
+    assert "-n" not in captured["args"]
+    # Linux: -W is in seconds; 1s is the intended timeout
+    w_idx = captured["args"].index("-W")
+    assert captured["args"][w_idx + 1] == "1"
+
+
+@pytest.mark.asyncio
+async def test_ping_uses_macos_millisecond_timeout():
+    """macOS ping(8) -W is milliseconds, not seconds. 1ms would fail any RTT >1ms."""
+    captured = {}
+
+    async def fake_exec(*args, **kwargs):
+        captured["args"] = args
+        proc = MagicMock()
+        proc.returncode = 0
+        proc.wait = AsyncMock()
+        return proc
+
+    with patch("app.services.status_checker.sys.platform", "darwin"), \
+         patch("asyncio.create_subprocess_exec", side_effect=fake_exec):
+        await _ping("192.168.1.1")
+
+    assert "-c" in captured["args"]
+    assert "-W" in captured["args"]
+    w_idx = captured["args"].index("-W")
+    assert captured["args"][w_idx + 1] == "1000"
+
+
+@pytest.mark.asyncio
+async def test_ping_uses_windows_args_on_win32():
+    captured = {}
+
+    async def fake_exec(*args, **kwargs):
+        captured["args"] = args
+        proc = MagicMock()
+        proc.returncode = 0
+        proc.wait = AsyncMock()
+        return proc
+
+    with patch("app.services.status_checker.sys.platform", "win32"), \
+         patch("asyncio.create_subprocess_exec", side_effect=fake_exec):
+        await _ping("192.168.1.1")
+
+    assert "-n" in captured["args"]
+    assert "-w" in captured["args"]
+    assert "-c" not in captured["args"]
+
+
 # --- _tcp_connect ---
 
 @pytest.mark.asyncio

backend/tests/test_zigbee_router.py

@@ -0,0 +1,417 @@
+"""API endpoint tests for /api/v1/zigbee/*."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from httpx import AsyncClient
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+async def headers(client: AsyncClient):
+    res = await client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin"})
+    token = res.json()["access_token"]
+    return {"Authorization": f"Bearer {token}"}
+
+
+# ---------------------------------------------------------------------------
+# /api/v1/zigbee/test-connection
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_test_connection_success(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.test_mqtt_connection") as mock_conn:
+        mock_conn.return_value = True
+        res = await client.post(
+            "/api/v1/zigbee/test-connection",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["connected"] is True
+    assert "success" in data["message"].lower()
+
+
+@pytest.mark.asyncio
+async def test_test_connection_failure(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.test_mqtt_connection") as mock_conn:
+        mock_conn.side_effect = ConnectionError("Connection refused")
+        res = await client.post(
+            "/api/v1/zigbee/test-connection",
+            json={"mqtt_host": "bad-host", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["connected"] is False
+    assert "refused" in data["message"].lower()
+
+
+@pytest.mark.asyncio
+async def test_test_connection_requires_auth(client: AsyncClient) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/test-connection",
+        json={"mqtt_host": "localhost", "mqtt_port": 1883},
+    )
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_test_connection_invalid_port(client: AsyncClient, headers: dict) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/test-connection",
+        json={"mqtt_host": "localhost", "mqtt_port": 99999},
+        headers=headers,
+    )
+    assert res.status_code == 422  # pydantic validation error
+
+
+# ---------------------------------------------------------------------------
+# /api/v1/zigbee/import
+# ---------------------------------------------------------------------------
+
+_SAMPLE_NODES = [
+    {
+        "id": "0x00000000",
+        "label": "Coordinator",
+        "type": "zigbee_coordinator",
+        "ieee_address": "0x00000000",
+        "friendly_name": "Coordinator",
+        "device_type": "Coordinator",
+        "model": None,
+        "vendor": None,
+        "lqi": None,
+        "parent_id": None,
+    },
+    {
+        "id": "0x00000001",
+        "label": "router_1",
+        "type": "zigbee_router",
+        "ieee_address": "0x00000001",
+        "friendly_name": "router_1",
+        "device_type": "Router",
+        "model": "CC2530",
+        "vendor": "Texas Instruments",
+        "lqi": 230,
+        "parent_id": "0x00000000",
+    },
+]
+
+_SAMPLE_EDGES = [
+    {"source": "0x00000000", "target": "0x00000001"},
+]
+
+
+@pytest.mark.asyncio
+async def test_import_success(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={
+                "mqtt_host": "localhost",
+                "mqtt_port": 1883,
+                "base_topic": "zigbee2mqtt",
+            },
+            headers=headers,
+        )
+
+    assert res.status_code == 200
+    data = res.json()
+    assert data["device_count"] == 2
+    assert len(data["nodes"]) == 2
+    assert len(data["edges"]) == 1
+    coordinator = next(n for n in data["nodes"] if n["type"] == "zigbee_coordinator")
+    assert coordinator["ieee_address"] == "0x00000000"
+
+
+@pytest.mark.asyncio
+async def test_import_with_credentials(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = ([], [])
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={
+                "mqtt_host": "localhost",
+                "mqtt_port": 1883,
+                "mqtt_username": "admin",
+                "mqtt_password": "secret",
+                "base_topic": "z2m",
+            },
+            headers=headers,
+        )
+    assert res.status_code == 200
+    mock_fetch.assert_called_once_with(
+        mqtt_host="localhost",
+        mqtt_port=1883,
+        base_topic="z2m",
+        username="admin",
+        password="secret",
+        tls=False,
+        tls_insecure=False,
+    )
+
+
+@pytest.mark.asyncio
+async def test_import_connection_error_returns_502(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.side_effect = ConnectionError("broker unreachable")
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={"mqtt_host": "bad-host", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 502
+    assert "broker unreachable" in res.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_import_timeout_returns_504(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.side_effect = TimeoutError("timed out")
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 504
+
+
+@pytest.mark.asyncio
+async def test_import_malformed_payload_returns_422(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.side_effect = ValueError("malformed response")
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_import_requires_auth(client: AsyncClient) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/import",
+        json={"mqtt_host": "localhost", "mqtt_port": 1883},
+    )
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_import_empty_network(client: AsyncClient, headers: dict) -> None:
+    """An empty Zigbee network (coordinator only) is a valid response."""
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = ([], [])
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["device_count"] == 0
+    assert data["nodes"] == []
+    assert data["edges"] == []
+
+
+@pytest.mark.asyncio
+async def test_import_missing_mqtt_host(client: AsyncClient, headers: dict) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/import",
+        json={"mqtt_port": 1883},
+        headers=headers,
+    )
+    assert res.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_import_with_tls_passes_flags(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:
+        mock_fetch.return_value = ([], [])
+        res = await client.post(
+            "/api/v1/zigbee/import",
+            json={
+                "mqtt_host": "broker.example.com",
+                "mqtt_port": 8883,
+                "mqtt_tls": True,
+            },
+            headers=headers,
+        )
+    assert res.status_code == 200
+    kwargs = mock_fetch.call_args.kwargs
+    assert kwargs["tls"] is True
+    assert kwargs["tls_insecure"] is False
+
+
+@pytest.mark.asyncio
+async def test_import_tls_insecure_requires_tls(client: AsyncClient, headers: dict) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/import",
+        json={
+            "mqtt_host": "broker.example.com",
+            "mqtt_port": 1883,
+            "mqtt_tls": False,
+            "mqtt_tls_insecure": True,
+        },
+        headers=headers,
+    )
+    assert res.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# /api/v1/zigbee/import-pending
+# ---------------------------------------------------------------------------
+
+_PENDING_NODES = [
+    {
+        "id": "0xCOORD",
+        "label": "Coordinator",
+        "type": "zigbee_coordinator",
+        "ieee_address": "0xCOORD",
+        "friendly_name": "Coordinator",
+        "device_type": "Coordinator",
+        "model": None,
+        "vendor": None,
+        "lqi": None,
+        "parent_id": None,
+    },
+    {
+        "id": "0xR1",
+        "label": "router_1",
+        "type": "zigbee_router",
+        "ieee_address": "0xR1",
+        "friendly_name": "router_1",
+        "device_type": "Router",
+        "model": "CC2530",
+        "vendor": "TI",
+        "lqi": 220,
+        "parent_id": "0xCOORD",
+    },
+    {
+        "id": "0xE1",
+        "label": "bulb_kitchen",
+        "type": "zigbee_enddevice",
+        "ieee_address": "0xE1",
+        "friendly_name": "bulb_kitchen",
+        "device_type": "EndDevice",
+        "model": "TRADFRI",
+        "vendor": "IKEA",
+        "lqi": 180,
+        "parent_id": "0xR1",
+    },
+]
+
+_PENDING_EDGES = [
+    {"source": "0xCOORD", "target": "0xR1"},
+    {"source": "0xR1", "target": "0xE1"},
+]
+
+
+@pytest.mark.asyncio
+async def test_import_pending_endpoint_creates_zigbee_scan_run(
+    client: AsyncClient, headers: dict
+) -> None:
+    """Endpoint returns a ScanRun (kind=zigbee, status=running) immediately;
+    the actual networkmap fetch + pending persist runs in the background."""
+    from unittest.mock import AsyncMock
+
+    with patch(
+        "app.api.routes.zigbee._background_zigbee_import",
+        new_callable=AsyncMock,
+    ):
+        res = await client.post(
+            "/api/v1/zigbee/import-pending",
+            json={"mqtt_host": "localhost", "mqtt_port": 1883},
+            headers=headers,
+        )
+    assert res.status_code == 200
+    run = res.json()
+    assert run["kind"] == "zigbee"
+    assert run["status"] == "running"
+    assert run["ranges"] == ["localhost:1883"]
+
+
+@pytest.mark.asyncio
+async def test_persist_pending_import_creates_coordinator_and_pending(
+    db_session,
+) -> None:
+    from app.api.routes.zigbee import _persist_pending_import
+
+    result = await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
+    assert result.device_count == 3
+    assert result.pending_created == 2
+    assert result.pending_updated == 0
+    assert result.coordinator is not None
+    assert result.coordinator.ieee_address == "0xCOORD"
+    assert result.coordinator_already_existed is False
+    assert result.links_recorded == 2
+
+
+@pytest.mark.asyncio
+async def test_persist_pending_import_idempotent_updates_existing(
+    db_session,
+) -> None:
+    from app.api.routes.zigbee import _persist_pending_import
+
+    await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
+
+    bumped = [dict(n) for n in _PENDING_NODES]
+    bumped[1]["lqi"] = 99
+    result = await _persist_pending_import(db_session, bumped, _PENDING_EDGES)
+
+    assert result.pending_created == 0
+    assert result.pending_updated == 2
+    assert result.coordinator_already_existed is True
+    assert result.links_recorded == 2
+
+
+@pytest.mark.asyncio
+async def test_persist_pending_import_replaces_links(db_session) -> None:
+    from sqlalchemy import select
+
+    from app.api.routes.zigbee import _persist_pending_import
+    from app.db.models import PendingDeviceLink
+
+    await _persist_pending_import(db_session, _PENDING_NODES, _PENDING_EDGES)
+
+    new_edges = [{"source": "0xCOORD", "target": "0xR1"}]
+    await _persist_pending_import(db_session, _PENDING_NODES[:2], new_edges)
+
+    rows = (await db_session.execute(select(PendingDeviceLink))).scalars().all()
+    assert len(rows) == 1
+    assert (rows[0].source_ieee, rows[0].target_ieee) == ("0xCOORD", "0xR1")
+
+
+@pytest.mark.asyncio
+async def test_import_pending_requires_auth(client: AsyncClient) -> None:
+    res = await client.post(
+        "/api/v1/zigbee/import-pending",
+        json={"mqtt_host": "localhost", "mqtt_port": 1883},
+    )
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_test_connection_with_tls(client: AsyncClient, headers: dict) -> None:
+    with patch("app.api.routes.zigbee.test_mqtt_connection") as mock_conn:
+        mock_conn.return_value = True
+        res = await client.post(
+            "/api/v1/zigbee/test-connection",
+            json={
+                "mqtt_host": "broker.example.com",
+                "mqtt_port": 8883,
+                "mqtt_tls": True,
+                "mqtt_tls_insecure": True,
+            },
+            headers=headers,
+        )
+    assert res.status_code == 200
+    kwargs = mock_conn.call_args.kwargs
+    assert kwargs["tls"] is True
+    assert kwargs["tls_insecure"] is True

backend/tests/test_zigbee_service.py

@@ -0,0 +1,573 @@
+"""Unit tests for zigbee_service: parser and hierarchy builder."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import patch
+
+import aiomqtt  # noqa: F401
+import pytest
+
+from app.services.zigbee_service import (
+    _find_parent_router,
+    _z2m_type_to_homelable,
+    fetch_networkmap,
+    parse_networkmap,
+)
+from app.services.zigbee_service import (
+    test_mqtt_connection as _test_mqtt_connection,
+)
+
+# ---------------------------------------------------------------------------
+# Helper builders — real Z2M `bridge/response/networkmap` shape
+# (data.value.nodes + data.value.links)
+# ---------------------------------------------------------------------------
+
+def _make_node(
+    ieee: str,
+    device_type: str = "EndDevice",
+    friendly_name: str | None = None,
+    model: str | None = None,
+    vendor: str | None = None,
+) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "ieeeAddr": ieee,
+        "type": device_type,
+        "friendlyName": friendly_name or ieee,
+    }
+    if model or vendor:
+        entry["definition"] = {"model": model, "vendor": vendor}
+    return entry
+
+
+def _make_link(source_ieee: str, target_ieee: str, lqi: int = 200) -> dict[str, Any]:
+    return {
+        "source": {"ieeeAddr": source_ieee},
+        "target": {"ieeeAddr": target_ieee},
+        "lqi": lqi,
+    }
+
+
+def _wrap(nodes: list[dict[str, Any]], links: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    return {
+        "data": {
+            "type": "raw",
+            "routes": False,
+            "value": {"nodes": nodes, "links": links or []},
+        },
+        "status": "ok",
+    }
+
+
+# ---------------------------------------------------------------------------
+# _z2m_type_to_homelable
+# ---------------------------------------------------------------------------
+
+class TestZ2mTypeToHomelable:
+    def test_coordinator(self) -> None:
+        assert _z2m_type_to_homelable("Coordinator") == "zigbee_coordinator"
+
+    def test_router(self) -> None:
+        assert _z2m_type_to_homelable("Router") == "zigbee_router"
+
+    def test_enddevice(self) -> None:
+        assert _z2m_type_to_homelable("EndDevice") == "zigbee_enddevice"
+
+    def test_unknown_defaults_to_enddevice(self) -> None:
+        assert _z2m_type_to_homelable("Unknown") == "zigbee_enddevice"
+
+
+# ---------------------------------------------------------------------------
+# parse_networkmap
+# ---------------------------------------------------------------------------
+
+class TestParseNetworkmap:
+    def test_empty_payload(self) -> None:
+        nodes, edges = parse_networkmap({})
+        assert nodes == []
+        assert edges == []
+
+    def test_empty_value(self) -> None:
+        nodes, edges = parse_networkmap(_wrap([], []))
+        assert nodes == []
+        assert edges == []
+
+    def test_coordinator_only(self) -> None:
+        payload = _wrap([_make_node("0x0000000000000000", "Coordinator", "Coordinator")])
+        nodes, edges = parse_networkmap(payload)
+        assert len(nodes) == 1
+        assert nodes[0]["type"] == "zigbee_coordinator"
+        assert nodes[0]["ieee_address"] == "0x0000000000000000"
+        assert edges == []
+
+    def test_coordinator_router_enddevice(self) -> None:
+        coord_ieee = "0x0000000000000000"
+        router_ieee = "0x0000000000000001"
+        end_ieee = "0x0000000000000002"
+
+        payload = _wrap(
+            nodes=[
+                _make_node(coord_ieee, "Coordinator", "Coordinator"),
+                _make_node(router_ieee, "Router", "my_router"),
+                _make_node(end_ieee, "EndDevice"),
+            ],
+            links=[
+                _make_link(coord_ieee, router_ieee),
+                _make_link(router_ieee, end_ieee),
+            ],
+        )
+
+        nodes, edges = parse_networkmap(payload)
+        node_by_id = {n["id"]: n for n in nodes}
+
+        assert coord_ieee in node_by_id
+        assert router_ieee in node_by_id
+        assert end_ieee in node_by_id
+
+        assert node_by_id[coord_ieee]["type"] == "zigbee_coordinator"
+        assert node_by_id[router_ieee]["type"] == "zigbee_router"
+        assert node_by_id[end_ieee]["type"] == "zigbee_enddevice"
+
+        # Parent hierarchy
+        assert node_by_id[router_ieee]["parent_id"] == coord_ieee
+        assert node_by_id[end_ieee]["parent_id"] == router_ieee
+        assert len(edges) == 2
+
+    def test_no_duplicate_nodes(self) -> None:
+        ieee = "0x0000000000000001"
+        payload = _wrap(
+            nodes=[_make_node(ieee, "Router"), _make_node(ieee, "Router")],
+        )
+        nodes, _ = parse_networkmap(payload)
+        assert len(nodes) == 1
+
+    def test_edges_built_correctly(self) -> None:
+        coord = "0x0000"
+        router = "0x0001"
+        payload = _wrap(
+            nodes=[_make_node(coord, "Coordinator"), _make_node(router, "Router")],
+            links=[_make_link(coord, router)],
+        )
+        _, edges = parse_networkmap(payload)
+        assert len(edges) == 1
+        assert edges[0]["source"] == coord
+        assert edges[0]["target"] == router
+
+    def test_friendly_name_used_as_label(self) -> None:
+        payload = _wrap([_make_node("0xABCD", "EndDevice", "Living Room Sensor")])
+        nodes, _ = parse_networkmap(payload)
+        assert nodes[0]["label"] == "Living Room Sensor"
+
+    def test_enddevice_falls_back_to_coordinator_when_no_router(self) -> None:
+        coord = "0x0000"
+        end = "0x0003"
+        payload = _wrap([_make_node(coord, "Coordinator"), _make_node(end, "EndDevice")])
+        nodes, _ = parse_networkmap(payload)
+        end_node = next(n for n in nodes if n["id"] == end)
+        assert end_node["parent_id"] == coord
+
+    def test_missing_ieee_skipped(self) -> None:
+        payload = _wrap([{"type": "EndDevice"}])  # no ieeeAddr
+        nodes, edges = parse_networkmap(payload)
+        assert nodes == []
+        assert edges == []
+
+    def test_lqi_propagated_from_link_to_target_node(self) -> None:
+        coord = "0x0000"
+        end = "0x0001"
+        payload = _wrap(
+            nodes=[_make_node(coord, "Coordinator"), _make_node(end, "EndDevice")],
+            links=[_make_link(coord, end, lqi=180)],
+        )
+        nodes, _ = parse_networkmap(payload)
+        end_node = next(n for n in nodes if n["id"] == end)
+        assert end_node["lqi"] == 180
+
+    def test_definition_model_and_vendor_extracted(self) -> None:
+        payload = _wrap([
+            _make_node("0xAA", "EndDevice", "Sensor", model="WSDCGQ11LM", vendor="Aqara"),
+        ])
+        nodes, _ = parse_networkmap(payload)
+        assert nodes[0]["model"] == "WSDCGQ11LM"
+        assert nodes[0]["vendor"] == "Aqara"
+
+    def test_legacy_shape_without_value_wrapper(self) -> None:
+        """Some Z2M variants put nodes/links directly under data."""
+        payload = {"data": {"nodes": [_make_node("0x01", "Coordinator")], "links": []}}
+        nodes, _ = parse_networkmap(payload)
+        assert len(nodes) == 1
+        assert nodes[0]["type"] == "zigbee_coordinator"
+
+    def test_routes_bool_is_ignored(self) -> None:
+        """`routes: false` echo from the request must not crash the parser."""
+        payload = {"data": {"routes": False, "type": "raw", "value": {"nodes": [], "links": []}}}
+        nodes, edges = parse_networkmap(payload)
+        assert nodes == []
+        assert edges == []
+
+    def test_malformed_nodes_not_list_raises(self) -> None:
+        with pytest.raises(ValueError, match="not a list"):
+            parse_networkmap({"data": {"value": {"nodes": "oops", "links": []}}})
+
+    def test_link_to_unknown_node_dropped(self) -> None:
+        payload = _wrap(
+            nodes=[_make_node("0x01", "Coordinator")],
+            links=[_make_link("0x01", "0xDEAD")],  # 0xDEAD not in nodes
+        )
+        _, edges = parse_networkmap(payload)
+        assert edges == []
+
+    def test_bidirectional_links_yield_single_edge(self) -> None:
+        """Z2M links are bidirectional — every pair appears twice. The output
+        must collapse to a single parent→child edge (no back-link, no dup)."""
+        coord = "0x0000"
+        router = "0x0001"
+        payload = _wrap(
+            nodes=[_make_node(coord, "Coordinator"), _make_node(router, "Router")],
+            links=[
+                _make_link(coord, router),
+                _make_link(router, coord),  # reverse direction
+            ],
+        )
+        _, edges = parse_networkmap(payload)
+        assert edges == [{"source": coord, "target": router}]
+
+    def test_router_mesh_siblings_dropped(self) -> None:
+        """Router↔router mesh paths in `links` must NOT produce sibling edges
+        in the final tree. Each router gets exactly one edge from coordinator."""
+        coord = "0x0000"
+        r1 = "0x0001"
+        r2 = "0x0002"
+        payload = _wrap(
+            nodes=[
+                _make_node(coord, "Coordinator"),
+                _make_node(r1, "Router"),
+                _make_node(r2, "Router"),
+            ],
+            links=[
+                _make_link(coord, r1),
+                _make_link(coord, r2),
+                _make_link(r1, r2),  # mesh sibling — must be dropped
+                _make_link(r2, r1),
+            ],
+        )
+        _, edges = parse_networkmap(payload)
+        pairs = {(e["source"], e["target"]) for e in edges}
+        assert pairs == {(coord, r1), (coord, r2)}
+
+    def test_coordinator_has_no_incoming_edge(self) -> None:
+        coord = "0x0000"
+        end = "0x0001"
+        payload = _wrap(
+            nodes=[_make_node(coord, "Coordinator"), _make_node(end, "EndDevice")],
+            links=[_make_link(end, coord)],  # back-edge from end to coord
+        )
+        _, edges = parse_networkmap(payload)
+        # No edge should target the coordinator
+        assert all(e["target"] != coord for e in edges)
+        assert edges == [{"source": coord, "target": end}]
+
+
+# ---------------------------------------------------------------------------
+# _find_parent_router
+# ---------------------------------------------------------------------------
+
+class TestFindParentRouter:
+    def test_finds_router_as_source(self) -> None:
+        router_ids = {"r1"}
+        edges = [{"source": "r1", "target": "e1"}]
+        assert _find_parent_router("e1", router_ids, edges) == "r1"
+
+    def test_finds_router_as_target(self) -> None:
+        router_ids = {"r1"}
+        edges = [{"source": "e1", "target": "r1"}]
+        assert _find_parent_router("e1", router_ids, edges) == "r1"
+
+    def test_returns_none_when_no_router(self) -> None:
+        router_ids: set[str] = set()
+        edges = [{"source": "e1", "target": "e2"}]
+        assert _find_parent_router("e1", router_ids, edges) is None
+
+    def test_returns_none_empty_edges(self) -> None:
+        assert _find_parent_router("e1", {"r1"}, []) is None
+
+
+# ---------------------------------------------------------------------------
+# fetch_networkmap (integration-style with mocked aiomqtt)
+# ---------------------------------------------------------------------------
+
+SAMPLE_RESPONSE_PAYLOAD = {
+    "data": {
+        "type": "raw",
+        "routes": False,
+        "value": {
+            "nodes": [
+                {
+                    "ieeeAddr": "0x00000000",
+                    "type": "Coordinator",
+                    "friendlyName": "Coordinator",
+                },
+                {
+                    "ieeeAddr": "0x00000001",
+                    "type": "Router",
+                    "friendlyName": "router_1",
+                },
+            ],
+            "links": [
+                {
+                    "source": {"ieeeAddr": "0x00000000"},
+                    "target": {"ieeeAddr": "0x00000001"},
+                    "lqi": 230,
+                }
+            ],
+        },
+    },
+    "status": "ok",
+}
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_success() -> None:
+    """fetch_networkmap returns parsed nodes/edges when MQTT responds normally."""
+
+    class _FakeMessage:
+        topic = "zigbee2mqtt/bridge/response/networkmap"
+        payload = json.dumps(SAMPLE_RESPONSE_PAYLOAD).encode()
+        _yielded = False
+
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            if self._yielded:
+                raise StopAsyncIteration
+            self._yielded = True
+            return self
+
+    class _FakeClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_):
+            pass
+
+        async def subscribe(self, _topic: str) -> None:
+            pass
+
+        async def publish(self, _topic: str, _payload: str) -> None:
+            pass
+
+        @property
+        def messages(self):
+            return _FakeMessage()
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        nodes, edges = await fetch_networkmap(
+            mqtt_host="localhost",
+            mqtt_port=1883,
+            base_topic="zigbee2mqtt",
+        )
+
+    assert any(n["type"] == "zigbee_coordinator" for n in nodes)
+    assert any(n["type"] == "zigbee_router" for n in nodes)
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_connection_error() -> None:
+    """fetch_networkmap raises ConnectionError when MQTT broker is unreachable."""
+
+    class _FakeClient:
+        async def __aenter__(self):
+            raise Exception("Connection refused")
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        with pytest.raises(ConnectionError):
+            await fetch_networkmap(
+                mqtt_host="bad-host",
+                mqtt_port=1883,
+                base_topic="zigbee2mqtt",
+            )
+
+
+@pytest.mark.asyncio
+async def test_test_mqtt_connection_success() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        result = await _test_mqtt_connection("localhost", 1883)
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_test_mqtt_connection_failure() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            raise Exception("refused")
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        with pytest.raises(ConnectionError):
+            await _test_mqtt_connection("bad-host", 1883)
+
+
+# ---------------------------------------------------------------------------
+# TLS context
+# ---------------------------------------------------------------------------
+
+import ssl  # noqa: E402
+
+from app.services.zigbee_service import _build_tls_context  # noqa: E402
+
+
+def test_build_tls_context_secure_verifies_cert() -> None:
+    ctx = _build_tls_context(insecure=False)
+    assert ctx.check_hostname is True
+    assert ctx.verify_mode == ssl.CERT_REQUIRED
+
+
+def test_build_tls_context_insecure_disables_verification() -> None:
+    ctx = _build_tls_context(insecure=True)
+    assert ctx.check_hostname is False
+    assert ctx.verify_mode == ssl.CERT_NONE
+
+
+@pytest.mark.asyncio
+async def test_test_mqtt_connection_passes_tls_context() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        await _test_mqtt_connection("host", 8883, tls=True)
+        kwargs = mock_aiomqtt.Client.call_args.kwargs
+        assert kwargs["tls_context"] is not None
+        assert kwargs["tls_context"].verify_mode == ssl.CERT_REQUIRED
+
+
+@pytest.mark.asyncio
+async def test_test_mqtt_connection_no_tls_context_when_disabled() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        await _test_mqtt_connection("host", 1883, tls=False)
+        assert mock_aiomqtt.Client.call_args.kwargs["tls_context"] is None
+
+
+@pytest.mark.asyncio
+async def test_test_mqtt_connection_insecure_passes_no_verify_context() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        await _test_mqtt_connection("host", 8883, tls=True, tls_insecure=True)
+        ctx = mock_aiomqtt.Client.call_args.kwargs["tls_context"]
+        assert ctx.verify_mode == ssl.CERT_NONE
+        assert ctx.check_hostname is False
+
+
+# ---------------------------------------------------------------------------
+# Sanitize MQTT errors
+# ---------------------------------------------------------------------------
+
+from app.services.zigbee_service import _sanitize_mqtt_error  # noqa: E402
+
+
+def test_sanitize_auth_error_does_not_leak_credentials() -> None:
+    msg = _sanitize_mqtt_error(
+        Exception("Not authorized: bad username or password for user=admin pwd=secret")
+    )
+    assert msg == "Authentication failed"
+    assert "admin" not in msg
+    assert "secret" not in msg
+
+
+def test_sanitize_refused() -> None:
+    assert _sanitize_mqtt_error(Exception("Connection refused")) == "Connection refused by broker"
+
+
+def test_sanitize_dns_failure_strips_host() -> None:
+    msg = _sanitize_mqtt_error(
+        Exception("[Errno 8] nodename nor servname provided, or not known: broker.internal.lan")
+    )
+    assert msg == "Broker hostname could not be resolved"
+    assert "broker.internal.lan" not in msg
+
+
+def test_sanitize_tls_error() -> None:
+    assert _sanitize_mqtt_error(
+        Exception("[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed")
+    ) == "TLS handshake failed"
+
+
+def test_sanitize_unknown_falls_back_to_generic() -> None:
+    msg = _sanitize_mqtt_error(Exception("mqtt://admin:hunter2@broker:1883 weird state"))
+    assert msg == "MQTT connection failed"
+    assert "hunter2" not in msg
+    assert "admin" not in msg
+
+
+@pytest.mark.asyncio
+async def test_fetch_networkmap_does_not_leak_creds_in_connection_error() -> None:
+    class _FakeClient:
+        async def __aenter__(self):
+            raise Exception("Not authorized: rejected mqtt://admin:hunter2@host")
+
+        async def __aexit__(self, *_):
+            pass
+
+    with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:
+        mock_aiomqtt.Client.return_value = _FakeClient()
+        mock_aiomqtt.MqttError = Exception
+
+        with pytest.raises(ConnectionError) as ei:
+            await fetch_networkmap(
+                mqtt_host="host", mqtt_port=1883, base_topic="zigbee2mqtt"
+            )
+    msg = str(ei.value)
+    assert "hunter2" not in msg
+    assert "admin" not in msg
+    assert msg == "Authentication failed"

docker-compose.ci.yml

@@ -0,0 +1,14 @@
+# CI override — exposes backend port 8000 and injects credentials.
+# Usage: docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d backend frontend
+#
+# AUTH_PASSWORD_HASH uses $$ escaping: docker-compose converts $$ → $ before
+# passing to the container, so the backend receives a valid bcrypt hash.
+# This avoids the project .env file being subject to docker-compose $VAR expansion.
+services:
+  backend:
+    ports:
+      - "8000:8000"
+    environment:
+      AUTH_USERNAME: admin
+      # bcrypt hash of "admin" — $$ is docker-compose escape for literal $
+      AUTH_PASSWORD_HASH: $$2b$$12$$RtMbyw17l4N5UGzeXMNAWuzCaVV.XFBY7ZetWheQhxcBDcxahapkG

docker-compose.yml

@@ -7,9 +7,8 @@ services:
     env_file:
       - .env
     environment:
-      # Override env_file values that differ in Docker
+      # Override env_file: SQLite path must point inside the container volume
       SQLITE_PATH: /app/data/homelab.db
-      CORS_ORIGINS: '["http://localhost:3000"]'
     volumes:
       - backend_data:/app/data
     networks:
@@ -17,6 +16,28 @@ services:
     # Required for ping-based status checks
     cap_add:
       - NET_RAW
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+      start_period: 15s
+
+  mcp:
+    build:
+      context: ./mcp
+      dockerfile: Dockerfile.mcp
+    restart: unless-stopped
+    ports:
+      - "8001:8001"
+    env_file:
+      - .env
+    environment:
+      BACKEND_URL: "http://backend:8000"
+    depends_on:
+      - backend
+    networks:
+      - homelable
 
   frontend:
     build:

docker/nginx.conf

@@ -4,6 +4,16 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # Proxy WebSocket (must be before /api/ to take priority)
+    location /api/v1/status/ws/ {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
     # Proxy API to backend
     location /api/ {
         proxy_pass http://backend:8000;
@@ -11,7 +21,7 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
     }
 
-    # Proxy WebSocket
+    # Proxy legacy /ws/ path
     location /ws/ {
         proxy_pass http://backend:8000;
         proxy_http_version 1.1;

docs/logo/icon-128.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="128" height="128" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon-16.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="16" height="16" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon-256.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="256" height="256" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon-32.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="32" height="32" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon-512.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="512" height="512" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon-64.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/icon.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+  <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+
+  <!-- House body -->
+  <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+
+  <!-- Floor line (subtle) -->
+  <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+
+  <!-- Door -->
+  <rect x="27" y="40" width="10" height="13" rx="1.5"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+
+  <!-- Network lines (drawn under nodes) -->
+  <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+  <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+
+  <!-- Center hub glow -->
+  <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+  <!-- Center hub -->
+  <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+
+  <!-- Left node -->
+  <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+
+  <!-- Right node -->
+  <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+
+  <!-- Top node -->
+  <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+</svg>

docs/logo/logo-lg.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 280 72" width="640" height="164" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <g transform="translate(4, 4)">
+    <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+    <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+    <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+          fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+    <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+    <rect x="27" y="40" width="10" height="13" rx="1.5"
+          fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+    <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+    <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+    <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+  </g>
+  <text x="80" y="42" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="600" font-size="30" letter-spacing="-0.5">
+    <tspan fill="#e6edf3">Home</tspan><tspan fill="#00d4ff">lable</tspan>
+  </text>
+  <text x="81" y="58" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="400" font-size="11" fill="#8b949e" letter-spacing="0.5">HomeLab Visualizer</text>
+</svg>

docs/logo/logo-md.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 280 72" width="360" height="92" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <g transform="translate(4, 4)">
+    <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+    <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+    <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+          fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+    <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+    <rect x="27" y="40" width="10" height="13" rx="1.5"
+          fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+    <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+    <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+    <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+  </g>
+  <text x="80" y="42" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="600" font-size="30" letter-spacing="-0.5">
+    <tspan fill="#e6edf3">Home</tspan><tspan fill="#00d4ff">lable</tspan>
+  </text>
+  <text x="81" y="58" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="400" font-size="11" fill="#8b949e" letter-spacing="0.5">HomeLab Visualizer</text>
+</svg>

docs/logo/logo-sm.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 280 72" width="200" height="51" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <g transform="translate(4, 4)">
+    <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+    <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+    <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+          fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+    <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+    <rect x="27" y="40" width="10" height="13" rx="1.5"
+          fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+    <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+    <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+    <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+  </g>
+  <text x="80" y="42" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="600" font-size="30" letter-spacing="-0.5">
+    <tspan fill="#e6edf3">Home</tspan><tspan fill="#00d4ff">lable</tspan>
+  </text>
+  <text x="81" y="58" font-family="Inter, system-ui, -apple-system, sans-serif" font-weight="400" font-size="11" fill="#8b949e" letter-spacing="0.5">HomeLab Visualizer</text>
+</svg>

docs/logo/logo.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 280 72" fill="none">
+  <defs>
+    <radialGradient id="bg-glow" cx="50%" cy="35%" r="55%">
+      <stop offset="0%" stop-color="#00d4ff" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="node-glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- Icon (72×72, scaled from 64 viewBox) -->
+  <g transform="translate(4, 4) scale(1)">
+    <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+    <circle cx="32" cy="32" r="32" fill="url(#bg-glow)"/>
+    <path d="M32 11 L53 30 L48 30 L48 53 L16 53 L16 30 L11 30 Z"
+          fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+    <line x1="16" y1="30" x2="48" y2="30" stroke="#00d4ff" stroke-width="0.5" opacity="0.25"/>
+    <rect x="27" y="40" width="10" height="13" rx="1.5"
+          fill="#0d1117" stroke="#00d4ff" stroke-width="1" opacity="0.9"/>
+    <line x1="32" y1="23" x2="32" y2="30" stroke="#a855f7" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="21" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <line x1="43" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1.2" opacity="0.7" stroke-linecap="round"/>
+    <circle cx="32" cy="33" r="5" fill="#00d4ff" opacity="0.12"/>
+    <circle cx="32" cy="33" r="3" fill="#00d4ff" filter="url(#node-glow)"/>
+    <circle cx="21" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="43" cy="38" r="2.5" fill="#39d353" filter="url(#node-glow)"/>
+    <circle cx="32" cy="23" r="2" fill="#a855f7" filter="url(#node-glow)"/>
+  </g>
+
+  <!-- Text -->
+  <text x="80" y="42"
+        font-family="Inter, system-ui, -apple-system, sans-serif"
+        font-weight="600"
+        font-size="30"
+        letter-spacing="-0.5">
+    <tspan fill="#e6edf3">Home</tspan><tspan fill="#00d4ff">lable</tspan>
+  </text>
+
+  <!-- Subtitle -->
+  <text x="81" y="58"
+        font-family="Inter, system-ui, -apple-system, sans-serif"
+        font-weight="400"
+        font-size="11"
+        fill="#8b949e"
+        letter-spacing="0.5">HomeLab Visualizer</text>
+</svg>

docs/zigbee-import.md

@@ -0,0 +1,130 @@
+# Zigbee2MQTT Network Map Importer
+
+This feature lets you connect Homelable to your MQTT broker, fetch the Zigbee2MQTT network topology, and drop all Zigbee devices onto the canvas as typed nodes with proper hierarchy.
+
+---
+
+## Feature Overview
+
+- **Automatic device discovery** — Requests the Z2M networkmap via the MQTT bridge API and parses the full device list
+- **Typed nodes** — Devices are mapped to three homelable node types:
+  - `zigbee_coordinator` — The Zigbee coordinator (hub)
+  - `zigbee_router` — Mains-powered router devices
+  - `zigbee_enddevice` — Battery-powered end devices (sensors, bulbs, etc.)
+- **Hierarchy** — `parent_id` is set automatically: coordinator → routers → end devices
+- **LQI display** — Link Quality Indicator is stored as a node property
+- **IoT edges** — Links between devices are added as `IoT / Zigbee` edge type
+
+---
+
+## Prerequisites
+
+1. A running **MQTT broker** (e.g. Mosquitto) accessible from your Homelable host
+2. **Zigbee2MQTT** connected to the broker and running
+3. Z2M must respond to networkmap requests on:
+   - **Request topic:** `<base_topic>/bridge/request/networkmap`
+   - **Response topic:** `<base_topic>/bridge/response/networkmap`
+   - The default base topic is `zigbee2mqtt`
+
+---
+
+## Step-by-step Usage
+
+### 1. Open the Zigbee Import dialog
+
+Click **Zigbee Import** in the left sidebar (below "Scan Network").
+
+### 2. Configure the MQTT connection
+
+| Field | Default | Description |
+|---|---|---|
+| Broker Host | — | IP or hostname of your MQTT broker |
+| Port | 1883 | MQTT broker port |
+| Base Topic | `zigbee2mqtt` | Zigbee2MQTT base topic |
+| Username | _(optional)_ | MQTT username if authentication is enabled |
+| Password | _(optional)_ | MQTT password |
+
+### 3. Test the connection (optional)
+
+Click **Test Connection** to verify broker reachability before fetching devices.  
+A green indicator confirms success; red shows the error message from the broker.
+
+### 4. Fetch devices
+
+Click **Fetch Devices**. Homelable will:
+1. Connect to the broker
+2. Subscribe to the response topic
+3. Publish `{"type": "raw", "routes": false}` to the request topic
+4. Wait up to 60 seconds for the network map response (large meshes can take 30 s+)
+5. Parse and group devices by type
+
+### 5. Select and add to canvas
+
+Devices are grouped by type (Coordinator / Router / End Device).  
+Use the checkboxes to select which devices to add, then click **Add N to Canvas**.
+
+> **Tip:** All devices are selected by default. Uncheck any you don't want.
+
+### 6. Arrange on the canvas
+
+Devices are placed in a grid at the top-right of the canvas.  
+Use **Auto Layout** (toolbar) to re-arrange the full canvas, or drag nodes manually.
+
+---
+
+## MQTT Configuration Tips
+
+### Mosquitto without authentication
+
+```
+listener 1883
+allow_anonymous true
+```
+
+### Mosquitto with password file
+
+```
+listener 1883
+password_file /etc/mosquitto/passwd
+```
+
+Create a user:
+```bash
+mosquitto_passwd -c /etc/mosquitto/passwd <username>
+```
+
+### Zigbee2MQTT `configuration.yaml`
+
+```yaml
+mqtt:
+  base_topic: zigbee2mqtt
+  server: mqtt://localhost:1883
+  # user: mqtt_user
+  # password: mqtt_password
+```
+
+---
+
+## Supported Z2M Versions
+
+The networkmap bridge API is available in **Zigbee2MQTT 1.x and 2.x**.  
+Tested against Z2M 1.35+ and 2.x.
+
+The importer uses the `raw` topology format (`routes: false`) which is the most widely supported mode.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Connection refused" | Broker unreachable | Check host/port, firewall rules |
+| "Timed out waiting for networkmap" | Z2M not running or wrong base_topic | Verify Z2M is connected, check base_topic setting |
+| 0 devices returned | Z2M has no devices paired | Pair at least one device first |
+| "Malformed networkmap response" | Z2M returned unexpected format | Check Z2M version; open an issue |
+
+---
+
+## Screenshots
+
+_(Screenshots will be added in a future release)_

frontend/index.html

@@ -2,9 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>frontend</title>
+    <meta name="description" content="Homelable — Visual homelab infrastructure map with live monitoring" />
+    <title>Homelable</title>
   </head>
   <body>
     <div id="root"></div>

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "1.0.0",
+  "version": "2.0.1",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -19,12 +19,15 @@
     "@fontsource-variable/geist": "^5.2.8",
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource/jetbrains-mono": "^5.2.8",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@types/js-yaml": "^4.0.9",
     "@xyflow/react": "^12.10.1",
-    "axios": "^1.13.6",
+    "axios": "^1.15.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "dagre": "^0.8.5",
     "html-to-image": "^1.11.13",
+    "js-yaml": "^4.1.1",
     "next-themes": "^0.4.6",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
@@ -46,12 +49,12 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.0",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "globals": "^16.5.0",
     "jsdom": "^28.1.0",
-    "lucide-react": "^0.577.0",
+    "lucide-react": "^1.7.0",
     "tailwindcss": "^4.2.1",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",

frontend/public/favicon.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <!-- Background circle -->
+  <circle cx="32" cy="32" r="32" fill="#0d1117"/>
+
+  <!-- House silhouette -->
+  <path d="M32 12 L52 30 L48 30 L48 52 L16 52 L16 30 L12 30 Z"
+        fill="#161b22" stroke="#00d4ff" stroke-width="1.5" stroke-linejoin="round"/>
+
+  <!-- Door -->
+  <rect x="27" y="40" width="10" height="12" rx="1"
+        fill="#0d1117" stroke="#00d4ff" stroke-width="1"/>
+
+  <!-- Network nodes -->
+  <!-- Center node (hub) -->
+  <circle cx="32" cy="33" r="3" fill="#00d4ff"/>
+
+  <!-- Left node -->
+  <circle cx="22" cy="38" r="2" fill="#39d353"/>
+  <line x1="22" y1="38" x2="29" y2="33" stroke="#39d353" stroke-width="1" opacity="0.7"/>
+
+  <!-- Right node -->
+  <circle cx="42" cy="38" r="2" fill="#39d353"/>
+  <line x1="42" y1="38" x2="35" y2="33" stroke="#39d353" stroke-width="1" opacity="0.7"/>
+
+  <!-- Top node (inside roof area) -->
+  <circle cx="32" cy="24" r="2" fill="#a855f7"/>
+  <line x1="32" y1="24" x2="32" y2="30" stroke="#a855f7" stroke-width="1" opacity="0.7"/>
+
+  <!-- Glow effect on center node -->
+  <circle cx="32" cy="33" r="3" fill="none" stroke="#00d4ff" stroke-width="1.5" opacity="0.4"/>
+</svg>

frontend/scripts/fetch-dashboard-icons.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Regenerate frontend/src/data/dashboardIcons.json from the upstream
+// homarr-labs/dashboard-icons repo. Run manually to refresh the manifest.
+//
+//   node scripts/fetch-dashboard-icons.mjs
+
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const TREE_URL = 'https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/tree.json'
+const OUT = resolve(dirname(fileURLToPath(import.meta.url)), '../src/data/dashboardIcons.json')
+
+const res = await fetch(TREE_URL)
+if (!res.ok) {
+  console.error(`fetch failed: ${res.status} ${res.statusText}`)
+  process.exit(1)
+}
+const tree = await res.json()
+const slugs = (tree.svg ?? [])
+  .filter((f) => f.endsWith('.svg'))
+  .map((f) => f.slice(0, -4))
+  .sort()
+
+mkdirSync(dirname(OUT), { recursive: true })
+writeFileSync(OUT, JSON.stringify(slugs))
+console.log(`wrote ${slugs.length} slugs → ${OUT}`)

frontend/src/App.tsx

@@ -2,7 +2,12 @@ import { useEffect, useCallback, useRef, useState } from 'react'
 import { ReactFlowProvider, type Connection, type Edge } from '@xyflow/react'
 import { type Node } from '@xyflow/react'
 import { applyDagreLayout } from '@/utils/layout'
-import { exportToPng } from '@/utils/export'
+import { serializeNode, serializeEdge, deserializeApiNode, deserializeApiEdge, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
+import { generateUUID } from '@/utils/uuid'
+import { generateMarkdownTable } from '@/utils/exportMarkdown'
+import { ExportModal } from '@/components/modals/ExportModal'
+import { exportCanvasToYaml, downloadYaml } from '@/utils/exportYaml'
+import { parseYamlToCanvas } from '@/utils/importYaml'
 import { TooltipProvider } from '@/components/ui/tooltip'
 import { Toaster } from '@/components/ui/sonner'
 import { toast } from 'sonner'
@@ -14,111 +19,75 @@ import { LoginPage } from '@/components/LoginPage'
 import { NodeModal } from '@/components/modals/NodeModal'
 import { EdgeModal } from '@/components/modals/EdgeModal'
 import { ScanConfigModal } from '@/components/modals/ScanConfigModal'
+import { ZigbeeImportModal } from '@/components/zigbee/ZigbeeImportModal'
 import { GroupRectModal, type GroupRectFormData } from '@/components/modals/GroupRectModal'
+import { TextModal, type TextFormData } from '@/components/modals/TextModal'
+import { ThemeModal } from '@/components/modals/ThemeModal'
+import { SearchModal } from '@/components/modals/SearchModal'
+import { PendingDevicesModal } from '@/components/modals/PendingDevicesModal'
+import { ShortcutsModal } from '@/components/modals/ShortcutsModal'
 import { useCanvasStore } from '@/stores/canvasStore'
 import { useAuthStore } from '@/stores/authStore'
+import { useThemeStore } from '@/stores/themeStore'
 import { canvasApi } from '@/api/client'
 import { demoNodes, demoEdges } from '@/utils/demoData'
 import { useStatusPolling } from '@/hooks/useStatusPolling'
-import type { NodeData, EdgeData } from '@/types'
+import type { NodeData, EdgeData, CustomStyleDef } from '@/types'
+import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
 
 const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
 const STANDALONE_STORAGE_KEY = 'homelable_canvas'
+const CONTAINER_MODE_TYPES = new Set<NodeData['type']>(['proxmox', 'vm', 'lxc', 'docker_host'])
 
 export default function App() {
-  const { loadCanvas, markSaved, selectedNodeId, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, nodes, edges } = useCanvasStore()
+  const { loadCanvas, markSaved, markUnsaved, selectedNodeId, selectedNodeIds, addNode, updateNode, deleteNode, onConnect, updateEdge, deleteEdge, setProxmoxContainerMode, setNodeZIndex, editingGroupRectId, setEditingGroupRectId, editingTextId, setEditingTextId, nodes, edges, snapshotHistory, undo, redo, copySelectedNodes, pasteNodes } = useCanvasStore()
   const canvasRef = useRef<HTMLDivElement>(null)
   const { isAuthenticated } = useAuthStore()
+  const { activeTheme, setTheme, customStyle, setCustomStyle } = useThemeStore()
 
   useStatusPolling()
 
+  const [themeModalOpen, setThemeModalOpen] = useState(false)
+  const [searchOpen, setSearchOpen] = useState(false)
+  const [sidebarForceView, setSidebarForceView] = useState<'history' | undefined>(undefined)
+  const [pendingModalOpen, setPendingModalOpen] = useState(false)
+  const [pendingModalStatus, setPendingModalStatus] = useState<'pending' | 'hidden'>('pending')
+  const [pendingHighlightId, setPendingHighlightId] = useState<string | undefined>(undefined)
+  const openPendingModal = useCallback((deviceId?: string, status: 'pending' | 'hidden' = 'pending') => {
+    setPendingHighlightId(undefined)
+    setPendingModalStatus(status)
+    setPendingModalOpen(true)
+    if (deviceId) setTimeout(() => setPendingHighlightId(deviceId), 0)
+  }, [])
+  const [shortcutsOpen, setShortcutsOpen] = useState(false)
   const [addNodeOpen, setAddNodeOpen] = useState(false)
   const [addGroupRectOpen, setAddGroupRectOpen] = useState(false)
+  const [addTextOpen, setAddTextOpen] = useState(false)
   const [editNodeId, setEditNodeId] = useState<string | null>(null)
   const [pendingConnection, setPendingConnection] = useState<Connection | null>(null)
   const [editEdgeId, setEditEdgeId] = useState<string | null>(null)
   const [scanConfigOpen, setScanConfigOpen] = useState(false)
+  const [exportModalOpen, setExportModalOpen] = useState(false)
+  const [zigbeeImportOpen, setZigbeeImportOpen] = useState(false)
 
   // Declare handleSave before the Ctrl+S effect so it is in scope
   const handleSave = useCallback(async () => {
     try {
       if (STANDALONE) {
-        localStorage.setItem(STANDALONE_STORAGE_KEY, JSON.stringify({ nodes, edges }))
+        localStorage.setItem(STANDALONE_STORAGE_KEY, JSON.stringify({ nodes, edges, theme_id: activeTheme, custom_style: customStyle }))
         markSaved()
         toast.success('Canvas saved')
         return
       }
-      const nodesToSave = nodes.map((n) => {
-        if (n.data.type === 'groupRect') {
-          return {
-            id: n.id,
-            type: 'groupRect',
-            label: n.data.label,
-            hostname: null,
-            ip: null,
-            mac: null,
-            os: null,
-            status: 'unknown',
-            check_method: null,
-            check_target: null,
-            services: [],
-            notes: null,
-            parent_id: null,
-            container_mode: false,
-            custom_icon: null,
-            pos_x: n.position.x,
-            pos_y: n.position.y,
-            // Persist size and all rect config inside custom_colors
-            custom_colors: {
-              ...n.data.custom_colors,
-              width: n.measured?.width ?? n.width ?? 360,
-              height: n.measured?.height ?? n.height ?? 240,
-            },
-          }
-        }
-        return {
-          id: n.id,
-          type: n.data.type,
-          label: n.data.label,
-          hostname: n.data.hostname ?? null,
-          ip: n.data.ip ?? null,
-          mac: n.data.mac ?? null,
-          os: n.data.os ?? null,
-          status: n.data.status,
-          check_method: n.data.check_method ?? null,
-          check_target: n.data.check_target ?? null,
-          services: n.data.services ?? [],
-          notes: n.data.notes ?? null,
-          parent_id: n.data.parent_id ?? null,
-          container_mode: n.data.container_mode ?? false,
-          custom_colors: n.data.custom_colors ?? null,
-          custom_icon: n.data.custom_icon ?? null,
-          pos_x: n.position.x,
-          pos_y: n.position.y,
-        }
-      })
-      const edgesToSave = edges.map((e) => ({
-        id: e.id,
-        source: e.source,
-        target: e.target,
-        type: e.data?.type ?? 'ethernet',
-        label: e.data?.label ?? null,
-        vlan_id: e.data?.vlan_id ?? null,
-        speed: e.data?.speed ?? null,
-        custom_color: e.data?.custom_color ?? null,
-        path_style: e.data?.path_style ?? null,
-        // Normalize stub handle IDs: "top-t" / "bottom-t" are invisible target stubs;
-        // map them back to their canonical source handle ID so reload works correctly.
-        source_handle: e.sourceHandle === 'top-t' ? 'top' : e.sourceHandle === 'bottom-t' ? 'bottom' : (e.sourceHandle ?? null),
-        target_handle: e.targetHandle === 'top-t' ? 'top' : e.targetHandle === 'bottom-t' ? 'bottom' : (e.targetHandle ?? null),
-      }))
-      await canvasApi.save({ nodes: nodesToSave, edges: edgesToSave, viewport: {} })
+      const nodesToSave = nodes.map(serializeNode)
+      const edgesToSave = edges.map(serializeEdge)
+      await canvasApi.save({ nodes: nodesToSave, edges: edgesToSave, viewport: { theme_id: activeTheme }, custom_style: customStyle })
       markSaved()
       toast.success('Canvas saved')
     } catch {
       toast.error('Save failed')
     }
-  }, [nodes, edges, markSaved])
+  }, [nodes, edges, markSaved, activeTheme, customStyle])
 
   // Keep a ref so the keydown handler always calls the latest version
   const handleSaveRef = useRef(handleSave)
@@ -130,7 +99,9 @@ export default function App() {
       try {
         const saved = localStorage.getItem(STANDALONE_STORAGE_KEY)
         if (saved) {
-          const { nodes: savedNodes, edges: savedEdges } = JSON.parse(saved)
+          const { nodes: savedNodes, edges: savedEdges, theme_id, custom_style } = JSON.parse(saved)
+          if (theme_id) setTheme(theme_id)
+          if (custom_style) setCustomStyle(custom_style)
           loadCanvas(savedNodes, savedEdges)
         } else {
           loadCanvas(demoNodes, demoEdges)
@@ -145,69 +116,59 @@ export default function App() {
       .then((res) => {
         const { nodes: apiNodes, edges: apiEdges } = res.data
         if (apiNodes.length > 0) {
-          // Build a map of proxmox container mode to know if children should be nested
+          // Build a map of container mode nodes to know if children should be nested
           const proxmoxContainerMap = new Map<string, boolean>(
-            apiNodes
-              .filter((n: NodeData & { id: string }) => n.type === 'proxmox')
-              .map((n: NodeData & { id: string }) => [n.id, n.container_mode !== false])
+            (apiNodes as ApiNode[])
+              .filter((n) => n.type === 'group' || n.container_mode === true)
+              .map((n) => [n.id, true])
           )
-          const rfNodes = apiNodes.map((n: NodeData & { id: string; pos_x: number; pos_y: number; parent_id?: string }) => {
-            if (n.type === 'groupRect') {
-              const w = n.custom_colors?.width ?? 360
-              const h = n.custom_colors?.height ?? 240
-              const z = n.custom_colors?.z_order ?? 1
-              return {
-                id: n.id,
-                type: 'groupRect',
-                position: { x: n.pos_x, y: n.pos_y },
-                data: n,
-                width: w,
-                height: h,
-                zIndex: z - 10,
-              }
-            }
-            const parentIsContainer = n.parent_id ? (proxmoxContainerMap.get(n.parent_id) ?? false) : false
-            return {
-              id: n.id,
-              type: n.type,
-              position: { x: n.pos_x, y: n.pos_y },
-              data: n,
-              ...(n.parent_id && parentIsContainer ? { parentId: n.parent_id, extent: 'parent' as const } : {}),
-              ...(n.type === 'proxmox' && n.container_mode !== false ? { width: 300, height: 200 } : {}),
-            }
-          })
-          const rfEdges = apiEdges.map((e: EdgeData & { id: string; source: string; target: string; source_handle?: string; target_handle?: string }) => ({
-            id: e.id,
-            source: e.source,
-            target: e.target,
-            type: e.type,
-            sourceHandle: e.source_handle ?? null,
-            targetHandle: e.target_handle ?? null,
-            data: e,
-          }))
+          const rfNodes = (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxContainerMap))
+          const rfEdges = (apiEdges as ApiEdge[]).map(deserializeApiEdge)
+          const savedTheme = res.data.viewport?.theme_id
+          if (savedTheme) setTheme(savedTheme)
+          if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
           loadCanvas(rfNodes, rfEdges)
         } else {
           loadCanvas(demoNodes, demoEdges)
         }
       })
       .catch(() => loadCanvas(demoNodes, demoEdges))
-  }, [isAuthenticated, loadCanvas])
+  }, [isAuthenticated, loadCanvas, setTheme, setCustomStyle])
 
-  // Ctrl+S
+  // Keep refs for store actions so keydown handler is always up-to-date without re-registering
+  const undoRef = useRef(undo)
+  const redoRef = useRef(redo)
+  const copyRef = useRef(copySelectedNodes)
+  const pasteRef = useRef(pasteNodes)
+  useEffect(() => { undoRef.current = undo }, [undo])
+  useEffect(() => { redoRef.current = redo }, [redo])
+  useEffect(() => { copyRef.current = copySelectedNodes }, [copySelectedNodes])
+  useEffect(() => { pasteRef.current = pasteNodes }, [pasteNodes])
+
+  // Global keyboard shortcuts
   useEffect(() => {
     const handler = (e: KeyboardEvent) => {
-      if ((e.ctrlKey || e.metaKey) && e.key === 's') {
-        e.preventDefault()
-        handleSaveRef.current()
-      }
+      const ctrl = e.ctrlKey || e.metaKey
+      // Ignore shortcuts when typing in an input/textarea
+      const tag = (e.target as HTMLElement).tagName
+      const isInput = tag === 'INPUT' || tag === 'TEXTAREA' || (e.target as HTMLElement).isContentEditable
+
+      if (ctrl && e.key === 's') { e.preventDefault(); handleSaveRef.current(); return }
+      if (ctrl && e.key === 'z') { e.preventDefault(); undoRef.current(); return }
+      if (ctrl && (e.key === 'y' || (e.shiftKey && e.key === 'z'))) { e.preventDefault(); redoRef.current(); return }
+      if (ctrl && e.key === 'k') { e.preventDefault(); setSearchOpen(true); return }
+      if (ctrl && e.key === 'c' && !isInput) { copyRef.current(); return }
+      if (ctrl && e.key === 'v' && !isInput) { pasteRef.current(); return }
+      if (e.key === '?' && !isInput) { setShortcutsOpen(true); return }
     }
     window.addEventListener('keydown', handler)
     return () => window.removeEventListener('keydown', handler)
   }, [])
 
   const handleAddNode = useCallback((data: Partial<NodeData>) => {
-    const id = crypto.randomUUID()
-    const isProxmox = data.type === 'proxmox'
+    snapshotHistory()
+    const id = generateUUID()
+    const isContainerNode = data.container_mode === true
     const parentNode = data.parent_id ? nodes.find((n) => n.id === data.parent_id) : null
     // Children position is relative to parent; place near top-left with padding
     const position = parentNode
@@ -220,14 +181,15 @@ export default function App() {
       position,
       data: { status: 'unknown', services: [], ...data } as NodeData,
       ...(data.parent_id ? { parentId: data.parent_id, extent: 'parent' as const } : {}),
-      ...(isProxmox ? { width: 300, height: 200 } : {}),
+      ...(isContainerNode ? { width: 300, height: 200 } : {}),
     }
     addNode(newNode)
     toast.success(`Added "${data.label}"`)
-  }, [addNode, nodes])
+  }, [addNode, nodes, snapshotHistory])
 
   const handleAddGroupRect = useCallback((data: GroupRectFormData) => {
-    const id = crypto.randomUUID()
+    snapshotHistory()
+    const id = generateUUID()
     const newNode: Node<NodeData> = {
       id,
       type: 'groupRect',
@@ -239,9 +201,13 @@ export default function App() {
         services: [],
         custom_colors: {
           border: data.border_color,
+          border_style: data.border_style,
+          border_width: data.border_width,
           background: data.background_color,
           text_color: data.text_color,
           text_position: data.text_position,
+          text_size: data.text_size,
+          label_position: data.label_position,
           font: data.font,
           z_order: data.z_order,
         },
@@ -251,32 +217,99 @@ export default function App() {
       zIndex: data.z_order - 10,
     }
     addNode(newNode)
-  }, [addNode])
+  }, [addNode, snapshotHistory])
 
   const handleUpdateGroupRect = useCallback((data: GroupRectFormData) => {
     if (!editingGroupRectId) return
+    snapshotHistory()
     const existing = nodes.find((n) => n.id === editingGroupRectId)
     updateNode(editingGroupRectId, {
       label: data.label,
       custom_colors: {
         ...existing?.data.custom_colors,
         border: data.border_color,
+        border_style: data.border_style,
+        border_width: data.border_width,
         background: data.background_color,
         text_color: data.text_color,
         text_position: data.text_position,
+        text_size: data.text_size,
+        label_position: data.label_position,
         font: data.font,
         z_order: data.z_order,
       },
     })
     setNodeZIndex(editingGroupRectId, data.z_order - 10)
     setEditingGroupRectId(null)
-  }, [editingGroupRectId, nodes, updateNode, setNodeZIndex, setEditingGroupRectId])
+  }, [editingGroupRectId, nodes, updateNode, setNodeZIndex, setEditingGroupRectId, snapshotHistory])
+
+  const handleAddText = useCallback((data: TextFormData) => {
+    snapshotHistory()
+    const id = generateUUID()
+    const newNode: Node<NodeData> = {
+      id,
+      // Text lives in `label` because the API serializer only persists top-level
+      // node fields; text_content is not in the schema and was lost on reload.
+      // TextNode and the edit modal both already fall back to label.
+      type: 'text',
+      position: { x: 250, y: 250 },
+      data: {
+        label: data.text,
+        type: 'text',
+        status: 'unknown',
+        services: [],
+        custom_colors: {
+          border: data.border_color,
+          border_style: data.border_style,
+          border_width: data.border_width,
+          background: data.background_color,
+          text_color: data.text_color,
+          text_size: data.text_size,
+          font: data.font,
+        },
+      },
+      width: 200,
+      height: 60,
+    }
+    addNode(newNode)
+  }, [addNode, snapshotHistory])
+
+  const handleUpdateText = useCallback((data: TextFormData) => {
+    if (!editingTextId) return
+    snapshotHistory()
+    const existing = nodes.find((n) => n.id === editingTextId)
+    updateNode(editingTextId, {
+      label: data.text,
+      // Clear stale text_content if present from older builds — label is the
+      // source of truth now.
+      text_content: undefined,
+      custom_colors: {
+        ...existing?.data.custom_colors,
+        border: data.border_color,
+        border_style: data.border_style,
+        border_width: data.border_width,
+        background: data.background_color,
+        text_color: data.text_color,
+        text_size: data.text_size,
+        font: data.font,
+      },
+    })
+    setEditingTextId(null)
+  }, [editingTextId, nodes, updateNode, setEditingTextId, snapshotHistory])
+
+  const handleDeleteText = useCallback(() => {
+    if (!editingTextId) return
+    snapshotHistory()
+    deleteNode(editingTextId)
+    setEditingTextId(null)
+  }, [editingTextId, deleteNode, setEditingTextId, snapshotHistory])
 
   const handleDeleteGroupRect = useCallback(() => {
     if (!editingGroupRectId) return
+    snapshotHistory()
     deleteNode(editingGroupRectId)
     setEditingGroupRectId(null)
-  }, [editingGroupRectId, deleteNode, setEditingGroupRectId])
+  }, [editingGroupRectId, deleteNode, setEditingGroupRectId, snapshotHistory])
 
   const handleEditNode = useCallback((id: string) => {
     setEditNodeId(id)
@@ -284,15 +317,16 @@ export default function App() {
 
   const handleUpdateNode = useCallback((data: Partial<NodeData>) => {
     if (!editNodeId) return
+    snapshotHistory()
     const existingNode = nodes.find((n) => n.id === editNodeId)
     updateNode(editNodeId, data)
-    // If proxmox container_mode changed, apply structural changes (children parentId, node dimensions)
-    if (data.type === 'proxmox' && typeof data.container_mode === 'boolean') {
+    // If container_mode changed, apply structural changes (children parentId, node dimensions)
+    if (typeof data.container_mode === 'boolean') {
       setProxmoxContainerMode(editNodeId, data.container_mode)
     }
     // Sync virtual edge when parent_id changes on an LXC/VM node
     const nodeType = data.type ?? existingNode?.data.type
-    if ((nodeType === 'lxc' || nodeType === 'vm') && 'parent_id' in data) {
+    if ((nodeType === 'lxc' || nodeType === 'vm' || nodeType === 'docker_container') && 'parent_id' in data) {
       const oldParentId = existingNode?.data.parent_id ?? null
       const newParentId = data.parent_id ?? null
       if (oldParentId !== newParentId) {
@@ -305,15 +339,18 @@ export default function App() {
           )
           if (oldEdge) deleteEdge(oldEdge.id)
         }
-        // Create new virtual edge: LXC top → Proxmox bottom
+        // Create virtual edge only when parent is NOT in container mode
+        // (container mode shows containment visually — no edge needed)
         if (newParentId) {
-          // Pass type as extra field — canvasStore.onConnect casts to Connection & Partial<EdgeData>
-          onConnect({ source: editNodeId, sourceHandle: 'top', target: newParentId, targetHandle: 'bottom', type: 'virtual' } as unknown as Connection)
+          const parentNode = nodes.find((n) => n.id === newParentId)
+          if (!parentNode?.data.container_mode) {
+            onConnect({ source: editNodeId, sourceHandle: 'top', target: newParentId, targetHandle: 'bottom', type: 'virtual' } as unknown as Connection)
+          }
         }
       }
     }
     setEditNodeId(null)
-  }, [editNodeId, updateNode, setProxmoxContainerMode, nodes, edges, deleteEdge, onConnect])
+  }, [editNodeId, updateNode, setProxmoxContainerMode, nodes, edges, deleteEdge, onConnect, snapshotHistory])
 
   const handleAutoLayout = useCallback(() => {
     const laid = applyDagreLayout(nodes, edges)
@@ -321,54 +358,146 @@ export default function App() {
     toast.success('Canvas auto-arranged')
   }, [nodes, edges, loadCanvas])
 
-  const handleExport = useCallback(async () => {
+  const handleExportMd = useCallback(async () => {
+    const md = generateMarkdownTable(nodes)
+    if (!md) { toast.error('No nodes to export'); return }
+    await navigator.clipboard.writeText(md)
+    toast.success('Markdown table copied to clipboard')
+  }, [nodes])
+
+  const handleExportYaml = useCallback(() => {
+    if (nodes.length === 0) { toast.error('No nodes to export'); return }
+    const content = exportCanvasToYaml(nodes, edges)
+    downloadYaml(content)
+    toast.success('Canvas exported as YAML')
+  }, [nodes, edges])
+
+  const handleImportYaml = useCallback((content: string) => {
+    try {
+      const { nodes: merged, edges: mergedEdges, imported } = parseYamlToCanvas(content, nodes, edges)
+      snapshotHistory()
+      loadCanvas(merged, mergedEdges)
+      markUnsaved()
+      toast.success(`Imported ${imported} node${imported !== 1 ? 's' : ''}`)
+    } catch (err) {
+      toast.error(`Import failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }, [nodes, edges, snapshotHistory, loadCanvas, markUnsaved])
+
+  const handleExport = useCallback(() => {
     const el = canvasRef.current?.querySelector<HTMLElement>('.react-flow')
     if (!el) { toast.error('Canvas not ready'); return }
-    try {
-      await exportToPng(el)
-      toast.success('Exported as PNG')
-    } catch {
-      toast.error('Export failed')
-    }
+    setExportModalOpen(true)
   }, [])
 
+  const handleZigbeeAddToCanvas = useCallback((zigbeeNodes: ZigbeeNode[], zigbeeEdges: ZigbeeEdge[]) => {
+    snapshotHistory()
+    // Place nodes in a grid starting at x=500, y=100
+    const COLS = 4
+    const SPACING_X = 170
+    const SPACING_Y = 100
+    zigbeeNodes.forEach((zn, i) => {
+      const id = zn.id
+      const col = i % COLS
+      const row = Math.floor(i / COLS)
+      const position = { x: 500 + col * SPACING_X, y: 100 + row * SPACING_Y }
+      const newNode: import('@xyflow/react').Node<NodeData> = {
+        id,
+        type: zn.type,
+        position,
+        data: {
+          label: zn.friendly_name,
+          type: zn.type as NodeData['type'],
+          status: 'unknown' as const,
+          services: [],
+          ...(zn.lqi != null ? { properties: [{ key: 'LQI', value: String(zn.lqi), icon: 'signal', visible: true }] } : {}),
+          ...(zn.model ? { os: zn.model } : {}),
+          ...(zn.parent_id ? { parent_id: zn.parent_id } : {}),
+        },
+      }
+      addNode(newNode)
+    })
+    // Add IoT edges between Zigbee devices: parent bottom -> child top
+    zigbeeEdges.forEach((ze) => {
+      onConnect({
+        source: ze.source,
+        sourceHandle: 'bottom',
+        target: ze.target,
+        targetHandle: 'top-t',
+        type: 'iot',
+      } as unknown as import('@xyflow/react').Connection)
+    })
+    // Auto-select only the freshly imported nodes so the user can drag the
+    // whole subtree as a group.
+    const importedIds = new Set(zigbeeNodes.map((zn) => zn.id))
+    useCanvasStore.setState((state) => ({
+      nodes: state.nodes.map((n) => ({ ...n, selected: importedIds.has(n.id) })),
+      selectedNodeIds: Array.from(importedIds),
+      selectedNodeId: importedIds.size === 1 ? Array.from(importedIds)[0] : null,
+    }))
+    markUnsaved()
+  }, [addNode, onConnect, snapshotHistory, markUnsaved])
+
   const handleEdgeConnect = useCallback((connection: Connection) => {
     setPendingConnection(connection)
   }, [])
 
   const handleEdgeConfirm = useCallback((edgeData: EdgeData) => {
     if (!pendingConnection) return
+    snapshotHistory()
     onConnect({ ...pendingConnection, ...edgeData } as unknown as Connection)
-    // When a virtual edge is drawn between LXC/VM (top) and Proxmox (bottom), sync parent_id
+    // When a virtual edge is drawn between a child node and a container node, sync parent_id
     if (edgeData.type === 'virtual') {
       const src = nodes.find((n) => n.id === pendingConnection.source)
       const tgt = nodes.find((n) => n.id === pendingConnection.target)
-      const srcType = src?.data.type
-      const tgtType = tgt?.data.type
-      if ((srcType === 'lxc' || srcType === 'vm') && tgtType === 'proxmox') {
+      const srcType = src?.data.type as NodeData['type']
+      const tgtType = tgt?.data.type as NodeData['type']
+      if ((srcType === 'lxc' || srcType === 'vm') && CONTAINER_MODE_TYPES.has(tgtType)) {
         updateNode(pendingConnection.source, { parent_id: pendingConnection.target })
-      } else if (srcType === 'proxmox' && (tgtType === 'lxc' || tgtType === 'vm')) {
+      } else if (CONTAINER_MODE_TYPES.has(srcType) && (tgtType === 'lxc' || tgtType === 'vm')) {
+        updateNode(pendingConnection.target, { parent_id: pendingConnection.source })
+      } else if (srcType === 'docker_container' && tgtType === 'docker_host') {
+        updateNode(pendingConnection.source, { parent_id: pendingConnection.target })
+      } else if (tgtType === 'docker_container' && srcType === 'docker_host') {
         updateNode(pendingConnection.target, { parent_id: pendingConnection.source })
       }
     }
     setPendingConnection(null)
-  }, [pendingConnection, onConnect, nodes, updateNode])
+  }, [pendingConnection, onConnect, nodes, updateNode, snapshotHistory])
 
   const handleEdgeDoubleClick = useCallback((edge: Edge<EdgeData>) => {
     setEditEdgeId(edge.id)
   }, [])
 
+  const handleNodeDoubleClick = useCallback((node: Node<NodeData>) => {
+    // 'group' uses inline rename (pencil button in header). Opening the
+    // generic NodeModal would clobber the group's height (via the
+    // properties-clears-height rule in updateNode) and lose its children.
+    // 'groupRect' has its own onDoubleClick that already routes to GroupRectModal.
+    if (node.data.type === 'group' || node.data.type === 'groupRect') return
+    handleEditNode(node.id)
+  }, [handleEditNode])
+
   const handleEdgeUpdate = useCallback((data: EdgeData) => {
     if (!editEdgeId) return
+    snapshotHistory()
     updateEdge(editEdgeId, data)
     setEditEdgeId(null)
-  }, [editEdgeId, updateEdge])
+  }, [editEdgeId, updateEdge, snapshotHistory])
 
   const handleEdgeDelete = useCallback(() => {
     if (!editEdgeId) return
+    snapshotHistory()
     deleteEdge(editEdgeId)
     setEditEdgeId(null)
-  }, [editEdgeId, deleteEdge])
+  }, [editEdgeId, deleteEdge, snapshotHistory])
+
+  const handleClearWaypoints = useCallback(() => {
+    if (!editEdgeId) return
+    snapshotHistory()
+    updateEdge(editEdgeId, { waypoints: [] })
+    setEditEdgeId(null)
+  }, [editEdgeId, updateEdge, snapshotHistory])
 
   const editNode = editNodeId ? nodes.find((n) => n.id === editNodeId) : null
   const editEdge = editEdgeId ? edges.find((e) => e.id === editEdgeId) : null
@@ -382,31 +511,50 @@ export default function App() {
           <Sidebar
             onAddNode={() => setAddNodeOpen(true)}
             onAddGroupRect={() => setAddGroupRectOpen(true)}
+            onAddText={() => setAddTextOpen(true)}
             onScan={() => setScanConfigOpen(true)}
+            onZigbeeImport={() => setZigbeeImportOpen(true)}
             onSave={handleSave}
-            onNodeApproved={setEditNodeId}
+            forceView={sidebarForceView}
+            onOpenPending={openPendingModal}
           />
           <div className="flex flex-col flex-1 min-w-0">
             <Toolbar
               onSave={handleSave}
               onAutoLayout={handleAutoLayout}
               onExport={handleExport}
+              onChangeStyle={() => setThemeModalOpen(true)}
+              onUndo={undo}
+              onRedo={redo}
+              onShortcuts={() => setShortcutsOpen(true)}
+              onExportMd={handleExportMd}
+              onExportYaml={handleExportYaml}
+              onImportYaml={handleImportYaml}
             />
             <div className="flex flex-1 min-h-0">
               <div ref={canvasRef} className="flex-1 min-w-0 h-full">
-                <CanvasContainer onConnect={handleEdgeConnect} onEdgeDoubleClick={handleEdgeDoubleClick} />
+                <CanvasContainer
+                  onConnect={handleEdgeConnect}
+                  onEdgeDoubleClick={handleEdgeDoubleClick}
+                  onNodeDoubleClick={handleNodeDoubleClick}
+                  onNodeDragStart={snapshotHistory}
+                  onOpenPending={(deviceId) => openPendingModal(deviceId)}
+                />
               </div>
-              {selectedNodeId && <DetailPanel onEdit={handleEditNode} />}
+              {(selectedNodeId || selectedNodeIds.length > 1) && <DetailPanel onEdit={handleEditNode} />}
             </div>
           </div>
         </div>
 
         <NodeModal
+          key={addNodeOpen ? 'add-open' : 'add-closed'}
           open={addNodeOpen}
           onClose={() => setAddNodeOpen(false)}
           onSubmit={handleAddNode}
           title="Add Node"
-          proxmoxNodes={nodes.filter((n) => n.type === 'proxmox').map((n) => ({ id: n.id, label: n.data.label }))}
+          parentContainerNodes={nodes
+            .filter((n) => CONTAINER_MODE_TYPES.has(n.data.type) && n.data.container_mode)
+            .map((n) => ({ id: n.id, label: n.data.label, nodeType: n.data.type }))}
         />
 
         {/* key forces re-mount when editing a different node, resetting form state */}
@@ -417,7 +565,9 @@ export default function App() {
           onSubmit={handleUpdateNode}
           initial={editNode?.data}
           title="Edit Node"
-          proxmoxNodes={nodes.filter((n) => n.type === 'proxmox').map((n) => ({ id: n.id, label: n.data.label }))}
+          parentContainerNodes={nodes
+            .filter((n) => n.id !== editNodeId && CONTAINER_MODE_TYPES.has(n.data.type) && n.data.container_mode)
+            .map((n) => ({ id: n.id, label: n.data.label, nodeType: n.data.type }))}
         />
 
         <EdgeModal
@@ -438,6 +588,7 @@ export default function App() {
           onClose={() => setEditEdgeId(null)}
           onSubmit={handleEdgeUpdate}
           onDelete={handleEdgeDelete}
+          onClearWaypoints={handleClearWaypoints}
           initial={editEdge?.data}
           title="Edit Link"
         />
@@ -446,7 +597,23 @@ export default function App() {
           <ScanConfigModal
             open={scanConfigOpen}
             onClose={() => setScanConfigOpen(false)}
-            onScanNow={() => toast.success('Scan triggered')}
+            onScanNow={() => {
+              toast.success('Network scan started — check Scan History for results')
+              setSidebarForceView(undefined)
+              setTimeout(() => setSidebarForceView('history'), 0)
+            }}
+          />
+        )}
+
+        {!STANDALONE && (
+          <ZigbeeImportModal
+            open={zigbeeImportOpen}
+            onClose={() => setZigbeeImportOpen(false)}
+            onAddToCanvas={handleZigbeeAddToCanvas}
+            onPendingImported={() => {
+              setSidebarForceView(undefined)
+              setTimeout(() => setSidebarForceView('history'), 0)
+            }}
           />
         )}
 
@@ -454,7 +621,7 @@ export default function App() {
           open={addGroupRectOpen}
           onClose={() => setAddGroupRectOpen(false)}
           onSubmit={handleAddGroupRect}
-          title="Add Rectangle"
+          title="Add Zone"
         />
 
         {/* key forces re-mount when editing a different rect */}
@@ -474,11 +641,73 @@ export default function App() {
               text_color: rc.text_color ?? '#e6edf3',
               text_position: rc.text_position ?? 'top-left',
               border_color: rc.border ?? '#00d4ff',
+              border_style: rc.border_style ?? 'solid',
+              border_width: rc.border_width ?? 2,
               background_color: rc.background ?? '#00d4ff0d',
+              text_size: rc.text_size ?? 12,
+              label_position: rc.label_position ?? 'inside',
               z_order: rc.z_order ?? 1,
             }
           })()}
-          title="Edit Rectangle"
+          title="Edit Zone"
+        />
+
+        <TextModal
+          open={addTextOpen}
+          onClose={() => setAddTextOpen(false)}
+          onSubmit={handleAddText}
+          title="Add Text"
+        />
+
+        <TextModal
+          key={editingTextId ?? 'text-edit'}
+          open={!!editingTextId}
+          onClose={() => setEditingTextId(null)}
+          onSubmit={handleUpdateText}
+          onDelete={handleDeleteText}
+          initial={(() => {
+            const n = editingTextId ? nodes.find((nd) => nd.id === editingTextId) : null
+            if (!n) return undefined
+            const rc = n.data.custom_colors ?? {}
+            return {
+              text: n.data.text_content ?? n.data.label ?? '',
+              font: rc.font ?? 'inter',
+              text_color: rc.text_color ?? '#e6edf3',
+              text_size: rc.text_size ?? 14,
+              border_color: rc.border ?? '#30363d',
+              border_style: (rc.border_style ?? 'none') as TextFormData['border_style'],
+              border_width: rc.border_width ?? 1,
+              background_color: rc.background ?? '#00000000',
+            }
+          })()}
+          title="Edit Text"
+        />
+
+        {/* key forces re-mount on open so useState captures current theme as original */}
+        <ThemeModal
+          key={themeModalOpen ? 'theme-open' : 'theme-closed'}
+          open={themeModalOpen}
+          onClose={() => setThemeModalOpen(false)}
+        />
+
+        <SearchModal
+          open={searchOpen}
+          onClose={() => setSearchOpen(false)}
+          onOpenPending={(deviceId) => openPendingModal(deviceId)}
+        />
+        <ShortcutsModal open={shortcutsOpen} onClose={() => setShortcutsOpen(false)} />
+
+        <PendingDevicesModal
+          open={pendingModalOpen}
+          onClose={() => setPendingModalOpen(false)}
+          highlightId={pendingHighlightId}
+          initialStatus={pendingModalStatus}
+        />
+
+        <ExportModal
+          open={exportModalOpen}
+          onClose={() => setExportModalOpen(false)}
+          getElement={() => canvasRef.current?.querySelector<HTMLElement>('.react-flow') ?? null}
         />
 
         <Toaster theme="dark" position="bottom-right" />

frontend/src/api/client.ts

@@ -5,6 +5,9 @@ export const api = axios.create({
   baseURL: '/api/v1',
 })
 
+// Unauthenticated axios instance — no JWT, no 401 redirect (used for public endpoints)
+const publicApi = axios.create({ baseURL: '/api/v1' })
+
 api.interceptors.request.use((config) => {
   const token = useAuthStore.getState().token
   if (token) config.headers.Authorization = `Bearer ${token}`
@@ -30,6 +33,7 @@ export const canvasApi = {
     nodes: object[]
     edges: object[]
     viewport: object
+    custom_style?: object | null
   }) => api.post('/canvas/save', payload),
 }
 
@@ -44,14 +48,90 @@ export const edgesApi = {
   delete: (id: string) => api.delete(`/edges/${id}`),
 }
 
+export const liveviewApi = {
+  load: (key: string) => publicApi.get('/liveview', { params: { key } }),
+}
+
 export const scanApi = {
   trigger: () => api.post('/scan/trigger'),
   pending: () => api.get('/scan/pending'),
   hidden: () => api.get('/scan/hidden'),
   runs: () => api.get('/scan/runs'),
-  approve: (id: string, nodeData: object) => api.post(`/scan/pending/${id}/approve`, nodeData),
+  clearPending: () => api.delete('/scan/pending'),
+  approve: (id: string, nodeData: object) =>
+    api.post<{
+      approved: boolean
+      node_id: string
+      edges_created: number
+      edges: { id: string; source: string; target: string }[]
+    }>(`/scan/pending/${id}/approve`, nodeData),
   hide: (id: string) => api.post(`/scan/pending/${id}/hide`),
   ignore: (id: string) => api.post(`/scan/pending/${id}/ignore`),
-  getConfig: () => api.get<{ ranges: string[]; interval_seconds: number }>('/scan/config'),
-  saveConfig: (data: { ranges: string[]; interval_seconds: number }) => api.post('/scan/config', data),
+  bulkApprove: (ids: string[]) =>
+    api.post<{
+      approved: number
+      node_ids: string[]
+      device_ids: string[]
+      edges_created: number
+      edges: { id: string; source: string; target: string }[]
+      skipped: number
+    }>('/scan/pending/bulk-approve', { device_ids: ids }),
+  bulkHide: (ids: string[]) => api.post<{ hidden: number; skipped: number }>('/scan/pending/bulk-hide', { device_ids: ids }),
+  restore: (id: string) => api.post<{ restored: boolean; device_id: string }>(`/scan/pending/${id}/restore`),
+  bulkRestore: (ids: string[]) => api.post<{ restored: number; skipped: number }>('/scan/pending/bulk-restore', { device_ids: ids }),
+  stop: (runId: string) => api.post(`/scan/${runId}/stop`),
+  getConfig: () => api.get<{ ranges: string[] }>('/scan/config'),
+  saveConfig: (data: { ranges: string[] }) => api.post('/scan/config', data),
+}
+
+export const settingsApi = {
+  get: () => api.get<{ interval_seconds: number }>('/settings'),
+  save: (data: { interval_seconds: number }) => api.post<{ interval_seconds: number }>('/settings', data),
+}
+
+export const zigbeeApi = {
+  testConnection: (data: {
+    mqtt_host: string
+    mqtt_port: number
+    mqtt_username?: string
+    mqtt_password?: string
+    mqtt_tls?: boolean
+    mqtt_tls_insecure?: boolean
+  }) =>
+    api.post<{ connected: boolean; message: string }>('/zigbee/test-connection', data),
+
+  importNetwork: (data: {
+    mqtt_host: string
+    mqtt_port: number
+    mqtt_username?: string
+    mqtt_password?: string
+    base_topic?: string
+    mqtt_tls?: boolean
+    mqtt_tls_insecure?: boolean
+  }) =>
+    api.post<{
+      nodes: import('@/components/zigbee/types').ZigbeeNode[]
+      edges: import('@/components/zigbee/types').ZigbeeEdge[]
+      device_count: number
+    }>('/zigbee/import', data),
+
+  importToPending: (data: {
+    mqtt_host: string
+    mqtt_port: number
+    mqtt_username?: string
+    mqtt_password?: string
+    base_topic?: string
+    mqtt_tls?: boolean
+    mqtt_tls_insecure?: boolean
+  }) =>
+    api.post<{
+      id: string
+      status: string
+      kind: string
+      ranges: string[]
+      devices_found: number
+      started_at: string
+      finished_at: string | null
+      error: string | null
+    }>('/zigbee/import-pending', data),
 }

frontend/src/components/LiveView.tsx

@@ -0,0 +1,165 @@
+/**
+ * LiveView — read-only canvas accessible at /view?key=<LIVEVIEW_KEY>.
+ *
+ * - Non-standalone: fetches canvas from /api/v1/liveview?key=... (no JWT needed).
+ *   Returns 403 when the feature is disabled or the key is wrong.
+ * - Standalone: loads canvas from localStorage directly (no key required,
+ *   since there is no backend to validate against).
+ *
+ * Pan and zoom work. Editing is fully disabled.
+ * Clicking a node with an IP opens http://<ip> in a new tab.
+ */
+
+import { useCallback, useEffect, useState } from 'react'
+import {
+  ReactFlowProvider,
+  ReactFlow,
+  Background,
+  BackgroundVariant,
+  Controls,
+  ConnectionMode,
+  useReactFlow,
+  type Node,
+} from '@xyflow/react'
+import '@xyflow/react/dist/style.css'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { useThemeStore } from '@/stores/themeStore'
+import { THEMES } from '@/utils/themes'
+import { nodeTypes } from '@/components/canvas/nodes/nodeTypes'
+import { edgeTypes } from '@/components/canvas/edges/edgeTypes'
+import { deserializeApiNode, deserializeApiEdge, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'
+import { liveviewApi } from '@/api/client'
+import type { NodeData } from '@/types'
+
+const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
+const STORAGE_KEY = 'homelable_canvas'
+
+type ViewState = 'loading' | 'disabled' | 'invalid-key' | 'no-key' | 'network-error' | 'ready'
+
+function LiveViewCanvas() {
+  const { nodes, edges, loadCanvas, fitViewPending, clearFitViewPending } = useCanvasStore()
+  const { fitView } = useReactFlow()
+  const activeTheme = useThemeStore((s) => s.activeTheme)
+  const theme = THEMES[activeTheme]
+  // Derive initial view state synchronously (avoids calling setState inside an effect):
+  // - standalone → always ready (localStorage, no key required)
+  // - non-standalone, no ?key= → no-key error immediately
+  // - non-standalone, key present → loading (API call below)
+  const [viewState, setViewState] = useState<ViewState>(() => {
+    if (STANDALONE) return 'ready'
+    return new URLSearchParams(window.location.search).get('key') ? 'loading' : 'no-key'
+  })
+
+  useEffect(() => {
+    if (STANDALONE) {
+      try {
+        const saved = localStorage.getItem(STORAGE_KEY)
+        if (saved) {
+          const { nodes: savedNodes, edges: savedEdges } = JSON.parse(saved)
+          loadCanvas(savedNodes, savedEdges)
+        }
+      } catch {
+        // empty canvas on parse error — show empty canvas
+      }
+      return
+    }
+
+    // Already handled synchronously in useState initializer
+    const key = new URLSearchParams(window.location.search).get('key')
+    if (!key) return
+
+    liveviewApi.load(key)
+      .then((res) => {
+        const { nodes: apiNodes, edges: apiEdges } = res.data
+        const proxmoxMap = new Map<string, boolean>(
+          (apiNodes as ApiNode[])
+            .filter((n: ApiNode) => n.type === 'proxmox' || n.type === 'group')
+            .map((n: ApiNode) => [n.id, n.type === 'group' ? true : n.container_mode !== false])
+        )
+        loadCanvas(
+          (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxMap)),
+          (apiEdges as ApiEdge[]).map(deserializeApiEdge),
+        )
+        setViewState('ready')
+      })
+      .catch((err) => {
+        if (!err.response) { setViewState('network-error'); return }
+        const detail: string = err.response.data?.detail ?? ''
+        setViewState(detail === 'Live view is disabled' ? 'disabled' : 'invalid-key')
+      })
+  }, [loadCanvas])
+
+  useEffect(() => {
+    if (!fitViewPending || nodes.length === 0) return
+    const id = setTimeout(() => {
+      fitView({ padding: 0.12, duration: 350 })
+      clearFitViewPending()
+    }, 50)
+    return () => clearTimeout(id)
+  }, [fitViewPending, nodes.length, fitView, clearFitViewPending])
+
+  const onNodeClick = useCallback((_: React.MouseEvent, node: Node<NodeData>) => {
+    const ip = node.data.ip
+    if (ip) window.open(`http://${ip}`, '_blank', 'noopener,noreferrer')
+  }, [])
+
+  if (viewState === 'loading') {
+    return (
+      <div className="flex h-screen w-screen items-center justify-center bg-[#0d1117] text-[#8b949e]">
+        Loading…
+      </div>
+    )
+  }
+
+  if (viewState !== 'ready') {
+    const messages: Record<Exclude<ViewState, 'loading' | 'ready'>, string> = {
+      disabled: 'Live view is disabled on this instance.',
+      'invalid-key': 'Invalid or expired live view key.',
+      'no-key': 'Missing key — use ?key=your-secret in the URL.',
+      'network-error': 'Could not reach the server. Check your connection.',
+    }
+    return (
+      <div className="flex h-screen w-screen items-center justify-center bg-[#0d1117]">
+        <div className="text-center space-y-2">
+          <p className="text-[#f85149] text-lg font-medium">Access Denied</p>
+          <p className="text-[#8b949e] text-sm">{messages[viewState]}</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="w-full h-screen" style={{ background: theme.colors.canvasBackground }}>
+      <ReactFlow
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
+        nodesDraggable={false}
+        nodesConnectable={false}
+        elementsSelectable={false}
+        panOnDrag
+        zoomOnScroll
+        colorMode={theme.colors.reactFlowColorMode}
+        connectionMode={ConnectionMode.Loose}
+        onNodeClick={onNodeClick}
+      >
+        <Background
+          variant={BackgroundVariant.Dots}
+          gap={24}
+          size={1}
+          color={theme.colors.canvasDotColor}
+        />
+        <Controls showInteractive={false} />
+      </ReactFlow>
+    </div>
+  )
+}
+
+export default function LiveView() {
+  return (
+    <ReactFlowProvider>
+      <LiveViewCanvas />
+    </ReactFlowProvider>
+  )
+}

frontend/src/components/LoginPage.tsx

@@ -20,8 +20,9 @@ export function LoginPage() {
     try {
       const res = await authApi.login(username, password)
       login(res.data.access_token)
-    } catch {
-      setError('Invalid username or password')
+    } catch (err: unknown) {
+      const hasResponse = err && typeof err === 'object' && 'response' in err
+      setError(hasResponse ? 'Invalid username or password' : 'Could not reach the server — check your CORS_ORIGINS setting')
     } finally {
       setLoading(false)
     }
@@ -95,7 +96,7 @@ export function LoginPage() {
         </form>
 
         <p className="text-center text-[10px] text-muted-foreground/40 mt-4">
-          Credentials configured in <span className="font-mono">config.yml</span>
+          Credentials configured in <span className="font-mono">.env</span>
         </p>
       </div>
     </div>

frontend/src/components/__tests__/LiveView.test.tsx

@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import { useCanvasStore } from '@/stores/canvasStore'
+
+// ── Mock heavy dependencies ────────────────────────────────────────────────
+
+vi.mock('@xyflow/react', () => ({
+  ReactFlowProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  ReactFlow: () => <div data-testid="react-flow" />,
+  Background: () => null,
+  Controls: () => null,
+  BackgroundVariant: { Dots: 'dots' },
+  ConnectionMode: { Loose: 'loose' },
+  Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
+  useReactFlow: () => ({ fitView: vi.fn() }),
+}))
+vi.mock('@xyflow/react/dist/style.css', () => ({}))
+
+vi.mock('@/api/client', () => ({
+  liveviewApi: { load: vi.fn() },
+}))
+
+import { liveviewApi } from '@/api/client'
+import LiveView from '../LiveView'
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function setSearch(params: string) {
+  Object.defineProperty(window, 'location', {
+    writable: true,
+    value: { ...window.location, search: params, pathname: '/view' },
+  })
+}
+
+const canvasPayload = {
+  data: {
+    nodes: [{
+      id: 'n1', type: 'server', label: 'CI Node', status: 'online',
+      services: [], pos_x: 0, pos_y: 0,
+      created_at: '2024-01-01T00:00:00Z', updated_at: '2024-01-01T00:00:00Z',
+    }],
+    edges: [],
+    viewport: { x: 0, y: 0, zoom: 1 },
+  },
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe('LiveView (non-standalone)', () => {
+  beforeEach(() => {
+    vi.mocked(liveviewApi.load).mockReset()
+    useCanvasStore.setState({ nodes: [], edges: [] })
+  })
+
+  afterEach(() => { setSearch('') })
+
+  // ── No key ────────────────────────────────────────────────────────────────
+
+  it('shows no-key error when ?key= is missing', async () => {
+    setSearch('')
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByText('Access Denied')).toBeDefined()
+      expect(screen.getByText(/Missing key/)).toBeDefined()
+    })
+    expect(liveviewApi.load).not.toHaveBeenCalled()
+  })
+
+  // ── Disabled ──────────────────────────────────────────────────────────────
+
+  it('shows disabled error when backend returns "Live view is disabled"', async () => {
+    setSearch('?key=anything')
+    vi.mocked(liveviewApi.load).mockRejectedValue({
+      response: { data: { detail: 'Live view is disabled' } },
+    })
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByText(/disabled on this instance/)).toBeDefined()
+    })
+  })
+
+  // ── Invalid key ───────────────────────────────────────────────────────────
+
+  it('shows invalid-key error when backend returns "Invalid live view key"', async () => {
+    setSearch('?key=wrong')
+    vi.mocked(liveviewApi.load).mockRejectedValue({
+      response: { data: { detail: 'Invalid live view key' } },
+    })
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByText(/Invalid or expired/)).toBeDefined()
+    })
+  })
+
+  it('shows network-error for non-response errors (offline, CORS, 500)', async () => {
+    setSearch('?key=anything')
+    vi.mocked(liveviewApi.load).mockRejectedValue(new Error('network'))
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByText(/Could not reach the server/)).toBeDefined()
+    })
+  })
+
+  // ── Valid key → canvas rendered ───────────────────────────────────────────
+
+  it('renders the canvas on valid key', async () => {
+    setSearch('?key=correct-key')
+    vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByTestId('react-flow')).toBeDefined()
+    })
+    expect(liveviewApi.load).toHaveBeenCalledWith('correct-key')
+  })
+
+  it('loads nodes into the canvas store on success', async () => {
+    setSearch('?key=secret')
+    vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)
+    render(<LiveView />)
+    await waitFor(() => {
+      expect(screen.getByTestId('react-flow')).toBeDefined()
+    })
+    const { nodes } = useCanvasStore.getState()
+    expect(nodes.find((n) => n.id === 'n1')).toBeDefined()
+  })
+
+  // ── No editing props passed ───────────────────────────────────────────────
+
+  it('does not show any Access Denied when key is valid', async () => {
+    setSearch('?key=valid')
+    vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)
+    render(<LiveView />)
+    await waitFor(() => expect(screen.getByTestId('react-flow')).toBeDefined())
+    expect(screen.queryByText('Access Denied')).toBeNull()
+  })
+})
+
+// ── Standalone mode ────────────────────────────────────────────────────────
+
+const XYFLOW_MOCK = {
+  ReactFlowProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  ReactFlow: () => <div data-testid="react-flow" />,
+  Background: () => null,
+  Controls: () => null,
+  BackgroundVariant: { Dots: 'dots' },
+  ConnectionMode: { Loose: 'loose' },
+  Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
+  useReactFlow: () => ({ fitView: vi.fn() }),
+}
+
+describe('LiveView (standalone — localStorage)', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    useCanvasStore.setState({ nodes: [], edges: [] })
+  })
+
+  afterEach(() => {
+    setSearch('')
+    vi.unstubAllEnvs()
+  })
+
+  it('loads canvas from localStorage without calling the API', async () => {
+    const stored = {
+      nodes: [{
+        id: 'ls-node', type: 'router',
+        position: { x: 10, y: 20 },
+        data: { label: 'Router', type: 'router', status: 'unknown', services: [] },
+      }],
+      edges: [],
+    }
+    localStorage.setItem('homelable_canvas', JSON.stringify(stored))
+
+    vi.stubEnv('VITE_STANDALONE', 'true')
+    vi.resetModules()
+    const mockLoad = vi.fn()
+    vi.doMock('@xyflow/react', () => XYFLOW_MOCK)
+    vi.doMock('@xyflow/react/dist/style.css', () => ({}))
+    vi.doMock('@/api/client', () => ({ liveviewApi: { load: mockLoad } }))
+    const { default: LiveViewStandalone } = await import('../LiveView')
+
+    setSearch('')
+    render(<LiveViewStandalone />)
+
+    await waitFor(() => {
+      expect(screen.getByTestId('react-flow')).toBeDefined()
+    })
+    expect(mockLoad).not.toHaveBeenCalled()
+  })
+
+  it('shows canvas (empty) when localStorage has no saved data', async () => {
+    vi.stubEnv('VITE_STANDALONE', 'true')
+    vi.resetModules()
+    const mockLoad = vi.fn()
+    vi.doMock('@xyflow/react', () => XYFLOW_MOCK)
+    vi.doMock('@xyflow/react/dist/style.css', () => ({}))
+    vi.doMock('@/api/client', () => ({ liveviewApi: { load: mockLoad } }))
+    const { default: LiveViewStandalone } = await import('../LiveView')
+
+    setSearch('')
+    render(<LiveViewStandalone />)
+
+    await waitFor(() => {
+      expect(screen.getByTestId('react-flow')).toBeDefined()
+    })
+    expect(mockLoad).not.toHaveBeenCalled()
+  })
+})

frontend/src/components/__tests__/LoginPage.test.tsx

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { LoginPage } from '../LoginPage'
+import { useAuthStore } from '@/stores/authStore'
+
+vi.mock('@/api/client', () => ({
+  authApi: {
+    login: vi.fn(),
+  },
+}))
+
+import { authApi } from '@/api/client'
+
+describe('LoginPage', () => {
+  beforeEach(() => {
+    useAuthStore.setState({ token: null, isAuthenticated: false })
+    vi.mocked(authApi.login).mockReset()
+  })
+
+  // ── Rendering ────────────────────────────────────────────────────────────
+
+  it('renders username and password fields', () => {
+    render(<LoginPage />)
+    expect(screen.getByLabelText('Username')).toBeDefined()
+    expect(screen.getByLabelText('Password')).toBeDefined()
+  })
+
+  it('renders a Sign in button', () => {
+    render(<LoginPage />)
+    expect(screen.getByRole('button', { name: /sign in/i })).toBeDefined()
+  })
+
+  // ── Security checks ──────────────────────────────────────────────────────
+
+  it('password field type is "password" — not rendered as plain text', () => {
+    render(<LoginPage />)
+    const pw = screen.getByLabelText('Password') as HTMLInputElement
+    expect(pw.type).toBe('password')
+  })
+
+  it('username field has autocomplete="username"', () => {
+    render(<LoginPage />)
+    const un = screen.getByLabelText('Username') as HTMLInputElement
+    expect(un.getAttribute('autocomplete')).toBe('username')
+  })
+
+  it('password field has autocomplete="current-password" (supports password managers)', () => {
+    render(<LoginPage />)
+    const pw = screen.getByLabelText('Password') as HTMLInputElement
+    expect(pw.getAttribute('autocomplete')).toBe('current-password')
+  })
+
+  it('shows a generic error message — no credential enumeration', async () => {
+    vi.mocked(authApi.login).mockRejectedValue({ response: { status: 401 } })
+    render(<LoginPage />)
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'wrongpass' } })
+    fireEvent.submit(screen.getByRole('button', { name: /sign in/i }).closest('form')!)
+    await waitFor(() => {
+      expect(screen.getByText('Invalid username or password')).toBeDefined()
+    })
+    // Must show exactly ONE error — not separate per-field messages (no enumeration)
+    const errors = document.querySelectorAll('p.text-\\[\\#f85149\\]')
+    expect(errors.length).toBe(1)
+    expect(errors[0].textContent).toBe('Invalid username or password')
+  })
+
+  it('shows a network error message when no response (e.g. CORS misconfiguration)', async () => {
+    vi.mocked(authApi.login).mockRejectedValue(new Error('Network Error'))
+    render(<LoginPage />)
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'admin' } })
+    fireEvent.submit(screen.getByRole('button', { name: /sign in/i }).closest('form')!)
+    await waitFor(() => {
+      expect(screen.getByText(/Could not reach the server/)).toBeDefined()
+    })
+  })
+
+  it('clears previous error before each new attempt', async () => {
+    vi.mocked(authApi.login)
+      .mockRejectedValueOnce({ response: { status: 401 } })
+      .mockRejectedValueOnce({ response: { status: 401 } })
+    render(<LoginPage />)
+    const form = screen.getByRole('button', { name: /sign in/i }).closest('form')!
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'bad' } })
+    fireEvent.submit(form)
+    await waitFor(() => screen.getByText('Invalid username or password'))
+    fireEvent.submit(form)
+    // Error clears while loading (setError('') before try)
+    await waitFor(() => screen.getByText('Invalid username or password'))
+    expect(screen.getAllByText('Invalid username or password')).toHaveLength(1)
+  })
+
+  it('disables submit button while loading — prevents double-submit', async () => {
+    let resolve!: (v: unknown) => void
+    vi.mocked(authApi.login).mockReturnValue(new Promise((r) => { resolve = r }))
+    render(<LoginPage />)
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'pass' } })
+    fireEvent.submit(screen.getByRole('button', { name: /sign in/i }).closest('form')!)
+    await waitFor(() => {
+      expect((screen.getByRole('button', { name: '' }) as HTMLButtonElement).disabled).toBe(true)
+    })
+    resolve({ data: { access_token: 'tok' } })
+  })
+
+  it('calls authApi.login with credentials via POST body (not URL params)', async () => {
+    vi.mocked(authApi.login).mockResolvedValue({ data: { access_token: 'tok' } } as never)
+    render(<LoginPage />)
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'secret' } })
+    fireEvent.submit(screen.getByRole('button', { name: /sign in/i }).closest('form')!)
+    await waitFor(() => {
+      expect(authApi.login).toHaveBeenCalledWith('admin', 'secret')
+    })
+  })
+
+  it('stores token in authStore on successful login', async () => {
+    vi.mocked(authApi.login).mockResolvedValue({ data: { access_token: 'mytoken123' } } as never)
+    render(<LoginPage />)
+    fireEvent.change(screen.getByLabelText('Username'), { target: { value: 'admin' } })
+    fireEvent.change(screen.getByLabelText('Password'), { target: { value: 'correct' } })
+    fireEvent.submit(screen.getByRole('button', { name: /sign in/i }).closest('form')!)
+    await waitFor(() => {
+      expect(useAuthStore.getState().isAuthenticated).toBe(true)
+      expect(useAuthStore.getState().token).toBe('mytoken123')
+    })
+  })
+
+  it('token persisted via sessionStorage — not localStorage', () => {
+    // The authStore uses createJSONStorage(() => sessionStorage)
+    // Verify the storage key exists in sessionStorage after login
+    render(<LoginPage />)
+    // Even before login, the store is backed by sessionStorage
+    expect(typeof sessionStorage).toBe('object')
+    // localStorage should NOT contain the auth token
+    expect(localStorage.getItem('homelable-auth')).toBeNull()
+  })
+
+  it('does not show error on initial render', () => {
+    render(<LoginPage />)
+    expect(screen.queryByText('Invalid username or password')).toBeNull()
+  })
+
+  it('requires username (HTML required attribute)', () => {
+    render(<LoginPage />)
+    const un = screen.getByLabelText('Username') as HTMLInputElement
+    expect(un.required).toBe(true)
+  })
+
+  it('requires password (HTML required attribute)', () => {
+    render(<LoginPage />)
+    const pw = screen.getByLabelText('Password') as HTMLInputElement
+    expect(pw.required).toBe(true)
+  })
+})

frontend/src/components/canvas/AlignmentGuides.tsx

@@ -0,0 +1,70 @@
+import { useViewport } from '@xyflow/react'
+import type { Guide } from '@/utils/alignment'
+
+interface AlignmentGuidesProps {
+  guides: Guide[]
+  color?: string
+}
+
+/**
+ * SVG overlay that draws alignment guide lines on top of the React Flow canvas.
+ * Coordinates are in canvas (flow) space; we read the viewport transform to
+ * project them into screen space so lines stay locked to nodes when the user
+ * pans or zooms.
+ */
+export function AlignmentGuides({ guides, color = '#00d4ff' }: AlignmentGuidesProps) {
+  const { x: vx, y: vy, zoom } = useViewport()
+
+  if (guides.length === 0) return null
+
+  return (
+    <svg
+      style={{
+        position: 'absolute',
+        inset: 0,
+        width: '100%',
+        height: '100%',
+        pointerEvents: 'none',
+        zIndex: 5,
+        overflow: 'visible',
+      }}
+    >
+      {guides.map((g, i) => {
+        if (g.axis === 'x') {
+          const x = g.position * zoom + vx
+          const y1 = g.start * zoom + vy
+          const y2 = g.end * zoom + vy
+          return (
+            <line
+              key={`x-${i}-${g.position}`}
+              x1={x}
+              y1={y1}
+              x2={x}
+              y2={y2}
+              stroke={color}
+              strokeWidth={1}
+              strokeDasharray="4 3"
+              shapeRendering="crispEdges"
+            />
+          )
+        }
+        const y = g.position * zoom + vy
+        const x1 = g.start * zoom + vx
+        const x2 = g.end * zoom + vx
+        return (
+          <line
+            key={`y-${i}-${g.position}`}
+            x1={x1}
+            y1={y}
+            x2={x2}
+            y2={y}
+            stroke={color}
+            strokeWidth={1}
+            strokeDasharray="4 3"
+            shapeRendering="crispEdges"
+          />
+        )
+      })}
+    </svg>
+  )
+}

frontend/src/components/canvas/CanvasContainer.tsx

@@ -1,34 +1,66 @@
-import { useCallback } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import {
   ReactFlow,
   Background,
   Controls,
+  ControlButton,
   BackgroundVariant,
   ConnectionMode,
+  SelectionMode,
+  useReactFlow,
   type Node,
   type Edge,
   type Connection,
 } from '@xyflow/react'
+import { MousePointer2, Hand } from 'lucide-react'
 import '@xyflow/react/dist/style.css'
 import { useCanvasStore } from '@/stores/canvasStore'
+import { useThemeStore } from '@/stores/themeStore'
+import { THEMES } from '@/utils/themes'
 import { nodeTypes } from './nodes/nodeTypes'
 import { edgeTypes } from './edges/edgeTypes'
+import { SearchBar } from './SearchBar'
+import { AlignmentGuides } from './AlignmentGuides'
+import { useAlignmentGuides } from '@/hooks/useAlignmentGuides'
 import type { NodeData, EdgeData } from '@/types'
 
 interface CanvasContainerProps {
   onConnect?: (connection: Connection) => void
   onEdgeDoubleClick?: (edge: Edge<EdgeData>) => void
+  onNodeDoubleClick?: (node: Node<NodeData>) => void
+  onNodeDragStart?: () => void
+  onOpenPending?: (deviceId: string) => void
 }
 
-export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick }: CanvasContainerProps) {
+export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick, onNodeDoubleClick, onNodeDragStart, onOpenPending }: CanvasContainerProps) {
+  const [lassoMode, setLassoMode] = useState(true)
   const {
     nodes, edges,
     onNodesChange, onEdgesChange,
-    setSelectedNode,
+    setSelectedNode, snapshotHistory,
+    fitViewPending, clearFitViewPending,
   } = useCanvasStore()
+  const { fitView } = useReactFlow()
 
-  const onNodeClick = useCallback((_: React.MouseEvent, node: Node<NodeData>) => {
-    setSelectedNode(node.id)
+  // Fit view after canvas loads (fitViewPending is set by loadCanvas)
+  useEffect(() => {
+    if (!fitViewPending || nodes.length === 0) return
+    const id = setTimeout(() => {
+      fitView({ padding: 0.12, duration: 350 })
+      clearFitViewPending()
+    }, 50)
+    return () => clearTimeout(id)
+  }, [fitViewPending, nodes.length, fitView, clearFitViewPending])
+
+  const activeTheme = useThemeStore((s) => s.activeTheme)
+  const theme = THEMES[activeTheme]
+
+  const onNodeClick = useCallback((e: React.MouseEvent, node: Node<NodeData>) => {
+    if (e.ctrlKey || e.metaKey) {
+      setSelectedNode(null)
+    } else {
+      setSelectedNode(node.id)
+    }
   }, [setSelectedNode])
 
   const onPaneClick = useCallback(() => {
@@ -39,9 +71,24 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick }:
     onEdgeDoubleClick?.(edge)
   }, [onEdgeDoubleClick])
 
+  const handleNodeDoubleClick = useCallback((_: React.MouseEvent, node: Node<NodeData>) => {
+    onNodeDoubleClick?.(node)
+  }, [onNodeDoubleClick])
+
+  const handleBeforeDelete = useCallback(async () => {
+    snapshotHistory()
+    return true
+  }, [snapshotHistory])
+
+  const isValidConnection = useCallback(
+    (connection: { source: string | null; target: string | null }) => connection.source !== connection.target,
+    []
+  )
+
+  const { guides, onNodeDrag, onNodeDragStop } = useAlignmentGuides()
 
   return (
-    <div className="w-full h-full">
+    <div className="w-full h-full" style={{ background: theme.colors.canvasBackground }}>
       <ReactFlow
         nodes={nodes}
         edges={edges}
@@ -51,23 +98,44 @@ export function CanvasContainer({ onConnect: onConnectProp, onEdgeDoubleClick }:
         onNodeClick={onNodeClick}
         onPaneClick={onPaneClick}
         onEdgeDoubleClick={handleEdgeDoubleClick}
+        onNodeDoubleClick={handleNodeDoubleClick}
+        onNodeDragStart={onNodeDragStart}
+        onNodeDrag={onNodeDrag}
+        onNodeDragStop={onNodeDragStop}
         nodeTypes={nodeTypes}
         edgeTypes={edgeTypes}
+        deleteKeyCode={['Backspace', 'Delete']}
+        onBeforeDelete={handleBeforeDelete}
+        selectionOnDrag={lassoMode}
+        panOnDrag={lassoMode ? [1, 2] : true}
+        panActivationKeyCode="Space"
+        selectionMode={SelectionMode.Partial}
+        multiSelectionKeyCode={['Meta', 'Control']}
+        minZoom={0.25}
+        maxZoom={2.5}
         snapToGrid
-        snapGrid={[16, 16]}
-        fitView
-        colorMode="dark"
+        snapGrid={[8, 8]}
+        colorMode={theme.colors.reactFlowColorMode}
         elevateNodesOnSelect={false}
         connectionMode={ConnectionMode.Loose}
-        isValidConnection={(connection) => connection.source !== connection.target}
+        isValidConnection={isValidConnection}
       >
         <Background
           variant={BackgroundVariant.Dots}
-          gap={24}
+          gap={16}
           size={1}
-          color="#30363d"
+          color={theme.colors.canvasDotColor}
         />
-        <Controls />
+        <SearchBar onOpenPending={onOpenPending} />
+        <AlignmentGuides guides={guides} />
+        <Controls>
+          <ControlButton
+            onClick={() => setLassoMode((m) => !m)}
+            title={lassoMode ? 'Switch to pan mode (Space to pan)' : 'Switch to lasso mode'}
+          >
+            {lassoMode ? <MousePointer2 size={12} /> : <Hand size={12} />}
+          </ControlButton>
+        </Controls>
       </ReactFlow>
     </div>
   )

frontend/src/components/canvas/SearchBar.tsx

@@ -0,0 +1,220 @@
+import { useState, useEffect, useRef } from 'react'
+import { useReactFlow } from '@xyflow/react'
+import { Search, X } from 'lucide-react'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { scanApi } from '@/api/client'
+import { NODE_TYPE_LABELS } from '@/types'
+import type { PendingDevice } from '@/components/modals/PendingDeviceModal'
+
+interface SearchBarProps {
+  onOpenPending?: (deviceId: string) => void
+}
+
+export function SearchBar({ onOpenPending }: SearchBarProps) {
+  const [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const [pendingDevices, setPendingDevices] = useState<PendingDevice[]>([])
+  const inputRef = useRef<HTMLInputElement>(null)
+  const { nodes, setSelectedNode } = useCanvasStore()
+  const { setCenter } = useReactFlow()
+
+  useEffect(() => {
+    if (!open) return
+    scanApi.pending().then((res) => setPendingDevices(res.data)).catch(() => {})
+  }, [open])
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === 'f') {
+        e.preventDefault()
+        setOpen(true)
+      }
+      if (e.key === 'Escape') {
+        setOpen(false)
+        setQuery('')
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [])
+
+  useEffect(() => {
+    if (open) inputRef.current?.focus()
+  }, [open])
+
+  const q = query.toLowerCase().trim()
+  const nodeResults = q
+    ? nodes.filter((n) => {
+        if (n.data.type === 'groupRect') return false
+        return (
+          n.data.label?.toLowerCase().includes(q) ||
+          n.data.ip?.toLowerCase().includes(q) ||
+          n.data.hostname?.toLowerCase().includes(q) ||
+          (n.data.services ?? []).some((s) => s.service_name?.toLowerCase().includes(q))
+        )
+      })
+    : []
+
+  const pendingResults = q
+    ? pendingDevices.filter((d) =>
+        d.ip?.toLowerCase().includes(q) ||
+        d.hostname?.toLowerCase().includes(q) ||
+        d.friendly_name?.toLowerCase().includes(q) ||
+        d.ieee_address?.toLowerCase().includes(q) ||
+        d.services.some((s) =>
+          s.service_name?.toLowerCase().includes(q) ||
+          s.category?.toLowerCase().includes(q)
+        )
+      ).slice(0, 4)
+    : []
+
+  const totalResults = nodeResults.length + pendingResults.length
+
+  const goToNode = (id: string) => {
+    const node = nodes.find((n) => n.id === id)
+    if (!node) return
+    setSelectedNode(id)
+    // For grouped nodes, add parent's absolute position
+    let absX = node.position.x
+    let absY = node.position.y
+    if (node.parentId) {
+      const parent = nodes.find((n) => n.id === node.parentId)
+      if (parent) { absX += parent.position.x; absY += parent.position.y }
+    }
+    const w = node.measured?.width ?? node.width ?? 200
+    const h = node.measured?.height ?? node.height ?? 80
+    setCenter(absX + w / 2, absY + h / 2, { zoom: 1.5, duration: 500 })
+    setOpen(false)
+    setQuery('')
+  }
+
+  if (!open) return null
+
+  return (
+    <div
+      className="nodrag nowheel"
+      style={{
+        position: 'absolute',
+        top: 16,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        zIndex: 1000,
+        width: 360,
+        pointerEvents: 'all',
+      }}
+    >
+      <div style={{
+        background: '#161b22',
+        border: '1px solid #30363d',
+        borderRadius: 8,
+        boxShadow: '0 8px 24px rgba(0,0,0,0.6)',
+        overflow: 'hidden',
+      }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '8px 12px' }}>
+          <Search size={14} style={{ color: '#8b949e', flexShrink: 0 }} />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="Search by name, IP, hostname or service…"
+            style={{
+              flex: 1,
+              background: 'transparent',
+              border: 'none',
+              outline: 'none',
+              color: '#e6edf3',
+              fontSize: 13,
+            }}
+          />
+          {query && (
+            <span style={{ fontSize: 11, color: '#6e7681', flexShrink: 0 }}>
+              {totalResults} result{totalResults !== 1 ? 's' : ''}
+            </span>
+          )}
+          <button
+            onClick={() => { setOpen(false); setQuery('') }}
+            aria-label="Close search"
+            style={{ color: '#8b949e', background: 'none', border: 'none', cursor: 'pointer', padding: 2 }}
+          >
+            <X size={14} />
+          </button>
+        </div>
+
+        {totalResults > 0 && (
+          <div style={{ borderTop: '1px solid #30363d', maxHeight: 260, overflowY: 'auto' }}>
+            {nodeResults.map((n) => (
+              <button
+                key={n.id}
+                onClick={() => goToNode(n.id)}
+                style={{
+                  width: '100%',
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 10,
+                  padding: '7px 12px',
+                  background: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  textAlign: 'left',
+                }}
+                onMouseEnter={(e) => (e.currentTarget.style.background = '#21262d')}
+                onMouseLeave={(e) => (e.currentTarget.style.background = 'none')}
+              >
+                <span style={{ fontSize: 12, fontWeight: 600, color: '#e6edf3', flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                  {n.data.label}
+                </span>
+                {n.data.ip && (
+                  <span style={{ fontSize: 11, color: '#8b949e', fontFamily: 'JetBrains Mono, monospace', flexShrink: 0 }}>
+                    {n.data.ip}
+                  </span>
+                )}
+                <span style={{ fontSize: 10, color: '#6e7681', flexShrink: 0 }}>
+                  {NODE_TYPE_LABELS[n.data.type] ?? n.data.type}
+                </span>
+              </button>
+            ))}
+            {pendingResults.length > 0 && nodeResults.length > 0 && (
+              <div style={{ height: 1, background: '#30363d', margin: '2px 0' }} />
+            )}
+            {pendingResults.map((d) => {
+              const serviceName = d.services.find((s) => s.service_name)?.service_name
+              return (
+                <button
+                  key={d.id}
+                  onClick={() => { onOpenPending?.(d.id); setOpen(false); setQuery('') }}
+                  style={{
+                    width: '100%',
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 10,
+                    padding: '7px 12px',
+                    background: 'none',
+                    border: 'none',
+                    cursor: 'pointer',
+                    textAlign: 'left',
+                  }}
+                  onMouseEnter={(e) => (e.currentTarget.style.background = '#21262d')}
+                  onMouseLeave={(e) => (e.currentTarget.style.background = 'none')}
+                >
+                  <span style={{ fontSize: 10, color: '#e3b341', fontFamily: 'JetBrains Mono, monospace', flexShrink: 0 }}>pending</span>
+                  <span style={{ fontSize: 12, fontWeight: 600, color: '#e6edf3', flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                    {d.friendly_name ?? d.hostname ?? d.ip ?? d.ieee_address ?? 'device'}
+                  </span>
+                  <span style={{ fontSize: 11, color: '#8b949e', fontFamily: 'JetBrains Mono, monospace', flexShrink: 0 }}>
+                    {serviceName ?? d.ip ?? d.ieee_address ?? ''}
+                  </span>
+                </button>
+              )
+            })}
+          </div>
+        )}
+
+        {q && totalResults === 0 && (
+          <div style={{ borderTop: '1px solid #30363d', padding: '10px 12px', fontSize: 12, color: '#6e7681', textAlign: 'center' }}>
+            No results for &ldquo;{query}&rdquo;
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/canvas/__tests__/AlignmentGuides.test.tsx

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { AlignmentGuides } from '../AlignmentGuides'
+import type { Guide } from '@/utils/alignment'
+
+vi.mock('@xyflow/react', () => ({
+  useViewport: () => ({ x: 50, y: 100, zoom: 2 }),
+}))
+
+describe('AlignmentGuides', () => {
+  it('renders nothing when no guides', () => {
+    const { container } = render(<AlignmentGuides guides={[]} />)
+    expect(container.querySelector('svg')).toBeNull()
+  })
+
+  it('projects an x-axis guide through the viewport transform', () => {
+    const guides: Guide[] = [{ axis: 'x', position: 100, start: 0, end: 200 }]
+    const { container } = render(<AlignmentGuides guides={guides} />)
+    const line = container.querySelector('line')!
+    // x = position * zoom + vx → 100*2 + 50 = 250
+    expect(line.getAttribute('x1')).toBe('250')
+    expect(line.getAttribute('x2')).toBe('250')
+    // y1 = start * zoom + vy → 0*2 + 100 = 100; y2 = 200*2 + 100 = 500
+    expect(line.getAttribute('y1')).toBe('100')
+    expect(line.getAttribute('y2')).toBe('500')
+  })
+
+  it('projects a y-axis guide horizontally', () => {
+    const guides: Guide[] = [{ axis: 'y', position: 50, start: 10, end: 60 }]
+    const { container } = render(<AlignmentGuides guides={guides} />)
+    const line = container.querySelector('line')!
+    // y = 50*2 + 100 = 200; x1 = 10*2 + 50 = 70; x2 = 60*2 + 50 = 170
+    expect(line.getAttribute('y1')).toBe('200')
+    expect(line.getAttribute('y2')).toBe('200')
+    expect(line.getAttribute('x1')).toBe('70')
+    expect(line.getAttribute('x2')).toBe('170')
+  })
+
+  it('renders one line per guide', () => {
+    const guides: Guide[] = [
+      { axis: 'x', position: 100, start: 0, end: 200 },
+      { axis: 'y', position: 50, start: 10, end: 60 },
+    ]
+    const { container } = render(<AlignmentGuides guides={guides} />)
+    expect(container.querySelectorAll('line')).toHaveLength(2)
+  })
+})

frontend/src/components/canvas/__tests__/BaseNode.test.tsx

@@ -0,0 +1,246 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Server } from 'lucide-react'
+import { BaseNode } from '../nodes/BaseNode'
+import type { NodeData } from '@/types'
+import type { Node } from '@xyflow/react'
+
+let mockZoom = 1
+
+vi.mock('@xyflow/react', () => ({
+  Handle: () => null,
+  Position: { Top: 'top', Bottom: 'bottom' },
+  NodeResizer: () => null,
+  useUpdateNodeInternals: () => vi.fn(),
+  useViewport: () => ({ zoom: mockZoom }),
+}))
+
+vi.mock('@/stores/themeStore', () => ({
+  useThemeStore: (sel: (s: { activeTheme: string }) => unknown) => sel({ activeTheme: 'dark' }),
+}))
+
+vi.mock('@/stores/canvasStore', () => ({
+  useCanvasStore: (sel: (s: { hideIp: boolean }) => unknown) => sel({ hideIp: false }),
+}))
+
+vi.mock('@/utils/themes', () => ({
+  THEMES: {
+    dark: {
+      colors: {
+        statusColors: { online: '#39d353', offline: '#f85149', pending: '#e3b341', unknown: '#8b949e' },
+        nodeSubtextColor: '#8b949e',
+        nodeLabelColor: '#e6edf3',
+        nodeIconBackground: '#21262d',
+        handleBackground: '#30363d',
+        handleBorder: '#30363d',
+      },
+    },
+  },
+}))
+
+vi.mock('@/utils/nodeColors', () => ({
+  resolveNodeColors: () => ({ background: '#161b22', border: '#30363d', icon: '#00d4ff' }),
+}))
+
+vi.mock('@/utils/nodeIcons', () => ({
+  resolveNodeIcon: (_typeIcon: unknown) => _typeIcon,
+  isBrandIconKey: (k: string | undefined) => !!k && k.startsWith('brand:'),
+}))
+
+vi.mock('@/utils/maskIp', () => ({
+  maskIp: (ip: string) => ip,
+  splitIps: (ip: string) => ip ? ip.split(',').map((s: string) => s.trim()).filter(Boolean) : [],
+  primaryIp: (ip: string) => ip ? ip.split(',')[0].trim() : '',
+}))
+
+vi.mock('@/utils/propertyIcons', () => ({
+  resolvePropertyIcon: (icon: string | null) => icon ? Server : null,
+}))
+
+vi.mock('@/utils/handleUtils', () => ({
+  bottomHandleId: (idx: number) => idx === 0 ? 'bottom' : `bottom-${idx + 1}`,
+  bottomHandlePositions: () => [50],
+  clampBottomHandles: (n: unknown) => typeof n === 'number' ? n : 1,
+}))
+
+beforeEach(() => { mockZoom = 1 })
+
+function makeNode(data: Partial<NodeData>): Node<NodeData> {
+  return {
+    id: 'n1',
+    type: data.type ?? 'server',
+    position: { x: 0, y: 0 },
+    data: {
+      label: 'Test Node',
+      type: 'server',
+      status: 'online',
+      services: [],
+      ...data,
+    },
+  }
+}
+
+function renderBaseNode(data: Partial<NodeData>) {
+  const node = makeNode(data)
+  return render(
+    <BaseNode
+      id={node.id}
+      data={node.data}
+      selected={false}
+      icon={Server}
+      type="server"
+      dragging={false}
+      zIndex={0}
+      isConnectable={true}
+      positionAbsoluteX={0}
+      positionAbsoluteY={0}
+    />
+  )
+}
+
+describe('BaseNode — borderWidth zoom scaling', () => {
+  beforeEach(() => { mockZoom = 1 })
+
+  it('borderWidth is 1px at zoom=1', () => {
+    mockZoom = 1
+    const { container } = renderBaseNode({})
+    expect((container.firstChild as HTMLElement).style.borderWidth).toBe('1px')
+  })
+
+  it('borderWidth scales to 2px at zoom=0.5', () => {
+    mockZoom = 0.5
+    const { container } = renderBaseNode({})
+    expect((container.firstChild as HTMLElement).style.borderWidth).toBe('2px')
+  })
+
+  it('borderWidth is clamped to 1px at zoom=2', () => {
+    mockZoom = 2
+    const { container } = renderBaseNode({})
+    expect((container.firstChild as HTMLElement).style.borderWidth).toBe('1px')
+  })
+
+  it('boxShadow glow ring uses borderWidth when selected + online at zoom=0.5', () => {
+    mockZoom = 0.5
+    const node = makeNode({ status: 'online' })
+    const { container } = render(
+      <BaseNode id={node.id} data={node.data} selected={true} icon={Server}
+        type="server" dragging={false} zIndex={0} isConnectable={true}
+        positionAbsoluteX={0} positionAbsoluteY={0} />
+    )
+    expect((container.firstChild as HTMLElement).style.boxShadow).toContain('0 0 0 2px')
+  })
+})
+
+describe('BaseNode — properties rendering', () => {
+  it('renders visible properties on the node', () => {
+    renderBaseNode({
+      properties: [
+        { key: 'CPU Model', value: 'i7-12700K', icon: 'Cpu', visible: true },
+        { key: 'RAM', value: '32 GB', icon: 'MemoryStick', visible: true },
+      ],
+    })
+    expect(screen.getByText('CPU Model')).toBeDefined()
+    // Value is rendered with a middle-dot prefix: "· 32 GB"
+    expect(screen.getByText(/32 GB/)).toBeDefined()
+  })
+
+  it('does not render properties with visible=false', () => {
+    renderBaseNode({
+      properties: [
+        { key: 'Secret', value: 'hidden', icon: null, visible: false },
+      ],
+    })
+    expect(screen.queryByText('Secret')).toBeNull()
+  })
+
+  it('renders nothing when properties array is empty', () => {
+    const { container } = renderBaseNode({ properties: [] })
+    // No properties section — only the main node card
+    expect(container.querySelectorAll('.flex.flex-col.gap-1').length).toBe(0)
+  })
+
+  it('renders label and ip regardless of properties', () => {
+    renderBaseNode({
+      label: 'My Server',
+      ip: '192.168.1.10',
+      properties: [{ key: 'OS', value: 'Debian 12', icon: 'Server', visible: true }],
+    })
+    expect(screen.getByText('My Server')).toBeDefined()
+    expect(screen.getByText('192.168.1.10')).toBeDefined()
+    expect(screen.getByText('OS')).toBeDefined()
+  })
+})
+
+describe('BaseNode — services visibility toggle', () => {
+  it('does not render service toggle button on the node', () => {
+    renderBaseNode({ services: [{ service_name: 'nginx', port: 80, protocol: 'tcp' }] })
+    expect(screen.queryByTitle('Show services')).toBeNull()
+  })
+
+  it('renders service rows when services are toggled on', () => {
+    renderBaseNode({
+      ip: '192.168.1.10',
+      custom_colors: { show_services: true },
+      services: [
+        { service_name: 'nginx', port: 80, protocol: 'tcp' },
+        { service_name: 'ssh', port: 22, protocol: 'tcp' },
+      ],
+    })
+
+    expect(screen.getByText('nginx')).toBeDefined()
+    expect(screen.getByText('80')).toBeDefined()
+    expect(screen.getByText('ssh')).toBeDefined()
+  })
+
+  it('renders clickable service links for web services', () => {
+    renderBaseNode({
+      ip: '192.168.1.10',
+      custom_colors: { show_services: true },
+      services: [{ service_name: 'nginx', port: 80, protocol: 'tcp' }],
+    })
+
+    const link = screen.getByRole('link', { name: /nginx/i }) as HTMLAnchorElement
+    expect(link.getAttribute('href')).toBe('http://192.168.1.10:80')
+  })
+
+  it('keeps non-web services as non-clickable rows', () => {
+    renderBaseNode({
+      ip: '192.168.1.10',
+      custom_colors: { show_services: true },
+      services: [{ service_name: 'ssh', port: 22, protocol: 'tcp' }],
+    })
+
+    expect(screen.queryByRole('link', { name: /ssh/i })).toBeNull()
+  })
+})
+
+describe('BaseNode — legacy hardware fallback', () => {
+  it('renders legacy hardware when properties is undefined and show_hardware is true', () => {
+    renderBaseNode({
+      properties: undefined,
+      show_hardware: true,
+      cpu_model: 'Intel Xeon E5-2680',
+      ram_gb: 32,
+    })
+    expect(screen.getByText('Intel Xeon E5-2680')).toBeDefined()
+  })
+
+  it('does not render legacy hardware when properties array is present (even if empty)', () => {
+    renderBaseNode({
+      properties: [],
+      show_hardware: true,
+      cpu_model: 'Intel Xeon E5-2680',
+    })
+    // properties array exists → new system, legacy section skipped
+    expect(screen.queryByText('Intel Xeon E5-2680')).toBeNull()
+  })
+
+  it('does not render legacy hardware when show_hardware is false', () => {
+    renderBaseNode({
+      properties: undefined,
+      show_hardware: false,
+      cpu_model: 'Intel Xeon E5-2680',
+    })
+    expect(screen.queryByText('Intel Xeon E5-2680')).toBeNull()
+  })
+})

frontend/src/components/canvas/__tests__/CanvasContainer.test.tsx

@@ -0,0 +1,235 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { CanvasContainer } from '../CanvasContainer'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { useThemeStore } from '@/stores/themeStore'
+import type { Node, Edge } from '@xyflow/react'
+import type { NodeData, EdgeData } from '@/types'
+
+// Capture props passed to ReactFlow so we can test the callbacks
+let rfProps: Record<string, unknown> = {}
+
+vi.mock('@xyflow/react', () => ({
+  ReactFlow: (props: Record<string, unknown>) => {
+    rfProps = props
+    return <div data-testid="react-flow" />
+  },
+  Background: () => null,
+  Controls: () => null,
+  ControlButton: () => null,
+  BackgroundVariant: { Dots: 'dots' },
+  ConnectionMode: { Loose: 'loose' },
+  SelectionMode: { Partial: 'partial' },
+  Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
+  useReactFlow: () => ({ fitView: vi.fn() }),
+}))
+
+vi.mock('@xyflow/react/dist/style.css', () => ({}))
+
+function makeNode(id: string): Node<NodeData> {
+  return {
+    id,
+    type: 'server',
+    position: { x: 0, y: 0 },
+    data: { label: id, type: 'server', status: 'unknown', services: [] },
+  }
+}
+
+function makeEdge(id: string): Edge<EdgeData> {
+  return { id, source: 'n1', target: 'n2', type: 'ethernet', data: { type: 'ethernet' } }
+}
+
+describe('CanvasContainer', () => {
+  beforeEach(() => {
+    rfProps = {}
+    useCanvasStore.setState({ nodes: [], edges: [], selectedNodeId: null })
+    useThemeStore.setState({ activeTheme: 'default' })
+  })
+
+  // ── Rendering ─────────────────────────────────────────────────────────────
+
+  it('renders without crashing', () => {
+    const { getByTestId } = render(<CanvasContainer />)
+    expect(getByTestId('react-flow')).toBeDefined()
+  })
+
+  it('passes nodes from store to ReactFlow', () => {
+    useCanvasStore.setState({ nodes: [makeNode('n1'), makeNode('n2')] })
+    render(<CanvasContainer />)
+    expect((rfProps.nodes as Node[]).length).toBe(2)
+  })
+
+  it('passes edges from store to ReactFlow', () => {
+    useCanvasStore.setState({
+      nodes: [makeNode('n1'), makeNode('n2')],
+      edges: [makeEdge('e1')],
+    })
+    render(<CanvasContainer />)
+    expect((rfProps.edges as Edge[]).length).toBe(1)
+  })
+
+  // ── Node click → selection ────────────────────────────────────────────────
+
+  it('calls setSelectedNode with node id on node click', () => {
+    const node = makeNode('n1')
+    useCanvasStore.setState({ nodes: [node] })
+    render(<CanvasContainer />)
+    ;(rfProps.onNodeClick as (...args: unknown[]) => unknown)({} as MouseEvent, node)
+    expect(useCanvasStore.getState().selectedNodeId).toBe('n1')
+  })
+
+  // ── Pane click → deselect ─────────────────────────────────────────────────
+
+  it('calls setSelectedNode(null) on pane click', () => {
+    useCanvasStore.setState({ selectedNodeId: 'n1' })
+    render(<CanvasContainer />)
+    ;(rfProps.onPaneClick as (...args: unknown[]) => unknown)()
+    expect(useCanvasStore.getState().selectedNodeId).toBeNull()
+  })
+
+  // ── Edge double-click ─────────────────────────────────────────────────────
+
+  it('calls onEdgeDoubleClick prop when an edge is double-clicked', () => {
+    const onEdgeDoubleClick = vi.fn()
+    const edge = makeEdge('e1')
+    render(<CanvasContainer onEdgeDoubleClick={onEdgeDoubleClick} />)
+    ;(rfProps.onEdgeDoubleClick as (...args: unknown[]) => unknown)({} as MouseEvent, edge)
+    expect(onEdgeDoubleClick).toHaveBeenCalledWith(edge)
+  })
+
+  it('does not throw when onEdgeDoubleClick is not provided', () => {
+    const edge = makeEdge('e1')
+    render(<CanvasContainer />)
+    expect(() => {
+      ;(rfProps.onEdgeDoubleClick as (...args: unknown[]) => unknown)({} as MouseEvent, edge)
+    }).not.toThrow()
+  })
+
+  // ── Node double-click ─────────────────────────────────────────────────────
+
+  it('calls onNodeDoubleClick prop when a node is double-clicked', () => {
+    const onNodeDoubleClick = vi.fn()
+    const node = makeNode('n1')
+    render(<CanvasContainer onNodeDoubleClick={onNodeDoubleClick} />)
+    ;(rfProps.onNodeDoubleClick as (...args: unknown[]) => unknown)({} as MouseEvent, node)
+    expect(onNodeDoubleClick).toHaveBeenCalledWith(node)
+  })
+
+  it('does not throw when onNodeDoubleClick is not provided', () => {
+    const node = makeNode('n1')
+    render(<CanvasContainer />)
+    expect(() => {
+      ;(rfProps.onNodeDoubleClick as (...args: unknown[]) => unknown)({} as MouseEvent, node)
+    }).not.toThrow()
+  })
+
+  // ── Connection validation ─────────────────────────────────────────────────
+
+  it('isValidConnection returns false for self-connections', () => {
+    render(<CanvasContainer />)
+    const isValid = rfProps.isValidConnection as (c: { source: string; target: string }) => boolean
+    expect(isValid({ source: 'n1', target: 'n1' })).toBe(false)
+  })
+
+  it('isValidConnection returns true for different nodes', () => {
+    render(<CanvasContainer />)
+    const isValid = rfProps.isValidConnection as (c: { source: string; target: string }) => boolean
+    expect(isValid({ source: 'n1', target: 'n2' })).toBe(true)
+  })
+
+  // ── onConnect prop passthrough ────────────────────────────────────────────
+
+  it('passes onConnect prop to ReactFlow', () => {
+    const onConnect = vi.fn()
+    render(<CanvasContainer onConnect={onConnect} />)
+    ;(rfProps.onConnect as (...args: unknown[]) => unknown)({ source: 'a', target: 'b', sourceHandle: null, targetHandle: null })
+    expect(onConnect).toHaveBeenCalledOnce()
+  })
+
+  // ── onNodeDragStart prop passthrough ──────────────────────────────────────
+
+  it('passes onNodeDragStart prop to ReactFlow', () => {
+    const onNodeDragStart = vi.fn()
+    render(<CanvasContainer onNodeDragStart={onNodeDragStart} />)
+    expect(rfProps.onNodeDragStart).toBe(onNodeDragStart)
+  })
+
+  // ── Canvas settings ───────────────────────────────────────────────────────
+
+  it('enables snapToGrid', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.snapToGrid).toBe(true)
+  })
+
+  it('sets snapGrid to [8, 8]', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.snapGrid).toEqual([8, 8])
+  })
+
+  // ── Delete key ────────────────────────────────────────────────────────────
+
+  it('sets deleteKeyCode to include both Backspace and Delete', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.deleteKeyCode).toEqual(['Backspace', 'Delete'])
+  })
+
+  // ── Lasso / multi-select ──────────────────────────────────────────────────
+
+  it('enables selectionOnDrag for lasso selection', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.selectionOnDrag).toBe(true)
+  })
+
+  it('sets panActivationKeyCode to Space', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.panActivationKeyCode).toBe('Space')
+  })
+
+  it('sets panOnDrag to [1, 2]', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.panOnDrag).toEqual([1, 2])
+  })
+
+  it('sets selectionMode to Partial', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.selectionMode).toBe('partial')
+  })
+
+  it('sets multiSelectionKeyCode to Meta and Control', () => {
+    render(<CanvasContainer />)
+    expect(rfProps.multiSelectionKeyCode).toEqual(['Meta', 'Control'])
+  })
+
+  it('clears selectedNode (sets null) on Ctrl+click instead of selecting', () => {
+    const node = makeNode('n1')
+    useCanvasStore.setState({ nodes: [node], selectedNodeId: 'n1' })
+    render(<CanvasContainer />)
+    ;(rfProps.onNodeClick as (...args: unknown[]) => unknown)(
+      { ctrlKey: true, metaKey: false } as unknown as MouseEvent,
+      node,
+    )
+    expect(useCanvasStore.getState().selectedNodeId).toBeNull()
+  })
+
+  it('clears selectedNode (sets null) on Cmd+click', () => {
+    const node = makeNode('n1')
+    useCanvasStore.setState({ nodes: [node], selectedNodeId: 'n1' })
+    render(<CanvasContainer />)
+    ;(rfProps.onNodeClick as (...args: unknown[]) => unknown)(
+      { ctrlKey: false, metaKey: true } as unknown as MouseEvent,
+      node,
+    )
+    expect(useCanvasStore.getState().selectedNodeId).toBeNull()
+  })
+
+  // ── onBeforeDelete snapshot ───────────────────────────────────────────────
+
+  it('onBeforeDelete calls snapshotHistory and returns true', async () => {
+    const snapshotHistory = vi.fn()
+    useCanvasStore.setState({ snapshotHistory } as unknown as Parameters<typeof useCanvasStore.setState>[0])
+    render(<CanvasContainer />)
+    const result = await (rfProps.onBeforeDelete as () => Promise<boolean>)()
+    expect(snapshotHistory).toHaveBeenCalledOnce()
+    expect(result).toBe(true)
+  })
+})

frontend/src/components/canvas/__tests__/GroupNode.test.tsx

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { GroupNode } from '../nodes/GroupNode'
+import * as canvasStore from '@/stores/canvasStore'
+import type { Node } from '@xyflow/react'
+import type { NodeData } from '@/types'
+
+vi.mock('@/stores/canvasStore')
+
+vi.mock('@xyflow/react', () => ({
+  NodeResizer: ({ isVisible }: { isVisible: boolean }) => (
+    <div data-testid="node-resizer" data-visible={isVisible} />
+  ),
+  useReactFlow: () => ({}),
+}))
+
+vi.mock('@xyflow/react/dist/style.css', () => ({}))
+
+function makeGroupNode(overrides: Partial<NodeData> = {}): Node<NodeData> {
+  return {
+    id: 'g1',
+    type: 'group',
+    position: { x: 0, y: 0 },
+    width: 400,
+    height: 250,
+    data: {
+      label: 'My Group',
+      type: 'group',
+      status: 'unknown',
+      services: [],
+      custom_colors: { show_border: true },
+      ...overrides,
+    },
+  }
+}
+
+function renderGroupNode(props: Partial<Parameters<typeof GroupNode>[0]> = {}, storeNodes: unknown[] = []) {
+  const node = makeGroupNode(props.data)
+  vi.mocked(canvasStore.useCanvasStore).mockReturnValue({
+    nodes: storeNodes,
+    updateNode: vi.fn(),
+    snapshotHistory: vi.fn(),
+  } as unknown as ReturnType<typeof canvasStore.useCanvasStore>)
+
+  return render(
+    <GroupNode
+      id="g1"
+      data={node.data}
+      selected={false}
+      dragging={false}
+      zIndex={1}
+      isConnectable={true}
+      positionAbsoluteX={0}
+      positionAbsoluteY={0}
+      {...props}
+    />,
+  )
+}
+
+describe('GroupNode', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('renders the group label when show_border is true', () => {
+    renderGroupNode()
+    expect(screen.getByText('My Group')).toBeDefined()
+  })
+
+  it('hides the header when show_border is false and not selected', () => {
+    renderGroupNode({ data: makeGroupNode({ custom_colors: { show_border: false } }).data, selected: false })
+    expect(screen.queryByText('My Group')).toBeNull()
+  })
+
+  it('shows header when show_border is false but node is selected', () => {
+    renderGroupNode({ data: makeGroupNode({ custom_colors: { show_border: false } }).data, selected: true })
+    expect(screen.getByText('My Group')).toBeDefined()
+  })
+
+  it('shows NodeResizer only when selected', () => {
+    const { rerender } = renderGroupNode({ selected: false })
+    expect(screen.getByTestId('node-resizer').getAttribute('data-visible')).toBe('false')
+
+    vi.mocked(canvasStore.useCanvasStore).mockReturnValue({
+      nodes: [],
+      updateNode: vi.fn(),
+      snapshotHistory: vi.fn(),
+    } as unknown as ReturnType<typeof canvasStore.useCanvasStore>)
+
+    rerender(
+      <GroupNode
+        id="g1"
+        data={makeGroupNode().data}
+        selected={true}
+        dragging={false}
+        zIndex={1}
+        isConnectable={true}
+        positionAbsoluteX={0}
+        positionAbsoluteY={0}
+      />,
+    )
+    expect(screen.getByTestId('node-resizer').getAttribute('data-visible')).toBe('true')
+  })
+
+  it('allows dragging from the header while keeping rename controls nodrag', () => {
+    renderGroupNode({ selected: true })
+
+    expect(screen.getByText('My Group').closest('div')).not.toHaveClass('nodrag')
+
+    const renameButton = screen.getByTitle('Rename group')
+    expect(renameButton).toHaveClass('nodrag')
+
+    fireEvent.click(renameButton)
+
+    expect(screen.getByDisplayValue('My Group')).toHaveClass('nodrag')
+  })
+
+  it('shows online/offline status summary from children', () => {
+    const storeNodes = [
+      { id: 'c1', parentId: 'g1', data: { status: 'online' } },
+      { id: 'c2', parentId: 'g1', data: { status: 'offline' } },
+      { id: 'c3', parentId: 'other', data: { status: 'online' } }, // different group — excluded
+    ]
+
+    renderGroupNode({}, storeNodes)
+    // Two status indicators: one online, one offline (c3 excluded — wrong parent)
+    const statusSpans = screen.getAllByText(/● \d+/)
+    expect(statusSpans).toHaveLength(2)
+  })
+
+  it('does not show status summary when group has no children', () => {
+    renderGroupNode()
+    expect(screen.queryByText(/●/)).toBeNull()
+  })
+})

frontend/src/components/canvas/__tests__/GroupRectNode.test.tsx

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { GroupRectNode } from '../nodes/GroupRectNode'
+import type { NodeData } from '@/types'
+import type { Node } from '@xyflow/react'
+
+vi.mock('@xyflow/react', () => ({
+  Handle: ({ id, type }: { id: string; type: string }) => <div data-testid={`handle-${id}`} data-type={type} />,
+  Position: { Top: 'top', Right: 'right', Bottom: 'bottom', Left: 'left' },
+  NodeResizer: () => null,
+}))
+
+vi.mock('@/stores/canvasStore', () => ({
+  useCanvasStore: (sel: (s: { setEditingGroupRectId: () => void }) => unknown) =>
+    sel({ setEditingGroupRectId: vi.fn() }),
+}))
+
+function makeNode(overrides: Partial<NodeData> = {}): Node<NodeData> {
+  return {
+    id: 'zone1',
+    type: 'groupRect',
+    position: { x: 0, y: 0 },
+    data: { label: 'My Zone', type: 'groupRect', status: 'unknown', services: [], ...overrides },
+  }
+}
+
+function renderZone(overrides: Partial<NodeData> = {}) {
+  const node = makeNode(overrides)
+  return render(
+    <GroupRectNode
+      id={node.id}
+      data={node.data}
+      selected={false}
+      type="groupRect"
+      dragging={false}
+      zIndex={0}
+      isConnectable={true}
+      positionAbsoluteX={0}
+      positionAbsoluteY={0}
+    />
+  )
+}
+
+describe('GroupRectNode — handles', () => {
+  it('renders source handles on all four sides', () => {
+    renderZone()
+    expect(screen.getByTestId('handle-zone-top')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-right')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-bottom')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-left')).toBeDefined()
+  })
+
+  it('renders target handles on all four sides', () => {
+    renderZone()
+    expect(screen.getByTestId('handle-zone-top-t')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-right-t')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-bottom-t')).toBeDefined()
+    expect(screen.getByTestId('handle-zone-left-t')).toBeDefined()
+  })
+
+  it('renders 8 handles total (4 source + 4 target)', () => {
+    renderZone()
+    expect(screen.getAllByTestId(/^handle-zone-/).length).toBe(8)
+  })
+})
+
+describe('GroupRectNode — label', () => {
+  it('renders inside label by default', () => {
+    renderZone({ label: 'DMZ' })
+    expect(screen.getByText('DMZ')).toBeDefined()
+  })
+
+  it('renders no label when label is empty', () => {
+    renderZone({ label: '' })
+    expect(screen.queryByText('DMZ')).toBeNull()
+  })
+})

frontend/src/components/canvas/__tests__/SearchBar.test.tsx

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { SearchBar } from '../SearchBar'
+import * as canvasStore from '@/stores/canvasStore'
+
+vi.mock('@/stores/canvasStore')
+
+vi.mock('@xyflow/react', () => ({
+  useReactFlow: () => ({ setCenter: vi.fn() }),
+}))
+
+function makeNode(id: string, overrides = {}) {
+  return {
+    id,
+    type: 'server',
+    position: { x: 0, y: 0 },
+    data: { label: id, type: 'server', status: 'online', services: [], ip: null, hostname: null },
+    ...overrides,
+  }
+}
+
+function setupStore(nodes: unknown[] = []) {
+  vi.mocked(canvasStore.useCanvasStore).mockReturnValue({
+    nodes,
+    setSelectedNode: vi.fn(),
+  } as unknown as ReturnType<typeof canvasStore.useCanvasStore>)
+}
+
+function openSearch() {
+  fireEvent.keyDown(window, { key: 'f', ctrlKey: true })
+}
+
+describe('SearchBar', () => {
+  beforeEach(() => {
+    setupStore([])
+    vi.clearAllMocks()
+  })
+
+  it('is hidden by default', () => {
+    render(<SearchBar />)
+    expect(screen.queryByPlaceholderText(/search/i)).toBeNull()
+  })
+
+  it('opens on Ctrl+F', () => {
+    render(<SearchBar />)
+    openSearch()
+    expect(screen.getByPlaceholderText(/search/i)).toBeDefined()
+  })
+
+  it('opens on Cmd+F', () => {
+    render(<SearchBar />)
+    fireEvent.keyDown(window, { key: 'f', metaKey: true })
+    expect(screen.getByPlaceholderText(/search/i)).toBeDefined()
+  })
+
+  it('closes on Escape', () => {
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.keyDown(window, { key: 'Escape' })
+    expect(screen.queryByPlaceholderText(/search/i)).toBeNull()
+  })
+
+  it('closes when X button is clicked', () => {
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.click(screen.getByLabelText('Close search'))
+    expect(screen.queryByPlaceholderText(/search/i)).toBeNull()
+  })
+
+  it('filters by label', () => {
+    setupStore([
+      makeNode('n1', { data: { label: 'My Router', type: 'router', status: 'online', services: [], ip: null, hostname: null } }),
+      makeNode('n2', { data: { label: 'My NAS', type: 'nas', status: 'online', services: [], ip: null, hostname: null } }),
+    ])
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'router' } })
+    expect(screen.getByText('My Router')).toBeDefined()
+    expect(screen.queryByText('My NAS')).toBeNull()
+  })
+
+  it('filters by IP', () => {
+    setupStore([
+      makeNode('n1', { data: { label: 'Server A', type: 'server', status: 'online', services: [], ip: '192.168.1.10', hostname: null } }),
+      makeNode('n2', { data: { label: 'Server B', type: 'server', status: 'online', services: [], ip: '10.0.0.1', hostname: null } }),
+    ])
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: '192.168' } })
+    expect(screen.getByText('Server A')).toBeDefined()
+    expect(screen.queryByText('Server B')).toBeNull()
+  })
+
+  it('filters by service name', () => {
+    setupStore([
+      makeNode('n1', { data: { label: 'Web Server', type: 'server', status: 'online', services: [{ service_name: 'nginx', port: 80, protocol: 'tcp' }], ip: null, hostname: null } }),
+      makeNode('n2', { data: { label: 'DB Server', type: 'server', status: 'online', services: [{ service_name: 'mysql', port: 3306, protocol: 'tcp' }], ip: null, hostname: null } }),
+    ])
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'nginx' } })
+    expect(screen.getByText('Web Server')).toBeDefined()
+    expect(screen.queryByText('DB Server')).toBeNull()
+  })
+
+  it('excludes groupRect nodes from results', () => {
+    setupStore([
+      makeNode('gr1', { data: { label: 'DMZ Zone', type: 'groupRect', status: 'unknown', services: [], ip: null, hostname: null } }),
+    ])
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'dmz' } })
+    expect(screen.queryByText('DMZ Zone')).toBeNull()
+  })
+
+  it('shows no-results message when query has no matches', () => {
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'zzznomatch' } })
+    expect(screen.getByText(/no results/i)).toBeDefined()
+  })
+
+  it('calls setSelectedNode when a result is clicked', () => {
+    const setSelectedNode = vi.fn()
+    vi.mocked(canvasStore.useCanvasStore).mockReturnValue({
+      nodes: [makeNode('n1', { data: { label: 'My Server', type: 'server', status: 'online', services: [], ip: null, hostname: null } })],
+      setSelectedNode,
+    } as unknown as ReturnType<typeof canvasStore.useCanvasStore>)
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'my server' } })
+    fireEvent.click(screen.getByText('My Server'))
+    expect(setSelectedNode).toHaveBeenCalledWith('n1')
+  })
+
+  it('shows result count', () => {
+    setupStore([
+      makeNode('n1', { data: { label: 'Alpha', type: 'server', status: 'online', services: [], ip: null, hostname: null } }),
+      makeNode('n2', { data: { label: 'Beta', type: 'server', status: 'online', services: [], ip: null, hostname: null } }),
+    ])
+    render(<SearchBar />)
+    openSearch()
+    fireEvent.change(screen.getByPlaceholderText(/search/i), { target: { value: 'a' } })
+    expect(screen.getByText(/2 results/i)).toBeDefined()
+  })
+})

frontend/src/components/canvas/edges/__tests__/waypointUtils.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest'
+import { buildWaypointPath, distToSegment, findInsertIndex, getAddWaypointHandlePosition, getWaypointLabelPosition, snap45, snap45both } from '../waypointUtils'
+
+describe('buildWaypointPath — bezier (default)', () => {
+  it('builds a catmull-rom curve with no waypoints (start = end clamp)', () => {
+    // With only 2 pts (src + target), catmull-rom = cubic bezier
+    const path = buildWaypointPath(0, 0, [], 100, 100)
+    expect(path).toMatch(/^M 0 0 C/)
+  })
+
+  it('routes through a single waypoint with smooth curve', () => {
+    const path = buildWaypointPath(0, 0, [{ x: 50, y: 0 }], 100, 100)
+    expect(path).toMatch(/^M 0 0 C/)
+    // Should not be a straight polyline
+    expect(path).not.toContain(' L ')
+  })
+
+  it('routes through multiple waypoints', () => {
+    const path = buildWaypointPath(0, 0, [{ x: 50, y: 0 }, { x: 50, y: 100 }], 100, 100)
+    expect(path).toMatch(/^M 0 0 C/)
+  })
+})
+
+describe('buildWaypointPath — smooth style', () => {
+  it('builds a direct straight line with no waypoints (no bend)', () => {
+    // Only 2 points → no intermediate vertex → no rounding needed
+    expect(buildWaypointPath(0, 0, [], 100, 100, 'smooth')).toBe('M 0 0 L 100 100')
+  })
+
+  it('routes through a single waypoint with straight lines (no intermediate bend)', () => {
+    // 3 pts: src → wp → target — only 1 intermediate → rounded corners at wp
+    const path = buildWaypointPath(0, 0, [{ x: 50, y: 0 }], 100, 100, 'smooth')
+    // Should start at source and end at target
+    expect(path).toMatch(/^M 0 0/)
+    expect(path).toMatch(/100 100$/)
+    // Should contain a quadratic bezier at the waypoint corner
+    expect(path).toContain('Q')
+  })
+
+  it('routes through multiple waypoints with rounded corners', () => {
+    const path = buildWaypointPath(0, 0, [{ x: 50, y: 0 }, { x: 50, y: 100 }], 100, 100, 'smooth')
+    expect(path).toMatch(/^M 0 0/)
+    expect(path).toMatch(/100 100$/)
+    expect(path).toContain('Q')
+  })
+
+  it('does not round corners when segment is too short (r clamped to 0)', () => {
+    // Adjacent waypoints very close together — r → 0, falls back to L
+    const path = buildWaypointPath(0, 0, [{ x: 1, y: 0 }, { x: 2, y: 0 }], 100, 0, 'smooth')
+    expect(path).toMatch(/^M 0 0/)
+  })
+})
+
+describe('snap45', () => {
+  // Use positions very close to a 45° angle so deviation < SNAP_THRESHOLD (15px)
+  it('snaps horizontal direction when close (deviation < threshold)', () => {
+    // (100, 3) — nearly horizontal, deviation from 0° ≈ 3px → snaps
+    const r = snap45({ x: 0, y: 0 }, { x: 100, y: 3 })
+    expect(r.y).toBe(0)
+    expect(r.x).toBeGreaterThan(0)
+  })
+
+  it('snaps vertical direction when close', () => {
+    const r = snap45({ x: 0, y: 0 }, { x: 3, y: 100 })
+    expect(r.x).toBe(0)
+    expect(r.y).toBeGreaterThan(0)
+  })
+
+  it('snaps 45° diagonal when close', () => {
+    // (80, 83) — nearly 45°, deviation ≈ 2px → snaps
+    const r = snap45({ x: 0, y: 0 }, { x: 80, y: 83 })
+    expect(r.x).toBe(r.y)
+  })
+
+  it('does NOT snap when deviation exceeds threshold', () => {
+    // (100, 40) — deviation from 0° is ~40px > 15 → no snap
+    const pos = { x: 100, y: 40 }
+    const r = snap45({ x: 0, y: 0 }, pos)
+    expect(r).toEqual(pos)
+  })
+
+  it('returns pos unchanged when distance < 1', () => {
+    const pos = { x: 5, y: 5 }
+    expect(snap45({ x: 5, y: 5 }, pos)).toBe(pos)
+  })
+
+  it('preserves distance from origin when snapping', () => {
+    const from = { x: 0, y: 0 }
+    const pos = { x: 100, y: 3 }  // close to horizontal
+    const r = snap45(from, pos)
+    const origDist = Math.hypot(pos.x - from.x, pos.y - from.y)
+    const snapDist = Math.hypot(r.x - from.x, r.y - from.y)
+    expect(snapDist).toBeCloseTo(origDist, 0)
+  })
+})
+
+describe('snap45both', () => {
+  it('finds intersection satisfying 45° from both adjacent points (axis-aligned)', () => {
+    // prev=(0,0), next=(100,100): diagonal — midpoint (50,50) should satisfy both
+    const r = snap45both({ x: 0, y: 0 }, { x: 100, y: 100 }, { x: 50, y: 50 })
+    // Result must be on a 45°-ray from (0,0)
+    const a1 = Math.atan2(r.y - 0, r.x - 0) / (Math.PI / 4)
+    expect(Math.abs(a1 - Math.round(a1))).toBeLessThan(0.05)
+    // Result must be on a 45°-ray from (100,100)
+    const a2 = Math.atan2(r.y - 100, r.x - 100) / (Math.PI / 4)
+    expect(Math.abs(a2 - Math.round(a2))).toBeLessThan(0.05)
+  })
+
+  it('snaps so both incoming and outgoing segments are at 45° when within threshold', () => {
+    // prev=(0,0), next=(200,0) — valid intersection at (100,100) (45° from each)
+    // pos=(100,93) is 7px away → within 15px threshold → should snap to (100,100)
+    const r = snap45both({ x: 0, y: 0 }, { x: 200, y: 0 }, { x: 100, y: 93 })
+    const a1 = Math.atan2(r.y - 0, r.x - 0) / (Math.PI / 4)
+    expect(Math.abs(a1 - Math.round(a1))).toBeLessThan(0.05)
+    const a2 = Math.atan2(r.y - 0, r.x - 200) / (Math.PI / 4)
+    expect(Math.abs(a2 - Math.round(a2))).toBeLessThan(0.05)
+  })
+
+  it('returns raw pos when beyond threshold', () => {
+    // pos=(100,80) is 20px from nearest intersection (100,100) → no snap
+    const pos = { x: 100, y: 80 }
+    const r = snap45both({ x: 0, y: 0 }, { x: 200, y: 0 }, pos)
+    expect(r).toEqual(pos)
+  })
+
+  it('falls back gracefully when prev === next', () => {
+    // No valid intersection → fallback to snap45
+    const r = snap45both({ x: 50, y: 50 }, { x: 50, y: 50 }, { x: 100, y: 90 })
+    expect(r).toBeDefined()
+  })
+})
+
+describe('distToSegment', () => {
+  it('returns 0 when point is on the segment', () => {
+    expect(distToSegment({ x: 50, y: 0 }, { x: 0, y: 0 }, { x: 100, y: 0 })).toBeCloseTo(0)
+  })
+
+  it('returns perpendicular distance when point is beside segment', () => {
+    expect(distToSegment({ x: 50, y: 10 }, { x: 0, y: 0 }, { x: 100, y: 0 })).toBeCloseTo(10)
+  })
+
+  it('returns distance to nearest endpoint when point is past the segment', () => {
+    expect(distToSegment({ x: 200, y: 0 }, { x: 0, y: 0 }, { x: 100, y: 0 })).toBeCloseTo(100)
+  })
+
+  it('handles zero-length segment (a === b)', () => {
+    expect(distToSegment({ x: 3, y: 4 }, { x: 0, y: 0 }, { x: 0, y: 0 })).toBeCloseTo(5)
+  })
+})
+
+describe('findInsertIndex', () => {
+  it('returns 0 when there are no waypoints (only one segment)', () => {
+    expect(findInsertIndex(0, 0, [], 100, 0, { x: 50, y: 5 })).toBe(0)
+  })
+
+  it('inserts before first waypoint when click is on first segment', () => {
+    const idx = findInsertIndex(0, 0, [{ x: 100, y: 0 }], 200, 0, { x: 30, y: 5 })
+    expect(idx).toBe(0)
+  })
+
+  it('inserts after first waypoint when click is on second segment', () => {
+    const idx = findInsertIndex(0, 0, [{ x: 100, y: 0 }], 200, 0, { x: 160, y: 5 })
+    expect(idx).toBe(1)
+  })
+
+  it('picks the closest segment among multiple', () => {
+    const idx = findInsertIndex(
+      0, 0,
+      [{ x: 100, y: 0 }, { x: 100, y: 100 }],
+      200, 100,
+      { x: 150, y: 105 },
+    )
+    expect(idx).toBe(2)
+  })
+})
+
+describe('getWaypointLabelPosition', () => {
+  it('uses the routed midpoint for a symmetric bezier waypoint path', () => {
+    const point = getWaypointLabelPosition(0, 0, [{ x: 50, y: 100 }], 100, 0)
+    expect(point.x).toBeCloseTo(50, 0)
+    expect(point.y).toBeCloseTo(100, 0)
+  })
+
+  it('uses the routed midpoint for a smooth waypoint path', () => {
+    const point = getWaypointLabelPosition(0, 0, [{ x: 50, y: 0 }, { x: 50, y: 100 }], 100, 100, 'smooth')
+    expect(point.x).toBeCloseTo(50, 0)
+    expect(point.y).toBeCloseTo(50, 0)
+  })
+
+  it('falls back to the source point when the path is degenerate', () => {
+    const point = getWaypointLabelPosition(10, 20, [], 10, 20, 'smooth')
+    expect(point).toEqual({ x: 10, y: 20 })
+  })
+})
+
+describe('getAddWaypointHandlePosition', () => {
+  it('places bezier add handle on the rendered curved segment', () => {
+    const point = getAddWaypointHandlePosition(0, 0, [{ x: 50, y: 100 }], 100, 0, 0, 'bezier')
+    expect(point.x).toBeCloseTo(21.875, 3)
+    expect(point.y).toBeCloseTo(56.25, 3)
+  })
+
+  it('keeps smooth add handle at straight segment midpoint', () => {
+    const point = getAddWaypointHandlePosition(0, 0, [{ x: 50, y: 0 }, { x: 50, y: 100 }], 100, 100, 1, 'smooth')
+    expect(point).toEqual({ x: 50, y: 50 })
+  })
+})

frontend/src/components/canvas/edges/index.tsx

@@ -1,12 +1,19 @@
+import { useCallback } from 'react'
 import {
   BaseEdge,
   EdgeLabelRenderer,
   getBezierPath,
   getSmoothStepPath,
+  useReactFlow,
+  useStore,
   type EdgeProps,
   type Edge,
 } from '@xyflow/react'
-import type { EdgeData, EdgeType } from '@/types'
+import type { EdgeData, EdgeType, Waypoint } from '@/types'
+import { useThemeStore } from '@/stores/themeStore'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { THEMES } from '@/utils/themes'
+import { buildWaypointPath, getAddWaypointHandlePosition, getWaypointLabelPosition, snap45, snap45both } from './waypointUtils'
 
 const VLAN_COLORS = ['#00d4ff', '#a855f7', '#39d353', '#ff6e00', '#e3b341', '#f85149']
 
@@ -15,48 +22,334 @@ function getVlanColor(vlanId?: number): string {
   return VLAN_COLORS[vlanId % VLAN_COLORS.length]
 }
 
-const EDGE_STYLES: Record<EdgeType, React.CSSProperties> = {
-  ethernet: { stroke: '#30363d', strokeWidth: 2 },
-  wifi: { stroke: '#00d4ff', strokeWidth: 1.5, strokeDasharray: '6 3' },
-  iot: { stroke: '#e3b341', strokeWidth: 1.5, strokeDasharray: '2 4' },
-  vlan: { strokeWidth: 2.5 },
-  virtual: { stroke: '#8b949e', strokeWidth: 1, strokeDasharray: '4 4' },
-  cluster: { stroke: '#ff6e00', strokeWidth: 2.5, strokeDasharray: '8 3' },
+// ── Waypoint drag handle ─────────────────────────────────────────────────────
+
+interface WaypointHandleProps {
+  edgeId: string
+  index: number
+  waypoint: Waypoint
+  waypoints: Waypoint[]
+  color: string
+  pathStyle?: string
+  prevPoint: Waypoint
+  nextPoint: Waypoint
 }
 
-export function HomelableEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, data, selected }: EdgeProps<Edge<EdgeData>>) {
+function WaypointHandle({ edgeId, index, waypoint, waypoints, color, pathStyle, prevPoint, nextPoint }: WaypointHandleProps) {
+  const { screenToFlowPosition } = useReactFlow()
+  const updateEdge = useCanvasStore((s) => s.updateEdge)
+
+  const handlePointerDown = useCallback((e: React.PointerEvent) => {
+    e.stopPropagation()
+    e.currentTarget.setPointerCapture(e.pointerId)
+  }, [])
+
+  const handlePointerMove = useCallback((e: React.PointerEvent) => {
+    if (e.buttons !== 1) return
+    let pos = screenToFlowPosition({ x: e.clientX, y: e.clientY })
+    if (pathStyle === 'smooth') {
+      // Find the intersection of 45°-rays from both adjacent points so that
+      // ALL segments (prev→this and this→next) snap to 45° simultaneously.
+      pos = snap45both(prevPoint, nextPoint, pos)
+    }
+    const next = [...waypoints]
+    next[index] = pos
+    updateEdge(edgeId, { waypoints: next })
+  }, [screenToFlowPosition, waypoints, index, edgeId, updateEdge, pathStyle, prevPoint, nextPoint])
+
+  const handlePointerUp = useCallback((e: React.PointerEvent) => {
+    e.currentTarget.releasePointerCapture(e.pointerId)
+  }, [])
+
+  const handleDoubleClick = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation()
+    updateEdge(edgeId, { waypoints: waypoints.filter((_, i) => i !== index) })
+  }, [edgeId, waypoints, index, updateEdge])
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        transform: `translate(-50%, -50%) translate(${waypoint.x}px, ${waypoint.y}px)`,
+        width: 10,
+        height: 10,
+        borderRadius: '50%',
+        background: color,
+        border: '2px solid #0d1117',
+        cursor: 'grab',
+        pointerEvents: 'all',
+        zIndex: 10,
+      }}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onDoubleClick={handleDoubleClick}
+      title="Drag to move · Double-click to remove"
+    />
+  )
+}
+
+// ── Add waypoint handle (+ button at segment midpoints) ──────────────────────
+
+interface AddWaypointHandleProps {
+  edgeId: string
+  insertIndex: number
+  x: number
+  y: number
+  waypoints: Waypoint[]
+  color: string
+  pathStyle?: string
+  prevPoint: Waypoint
+}
+
+function AddWaypointHandle({ edgeId, insertIndex, x, y, waypoints, color, pathStyle, prevPoint }: AddWaypointHandleProps) {
+  const updateEdge = useCanvasStore((s) => s.updateEdge)
+
+  const handleClick = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation()
+    let pos = { x, y }
+    if (pathStyle === 'smooth') pos = snap45(prevPoint, pos)
+    const next = [...waypoints.slice(0, insertIndex), pos, ...waypoints.slice(insertIndex)]
+    updateEdge(edgeId, { waypoints: next })
+  }, [edgeId, insertIndex, x, y, waypoints, updateEdge, pathStyle, prevPoint])
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{
+        position: 'absolute',
+        transform: `translate(-50%, -50%) translate(${x}px, ${y}px)`,
+        width: 14,
+        height: 14,
+        borderRadius: '50%',
+        background: '#0d1117',
+        border: `1.5px solid ${color}`,
+        color,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        fontSize: 12,
+        lineHeight: 1,
+        cursor: 'crosshair',
+        pointerEvents: 'all',
+        zIndex: 9,
+        opacity: 0.7,
+      }}
+      title="Click to add waypoint"
+    >
+      +
+    </div>
+  )
+}
+
+// ── Segment midpoints ────────────────────────────────────────────────────────
+
+/**
+ * Compute + handle positions for each path segment.
+ * For smooth style: bias the first + handle to the source handle axis and the
+ * last + handle to the target handle axis, so clicking always gives a clean
+ * perpendicular exit/entry (no diagonal guesswork near the nodes).
+ */
+function segmentMidpoints(
+  sourceX: number, sourceY: number,
+  waypoints: Waypoint[],
+  targetX: number, targetY: number,
+  pathStyle?: string,
+  sourcePosition?: string,
+): { x: number; y: number; insertIndex: number }[] {
+  const pts = [{ x: sourceX, y: sourceY }, ...waypoints, { x: targetX, y: targetY }]
+  const isSmooth = pathStyle === 'smooth'
+
+  return pts.slice(0, -1).map((a, i) => {
+    const base = getAddWaypointHandlePosition(sourceX, sourceY, waypoints, targetX, targetY, i, pathStyle)
+    let mx = base.x
+    const my = base.y
+
+    // For smooth style with no existing waypoints, bias the single + handle onto
+    // the source handle axis so clicking it creates a perpendicular exit.
+    // Only applies to bottom/top handles (vertical exits) and only when the edge
+    // has no waypoints yet — once waypoints exist, all + handles stay at the
+    // real segment midpoint so they remain visually on the edge.
+    if (isSmooth && i === 0 && pts.length === 2) {
+      const vertSrc = sourcePosition === 'bottom' || sourcePosition === 'top'
+      if (vertSrc) mx = a.x  // same X as source → + sits directly below/above node
+    }
+
+    return { x: mx, y: my, insertIndex: i }
+  })
+}
+
+// ── Main edge component ──────────────────────────────────────────────────────
+
+export function HomelableEdge({ id, source, target, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, data, selected }: EdgeProps<Edge<EdgeData>>) {
+  const activeTheme = useThemeStore((s) => s.activeTheme)
+  const theme = THEMES[activeTheme]
+  const sourceType = useStore((s) => s.nodeLookup.get(source)?.type)
+  const targetType = useStore((s) => s.nodeLookup.get(target)?.type)
+  const isBidirectional = sourceType === 'proxmox' && targetType === 'proxmox'
+
+  const waypoints: Waypoint[] = Array.isArray(data?.waypoints) && data.waypoints.length > 0
+    ? data.waypoints as Waypoint[]
+    : []
+
+  const hasWaypoints = waypoints.length > 0
+
+  const pathStyle = data?.path_style as string | undefined
+
   const pathArgs = { sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition }
-  const [edgePath, labelX, labelY] = data?.path_style === 'smooth'
+  const [autoPath, labelX] = pathStyle === 'smooth'
     ? getSmoothStepPath({ ...pathArgs, borderRadius: 8 })
     : getBezierPath(pathArgs)
 
+  const edgePath = hasWaypoints
+    ? buildWaypointPath(sourceX, sourceY, waypoints, targetX, targetY, pathStyle)
+    : autoPath
+
+  const labelPosition = hasWaypoints
+    ? getWaypointLabelPosition(sourceX, sourceY, waypoints, targetX, targetY, pathStyle)
+    : { x: labelX, y: (sourceY + targetY) / 2 }
+
   const edgeType: EdgeType = data?.type ?? 'ethernet'
+  const edgeColors = theme.colors.edgeColors
+
+  const BASE_STYLES: Record<EdgeType, React.CSSProperties> = {
+    ethernet: { stroke: edgeColors.ethernet, strokeWidth: 2 },
+    wifi:     { stroke: edgeColors.wifi,     strokeWidth: 1.5, strokeDasharray: '6 3' },
+    iot:      { stroke: edgeColors.iot,      strokeWidth: 1.5, strokeDasharray: '2 4' },
+    vlan:     { strokeWidth: 2.5 },
+    virtual:  { stroke: edgeColors.virtual,  strokeWidth: 1,   strokeDasharray: '4 4' },
+    cluster:  { stroke: edgeColors.cluster,  strokeWidth: 2.5, strokeDasharray: '8 3' },
+  }
+
   const customColor = data?.custom_color as string | undefined
+  const strokeColor: string = selected
+    ? theme.colors.edgeSelectedColor
+    : customColor
+    ?? (edgeType === 'vlan' ? getVlanColor(data?.vlan_id as number | undefined) : (BASE_STYLES[edgeType].stroke as string ?? edgeColors.ethernet))
+
   const style: React.CSSProperties = {
-    ...EDGE_STYLES[edgeType],
+    ...BASE_STYLES[edgeType],
     ...(edgeType === 'vlan' ? { stroke: getVlanColor(data?.vlan_id as number | undefined) } : {}),
     ...(customColor ? { stroke: customColor } : {}),
-    ...(selected ? { stroke: '#00d4ff', filter: 'drop-shadow(0 0 4px #00d4ff88)' } : {}),
+    ...(selected ? { stroke: theme.colors.edgeSelectedColor, filter: `drop-shadow(0 0 4px ${theme.colors.edgeSelectedColor}88)` } : {}),
   }
 
+  const animMode: 'none' | 'snake' | 'flow' | 'basic' =
+    data?.animated === true || data?.animated === 'snake' ? 'snake' :
+    data?.animated === 'flow' ? 'flow' :
+    data?.animated === 'basic' ? 'basic' : 'none'
+
+  const animColor = customColor ?? (edgeType === 'vlan' ? getVlanColor(data?.vlan_id as number | undefined) : edgeColors[edgeType as keyof typeof edgeColors] as string)
+
+  const midpoints = selected
+    ? segmentMidpoints(sourceX, sourceY, waypoints, targetX, targetY, pathStyle, sourcePosition)
+    : []
+
   return (
     <>
-      <BaseEdge id={id} path={edgePath} style={style} />
-      {data?.label && (
-        <EdgeLabelRenderer>
+      <BaseEdge id={id} path={edgePath} style={animMode === 'basic' ? { ...style, stroke: 'transparent' } : style} interactionWidth={16} />
+
+      {animMode === 'basic' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={strokeColor}
+          strokeWidth={style.strokeWidth as number ?? 2}
+          strokeDasharray="5"
+          style={{
+            pointerEvents: 'none',
+            animation: 'homelable-basic-dash 0.5s linear infinite',
+            animationDirection: sourceY <= targetY ? 'normal' : 'reverse',
+          }}
+        />
+      )}
+
+      {animMode === 'snake' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={animColor}
+          strokeWidth={((style.strokeWidth as number ?? 2) + 1.5) * 2}
+          strokeDasharray="20 10000"
+          strokeLinecap="round"
+          style={{ pointerEvents: 'none' }}
+        >
+          {isBidirectional ? (
+            <animate attributeName="stroke-dashoffset" values="-10000;0;-10000" keyTimes="0;0.5;1" dur="20s" repeatCount="indefinite" />
+          ) : (
+            <animate attributeName="stroke-dashoffset" from="-10000" to="0" dur="10s" repeatCount="indefinite" />
+          )}
+        </path>
+      )}
+      {animMode === 'flow' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={animColor}
+          strokeWidth={Math.max(3, (style.strokeWidth as number ?? 2) * 1.8)}
+          strokeDasharray="6 12"
+          strokeLinecap="round"
+          strokeOpacity={0.85}
+          style={{ pointerEvents: 'none' }}
+        >
+          <animate attributeName="stroke-dashoffset" from="0" to="18" dur="1.2s" repeatCount="indefinite" />
+        </path>
+      )}
+
+      <EdgeLabelRenderer>
+        {data?.label && (
           <div
-            className="absolute pointer-events-none font-mono text-[10px] px-1 rounded"
+            className="absolute pointer-events-none font-mono text-[10px] px-1.5 py-0.5 rounded"
             style={{
-              transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
-              background: '#161b22',
-              color: '#8b949e',
-              border: '1px solid #30363d',
+              transform: `translate(-50%, -50%) translate(${labelPosition.x}px, ${labelPosition.y}px)`,
+              background: theme.colors.edgeLabelBackground,
+              color:      theme.colors.edgeLabelColor,
+              border:     `1px solid ${theme.colors.edgeLabelBorder}`,
             }}
           >
             {data.label as string}
           </div>
-        </EdgeLabelRenderer>
-      )}
+        )}
+
+        {/* Existing waypoint drag handles */}
+        {selected && waypoints.map((wp, idx) => {
+          const prevPoint = idx === 0 ? { x: sourceX, y: sourceY } : waypoints[idx - 1]
+          const nextPoint = idx === waypoints.length - 1 ? { x: targetX, y: targetY } : waypoints[idx + 1]
+          return (
+            <WaypointHandle
+              key={`wp-${idx}`}
+              edgeId={id}
+              index={idx}
+              waypoint={wp}
+              waypoints={waypoints}
+              color={strokeColor}
+              pathStyle={pathStyle}
+              prevPoint={prevPoint}
+              nextPoint={nextPoint}
+            />
+          )
+        })}
+
+        {/* + handles at segment midpoints to add new waypoints */}
+        {selected && midpoints.map((mp) => {
+          const prevPoint = mp.insertIndex === 0
+            ? { x: sourceX, y: sourceY }
+            : waypoints[mp.insertIndex - 1]
+          return (
+            <AddWaypointHandle
+              key={`add-${mp.insertIndex}`}
+              edgeId={id}
+              insertIndex={mp.insertIndex}
+              x={mp.x}
+              y={mp.y}
+              waypoints={waypoints}
+              color={strokeColor}
+              pathStyle={pathStyle}
+              prevPoint={prevPoint}
+            />
+          )
+        })}
+      </EdgeLabelRenderer>
     </>
   )
 }

frontend/src/components/canvas/edges/waypointUtils.ts

@@ -0,0 +1,377 @@
+import type { Waypoint } from '@/types'
+
+// ── Path builders ─────────────────────────────────────────────────────────────
+
+/** Catmull-Rom → cubic bezier for smooth curves through waypoints */
+function buildCatmullRomPath(pts: Waypoint[]): string {
+  if (pts.length < 2) return `M ${pts[0].x} ${pts[0].y}`
+  let d = `M ${pts[0].x} ${pts[0].y}`
+  for (let i = 0; i < pts.length - 1; i++) {
+    const p0 = pts[Math.max(i - 1, 0)]
+    const p1 = pts[i]
+    const p2 = pts[i + 1]
+    const p3 = pts[Math.min(i + 2, pts.length - 1)]
+    const cp1x = p1.x + (p2.x - p0.x) / 6
+    const cp1y = p1.y + (p2.y - p0.y) / 6
+    const cp2x = p2.x - (p3.x - p1.x) / 6
+    const cp2y = p2.y - (p3.y - p1.y) / 6
+    d += ` C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${p2.x} ${p2.y}`
+  }
+  return d
+}
+
+/** Polyline with rounded corners at each waypoint vertex (quadratic bezier) */
+function buildRoundedPolylinePath(pts: Waypoint[], radius = 8): string {
+  if (pts.length < 2) return `M ${pts[0].x} ${pts[0].y}`
+  if (pts.length === 2) return `M ${pts[0].x} ${pts[0].y} L ${pts[1].x} ${pts[1].y}`
+
+  let d = `M ${pts[0].x} ${pts[0].y}`
+
+  for (let i = 1; i < pts.length - 1; i++) {
+    const prev = pts[i - 1]
+    const curr = pts[i]
+    const next = pts[i + 1]
+
+    const dx1 = curr.x - prev.x
+    const dy1 = curr.y - prev.y
+    const len1 = Math.hypot(dx1, dy1)
+
+    const dx2 = next.x - curr.x
+    const dy2 = next.y - curr.y
+    const len2 = Math.hypot(dx2, dy2)
+
+    if (len1 < 1 || len2 < 1) {
+      d += ` L ${curr.x} ${curr.y}`
+      continue
+    }
+
+    const r = Math.min(radius, len1 / 2, len2 / 2)
+
+    // Approach point (on segment prev→curr, r units before corner)
+    const bx = curr.x - (dx1 / len1) * r
+    const by = curr.y - (dy1 / len1) * r
+
+    // Departure point (on segment curr→next, r units after corner)
+    const ax = curr.x + (dx2 / len2) * r
+    const ay = curr.y + (dy2 / len2) * r
+
+    d += ` L ${bx} ${by} Q ${curr.x} ${curr.y} ${ax} ${ay}`
+  }
+
+  d += ` L ${pts[pts.length - 1].x} ${pts[pts.length - 1].y}`
+  return d
+}
+
+export function buildWaypointPath(
+  sourceX: number, sourceY: number,
+  waypoints: Waypoint[],
+  targetX: number, targetY: number,
+  pathStyle: string = 'bezier',
+): string {
+  const pts = [{ x: sourceX, y: sourceY }, ...waypoints, { x: targetX, y: targetY }]
+  return pathStyle === 'smooth' ? buildRoundedPolylinePath(pts) : buildCatmullRomPath(pts)
+}
+
+function interpolateLine(a: Waypoint, b: Waypoint, t: number): Waypoint {
+  return {
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+  }
+}
+
+function interpolateQuadratic(a: Waypoint, b: Waypoint, c: Waypoint, t: number): Waypoint {
+  const mt = 1 - t
+  return {
+    x: mt * mt * a.x + 2 * mt * t * b.x + t * t * c.x,
+    y: mt * mt * a.y + 2 * mt * t * b.y + t * t * c.y,
+  }
+}
+
+function interpolateCubic(a: Waypoint, b: Waypoint, c: Waypoint, d: Waypoint, t: number): Waypoint {
+  const mt = 1 - t
+  return {
+    x: mt * mt * mt * a.x + 3 * mt * mt * t * b.x + 3 * mt * t * t * c.x + t * t * t * d.x,
+    y: mt * mt * mt * a.y + 3 * mt * mt * t * b.y + 3 * mt * t * t * c.y + t * t * t * d.y,
+  }
+}
+
+function approximateLength(pointAt: (t: number) => Waypoint, steps = 24): number {
+  let length = 0
+  let prev = pointAt(0)
+
+  for (let step = 1; step <= steps; step++) {
+    const next = pointAt(step / steps)
+    length += Math.hypot(next.x - prev.x, next.y - prev.y)
+    prev = next
+  }
+
+  return length
+}
+
+type PathSegment = {
+  length: number
+  pointAt: (t: number) => Waypoint
+}
+
+function buildBezierSegments(pts: Waypoint[]): PathSegment[] {
+  if (pts.length < 2) return []
+
+  return pts.slice(0, -1).map((_, i) => {
+    const p0 = pts[Math.max(i - 1, 0)]
+    const p1 = pts[i]
+    const p2 = pts[i + 1]
+    const p3 = pts[Math.min(i + 2, pts.length - 1)]
+    const cp1 = {
+      x: p1.x + (p2.x - p0.x) / 6,
+      y: p1.y + (p2.y - p0.y) / 6,
+    }
+    const cp2 = {
+      x: p2.x - (p3.x - p1.x) / 6,
+      y: p2.y - (p3.y - p1.y) / 6,
+    }
+    const pointAt = (t: number) => interpolateCubic(p1, cp1, cp2, p2, t)
+
+    return {
+      length: approximateLength(pointAt),
+      pointAt,
+    }
+  })
+}
+
+function buildSmoothSegments(pts: Waypoint[], radius = 8): PathSegment[] {
+  if (pts.length < 2) return []
+  if (pts.length === 2) {
+    const pointAt = (t: number) => interpolateLine(pts[0], pts[1], t)
+    return [{ length: Math.hypot(pts[1].x - pts[0].x, pts[1].y - pts[0].y), pointAt }]
+  }
+
+  const segments: PathSegment[] = []
+  let cursor = pts[0]
+
+  for (let i = 1; i < pts.length - 1; i++) {
+    const prev = pts[i - 1]
+    const curr = pts[i]
+    const next = pts[i + 1]
+
+    const dx1 = curr.x - prev.x
+    const dy1 = curr.y - prev.y
+    const len1 = Math.hypot(dx1, dy1)
+
+    const dx2 = next.x - curr.x
+    const dy2 = next.y - curr.y
+    const len2 = Math.hypot(dx2, dy2)
+
+    if (len1 < 1 || len2 < 1) {
+      const start = { x: cursor.x, y: cursor.y }
+      const end = { x: curr.x, y: curr.y }
+      const lineToCurr = (t: number) => interpolateLine(start, end, t)
+      segments.push({
+        length: Math.hypot(curr.x - cursor.x, curr.y - cursor.y),
+        pointAt: lineToCurr,
+      })
+      cursor = curr
+      continue
+    }
+
+    const r = Math.min(radius, len1 / 2, len2 / 2)
+    const before = {
+      x: curr.x - (dx1 / len1) * r,
+      y: curr.y - (dy1 / len1) * r,
+    }
+    const after = {
+      x: curr.x + (dx2 / len2) * r,
+      y: curr.y + (dy2 / len2) * r,
+    }
+
+    const lineStart = { x: cursor.x, y: cursor.y }
+    const lineEnd = { x: before.x, y: before.y }
+    const lineToBefore = (t: number) => interpolateLine(lineStart, lineEnd, t)
+    segments.push({
+      length: Math.hypot(before.x - cursor.x, before.y - cursor.y),
+      pointAt: lineToBefore,
+    })
+
+    const curveAroundCorner = (t: number) => interpolateQuadratic(before, curr, after, t)
+    segments.push({
+      length: approximateLength(curveAroundCorner),
+      pointAt: curveAroundCorner,
+    })
+
+    cursor = after
+  }
+
+  const targetStart = { x: cursor.x, y: cursor.y }
+  const targetEnd = { x: pts[pts.length - 1].x, y: pts[pts.length - 1].y }
+  const lineToTarget = (t: number) => interpolateLine(targetStart, targetEnd, t)
+  segments.push({
+    length: Math.hypot(pts[pts.length - 1].x - cursor.x, pts[pts.length - 1].y - cursor.y),
+    pointAt: lineToTarget,
+  })
+
+  return segments
+}
+
+export function getWaypointLabelPosition(
+  sourceX: number, sourceY: number,
+  waypoints: Waypoint[],
+  targetX: number, targetY: number,
+  pathStyle: string = 'bezier',
+): Waypoint {
+  const pts = [{ x: sourceX, y: sourceY }, ...waypoints, { x: targetX, y: targetY }]
+  const segments = pathStyle === 'smooth' ? buildSmoothSegments(pts) : buildBezierSegments(pts)
+
+  if (segments.length === 0) return pts[0]
+
+  const totalLength = segments.reduce((sum, segment) => sum + segment.length, 0)
+  if (totalLength <= 0) return pts[Math.floor(pts.length / 2)]
+
+  let remaining = totalLength / 2
+  for (const segment of segments) {
+    if (remaining <= segment.length) {
+      const t = segment.length === 0 ? 0 : remaining / segment.length
+      return segment.pointAt(t)
+    }
+    remaining -= segment.length
+  }
+
+  const lastSegment = segments[segments.length - 1]
+  return lastSegment.pointAt(1)
+}
+
+function getBezierSegmentPoint(
+  pts: Waypoint[],
+  insertIndex: number,
+  t: number,
+): Waypoint {
+  const i = Math.max(0, Math.min(insertIndex, pts.length - 2))
+  const p0 = pts[Math.max(i - 1, 0)]
+  const p1 = pts[i]
+  const p2 = pts[i + 1]
+  const p3 = pts[Math.min(i + 2, pts.length - 1)]
+  const cp1 = {
+    x: p1.x + (p2.x - p0.x) / 6,
+    y: p1.y + (p2.y - p0.y) / 6,
+  }
+  const cp2 = {
+    x: p2.x - (p3.x - p1.x) / 6,
+    y: p2.y - (p3.y - p1.y) / 6,
+  }
+
+  return interpolateCubic(p1, cp1, cp2, p2, t)
+}
+
+export function getAddWaypointHandlePosition(
+  sourceX: number, sourceY: number,
+  waypoints: Waypoint[],
+  targetX: number, targetY: number,
+  insertIndex: number,
+  pathStyle: string = 'bezier',
+): Waypoint {
+  const pts = [{ x: sourceX, y: sourceY }, ...waypoints, { x: targetX, y: targetY }]
+
+  if (pts.length < 2) return { x: sourceX, y: sourceY }
+
+  if (pathStyle !== 'smooth') {
+    return getBezierSegmentPoint(pts, insertIndex, 0.5)
+  }
+
+  const i = Math.max(0, Math.min(insertIndex, pts.length - 2))
+  return {
+    x: (pts[i].x + pts[i + 1].x) / 2,
+    y: (pts[i].y + pts[i + 1].y) / 2,
+  }
+}
+
+// ── 45° snapping ──────────────────────────────────────────────────────────────
+
+/**
+ * Snap `pos` to the nearest 45°-multiple direction from `from`.
+ * Only snaps when within SNAP_THRESHOLD px of a 45° position.
+ */
+export function snap45(from: Waypoint, pos: Waypoint): Waypoint {
+  const dx = pos.x - from.x
+  const dy = pos.y - from.y
+  const dist = Math.hypot(dx, dy)
+  if (dist < 1) return pos
+  const angle = Math.atan2(dy, dx)
+  const snapped = Math.round(angle / (Math.PI / 4)) * (Math.PI / 4)
+  const candidate = {
+    x: Math.round(from.x + dist * Math.cos(snapped)),
+    y: Math.round(from.y + dist * Math.sin(snapped)),
+  }
+  const deviation = Math.hypot(candidate.x - pos.x, candidate.y - pos.y)
+  return deviation <= SNAP_THRESHOLD ? candidate : pos
+}
+
+/** Snap threshold in flow-space pixels. Only snap when this close to a 45° position. */
+const SNAP_THRESHOLD = 15
+
+/**
+ * Find the position closest to `pos` that lies simultaneously on a 45°-ray
+ * from `prev` AND on a 45°-ray from `next`.
+ *
+ * Only snaps when the nearest valid intersection is within SNAP_THRESHOLD px —
+ * outside that zone the raw drag position is returned, allowing free placement.
+ */
+export function snap45both(prev: Waypoint, next: Waypoint, pos: Waypoint): Waypoint {
+  let best: Waypoint | null = null
+  let bestDist = Infinity
+
+  for (let i = 0; i < 8; i++) {
+    const a1 = i * Math.PI / 4
+    const c1 = Math.cos(a1), s1 = Math.sin(a1)
+
+    for (let j = 0; j < 8; j++) {
+      const a2 = j * Math.PI / 4
+      const c2 = Math.cos(a2), s2 = Math.sin(a2)
+
+      const dx = next.x - prev.x
+      const dy = next.y - prev.y
+      const det = -c1 * s2 + c2 * s1
+      if (Math.abs(det) < 1e-6) continue
+
+      const t = (-dx * s2 + c2 * dy) / det
+      const s = (c1 * dy - s1 * dx) / det
+      if (t < -1e-6 || s < -1e-6) continue
+
+      const ix = prev.x + t * c1
+      const iy = prev.y + t * s1
+      const d = Math.hypot(ix - pos.x, iy - pos.y)
+      if (d < bestDist) {
+        bestDist = d
+        best = { x: Math.round(ix), y: Math.round(iy) }
+      }
+    }
+  }
+
+  // Only snap if close enough — otherwise let the waypoint move freely
+  if (best === null || bestDist > SNAP_THRESHOLD) return pos
+  return best
+}
+
+// ── Geometry helpers ──────────────────────────────────────────────────────────
+
+export function distToSegment(p: Waypoint, a: Waypoint, b: Waypoint): number {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const lenSq = dx * dx + dy * dy
+  if (lenSq === 0) return Math.hypot(p.x - a.x, p.y - a.y)
+  const t = Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / lenSq))
+  return Math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy))
+}
+
+export function findInsertIndex(
+  sourceX: number, sourceY: number,
+  waypoints: Waypoint[],
+  targetX: number, targetY: number,
+  point: Waypoint,
+): number {
+  const allPts = [{ x: sourceX, y: sourceY }, ...waypoints, { x: targetX, y: targetY }]
+  let minDist = Infinity
+  let best = 0
+  for (let i = 0; i < allPts.length - 1; i++) {
+    const d = distToSegment(point, allPts[i], allPts[i + 1])
+    if (d < minDist) { minDist = d; best = i }
+  }
+  return best
+}

frontend/src/components/canvas/nodes/BaseNode.tsx

@@ -1,75 +1,274 @@
-import { createElement } from 'react'
-import { Handle, Position, type NodeProps, type Node } from '@xyflow/react'
-import { type LucideIcon } from 'lucide-react'
-import type { NodeData, NodeStatus } from '@/types'
+import { createElement, useEffect, useMemo } from 'react'
+import { Handle, Position, NodeResizer, useUpdateNodeInternals, useViewport, type NodeProps, type Node } from '@xyflow/react'
+import { Cpu, MemoryStick, HardDrive, ExternalLink, type LucideIcon } from 'lucide-react'
+import type { NodeData } from '@/types'
 import { resolveNodeColors } from '@/utils/nodeColors'
-import { resolveNodeIcon } from '@/utils/nodeIcons'
-
-const STATUS_COLORS: Record<NodeStatus, string> = {
-  online: '#39d353',
-  offline: '#f85149',
-  pending: '#e3b341',
-  unknown: '#8b949e',
-}
+import { resolveNodeIcon, isBrandIconKey } from '@/utils/nodeIcons'
+import { NodeIcon } from '@/components/ui/NodeIcon'
+import { resolvePropertyIcon } from '@/utils/propertyIcons'
+import { useThemeStore } from '@/stores/themeStore'
+import { THEMES } from '@/utils/themes'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { maskIp, primaryIp, splitIps } from '@/utils/maskIp'
+import { bottomHandleId, bottomHandlePositions, clampBottomHandles } from '@/utils/handleUtils'
+import { getServiceUrl } from '@/utils/serviceUrl'
 
 interface BaseNodeProps extends NodeProps<Node<NodeData>> {
   icon: LucideIcon
 }
 
-export function BaseNode({ data, selected, icon: typeIcon }: BaseNodeProps) {
+function formatStorage(gb: number): string {
+  if (gb >= 1024) return `${(gb / 1024).toFixed(1).replace(/\.0$/, '')} TB`
+  return `${gb} GB`
+}
+
+export function BaseNode({ id, data, selected, icon: typeIcon, width, height }: BaseNodeProps) {
+  const updateNodeInternals = useUpdateNodeInternals()
+  useEffect(() => { updateNodeInternals(id) }, [data.bottom_handles, id, updateNodeInternals])
+
+  const { zoom } = useViewport()
+  const borderWidth = useMemo(() => Math.max(1, 1 / zoom), [zoom])
+
+  const activeTheme = useThemeStore((s) => s.activeTheme)
+  const hideIp = useCanvasStore((s) => s.hideIp)
+  const theme = THEMES[activeTheme]
+
   const resolvedIcon = resolveNodeIcon(typeIcon, data.custom_icon)
-  const colors = resolveNodeColors(data)
-  const statusColor = STATUS_COLORS[data.status]
+  const colors = resolveNodeColors(data, activeTheme)
+  const statusColor = theme.colors.statusColors[data.status]
   const isOnline = data.status === 'online'
+  const services = data.services ?? []
+  const showServices = data.custom_colors?.show_services === true
+  const serviceHost = data.ip ? primaryIp(data.ip) : data.hostname
+
+  // Properties: prefer new system; fall back to legacy hardware fields for unmigrated nodes
+  const visibleProperties = data.properties?.filter((p) => p.visible) ?? null
+  const showLegacyHardware = !data.properties && data.show_hardware &&
+    (data.cpu_count != null || data.cpu_model || data.ram_gb != null || data.disk_gb != null)
 
   return (
     <div
-      className="relative flex flex-row items-center gap-2.5 px-2.5 py-2 rounded-lg border transition-all duration-200"
+      className="relative flex flex-col rounded-lg border transition-all duration-200 overflow-hidden"
       style={{
         background: colors.background,
         borderColor: colors.border,
-        borderWidth: selected ? 2 : 1,
-        boxShadow: isOnline
+        borderWidth,
+        boxShadow: isOnline && selected
+          ? `0 0 0 ${borderWidth}px ${colors.border}, 0 0 10px ${colors.border}2e, 0 0 3px ${colors.border}1a`
+          : isOnline
           ? `0 0 10px ${colors.border}2e, 0 0 3px ${colors.border}1a`
           : selected
-          ? `0 0 8px ${colors.border}44`
+          ? `0 0 0 ${borderWidth}px ${colors.border}, 0 0 8px ${colors.border}44`
           : 'none',
         opacity: data.status === 'offline' ? 0.55 : 1,
-        minWidth: 140,
+        // Grow node width when many bottom handles so each stays clickable (~14px slot).
+        minWidth: Math.max(140, clampBottomHandles(data.bottom_handles ?? 1) * 14),
+        width: width ? '100%' : undefined,
+        height: height ? '100%' : undefined,
       }}
     >
-      <Handle type="source" position={Position.Top} id="top" className="!bg-[#30363d] !border-[#8b949e]" />
+      <NodeResizer
+        isVisible={selected}
+        minWidth={140}
+        minHeight={50}
+        lineStyle={{ borderColor: 'transparent' }}
+        handleStyle={{ borderColor: colors.border, background: colors.border, width: 16, height: 16 }}
+      />
+      <Handle
+        type="source"
+        position={Position.Top}
+        id="top"
+        style={{ background: theme.colors.handleBackground, borderColor: theme.colors.handleBorder }}
+      />
       <Handle type="target" position={Position.Top} id="top-t" style={{ opacity: 0, width: 12, height: 12 }} />
 
-      {/* Icon */}
+      {/* Status dot — absolute to avoid affecting node auto-width */}
       <div
-        className="flex items-center justify-center w-7 h-7 rounded-md shrink-0"
-        style={{ color: isOnline ? colors.icon : '#8b949e', background: '#161b22' }}
-      >
-        {createElement(resolvedIcon, { size: 15 })}
-      </div>
-
-      {/* Details */}
-      <div className="flex flex-col min-w-0">
-        <div className="text-xs font-medium leading-tight truncate max-w-[110px]" title={data.label}>
-          {data.label}
-        </div>
-        {data.ip && (
-          <div className="font-mono text-[10px] text-[#8b949e] truncate" title={data.ip}>
-            {data.ip}
-          </div>
-        )}
-      </div>
-
-      {/* Status dot */}
-      <div
-        className="absolute top-1.5 right-1.5 w-1.5 h-1.5 rounded-full shrink-0"
+        className="absolute top-2 right-2 w-1.5 h-1.5 rounded-full"
         style={{ backgroundColor: statusColor }}
         title={data.status}
       />
 
-      <Handle type="source" position={Position.Bottom} id="bottom" className="!bg-[#30363d] !border-[#8b949e]" />
-      <Handle type="target" position={Position.Bottom} id="bottom-t" style={{ opacity: 0, width: 12, height: 12 }} />
+      {/* Main row */}
+      <div className="flex flex-row items-center gap-2.5 px-2.5 py-2 min-w-0 overflow-hidden">
+        {/* Icon */}
+        <div
+          className="flex items-center justify-center w-7 h-7 rounded-md shrink-0"
+          style={{
+            color: isOnline ? colors.icon : theme.colors.nodeSubtextColor,
+            background: theme.colors.nodeIconBackground,
+          }}
+        >
+          {isBrandIconKey(data.custom_icon)
+            ? <NodeIcon typeIcon={typeIcon} customIconKey={data.custom_icon} size={15} />
+            : createElement(resolvedIcon, { size: 15 })}
+        </div>
+
+        {/* Label + IP */}
+        <div className="flex flex-col min-w-0">
+          <div
+            className="text-xs font-medium leading-tight truncate"
+            style={{ color: theme.colors.nodeLabelColor }}
+            title={data.label}
+          >
+            {data.label}
+          </div>
+          {data.ip && splitIps(data.ip).map((ip) => (
+            <div
+              key={ip}
+              className="font-mono text-[10px] truncate"
+              style={{ color: theme.colors.nodeSubtextColor }}
+              title={ip}
+            >
+              {hideIp ? maskIp(ip) : ip}
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Properties section (new system) */}
+      {visibleProperties && visibleProperties.length > 0 && (
+        <>
+          <div style={{ height: 1, background: `${colors.border}44`, margin: '0 8px' }} />
+          <div className="flex flex-col gap-1 px-2.5 py-1.5 overflow-hidden">
+            {visibleProperties.map((prop) => {
+              const Icon = resolvePropertyIcon(prop.icon)
+              return (
+                <div key={prop.key} className="flex items-center gap-1 font-mono text-[10px] min-w-0 overflow-hidden" style={{ color: theme.colors.nodeSubtextColor }}>
+                  {Icon && <Icon size={9} className="shrink-0" />}
+                  <span className="truncate max-w-15 shrink-0" title={prop.key}>{prop.key}</span>
+                  <span className="truncate min-w-0" title={prop.value}>· {prop.value}</span>
+                </div>
+              )
+            })}
+          </div>
+        </>
+      )}
+
+      {showServices && services.length > 0 && (
+        <>
+          <div style={{ height: 1, background: `${colors.border}44`, margin: '0 8px' }} />
+          <div className="flex flex-col gap-1 px-2.5 py-1.5 overflow-hidden">
+            {services.map((svc, idx) => {
+              const url = getServiceUrl(svc, serviceHost)
+              const row = (
+                <div
+                  className="nodrag flex items-center justify-between gap-2 px-1.5 py-1 rounded text-[10px] min-w-0 overflow-hidden"
+                  style={{
+                    background: theme.colors.nodeIconBackground,
+                    color: theme.colors.nodeSubtextColor,
+                  }}
+                >
+                  
+                  <div className="flex items-center justify-between gap-2 w-full min-w-0">
+                    {/* LEFT: service name */}
+                    <span
+                      className="font-medium truncate"
+                      style={{ minWidth: 0 }}
+                      title={svc.service_name}
+                    >
+                      {svc.service_name}
+                    </span>
+
+                    {/* RIGHT: path + port */}
+                    <div className="flex items-center gap-2 shrink-0 min-w-0">
+                      {svc.path && (
+                        <span
+                          className="truncate text-[#8b949e] text-right max-w-[80px]"
+                          title={svc.path}
+                        >
+                          {svc.path}
+                        </span>
+                      )}
+
+                      <span className="font-mono opacity-80 flex items-center gap-1">
+                        <span>{svc.port}</span>
+                        <ExternalLink
+                          size={9}
+                          className={`shrink-0 ${url ? '' : 'opacity-0'}`}
+                        />
+                      </span>
+                    </div>
+                  </div>
+                </div>
+              )
+
+              if (!url) return <div key={`${svc.port}-${svc.protocol}-${svc.service_name}-${idx}`}>{row}</div>
+
+              return (
+                <a
+                  key={`${svc.port}-${svc.protocol}-${svc.service_name}-${idx}`}
+                  href={url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="block hover:opacity-85 transition-opacity"
+                  title={url}
+                  onClick={(e) => e.stopPropagation()}
+                >
+                  {row}
+                </a>
+              )
+            })}
+          </div>
+        </>
+      )}
+
+      {/* Legacy hardware section — fallback for nodes not yet migrated */}
+      {showLegacyHardware && (
+        <>
+          <div style={{ height: 1, background: `${colors.border}44`, margin: '0 8px' }} />
+          <div className="flex flex-col gap-1 px-2.5 py-1.5">
+            {(data.cpu_model || data.cpu_count != null) && (
+              <div className="flex items-center gap-1 font-mono text-[10px]" style={{ color: theme.colors.nodeSubtextColor }}>
+                <Cpu size={9} className="shrink-0" />
+                {data.cpu_model && (
+                  <span className="truncate max-w-20" title={data.cpu_model}>{data.cpu_model}</span>
+                )}
+                {data.cpu_count != null && (
+                  <span className="shrink-0">{data.cpu_model ? `· ${data.cpu_count}c` : `${data.cpu_count} cores`}</span>
+                )}
+              </div>
+            )}
+            {(data.ram_gb != null || data.disk_gb != null) && (
+              <div className="flex items-center gap-2 font-mono text-[10px]" style={{ color: theme.colors.nodeSubtextColor }}>
+                {data.ram_gb != null && (
+                  <span className="flex items-center gap-0.5">
+                    <MemoryStick size={9} className="shrink-0" />
+                    {formatStorage(data.ram_gb)}
+                  </span>
+                )}
+                {data.disk_gb != null && (
+                  <span className="flex items-center gap-0.5">
+                    <HardDrive size={9} className="shrink-0" />
+                    {formatStorage(data.disk_gb)}
+                  </span>
+                )}
+              </div>
+            )}
+          </div>
+        </>
+      )}
+
+      {bottomHandlePositions(data.bottom_handles ?? 1).map((leftPct, idx) => {
+        const sourceId = bottomHandleId(idx)
+        const targetId = `${sourceId}-t`
+        return (
+          <span key={sourceId}>
+            <Handle
+              type="source"
+              position={Position.Bottom}
+              id={sourceId}
+              style={{ left: `${leftPct}%`, background: theme.colors.handleBackground, borderColor: theme.colors.handleBorder }}
+            />
+            <Handle
+              type="target"
+              position={Position.Bottom}
+              id={targetId}
+              style={{ left: `${leftPct}%`, opacity: 0, width: 12, height: 12 }}
+            />
+          </span>
+        )
+      })}
     </div>
   )
 }

frontend/src/components/canvas/nodes/GroupNode.tsx

@@ -0,0 +1,126 @@
+import { useState } from 'react'
+import { type NodeProps, type Node, NodeResizer } from '@xyflow/react'
+import { Layers, Pencil, Check, X } from 'lucide-react'
+import { useCanvasStore } from '@/stores/canvasStore'
+import { STATUS_COLORS, type NodeData } from '@/types'
+
+export function GroupNode({ id, data, selected }: NodeProps<Node<NodeData>>) {
+  const { nodes, updateNode, snapshotHistory } = useCanvasStore()
+  const showBorder = data.custom_colors?.show_border !== false
+  const isVisible = showBorder || selected
+
+  const [editing, setEditing] = useState(false)
+  const [labelDraft, setLabelDraft] = useState(data.label)
+
+  const children = nodes.filter((n) => n.parentId === id)
+  const onlineCount = children.filter((n) => n.data.status === 'online').length
+  const offlineCount = children.filter((n) => n.data.status === 'offline').length
+  const unknownCount = children.length - onlineCount - offlineCount
+
+  const handleRename = () => {
+    if (labelDraft.trim()) {
+      snapshotHistory()
+      updateNode(id, { label: labelDraft.trim() })
+    }
+    setEditing(false)
+  }
+
+  const borderColor = selected ? '#00d4ff' : '#30363d'
+  const borderStyle = selected ? 'solid' : 'dashed'
+
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        position: 'relative',
+        borderRadius: 8,
+        border: isVisible ? `2px ${borderStyle} ${borderColor}` : '2px solid transparent',
+        background: 'transparent',
+        transition: 'border-color 0.15s, background 0.15s',
+        boxSizing: 'border-box',
+      }}
+    >
+      <NodeResizer
+        isVisible={selected}
+        minWidth={120}
+        minHeight={80}
+        lineStyle={{ stroke: '#00d4ff', strokeWidth: 1 }}
+        handleStyle={{ fill: '#00d4ff', stroke: '#0d1117', width: 8, height: 8, borderRadius: 2 }}
+      />
+
+      {/* Header */}
+      {isVisible && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            right: 0,
+            padding: '5px 10px',
+            display: 'flex',
+            alignItems: 'center',
+            gap: 6,
+            background: selected ? 'rgba(0,212,255,0.08)' : 'rgba(22,27,34,0.8)',
+            borderRadius: '6px 6px 0 0',
+            borderBottom: isVisible ? `1px solid ${borderColor}40` : 'none',
+            pointerEvents: 'auto',
+          }}
+        >
+          <Layers size={12} style={{ color: '#00d4ff', flexShrink: 0 }} />
+
+          {editing ? (
+            <input
+              autoFocus
+              className="nodrag"
+              value={labelDraft}
+              onChange={(e) => setLabelDraft(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') handleRename()
+                if (e.key === 'Escape') { setLabelDraft(data.label); setEditing(false) }
+              }}
+              style={{
+                flex: 1,
+                background: 'transparent',
+                border: 'none',
+                outline: 'none',
+                color: '#e6edf3',
+                fontSize: 11,
+                fontWeight: 600,
+              }}
+            />
+          ) : (
+            <span style={{ flex: 1, fontSize: 11, fontWeight: 600, color: '#e6edf3', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+              {data.label}
+            </span>
+          )}
+
+          {editing ? (
+            <>
+              <button className="nodrag" onClick={handleRename} style={{ color: '#39d353', background: 'none', border: 'none', cursor: 'pointer', padding: 1 }}><Check size={11} /></button>
+              <button className="nodrag" onClick={() => { setLabelDraft(data.label); setEditing(false) }} style={{ color: '#f85149', background: 'none', border: 'none', cursor: 'pointer', padding: 1 }}><X size={11} /></button>
+            </>
+          ) : (
+            <button
+              className="nodrag"
+              onClick={() => { setLabelDraft(data.label); setEditing(true) }}
+              style={{ color: '#8b949e', background: 'none', border: 'none', cursor: 'pointer', padding: 1, opacity: selected ? 1 : 0 }}
+              title="Rename group"
+            >
+              <Pencil size={10} />
+            </button>
+          )}
+
+          {/* Status summary */}
+          {children.length > 0 && (
+            <div style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 10, flexShrink: 0, marginLeft: 4 }}>
+              {onlineCount > 0 && <span style={{ color: STATUS_COLORS.online }}>● {onlineCount}</span>}
+              {offlineCount > 0 && <span style={{ color: STATUS_COLORS.offline }}>● {offlineCount}</span>}
+              {unknownCount > 0 && <span style={{ color: STATUS_COLORS.unknown }}>● {unknownCount}</span>}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/components/canvas/nodes/GroupRectNode.tsx

@@ -1,4 +1,5 @@
-import { NodeResizer, type NodeProps, type Node } from '@xyflow/react'
+import { useState } from 'react'
+import { Handle, Position, NodeResizer, type NodeProps, type Node } from '@xyflow/react'
 import { useCanvasStore } from '@/stores/canvasStore'
 import type { NodeData, TextPosition } from '@/types'
 
@@ -26,17 +27,58 @@ const POSITION_STYLES: Record<TextPosition, AlignStyle> = {
   'bottom-right':  { alignItems: 'flex-end',   justifyContent: 'flex-end',   textAlign: 'right' },
 }
 
+const HANDLE_SIDES = [
+  { id: 'zone-top',    position: Position.Top },
+  { id: 'zone-right',  position: Position.Right },
+  { id: 'zone-bottom', position: Position.Bottom },
+  { id: 'zone-left',   position: Position.Left },
+] as const
+
 export function GroupRectNode({ id, data, selected }: NodeProps<Node<NodeData>>) {
   const setEditingGroupRectId = useCanvasStore((s) => s.setEditingGroupRectId)
+  const [hovered, setHovered] = useState(false)
 
   const rc = data.custom_colors ?? {}
   const borderColor = rc.border ?? '#00d4ff'
+  const borderStyle = rc.border_style ?? 'solid'
+  const borderWidth = rc.border_width ?? 2
   const backgroundColor = rc.background ?? 'rgba(0,212,255,0.05)'
   const textColor = rc.text_color ?? '#e6edf3'
+  const textSize: number = rc.text_size ?? 12
+  const labelPosition: string = rc.label_position ?? 'inside'
   const fontFamily = FONT_FAMILIES[rc.font ?? 'inter'] ?? FONT_FAMILIES.inter
   const textPos = (rc.text_position ?? 'top-left') as TextPosition
   const posStyle = POSITION_STYLES[textPos]
 
+  const outsideJustify = textPos.includes('right') ? 'flex-end'
+    : (textPos.includes('center') || textPos === 'center') ? 'center'
+    : 'flex-start'
+
+  const isOutsideBottom = textPos.startsWith('bottom')
+  const outsideOffset = textSize + 16
+  const outsideVertical: React.CSSProperties = isOutsideBottom
+    ? { bottom: -outsideOffset }
+    : { top: -outsideOffset }
+
+  const sharedTextStyle: React.CSSProperties = {
+    color: textColor,
+    fontFamily,
+    fontSize: textSize,
+    fontWeight: 500,
+    userSelect: 'none',
+    whiteSpace: 'pre-wrap',
+  }
+
+  const handleStyle: React.CSSProperties = {
+    width: 10,
+    height: 10,
+    background: borderColor,
+    border: '2px solid #0d1117',
+    borderRadius: '50%',
+    opacity: hovered ? 1 : 0,
+    transition: 'opacity 0.15s',
+  }
+
   return (
     <>
       <NodeResizer
@@ -50,10 +92,20 @@ export function GroupRectNode({ id, data, selected }: NodeProps<Node<NodeData>>)
           background: '#00d4ff',
           border: '1px solid #0d1117',
         }}
-        lineStyle={{ borderColor: '#00d4ff55', borderWidth: 1 }}
+        lineStyle={{ borderColor: 'transparent' }}
       />
+
+      {HANDLE_SIDES.map(({ id: hid, position }) => (
+        <span key={hid}>
+          <Handle type="source" id={hid} position={position} style={handleStyle} />
+          <Handle type="target" id={`${hid}-t`} position={position} style={{ ...handleStyle, opacity: 0, width: 14, height: 14 }} />
+        </span>
+      ))}
+
       <div
         style={{
+          position: 'relative',
+          overflow: 'visible',
           width: '100%',
           height: '100%',
           display: 'flex',
@@ -61,22 +113,37 @@ export function GroupRectNode({ id, data, selected }: NodeProps<Node<NodeData>>)
           justifyContent: posStyle.justifyContent,
           padding: 12,
           background: backgroundColor,
-          border: `${selected ? 2 : 1}px solid ${selected ? '#00d4ff' : borderColor}`,
+          border: `${borderWidth}px ${borderStyle} ${borderColor}`,
+          boxShadow: selected ? '0 0 0 1px #00d4ff, 0 0 8px #00d4ff44' : 'none',
           borderRadius: 10,
-          fontFamily,
-          color: textColor,
-          fontSize: 12,
-          fontWeight: 500,
           boxSizing: 'border-box',
           cursor: 'default',
         }}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
         onDoubleClick={(e) => {
           e.stopPropagation()
           setEditingGroupRectId(id)
         }}
       >
-        {data.label && (
-          <span style={{ textAlign: posStyle.textAlign, userSelect: 'none', whiteSpace: 'pre-wrap' }}>
+        {labelPosition === 'outside' && data.label && (
+          <span
+            style={{
+              position: 'absolute',
+              ...outsideVertical,
+              left: 0,
+              right: 0,
+              display: 'flex',
+              justifyContent: outsideJustify,
+              pointerEvents: 'none',
+              ...sharedTextStyle,
+            }}
+          >
+            {data.label}
+          </span>
+        )}
+        {labelPosition === 'inside' && data.label && (
+          <span style={{ textAlign: posStyle.textAlign, ...sharedTextStyle }}>
             {data.label}
           </span>
         )}