docs(debug): sherlock frame-select — not a regression, render-order clutter

Playwright drives the deployed image four ways. The frame <rect> has its
own pointerdown handler that calls startDrag; startDrag calls
e.stopPropagation() before the pan-start handler runs; the selector at
main.js:2087 already includes [data-frame-id]. Click that lands on the
rect → frame selected, inspector switches to the Frame panel. Verified.

m's complaint is real but cause is render order: frames paint first;
devices, ports, cables, clamps, IO markers all paint on top. Any click
on the frame interior that happens to land on one of those elements
hits that element, not the frame. For LOFT's big 'Entertainment' frame
the visible canvas portion is ~180×424 px and partly covered by yellow
cable polylines.

Not a one-line bug. Three UX options ordered by effort in the doc:
make the frame label the selection grip (drop pointer-events:none + add
pointerdown), parent-frame breadcrumb on the device inspector, modifier
key to escape to the enclosing frame. None applied — picasso/perseus
call.

docker-compose.yml

@@ -4,12 +4,7 @@
 
 services:
   mcables:
-    # Pushed under the mAi namespace because the mAi token doesn't have
-    # write permission to the m/* namespace on mgit.msbls.de today. If m
-    # later grants mAi collaborator access on m/mCables, retag to
-    # mgit.msbls.de/m/mcables:latest and align with the other mDock
-    # services (msports-garmin, mgreen-journal, …).
-    image: mgit.msbls.de/mai/mcables:latest
+    image: mgit.msbls.de/m/mcables:latest
     container_name: mcables
     restart: unless-stopped
     ports:

docs/sherlock-+dev-bug.md

@@ -0,0 +1,98 @@
+# +Dev click silently drops — root cause & fix
+
+**Reporter:** sherlock (Playwright debug shift, 2026-05-15 ~23:10)
+**Target:** http://mdock:7777 (deployed at e12b449)
+**Verdict:** Bug reproduced; root cause identified; one-line fix verified live.
+
+## Repro (Playwright, headless Chromium 1217)
+
+1. GET `http://mdock:7777/?project=1` (LOFT). Snapshot returns one frame (`Entertainment`).
+2. Click `#tool-device` — armed correctly (`.canvas-wrap.tool-device`, button `.armed`, cursor `crosshair` both over the empty SVG and over frame rects).
+3. Click inside the frame (rect centre).
+4. Expected: inline-namer `<foreignObject><input>` appears focused, m types name, Enter, `POST /api/projects/1/devices` fires, device renders.
+5. Observed: no FO visible, no POST, tool disarms silently. Same failure when clicking on **empty** canvas (outside any frame).
+
+## Trace (instrumented JS)
+
+```
+[782ms] svg.append              foreignObject  ← placeDeviceAt → promptInline appended it
+[782ms] focusout                BUTTON #tool-device
+[783ms] focusin                 INPUT          ← input.focus() succeeded
+[783ms] svg-bubble-pd           rect           ← pointerdown still bubbling
+[783ms] mutation.remove         foreignObject  ← FO ripped out
+```
+
+Patched `Element.prototype.remove` traces the offender:
+
+```
+at Element.remove (anon)
+at done (http://mdock:7777/main.js:585:36)
+at HTMLInputElement.<anonymous> (http://mdock:7777/main.js:592:42)
+```
+
+That's `input.addEventListener("blur", () => done(input.value.trim() || null))` in `promptInline`. The input was focused at 783 ms and blurred ~6 ms later, so `done(null)` removed the FO before m could type.
+
+## Root cause
+
+`placeDeviceAt` calls `promptInline` synchronously from inside the canvas `pointerdown` handler. `promptInline` does `input.focus()` synchronously. After the pointerdown handler returns, the browser performs the default mousedown action — focus the nearest focusable ancestor of the click target, else **blur the active element**. The click target is an SVG `<rect>` (or the `<svg>` root) which is not focusable, so the freshly-focused input gets blurred. The input's own `blur` listener fires `done(null)` → `fo.remove()`.
+
+This is independent of the previous fix at 94869f3 (which corrected the ordering of `onCanvasPointerDown` so the tool branches run before the "click on existing element" early-return). Routing is now correct, which is what unmasks the focus-blur bug. `+ Frame` is not affected because there `promptInline` runs from the pointer**up** callback, after pointer events have finished, so no mousedown is pending to steal focus.
+
+The cursor + Cache-Control fix at 28a376a addressed only the visual cursor lie and the redeploy staleness. It does not touch the click handler.
+
+## Fix (one line)
+
+`web/static/main.js` around line 472, in `onCanvasPointerDown`:
+
+```diff
+   if (state.tool === "frame") {
++    e.preventDefault();
+     startFrameRubberBand(e, p);
+     return;
+   }
+   if (state.tool === "device") {
++    e.preventDefault();
+     placeDeviceAt(p);
+     return;
+   }
+```
+
+`e.preventDefault()` on the pointerdown suppresses the compatibility mousedown's default focus-shift, so the input keeps focus and m can type. The `+ Frame` branch gets the same treatment for symmetry and to prevent a subtle text-selection side effect during rubber-band drag (it's not strictly required for the focus issue there because `+ Frame` focuses on pointerup).
+
+Per-call site rationale, not a blanket `if (state.tool) e.preventDefault()` at the top, because future tools that intentionally rely on default click behavior (e.g. a cable-drawing tool that needs link-clicks on ports) might want different semantics.
+
+### Verified live
+
+Monkey-patched the deployed page with a capture-phase listener that calls `e.preventDefault()` while `#tool-device.armed` exists. Result: device created, named `pc-sherlock`, persisted (POST `/api/projects/1/devices` 200). Screenshot: `/tmp/sherlock/fix_verified.png`.
+
+## Secondary observation (not blocking)
+
+After the fix, pressing `Enter` on the inline-namer logs a `pageerror`:
+
+```
+Failed to execute 'remove' on 'Element':
+  The node to be removed is no longer a child of this node.
+  Perhaps it was moved in a 'blur' event handler?
+```
+
+`done()` is called twice (once from Enter keydown, once from the resulting blur). The `if (activeNamer === fo)` guard on the second entry is recursive-safe because the first `done()` runs `fo.remove()` *before* setting `activeNamer = null`, so the synchronous blur fires inside the first remove() and re-enters with the guard still true. Cheap fix: reorder the two lines so the flag clears first:
+
+```diff
+ const done = (val) => {
+-  if (activeNamer === fo) { fo.remove(); activeNamer = null; }
++  if (activeNamer === fo) { activeNamer = null; fo.remove(); }
+   resolve(val);
+ };
+```
+
+Functional impact: none — the device is still created. Cosmetic console error only. Worth folding into the same patch.
+
+## Artifacts (sherlock side, /tmp)
+
+- `repro.py` — initial reproduction, screenshots before/after click.
+- `repro2.py` — event-trace instrumentation (capture+bubble pointerdowns, focus, mutations).
+- `repro3.py` — `remove()` stack-trace capture that named `done() <- blur listener`.
+- `verify_fix.py` — applied the proposed fix in-page; device created end-to-end.
+- `test_empty.py` — confirmed the bug bites on empty canvas too, not just inside frames.
+- `run.log`, `run2.log`, `run3.log`, `verify.log`, `empty.log` — full transcripts.
+- `fix_verified.png` — post-fix screenshot with `pc-sherlock` device visible inside the frame.

docs/sherlock-+port-bug.md

@@ -0,0 +1,144 @@
+# +Port "still does nothing" — root cause & fix
+
+**Reporter:** sherlock (Playwright debug shift 2, 2026-05-16 ~11:00)
+**Target:** http://mdock:7777 (deployed image c361bf38, picasso fix 3276cfe)
+**Verdict:** +Port is **not actually a no-op** — it successfully creates the port server-side AND client-side every time. The user-visible failure is **invisible stacking**: the new port renders at the exact same pixel as a pre-existing port on the same edge midpoint. m sees no canvas change and no panel switch, so the click feels dead.
+
+## What I ran
+
+Five Playwright drives against the live deployment, real Chromium (1217), full console + network + DOM mutation capture. Scripts and transcripts: `/tmp/sherlock/port_*`.
+
+| Scenario | Click target | POST result | DOM change | What m sees |
+|---|---|---|---|---|
+| (a) empty canvas inside frame | (443, 626) screen | 201, port id 40 created | new circle at TV bottom-left | maybe a new dot, but device list still selected, no halo |
+| (b) on the device body (TV center) | (563, 454) screen | 201, port id 41 | new circle at **(686.4, 643)** — same cx,cy as ports 37, 38, 39 already at that point | nothing — new dot stacks pixel-perfect under existing ones |
+| (c) directly on an existing port circle | (538, 445) screen | 201, port id 42 | new circle at **(636.4, 643)** — same cx,cy as port 27 | nothing — stacked |
+
+In every scenario:
+- `state.tool === "port"` after the +Port click (inferred from `.canvas-wrap.tool-port` + cursor `crosshair`)
+- `POST /api/projects/1/devices/2/ports` returns 201 with the new port row
+- `state.ports.push(port)` happens, `render()` redraws, the new circle exists in the DOM
+- The inspector port list grows by one row
+- **The canvas does not visibly change.**
+
+After 7 +Port placements on the TV, the inspector lists 7 ports, but only ~3 dots are visible on the device — the rest are stacked at identical (cx, cy):
+
+```
+ports on TV after the test run:
+  port 27  fill=#e03131 cx=636.4 cy=643.0  ← original
+  port 37  fill=#e03131 cx=686.4 cy=643.0
+  port 38  fill=#e03131 cx=686.4 cy=643.0   ← stacks on 37
+  port 39  fill=#1971c2 cx=686.4 cy=643.0   ← stacks on 37,38
+  port 40  fill=#e03131 cx=636.4 cy=678.0
+  port 41  fill=#e03131 cx=686.4 cy=643.0   ← stacks on 37,38,39
+  port 42  fill=#e03131 cx=636.4 cy=643.0   ← stacks on 27
+```
+
+## Why it stacks
+
+`snapToDeviceEdge` (main.js:1560–1574) projects the click to the nearest of the four device edges and clamps the parallel coordinate to `[0, device.width]` (or `device.height`). For the dominant click region — anywhere over the device body — `snapToDeviceEdge` collapses a wide band of clicks down to a handful of discrete `(xOff, yOff)` tuples. For a 100×35 device, clicking anywhere in the bottom half + roughly the horizontal middle resolves to `(xOff=50, yOff=35)`. Two clicks in that band produce two ports at identical coordinates. There is no de-dup against existing ports.
+
+This is geometry, not a regression — but it means the +Port tool has the same visible signature as a no-op tool for the most natural click region.
+
+## Why m's panel feedback is also weak
+
+`placePortAt` (main.js:1685–1706) finishes with `state.ports.push(port); armTool(null); render();`. It does **not** set `state.selection = { kind: "port", id: port.id }`. So:
+
+- `state.selection` stays on the device (set in the +Port-arming click).
+- The inspector continues to render the device panel; the port list grows by a row, but the panel doesn't switch.
+- The new port circle does not get the `.selected` halo (drop-shadow) defined in style.css.
+
+`placeDeviceAt`, `placeIOMarkerAt`, `startFrameRubberBand`, and `finishCableDrawAt` all set `state.selection` to the new entity. `placePortAt` is the odd one out.
+
+## Proposed fix (verified live)
+
+Two changes in `web/static/main.js`, one for stacking, one for feedback. The second is sufficient on its own to make the tool feel responsive.
+
+### A. Select the newly-placed port (primary)
+
+```diff
+ async function placePortAt(p) {
+   ...
+   try {
+     const port = await createPort(state.active.id, did, {
+       type_id: tid,
+       x_offset: snap.xOff,
+       y_offset: snap.yOff,
+     });
+     state.ports.push(port);
++    state.selection = { kind: "port", id: port.id };
+     armTool(null);
+     render();
+```
+
+Effect verified live by intercepting the POST response and dispatching a pointerdown on the new port circle (simulates the selection that the fix would set internally). Result:
+
+- Inspector immediately switches from the **DEVICE** panel to the **PORT** panel showing cable-type swatch, label input, edge dropdown (Top/Right/Bottom/Left), Delete button.
+- The new port circle gets the `.selected` class → drop-shadow halo, visually distinct even when stacked.
+- Screenshot: `/tmp/sherlock/port_fix_verified.png`.
+
+m clicking +Port now produces unambiguous feedback (panel switch + halo), AND he can immediately move the new port to the right edge with the dropdown — exactly the workflow when you wanted "another port over there".
+
+### B. De-dup snap position (secondary, optional)
+
+If two ports on the same device land within ~8 px of each other on the same edge, walk along that edge in 12 px increments until a free slot is found (or distribute the existing ones evenly — pick the lighter change). This eliminates pixel-perfect stacks for power users; (A) alone covers the perception bug.
+
+Sketch:
+
+```js
+function snapToDeviceEdge(device, x, y, existingPortsOnDevice) {
+  const raw = snapRaw(device, x, y); // current logic
+  if (!existingPortsOnDevice?.length) return raw;
+  const isOnEdge = (port, edge) =>
+    (edge === "left"   && port.x_offset === 0) ||
+    (edge === "right"  && port.x_offset === device.width) ||
+    (edge === "top"    && port.y_offset === 0) ||
+    (edge === "bottom" && port.y_offset === device.height);
+  const sibs = existingPortsOnDevice.filter((p) => isOnEdge(p, raw.edge));
+  // Walk along the parallel axis until no sibling within 8px tolerance.
+  ...
+}
+```
+
+Then `placePortAt` passes `state.ports.filter((p) => p.device_id === did)`.
+
+Not blocking — m's complaint is fixed by (A). File (B) as a polish ticket.
+
+## Unrelated bug surfaced during repro (separate fix, separate scope)
+
+Every click-only device selection throws this pageerror:
+
+```
+TypeError: Cannot read properties of null (reading 'classList')
+    at SVGSVGElement.onUp (http://mdock:7777/main.js:1846:21)
+```
+
+Source: `startDrag.onUp` does `e.currentTarget.classList.remove("dragging")` (main.js:1846). `e` is the closure-captured pointerdown event; by the time `onUp` runs (async, after pointerup), the browser has nulled out `e.currentTarget`. Click-only path aborts at line 1846 before the trailing `render()` (which is redundant here because `startDrag` already calls render at line 1794, so the user-visible state is fine — but the console error spams every click).
+
+Trivial fix: capture the target into a closure before defining the async handlers.
+
+```diff
+ function startDrag(e, kind, id) {
+   ...
++  const dragTarget = /** @type {Element} */ (e.currentTarget);
+   ...
+-  e.currentTarget.classList.add("dragging");
++  dragTarget.classList.add("dragging");
+   ...
+   const onUp = async (ev) => {
+     ...
+-    e.currentTarget.classList.remove("dragging");
++    dragTarget.classList.remove("dragging");
+```
+
+Not directly responsible for the +Port complaint, but it's noise in every console session and the fix is one line. Worth bundling with the port-select patch.
+
+## Artifacts
+
+Under `/tmp/sherlock/`:
+- `port_repro.py`, `port_repro2.py`, `port_repro3.py` — staged reproductions
+- `trace_pe.py` — pageerror stack capture
+- `verify_port_fix.py` — applied the proposed selection-after-placement fix in-page
+- `port_run.log`, `port_run2.log`, `port_run3.log`, `pe.log`, `verify_port.log` — full transcripts
+- `port_after_redo.png`, `port_scenario_*.png` — pre-fix screenshots showing the inspector-list-grows-but-canvas-doesn't symptom
+- `port_fix_verified.png` — post-fix screenshot, inspector switched to **PORT** panel with edge picker

docs/sherlock-frame-select.md

@@ -0,0 +1,99 @@
+# "I cannot change frames" — repro & verdict
+
+**Reporter:** sherlock (Playwright debug shift 3, 2026-05-16 ~19:30)
+**Target:** http://mdock:7777 (CableGUI, deployed at 79e17a5)
+**Hypothesis under test:** kandinsky's pan-on-left-drag (2933bb8) regressed frame select because the "isEmpty" selector missed `[data-frame-id]`.
+
+**Verdict:** **Hypothesis is wrong.** The selector at main.js:2087 already lists `[data-frame-id]`, the frame `<rect>` has its own pointerdown handler that calls `startDrag`, and `startDrag` calls `e.stopPropagation()` synchronously before the pan-start handler could fire. Frame selection works mechanically on the deployed image — verified four ways. m's complaint is real, but it's a **render-order / clutter** problem, not a click-handler regression.
+
+## What I ran (4 Playwright drives against the deployed image)
+
+### Selection works on a click that lands on the frame rect
+
+`frame_repro2.py` TEST 2 — Esc to deselect, then click 2 px inside frame 1's left edge:
+```
+before:  selected_frames=[]   inspector=None
+after:   selected_frames=['1'] inspector='Frame'
+pointerdowns: svg-capture target=rect.frame-rect frame=1
+pan changes:  []
+```
+Frame 1's inspector panel appears with name="Entertainment", x/y/w/h editable, "Delete frame" button. No pan-start fired.
+
+`frame_clean_test.py` — Esc, then click frame 3 (Network) bottom-left corner where nothing else is rendered:
+```
+top element at click point: rect.frame-rect (frame=3)
+after click: selected_frames=['3']  inspector='Frame'
+```
+
+### Selection works on a click + small drag too
+
+`frame_repro2.py` TEST 3 — 5 px drag (past the 3 px pan threshold) on frame interior:
+- `startDrag(e, "frame", f.id)` fires at the frame rect's `pointerdown`. It is the **first** pointerdown handler in the chain.
+- `startDrag` (main.js:2839) calls `e.stopPropagation()` synchronously when no tool is armed → pan-start handler never gets the event.
+- The 5 px movement is handled by `startDrag`'s own `onMove` (frame drag), not by the empty-canvas pan path.
+- Result: frame stays selected, frame nudges 5 px to the right. Inspector panel stays correct.
+
+50 px drag (TEST 4): same — frame stays selected, moves further.
+
+## Why m experiences "doesn't select"
+
+The frame `<rect>` paints **first**; everything else paints on top of it in this order (from index.html):
+
+```
+canvas-frames  ← frame rects (BOTTOM)
+canvas-devices ← device rects + port circles inside each device <g>
+canvas-ports
+canvas-cables  ← cable polylines (often crossing through frame interior)
+canvas-clamps
+canvas-io      ← IO marker diamonds
+```
+
+So any click on the frame's visible interior that happens to land on a device, port, port circle, cable polyline, clamp, or IO diamond hits THAT element, not the frame. The frame rect only "wins" the hit-test on pixels that are not covered by anything else.
+
+Two concrete observations from the LOFT snapshot:
+
+- Frame 1 "Entertainment" is huge (SVG 1340×848 at viewBox 2000×1500). Most of it renders past the canvas-wrap's right edge (x > 1220 px on a 1500 px viewport) and is occluded by the inspector `<aside>`. Only a ~180 × 424 px strip on the visible canvas right side is selectable. That strip is partly covered by devices and yellow cable polylines crossing diagonally.
+- Frame 3 "Network": grid hit-test, 9 sample points → 5 hit the frame, 2 hit cable polylines that cross through its centre. `frame_clean_test.py` confirmed: bottom-left corner click selects; centre click selects the cable.
+
+For m, "I click on the frame and it doesn't select" is **literally true at the click point he's choosing** — but the click is going to the cable/device on top, not the frame underneath. There is no regression in the dispatch.
+
+## Recommendation (no code change applied)
+
+Since the click-handler chain is correct, this is a UX call for picasso/perseus to make, not a one-line patch sherlock should apply. Three options ordered by effort:
+
+1. **Frame label is the selection grip.** Drop `pointer-events: none` from `.frame-label` (style.css:183) and add a pointerdown handler on the label that calls `startDrag(e, "frame", id)`. The label sits in the top-left of the frame, never overlaps a device, and is always visible — m gets a deterministic spot to click. This is a 2-line patch.
+
+2. **Selection breadcrumb on the device inspector.** When a selected device has `frame_id`, render `parent frame: <name>` as a clickable chip that calls `state.selection = {kind: "frame", id: frame.id}; render()`. Lets m drill from "I selected the wrong thing" → frame in one click.
+
+3. **Modifier-click to escape to frame.** Alt-click (or Ctrl-click) on any element promotes the hit-test to "select the enclosing frame, if any". Discoverable via tooltip on the inspector header.
+
+Option (1) is the cheapest and matches user mental model ("click the label to select that thing"). Probably worth pairing with the empty-canvas pan UX so m can hold Shift to disable pan when he wants to clear selection — but that's a separate refinement.
+
+## What the head's hypothesis *would* look like if it were the bug
+
+For completeness — if `[data-frame-id]` were missing from the selector in `onCanvasPointerDown`:
+
+```js
+// (hypothetical broken version)
+if (e.target instanceof Element && e.target.closest("[data-device-id], [data-io-id]")) return;
+//                                                                  ^^ no frame-id
+if (e.button === 0 && state.cableDrawFromPortID == null) {
+  startEmptyCanvasGesture(e);
+}
+```
+
+…then frame clicks would fall into `startEmptyCanvasGesture`. Sub-3 px clicks would still deselect (no good for m), and any tiny hand-jitter would promote to a pan. m would see "click frame → view shifts, no selection." That symptom matches m's wording — but the actual code is correct, so this isn't what's happening.
+
+The current code (main.js:2087):
+```js
+if (e.target instanceof Element && e.target.closest("[data-device-id], [data-frame-id], [data-io-id], [data-clamp-id], [data-port-id], [data-cable-id]")) return;
+```
+All six known target types are listed. No regression here.
+
+## Artifacts
+
+Under `/tmp/sherlock/`:
+- `frame_repro.py`, `frame_repro2.py`, `frame_repro3.py`, `frame_clean_test.py` — staged repros
+- `canvas_layout.py` — layout dump confirming canvas-wrap vs inspector aside geometry
+- `frame_run.log`, `frame_run2.log`, `frame_run3.log`, `clean.log`, `layout.log` — full transcripts
+- `frame2_01_interior.png`, `frame2_02_edge.png`, `frame_clean_result.png` — pre/post-click screenshots showing inspector switching to **Frame** panel on a clean rect-hit click

internal/db/frames_devices.go

@@ -0,0 +1,397 @@
+package db
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// -----------------------------------------------------------------------------
+// Frames
+// -----------------------------------------------------------------------------
+
+// FrameCreate is the create-shape; x/y/width/height carry full positions.
+type FrameCreate struct {
+	Name   string
+	X      float64
+	Y      float64
+	Width  float64
+	Height float64
+}
+
+// FrameUpdate is the partial-update shape for PATCH. project_id is
+// deliberately absent — moving a frame across projects would orphan its
+// devices' frame_id refs, so the API refuses to do it.
+type FrameUpdate struct {
+	Name   *string
+	X      *float64
+	Y      *float64
+	Width  *float64
+	Height *float64
+}
+
+// CreateFrame inserts a new frame inside a project.
+func (s *Store) CreateFrame(projectID int64, f FrameCreate) (*Frame, error) {
+	name := strings.TrimSpace(f.Name)
+	if name == "" {
+		return nil, fmt.Errorf("%w: name is required", ErrInvalidInput)
+	}
+	if f.Width <= 0 || f.Height <= 0 {
+		return nil, fmt.Errorf("%w: width and height must be positive", ErrInvalidInput)
+	}
+	if _, err := s.GetProject(projectID); err != nil {
+		return nil, err
+	}
+	res, err := s.db.Exec(
+		`INSERT INTO frames (project_id, name, x, y, width, height)
+		 VALUES (?, ?, ?, ?, ?, ?)`,
+		projectID, name, f.X, f.Y, f.Width, f.Height,
+	)
+	if err != nil {
+		return nil, mapWriteErr(err)
+	}
+	id, _ := res.LastInsertId()
+	return s.GetFrame(projectID, id)
+}
+
+// GetFrame loads a frame, enforcing project_id scoping.
+func (s *Store) GetFrame(projectID, id int64) (*Frame, error) {
+	var f Frame
+	var ex sql.NullString
+	err := s.db.QueryRow(
+		`SELECT id, project_id, name, x, y, width, height, excalidraw_id, created_at, updated_at
+		 FROM frames WHERE id = ? AND project_id = ?`, id, projectID,
+	).Scan(&f.ID, &f.ProjectID, &f.Name, &f.X, &f.Y, &f.Width, &f.Height,
+		&ex, &f.CreatedAt, &f.UpdatedAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	if ex.Valid {
+		f.ExcalidrawID = &ex.String
+	}
+	return &f, nil
+}
+
+// ListFrames returns every frame in a project, ordered by created_at so
+// the on-screen z-order is stable.
+func (s *Store) ListFrames(projectID int64) ([]Frame, error) {
+	rows, err := s.db.Query(
+		`SELECT id, project_id, name, x, y, width, height, excalidraw_id, created_at, updated_at
+		 FROM frames WHERE project_id = ? ORDER BY created_at, id`, projectID,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Frame{}
+	for rows.Next() {
+		var f Frame
+		var ex sql.NullString
+		if err := rows.Scan(&f.ID, &f.ProjectID, &f.Name, &f.X, &f.Y, &f.Width, &f.Height,
+			&ex, &f.CreatedAt, &f.UpdatedAt); err != nil {
+			return nil, err
+		}
+		if ex.Valid {
+			f.ExcalidrawID = &ex.String
+		}
+		out = append(out, f)
+	}
+	return out, rows.Err()
+}
+
+// UpdateFrame applies a partial update. project_id stays the same — we
+// don't expose moving a frame across projects.
+func (s *Store) UpdateFrame(projectID, id int64, u FrameUpdate) (*Frame, error) {
+	cur, err := s.GetFrame(projectID, id)
+	if err != nil {
+		return nil, err
+	}
+	if u.Name != nil {
+		v := strings.TrimSpace(*u.Name)
+		if v == "" {
+			return nil, fmt.Errorf("%w: name cannot be empty", ErrInvalidInput)
+		}
+		cur.Name = v
+	}
+	if u.X != nil {
+		cur.X = *u.X
+	}
+	if u.Y != nil {
+		cur.Y = *u.Y
+	}
+	if u.Width != nil {
+		if *u.Width <= 0 {
+			return nil, fmt.Errorf("%w: width must be positive", ErrInvalidInput)
+		}
+		cur.Width = *u.Width
+	}
+	if u.Height != nil {
+		if *u.Height <= 0 {
+			return nil, fmt.Errorf("%w: height must be positive", ErrInvalidInput)
+		}
+		cur.Height = *u.Height
+	}
+	if _, err := s.db.Exec(
+		`UPDATE frames
+		 SET name = ?, x = ?, y = ?, width = ?, height = ?, updated_at = datetime('now')
+		 WHERE id = ? AND project_id = ?`,
+		cur.Name, cur.X, cur.Y, cur.Width, cur.Height, id, projectID,
+	); err != nil {
+		return nil, mapWriteErr(err)
+	}
+	return s.GetFrame(projectID, id)
+}
+
+// DeleteFrame removes a frame. Devices with `frame_id = id` keep existing
+// — the schema's ON DELETE SET NULL drops their frame_id to NULL so they
+// stay in the project as "outside a frame".
+func (s *Store) DeleteFrame(projectID, id int64) error {
+	if _, err := s.GetFrame(projectID, id); err != nil {
+		return err
+	}
+	if _, err := s.db.Exec(
+		`DELETE FROM frames WHERE id = ? AND project_id = ?`, id, projectID,
+	); err != nil {
+		return err
+	}
+	return nil
+}
+
+// -----------------------------------------------------------------------------
+// Devices
+// -----------------------------------------------------------------------------
+
+// DeviceCreate is the create-shape. FrameID may be nil ("outside any frame").
+type DeviceCreate struct {
+	Name    string
+	FrameID *int64
+	Color   string
+	X       float64
+	Y       float64
+	Width   float64
+	Height  float64
+}
+
+// DeviceUpdate is the partial-update shape. project_id deliberately not
+// settable. FrameID is *(*int64) so callers can distinguish "leave as-is"
+// (nil) from "set to NULL" (&nil) — Go syntax: pass a *(*int64) where the
+// inner pointer is nil to clear.
+type DeviceUpdate struct {
+	Name      *string
+	FrameID   FrameRef // see FrameRef below
+	Color     *string
+	X         *float64
+	Y         *float64
+	Width     *float64
+	Height    *float64
+}
+
+// FrameRef encodes a tri-state for the FrameID PATCH:
+//
+//	Set=false               → leave the field untouched
+//	Set=true, ID=nil        → set to NULL (device leaves all frames)
+//	Set=true, ID=&someInt   → set to that frame id (must be in same project)
+type FrameRef struct {
+	Set bool
+	ID  *int64
+}
+
+// CreateDevice inserts a new device. FrameID, if provided, must reference
+// a frame in the same project.
+func (s *Store) CreateDevice(projectID int64, d DeviceCreate) (*Device, error) {
+	name := strings.TrimSpace(d.Name)
+	if name == "" {
+		return nil, fmt.Errorf("%w: name is required", ErrInvalidInput)
+	}
+	if d.Width <= 0 || d.Height <= 0 {
+		return nil, fmt.Errorf("%w: width and height must be positive", ErrInvalidInput)
+	}
+	if _, err := s.GetProject(projectID); err != nil {
+		return nil, err
+	}
+	if d.FrameID != nil {
+		if _, err := s.GetFrame(projectID, *d.FrameID); err != nil {
+			if errors.Is(err, ErrNotFound) {
+				return nil, fmt.Errorf("%w: frame_id %d not in project %d", ErrInvalidInput, *d.FrameID, projectID)
+			}
+			return nil, err
+		}
+	}
+	color := strings.TrimSpace(d.Color)
+	if color == "" {
+		color = "#1e1e1e"
+	}
+
+	res, err := s.db.Exec(
+		`INSERT INTO devices (project_id, frame_id, name, color, x, y, width, height)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+		projectID, nullableInt64(d.FrameID), name, color, d.X, d.Y, d.Width, d.Height,
+	)
+	if err != nil {
+		return nil, mapWriteErr(err)
+	}
+	id, _ := res.LastInsertId()
+	return s.GetDevice(projectID, id)
+}
+
+// GetDevice loads a device, project-scoped.
+func (s *Store) GetDevice(projectID, id int64) (*Device, error) {
+	var d Device
+	var frame sql.NullInt64
+	var ex sql.NullString
+	err := s.db.QueryRow(
+		`SELECT id, project_id, frame_id, name, color, x, y, width, height, excalidraw_id, created_at, updated_at
+		 FROM devices WHERE id = ? AND project_id = ?`, id, projectID,
+	).Scan(&d.ID, &d.ProjectID, &frame, &d.Name, &d.Color, &d.X, &d.Y, &d.Width, &d.Height,
+		&ex, &d.CreatedAt, &d.UpdatedAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	if frame.Valid {
+		v := frame.Int64
+		d.FrameID = &v
+	}
+	if ex.Valid {
+		d.ExcalidrawID = &ex.String
+	}
+	return &d, nil
+}
+
+// ListDevices returns devices in a project. If frameID is non-nil and
+// dereferences to a value, only devices with that frame_id are returned;
+// if frameID dereferences to nil (i.e. caller passed &FrameRef{Set:true,ID:nil})
+// — actually this signature uses *int64 directly: pass nil for "all
+// devices", or pass &someInt for "devices in that frame". The empty-
+// "outside-any-frame" filter isn't exposed yet — slice 2 doesn't need it.
+func (s *Store) ListDevices(projectID int64, frameID *int64) ([]Device, error) {
+	var (
+		rows *sql.Rows
+		err  error
+	)
+	if frameID != nil {
+		rows, err = s.db.Query(
+			`SELECT id, project_id, frame_id, name, color, x, y, width, height, excalidraw_id, created_at, updated_at
+			 FROM devices WHERE project_id = ? AND frame_id = ? ORDER BY created_at, id`,
+			projectID, *frameID,
+		)
+	} else {
+		rows, err = s.db.Query(
+			`SELECT id, project_id, frame_id, name, color, x, y, width, height, excalidraw_id, created_at, updated_at
+			 FROM devices WHERE project_id = ? ORDER BY created_at, id`,
+			projectID,
+		)
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Device{}
+	for rows.Next() {
+		var d Device
+		var frame sql.NullInt64
+		var ex sql.NullString
+		if err := rows.Scan(&d.ID, &d.ProjectID, &frame, &d.Name, &d.Color, &d.X, &d.Y, &d.Width, &d.Height,
+			&ex, &d.CreatedAt, &d.UpdatedAt); err != nil {
+			return nil, err
+		}
+		if frame.Valid {
+			v := frame.Int64
+			d.FrameID = &v
+		}
+		if ex.Valid {
+			d.ExcalidrawID = &ex.String
+		}
+		out = append(out, d)
+	}
+	return out, rows.Err()
+}
+
+// UpdateDevice applies a partial update. FrameID is tri-state — see FrameRef.
+// A FrameID set to a non-nil ID must reference a frame in the same project.
+func (s *Store) UpdateDevice(projectID, id int64, u DeviceUpdate) (*Device, error) {
+	cur, err := s.GetDevice(projectID, id)
+	if err != nil {
+		return nil, err
+	}
+	if u.Name != nil {
+		v := strings.TrimSpace(*u.Name)
+		if v == "" {
+			return nil, fmt.Errorf("%w: name cannot be empty", ErrInvalidInput)
+		}
+		cur.Name = v
+	}
+	if u.Color != nil {
+		v := strings.TrimSpace(*u.Color)
+		if v == "" {
+			return nil, fmt.Errorf("%w: color cannot be empty", ErrInvalidInput)
+		}
+		cur.Color = v
+	}
+	if u.X != nil {
+		cur.X = *u.X
+	}
+	if u.Y != nil {
+		cur.Y = *u.Y
+	}
+	if u.Width != nil {
+		if *u.Width <= 0 {
+			return nil, fmt.Errorf("%w: width must be positive", ErrInvalidInput)
+		}
+		cur.Width = *u.Width
+	}
+	if u.Height != nil {
+		if *u.Height <= 0 {
+			return nil, fmt.Errorf("%w: height must be positive", ErrInvalidInput)
+		}
+		cur.Height = *u.Height
+	}
+	if u.FrameID.Set {
+		if u.FrameID.ID != nil {
+			if _, err := s.GetFrame(projectID, *u.FrameID.ID); err != nil {
+				if errors.Is(err, ErrNotFound) {
+					return nil, fmt.Errorf("%w: frame_id %d not in project %d", ErrInvalidInput, *u.FrameID.ID, projectID)
+				}
+				return nil, err
+			}
+		}
+		cur.FrameID = u.FrameID.ID
+	}
+	if _, err := s.db.Exec(
+		`UPDATE devices
+		 SET frame_id = ?, name = ?, color = ?, x = ?, y = ?, width = ?, height = ?, updated_at = datetime('now')
+		 WHERE id = ? AND project_id = ?`,
+		nullableInt64(cur.FrameID), cur.Name, cur.Color, cur.X, cur.Y, cur.Width, cur.Height, id, projectID,
+	); err != nil {
+		return nil, mapWriteErr(err)
+	}
+	return s.GetDevice(projectID, id)
+}
+
+// DeleteDevice removes a device from a project.
+func (s *Store) DeleteDevice(projectID, id int64) error {
+	if _, err := s.GetDevice(projectID, id); err != nil {
+		return err
+	}
+	if _, err := s.db.Exec(
+		`DELETE FROM devices WHERE id = ? AND project_id = ?`, id, projectID,
+	); err != nil {
+		return err
+	}
+	return nil
+}
+
+// nullableInt64 converts a *int64 into a sql.NullInt64 so we can pass it
+// straight into a parameterised query.
+func nullableInt64(p *int64) any {
+	if p == nil {
+		return nil
+	}
+	return *p
+}

internal/db/frames_devices_test.go

@@ -0,0 +1,235 @@
+package db
+
+import (
+	"errors"
+	"testing"
+)
+
+// ----------------------------------------------------------------------- frames
+
+func TestCreateFrame_Basics(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f, err := s.CreateFrame(p.ID, FrameCreate{Name: "desk", X: 10, Y: 20, Width: 800, Height: 600})
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if f.ProjectID != p.ID || f.Name != "desk" || f.Width != 800 {
+		t.Errorf("unexpected frame: %+v", f)
+	}
+}
+
+func TestCreateFrame_RejectsZeroSize(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	if _, err := s.CreateFrame(p.ID, FrameCreate{Name: "x", Width: 0, Height: 50}); !errors.Is(err, ErrInvalidInput) {
+		t.Errorf("zero width should be ErrInvalidInput; got %v", err)
+	}
+	if _, err := s.CreateFrame(p.ID, FrameCreate{Name: "y", Width: 50, Height: 0}); !errors.Is(err, ErrInvalidInput) {
+		t.Errorf("zero height should be ErrInvalidInput; got %v", err)
+	}
+}
+
+func TestCreateFrame_DuplicateNameInSameProject(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	if _, err := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 100, Height: 50}); err != nil {
+		t.Fatalf("first: %v", err)
+	}
+	if _, err := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 200, Height: 70}); !errors.Is(err, ErrConflict) {
+		t.Errorf("duplicate frame name should ErrConflict; got %v", err)
+	}
+}
+
+func TestCreateFrame_SameNameAcrossProjectsOK(t *testing.T) {
+	s := newTestStore(t)
+	p1, _ := s.CreateProject("LOFT", "", "")
+	p2, _ := s.CreateProject("OFFICE", "", "")
+	if _, err := s.CreateFrame(p1.ID, FrameCreate{Name: "desk", Width: 100, Height: 50}); err != nil {
+		t.Fatalf("p1: %v", err)
+	}
+	if _, err := s.CreateFrame(p2.ID, FrameCreate{Name: "desk", Width: 100, Height: 50}); err != nil {
+		t.Fatalf("p2: %v", err)
+	}
+}
+
+func TestGetFrame_WrongProjectIsNotFound(t *testing.T) {
+	s := newTestStore(t)
+	p1, _ := s.CreateProject("LOFT", "", "")
+	p2, _ := s.CreateProject("OFFICE", "", "")
+	f, _ := s.CreateFrame(p1.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	if _, err := s.GetFrame(p2.ID, f.ID); !errors.Is(err, ErrNotFound) {
+		t.Errorf("cross-project GetFrame should be ErrNotFound; got %v", err)
+	}
+}
+
+func TestListFrames_OrderedByCreation(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	for _, n := range []string{"rack", "desk", "media"} {
+		if _, err := s.CreateFrame(p.ID, FrameCreate{Name: n, Width: 100, Height: 50}); err != nil {
+			t.Fatalf("create %s: %v", n, err)
+		}
+	}
+	got, _ := s.ListFrames(p.ID)
+	if len(got) != 3 {
+		t.Fatalf("len = %d", len(got))
+	}
+	if got[0].Name != "rack" || got[2].Name != "media" {
+		t.Errorf("order = %v", []string{got[0].Name, got[1].Name, got[2].Name})
+	}
+}
+
+func TestUpdateFrame_PartialFields(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f, _ := s.CreateFrame(p.ID, FrameCreate{Name: "desk", X: 0, Y: 0, Width: 100, Height: 50})
+	nx := 42.0
+	updated, err := s.UpdateFrame(p.ID, f.ID, FrameUpdate{X: &nx})
+	if err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	if updated.X != 42 || updated.Name != "desk" || updated.Width != 100 {
+		t.Errorf("got %+v", updated)
+	}
+}
+
+func TestDeleteFrame_SetsDeviceFrameIDToNull(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f, _ := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 800, Height: 600})
+	d, _ := s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", FrameID: &f.ID, X: 10, Y: 20, Width: 100, Height: 35})
+	if d.FrameID == nil || *d.FrameID != f.ID {
+		t.Fatalf("device frame_id pre-delete = %v, want %d", d.FrameID, f.ID)
+	}
+	if err := s.DeleteFrame(p.ID, f.ID); err != nil {
+		t.Fatalf("delete frame: %v", err)
+	}
+	d2, _ := s.GetDevice(p.ID, d.ID)
+	if d2.FrameID != nil {
+		t.Errorf("device frame_id post-delete = %v, want nil (SET NULL)", d2.FrameID)
+	}
+}
+
+// ---------------------------------------------------------------------- devices
+
+func TestCreateDevice_DefaultsColor(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	d, err := s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", X: 10, Y: 20, Width: 100, Height: 35})
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if d.Color != "#1e1e1e" {
+		t.Errorf("default color = %q, want #1e1e1e", d.Color)
+	}
+	if d.FrameID != nil {
+		t.Errorf("frame_id = %v, want nil for unframed device", d.FrameID)
+	}
+}
+
+func TestCreateDevice_DuplicateNameInProject(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	if _, err := s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", X: 0, Y: 0, Width: 100, Height: 35}); err != nil {
+		t.Fatalf("first: %v", err)
+	}
+	if _, err := s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", X: 10, Y: 10, Width: 100, Height: 35}); !errors.Is(err, ErrConflict) {
+		t.Errorf("dup device name should ErrConflict; got %v", err)
+	}
+}
+
+func TestCreateDevice_CrossProjectFrameRejected(t *testing.T) {
+	s := newTestStore(t)
+	p1, _ := s.CreateProject("LOFT", "", "")
+	p2, _ := s.CreateProject("OFFICE", "", "")
+	f2, _ := s.CreateFrame(p2.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	// Try to put a LOFT device into an OFFICE frame.
+	_, err := s.CreateDevice(p1.ID, DeviceCreate{Name: "Mac", FrameID: &f2.ID, X: 0, Y: 0, Width: 100, Height: 35})
+	if !errors.Is(err, ErrInvalidInput) {
+		t.Errorf("cross-project frame_id should ErrInvalidInput; got %v", err)
+	}
+}
+
+func TestUpdateDevice_FrameIDTriState(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f1, _ := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	f2, _ := s.CreateFrame(p.ID, FrameCreate{Name: "rack", Width: 100, Height: 50})
+	d, _ := s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", FrameID: &f1.ID, X: 0, Y: 0, Width: 100, Height: 35})
+
+	// Leave alone (FrameID.Set=false) — even passing a different X.
+	nx := 99.0
+	u1, _ := s.UpdateDevice(p.ID, d.ID, DeviceUpdate{X: &nx})
+	if u1.FrameID == nil || *u1.FrameID != f1.ID {
+		t.Errorf("frame_id should be unchanged (f1); got %v", u1.FrameID)
+	}
+
+	// Move to f2.
+	u2, _ := s.UpdateDevice(p.ID, d.ID, DeviceUpdate{FrameID: FrameRef{Set: true, ID: &f2.ID}})
+	if u2.FrameID == nil || *u2.FrameID != f2.ID {
+		t.Errorf("frame_id should be f2; got %v", u2.FrameID)
+	}
+
+	// Clear (move outside any frame).
+	u3, _ := s.UpdateDevice(p.ID, d.ID, DeviceUpdate{FrameID: FrameRef{Set: true, ID: nil}})
+	if u3.FrameID != nil {
+		t.Errorf("frame_id should be nil after Set:true,ID:nil; got %v", *u3.FrameID)
+	}
+}
+
+func TestUpdateDevice_RejectsCrossProjectFrame(t *testing.T) {
+	s := newTestStore(t)
+	p1, _ := s.CreateProject("LOFT", "", "")
+	p2, _ := s.CreateProject("OFFICE", "", "")
+	d, _ := s.CreateDevice(p1.ID, DeviceCreate{Name: "Mac", X: 0, Y: 0, Width: 100, Height: 35})
+	f2, _ := s.CreateFrame(p2.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	_, err := s.UpdateDevice(p1.ID, d.ID, DeviceUpdate{FrameID: FrameRef{Set: true, ID: &f2.ID}})
+	if !errors.Is(err, ErrInvalidInput) {
+		t.Errorf("cross-project frame_id should ErrInvalidInput; got %v", err)
+	}
+}
+
+func TestListDevices_FilterByFrame(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f1, _ := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	f2, _ := s.CreateFrame(p.ID, FrameCreate{Name: "rack", Width: 100, Height: 50})
+	_, _ = s.CreateDevice(p.ID, DeviceCreate{Name: "A", FrameID: &f1.ID, Width: 100, Height: 35})
+	_, _ = s.CreateDevice(p.ID, DeviceCreate{Name: "B", FrameID: &f2.ID, Width: 100, Height: 35})
+	_, _ = s.CreateDevice(p.ID, DeviceCreate{Name: "C", Width: 100, Height: 35}) // outside
+
+	all, _ := s.ListDevices(p.ID, nil)
+	if len(all) != 3 {
+		t.Errorf("all len = %d, want 3", len(all))
+	}
+	inF1, _ := s.ListDevices(p.ID, &f1.ID)
+	if len(inF1) != 1 || inF1[0].Name != "A" {
+		t.Errorf("inF1 = %+v", inF1)
+	}
+}
+
+func TestSnapshot_PopulatesFramesAndDevices(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	f, _ := s.CreateFrame(p.ID, FrameCreate{Name: "desk", Width: 100, Height: 50})
+	_, _ = s.CreateDevice(p.ID, DeviceCreate{Name: "Mac", FrameID: &f.ID, Width: 100, Height: 35})
+	snap, err := s.Snapshot(p.ID)
+	if err != nil {
+		t.Fatalf("snapshot: %v", err)
+	}
+	if len(snap.Frames) != 1 || len(snap.Devices) != 1 {
+		t.Errorf("snapshot frames=%d devices=%d", len(snap.Frames), len(snap.Devices))
+	}
+	if len(snap.CableTypes) != 5 {
+		t.Errorf("cable_types = %d, want 5", len(snap.CableTypes))
+	}
+}
+
+func TestDeleteDevice_NotFoundIsNotFound(t *testing.T) {
+	s := newTestStore(t)
+	p, _ := s.CreateProject("LOFT", "", "")
+	if err := s.DeleteDevice(p.ID, 999); !errors.Is(err, ErrNotFound) {
+		t.Errorf("got %v, want ErrNotFound", err)
+	}
+}

internal/db/models.go

@@ -19,13 +19,43 @@ type CableType struct {
 	UpdatedAt string `json:"updated_at"`
 }
 
+// Frame is a sub-zone inside a project (`desk`, `rack`, …).
+type Frame struct {
+	ID            int64   `json:"id"`
+	ProjectID     int64   `json:"project_id"`
+	Name          string  `json:"name"`
+	X             float64 `json:"x"`
+	Y             float64 `json:"y"`
+	Width         float64 `json:"width"`
+	Height        float64 `json:"height"`
+	ExcalidrawID  *string `json:"excalidraw_id,omitempty"`
+	CreatedAt     string  `json:"created_at"`
+	UpdatedAt     string  `json:"updated_at"`
+}
+
+// Device is a hardware item inside a project, optionally inside a frame.
+type Device struct {
+	ID            int64   `json:"id"`
+	ProjectID     int64   `json:"project_id"`
+	FrameID       *int64  `json:"frame_id"`           // nullable: device "outside" any frame
+	Name          string  `json:"name"`
+	Color         string  `json:"color"`
+	X             float64 `json:"x"`
+	Y             float64 `json:"y"`
+	Width         float64 `json:"width"`
+	Height        float64 `json:"height"`
+	ExcalidrawID  *string `json:"excalidraw_id,omitempty"`
+	CreatedAt     string  `json:"created_at"`
+	UpdatedAt     string  `json:"updated_at"`
+}
+
 // Snapshot is the editor's one-shot loader payload for a single project.
-// Slice 1 returns the project + the global cable_types; the other arrays
-// are present but empty until later slices ship their CRUD.
+// Arrays for collections still gated by future slices stay non-nil [] so
+// JSON encodes as [] not null.
 type Snapshot struct {
 	Project    Project     `json:"project"`
-	Frames     []any       `json:"frames"`
-	Devices    []any       `json:"devices"`
+	Frames     []Frame     `json:"frames"`
+	Devices    []Device    `json:"devices"`
 	Ports      []any       `json:"ports"`
 	Cables     []any       `json:"cables"`
 	IOMarkers  []any       `json:"io_markers"`

internal/db/store.go

@@ -147,8 +147,9 @@ func (s *Store) DeleteProject(id int64, confirmName string) error {
 	return nil
 }
 
-// Snapshot loads the full editor-init payload for one project. In slice
-// 1 the project-scoped collections are still empty.
+// Snapshot loads the full editor-init payload for one project. Slice 2
+// populates frames + devices; ports / cables / io_markers / bundles
+// still ship empty until their slices land.
 func (s *Store) Snapshot(id int64) (*Snapshot, error) {
 	p, err := s.GetProject(id)
 	if err != nil {
@@ -158,10 +159,18 @@ func (s *Store) Snapshot(id int64) (*Snapshot, error) {
 	if err != nil {
 		return nil, err
 	}
+	frames, err := s.ListFrames(id)
+	if err != nil {
+		return nil, err
+	}
+	devices, err := s.ListDevices(id, nil)
+	if err != nil {
+		return nil, err
+	}
 	return &Snapshot{
 		Project:    *p,
-		Frames:     []any{},
-		Devices:    []any{},
+		Frames:     frames,
+		Devices:    devices,
 		Ports:      []any{},
 		Cables:     []any{},
 		IOMarkers:  []any{},

internal/server/frames_devices.go

@@ -0,0 +1,234 @@
+package server
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"mgit.msbls.de/m/mcables/internal/db"
+)
+
+// ---------------------------------------------------------------- frames
+
+type frameCreate struct {
+	Name   string  `json:"name"`
+	X      float64 `json:"x"`
+	Y      float64 `json:"y"`
+	Width  float64 `json:"width"`
+	Height float64 `json:"height"`
+}
+
+type framePatch struct {
+	Name   *string  `json:"name,omitempty"`
+	X      *float64 `json:"x,omitempty"`
+	Y      *float64 `json:"y,omitempty"`
+	Width  *float64 `json:"width,omitempty"`
+	Height *float64 `json:"height,omitempty"`
+}
+
+func (h *handlers) listFrames(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	fs, err := h.store.ListFrames(pid)
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusOK, fs)
+}
+
+func (h *handlers) createFrame(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	var body frameCreate
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, errors.Join(db.ErrInvalidInput, err), nil)
+		return
+	}
+	f, err := h.store.CreateFrame(pid, db.FrameCreate{
+		Name: body.Name, X: body.X, Y: body.Y, Width: body.Width, Height: body.Height,
+	})
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusCreated, f)
+}
+
+func (h *handlers) patchFrame(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	id, ok := parseInt64Path(r, "id")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "id must be a positive integer")
+		return
+	}
+	var body framePatch
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, errors.Join(db.ErrInvalidInput, err), nil)
+		return
+	}
+	f, err := h.store.UpdateFrame(pid, id, db.FrameUpdate{
+		Name: body.Name, X: body.X, Y: body.Y, Width: body.Width, Height: body.Height,
+	})
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusOK, f)
+}
+
+func (h *handlers) deleteFrame(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	id, ok := parseInt64Path(r, "id")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "id must be a positive integer")
+		return
+	}
+	if err := h.store.DeleteFrame(pid, id); err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------- devices
+
+type deviceCreate struct {
+	Name    string  `json:"name"`
+	FrameID *int64  `json:"frame_id,omitempty"`
+	Color   string  `json:"color,omitempty"`
+	X       float64 `json:"x"`
+	Y       float64 `json:"y"`
+	Width   float64 `json:"width"`
+	Height  float64 `json:"height"`
+}
+
+// devicePatch uses a raw `json.RawMessage` for frame_id so we can tell
+// "key absent" (leave alone) from "key present and null" (set to NULL)
+// from "key present with an int" (move to that frame). Standard encoding
+// of nullable fields in JSON PATCH.
+type devicePatch struct {
+	Name    *string         `json:"name,omitempty"`
+	FrameID json.RawMessage `json:"frame_id,omitempty"`
+	Color   *string         `json:"color,omitempty"`
+	X       *float64        `json:"x,omitempty"`
+	Y       *float64        `json:"y,omitempty"`
+	Width   *float64        `json:"width,omitempty"`
+	Height  *float64        `json:"height,omitempty"`
+}
+
+// parseFrameRef decodes the raw frame_id field into a tri-state.
+func parseFrameRef(raw json.RawMessage) (db.FrameRef, error) {
+	if len(raw) == 0 {
+		return db.FrameRef{Set: false}, nil
+	}
+	// "null" → clear; otherwise expect an integer.
+	if string(raw) == "null" {
+		return db.FrameRef{Set: true, ID: nil}, nil
+	}
+	var id int64
+	if err := json.Unmarshal(raw, &id); err != nil {
+		return db.FrameRef{}, err
+	}
+	return db.FrameRef{Set: true, ID: &id}, nil
+}
+
+func (h *handlers) listDevices(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	ds, err := h.store.ListDevices(pid, nil)
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusOK, ds)
+}
+
+func (h *handlers) createDevice(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	var body deviceCreate
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, errors.Join(db.ErrInvalidInput, err), nil)
+		return
+	}
+	d, err := h.store.CreateDevice(pid, db.DeviceCreate{
+		Name: body.Name, FrameID: body.FrameID, Color: body.Color,
+		X: body.X, Y: body.Y, Width: body.Width, Height: body.Height,
+	})
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusCreated, d)
+}
+
+func (h *handlers) patchDevice(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	id, ok := parseInt64Path(r, "id")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "id must be a positive integer")
+		return
+	}
+	var body devicePatch
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, errors.Join(db.ErrInvalidInput, err), nil)
+		return
+	}
+	ref, err := parseFrameRef(body.FrameID)
+	if err != nil {
+		writeError(w, errors.Join(db.ErrInvalidInput, err), "frame_id must be an integer or null")
+		return
+	}
+	d, err := h.store.UpdateDevice(pid, id, db.DeviceUpdate{
+		Name: body.Name, FrameID: ref, Color: body.Color,
+		X: body.X, Y: body.Y, Width: body.Width, Height: body.Height,
+	})
+	if err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	writeJSON(w, http.StatusOK, d)
+}
+
+func (h *handlers) deleteDevice(w http.ResponseWriter, r *http.Request) {
+	pid, ok := parseInt64Path(r, "pid")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "pid must be a positive integer")
+		return
+	}
+	id, ok := parseInt64Path(r, "id")
+	if !ok {
+		writeError(w, db.ErrInvalidInput, "id must be a positive integer")
+		return
+	}
+	if err := h.store.DeleteDevice(pid, id); err != nil {
+		writeError(w, err, nil)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/server/server.go

@@ -33,8 +33,39 @@ func New(store *db.Store, frontend fs.FS) http.Handler {
 	mux.HandleFunc("PATCH /api/cable-types/{id}", h.patchCableType)
 	mux.HandleFunc("DELETE /api/cable-types/{id}", h.deleteCableType)
 
+	// Frames (project-scoped)
+	mux.HandleFunc("GET /api/projects/{pid}/frames", h.listFrames)
+	mux.HandleFunc("POST /api/projects/{pid}/frames", h.createFrame)
+	mux.HandleFunc("PATCH /api/projects/{pid}/frames/{id}", h.patchFrame)
+	mux.HandleFunc("DELETE /api/projects/{pid}/frames/{id}", h.deleteFrame)
+
+	// Devices (project-scoped)
+	mux.HandleFunc("GET /api/projects/{pid}/devices", h.listDevices)
+	mux.HandleFunc("POST /api/projects/{pid}/devices", h.createDevice)
+	mux.HandleFunc("PATCH /api/projects/{pid}/devices/{id}", h.patchDevice)
+	mux.HandleFunc("DELETE /api/projects/{pid}/devices/{id}", h.deleteDevice)
+
 	// Frontend (embedded). Serve "/" → index.html via http.FileServerFS.
-	mux.Handle("/", http.FileServerFS(frontend))
+	// Wrap in noCache so the browser revalidates with the ETag/Last-Modified
+	// the file server already emits — without this, browsers cache aggressively
+	// and m sees the old main.js after every redeploy until hard-reload.
+	mux.Handle("/", noCache(http.FileServerFS(frontend)))
 
 	return mux
 }
+
+// noCache wraps a static handler so each response carries
+// Cache-Control: no-cache. Combined with the ETag/Last-Modified headers
+// http.FileServer(FS) already emits, this turns every fetch into a
+// cheap revalidation request — the browser uses its cached body when
+// the ETag matches but always asks first, so freshly-built assets show
+// up on the next page load without a hard-reload.
+//
+// Applied to the static-asset handler only — API responses write their
+// own headers and aren't routed through this.
+func noCache(h http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Cache-Control", "no-cache")
+		h.ServeHTTP(w, r)
+	})
+}

web/static/index.html

@@ -35,8 +35,8 @@
       <section class="tools">
         <h2 class="sidebar-heading">Tools</h2>
         <ul class="tool-list">
-          <li><button type="button" class="btn btn-tiny" disabled title="Slice 2">+ Frame</button></li>
-          <li><button type="button" class="btn btn-tiny" disabled title="Slice 2">+ Device</button></li>
+          <li><button type="button" id="tool-frame"  class="btn btn-tiny" data-tool="frame">+ Frame</button></li>
+          <li><button type="button" id="tool-device" class="btn btn-tiny" data-tool="device">+ Device</button></li>
           <li><button type="button" class="btn btn-tiny" disabled title="Slice 4">+ IO</button></li>
           <li><button type="button" class="btn btn-tiny" disabled title="Slice 3">Draw cable</button></li>
         </ul>
@@ -58,7 +58,9 @@
 
     <aside class="inspector" aria-label="Inspector">
       <h2 class="sidebar-heading">Inspector</h2>
+      <div id="inspector-body">
         <p class="muted">Nothing selected.</p>
+      </div>
     </aside>
   </main>
 

web/static/main.js

@@ -1,23 +1,34 @@
 // mCables frontend entry — vanilla ES module, no build step.
 //
-// Slice 1 covers: list/create/delete projects, list/create/edit/delete
-// global cable types, and reflect the active project in ?project=<id>.
+// Slice 2 adds: frame + device rendering, +Frm/+Dev tools, drag-to-position,
+// inline naming, inspector for selection. State stays minimal: one
+// snapshot from the server, then individual PATCHes on each mutation.
 
 /**
  * @typedef {{ id: number, name: string, drawing_name: string,
  *             description: string, created_at: string, updated_at: string }} Project
  * @typedef {{ id: number, name: string, color: string,
  *             created_at: string, updated_at: string }} CableType
+ * @typedef {{ id: number, project_id: number, name: string,
+ *             x: number, y: number, width: number, height: number }} Frame
+ * @typedef {{ id: number, project_id: number, frame_id: number|null,
+ *             name: string, color: string,
+ *             x: number, y: number, width: number, height: number }} Device
  */
 
 const API = "/api";
+const SVG_NS = "http://www.w3.org/2000/svg";
 
 const state = {
   /** @type {Project[]} */ projects: [],
   /** @type {CableType[]} */ cableTypes: [],
   /** @type {Project | null} */ active: null,
-  /** active cable-type id (used for drawing in later slices) */
-  activeTypeId: null,
+  /** @type {Frame[]} */ frames: [],
+  /** @type {Device[]} */ devices: [],
+  activeTypeId: /** @type {number|null} */ (null),
+  /** "frame" | "device" | null */
+  tool: /** @type {string|null} */ (null),
+  /** @type {{kind: "frame"|"device", id: number} | null} */ selection: null,
 };
 
 // ---------- API client ---------- //
@@ -42,7 +53,6 @@ async function api(method, path, body) {
 
 const listProjects   = () => api("GET", "/projects");
 const createProject  = (body) => api("POST", "/projects", body);
-const patchProject   = (id, body) => api("PATCH", `/projects/${id}`, body);
 const deleteProject  = (id, confirm) =>
   api("DELETE", `/projects/${id}?confirm=${encodeURIComponent(confirm)}`);
 const getSnapshot    = (id) => api("GET", `/projects/${id}`);
@@ -52,6 +62,14 @@ const createCableType = (body) => api("POST", "/cable-types", body);
 const patchCableType  = (id, body) => api("PATCH", `/cable-types/${id}`, body);
 const deleteCableType = (id) => api("DELETE", `/cable-types/${id}`);
 
+const createFrame = (pid, body) => api("POST",   `/projects/${pid}/frames`, body);
+const patchFrame  = (pid, id, body) => api("PATCH",  `/projects/${pid}/frames/${id}`, body);
+const deleteFrame = (pid, id) => api("DELETE", `/projects/${pid}/frames/${id}`);
+
+const createDevice = (pid, body) => api("POST",   `/projects/${pid}/devices`, body);
+const patchDevice  = (pid, id, body) => api("PATCH",  `/projects/${pid}/devices/${id}`, body);
+const deleteDevice = (pid, id) => api("DELETE", `/projects/${pid}/devices/${id}`);
+
 // ---------- DOM helpers ---------- //
 
 const $ = (sel) => /** @type {HTMLElement} */ (document.querySelector(sel));
@@ -61,6 +79,15 @@ function setHidden(el, hidden) {
   else el.removeAttribute("hidden");
 }
 
+function svgEl(name, attrs = {}) {
+  const el = document.createElementNS(SVG_NS, name);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v == null) continue;
+    el.setAttribute(k, String(v));
+  }
+  return el;
+}
+
 // ---------- URL state ---------- //
 
 function activeProjectIdFromURL() {
@@ -76,14 +103,39 @@ function setActiveInURL(id) {
   history.replaceState(null, "", url.toString());
 }
 
+// ---------- geometry ---------- //
+
+/** Returns the smallest frame whose bbox contains (x, y), or null. */
+function frameAt(x, y) {
+  /** @type {Frame|null} */ let best = null;
+  let bestArea = Infinity;
+  for (const f of state.frames) {
+    if (x < f.x || x > f.x + f.width || y < f.y || y > f.y + f.height) continue;
+    const a = f.width * f.height;
+    if (a < bestArea) { best = f; bestArea = a; }
+  }
+  return best;
+}
+
+/** Convert a pointer event to SVG-canvas coordinates. */
+function svgPoint(evt) {
+  const svg = /** @type {SVGSVGElement} */ ($("#canvas"));
+  const pt = svg.createSVGPoint();
+  pt.x = evt.clientX;
+  pt.y = evt.clientY;
+  const ctm = svg.getScreenCTM();
+  if (!ctm) return { x: 0, y: 0 };
+  const local = pt.matrixTransform(ctm.inverse());
+  return { x: local.x, y: local.y };
+}
+
 // ---------- render ---------- //
 
 function renderProjectPicker() {
   const sel = /** @type {HTMLSelectElement} */ ($("#project-select"));
   const current = state.active?.id ?? "";
   sel.innerHTML = "";
-  const blank = new Option("— pick a project —", "");
-  sel.append(blank);
+  sel.append(new Option("— pick a project —", ""));
   for (const p of state.projects) {
     const opt = new Option(p.name, String(p.id));
     if (p.id === current) opt.selected = true;
@@ -126,16 +178,214 @@ function renderEmptyHint() {
       ? "Pick a project from the dropdown to start drawing."
       : "Create your first project to get started.";
     setHidden(hint, false);
-  } else {
-    hint.textContent = `${state.active.name} — slice 1: empty canvas. Frames + devices arrive in slice 2.`;
-    setHidden(hint, false);
+    return;
   }
+  if (state.frames.length === 0 && state.devices.length === 0) {
+    hint.textContent = `${state.active.name} — empty. Use + Frame / + Device to start (press F or D).`;
+    setHidden(hint, false);
+  } else {
+    setHidden(hint, true);
+  }
+}
+
+function renderCanvas() {
+  const gFrames  = $("#canvas-frames");
+  const gDevices = $("#canvas-devices");
+  gFrames.innerHTML = "";
+  gDevices.innerHTML = "";
+
+  for (const f of state.frames) {
+    const g = svgEl("g", { "data-frame-id": f.id });
+    const rect = svgEl("rect", {
+      x: f.x, y: f.y, width: f.width, height: f.height,
+      class: "frame-rect svg-draggable",
+      rx: 6, ry: 6,
+    });
+    if (state.selection?.kind === "frame" && state.selection.id === f.id) {
+      rect.classList.add("selected");
+    }
+    const label = svgEl("text", {
+      x: f.x + 8, y: f.y + 18,
+      class: "frame-label",
+    });
+    label.textContent = f.name;
+    g.append(rect, label);
+    gFrames.append(g);
+    rect.addEventListener("pointerdown", (e) => startDrag(e, "frame", f.id));
+  }
+
+  for (const d of state.devices) {
+    const g = svgEl("g", { "data-device-id": d.id });
+    const rect = svgEl("rect", {
+      x: d.x, y: d.y, width: d.width, height: d.height,
+      class: "device-rect svg-draggable",
+      stroke: d.color,
+      rx: 3, ry: 3,
+    });
+    if (state.selection?.kind === "device" && state.selection.id === d.id) {
+      rect.classList.add("selected");
+    }
+    const label = svgEl("text", {
+      x: d.x + d.width / 2, y: d.y + d.height / 2,
+      class: "device-label",
+    });
+    label.textContent = d.name;
+    g.append(rect, label);
+    gDevices.append(g);
+    rect.addEventListener("pointerdown", (e) => startDrag(e, "device", d.id));
+  }
+}
+
+function renderInspector() {
+  const body = $("#inspector-body");
+  if (!state.selection) {
+    body.innerHTML = `<p class="muted">Nothing selected.</p>`;
+    return;
+  }
+  if (state.selection.kind === "frame") {
+    renderInspectorFrame(body, state.selection.id);
+  } else {
+    renderInspectorDevice(body, state.selection.id);
+  }
+}
+
+function renderInspectorFrame(body, id) {
+  const f = state.frames.find((x) => x.id === id);
+  if (!f) { body.innerHTML = ""; return; }
+  const deviceCount = state.devices.filter((d) => d.frame_id === f.id).length;
+  body.innerHTML = `
+    <p class="section-title">Frame</p>
+    <label class="field">
+      <span>Name</span>
+      <input class="inline-input" id="frm-name" value="" />
+    </label>
+    <dl>
+      <dt>x</dt><dd id="frm-x"></dd>
+      <dt>y</dt><dd id="frm-y"></dd>
+      <dt>w</dt><dd id="frm-w"></dd>
+      <dt>h</dt><dd id="frm-h"></dd>
+      <dt>devices</dt><dd id="frm-count"></dd>
+    </dl>
+    <div class="inspector-actions">
+      <button type="button" class="btn btn-danger btn-tiny" id="frm-delete">Delete frame</button>
+    </div>
+  `;
+  body.querySelector("#frm-name").value = f.name;
+  body.querySelector("#frm-x").textContent = f.x.toFixed(0);
+  body.querySelector("#frm-y").textContent = f.y.toFixed(0);
+  body.querySelector("#frm-w").textContent = f.width.toFixed(0);
+  body.querySelector("#frm-h").textContent = f.height.toFixed(0);
+  body.querySelector("#frm-count").textContent = String(deviceCount);
+
+  bindDebouncedRename(body.querySelector("#frm-name"), async (name) => {
+    if (!state.active) return;
+    const updated = await patchFrame(state.active.id, f.id, { name });
+    Object.assign(f, updated);
+    renderCanvas();
+  });
+
+  body.querySelector("#frm-delete").addEventListener("click", () => {
+    if (!state.active) return;
+    if (!confirm(`Delete frame "${f.name}"? Its devices stay but lose their frame.`)) return;
+    deleteFrame(state.active.id, f.id).then(() => {
+      state.frames = state.frames.filter((x) => x.id !== f.id);
+      for (const d of state.devices) if (d.frame_id === f.id) d.frame_id = null;
+      state.selection = null;
+      render();
+    }).catch((e) => alert(`Delete failed: ${e.message}`));
+  });
+}
+
+function renderInspectorDevice(body, id) {
+  const d = state.devices.find((x) => x.id === id);
+  if (!d) { body.innerHTML = ""; return; }
+  const frame = d.frame_id ? state.frames.find((f) => f.id === d.frame_id) : null;
+  body.innerHTML = `
+    <p class="section-title">Device</p>
+    <label class="field">
+      <span>Name</span>
+      <input class="inline-input" id="dev-name" value="" />
+    </label>
+    <label class="field">
+      <span>Colour</span>
+      <input type="color" class="inline-input" id="dev-color" />
+    </label>
+    <dl>
+      <dt>x</dt><dd id="dev-x"></dd>
+      <dt>y</dt><dd id="dev-y"></dd>
+      <dt>w</dt><dd id="dev-w"></dd>
+      <dt>h</dt><dd id="dev-h"></dd>
+      <dt>frame</dt><dd id="dev-frame"></dd>
+    </dl>
+    <div class="inspector-actions">
+      <button type="button" class="btn btn-danger btn-tiny" id="dev-delete">Delete device</button>
+    </div>
+  `;
+  body.querySelector("#dev-name").value = d.name;
+  body.querySelector("#dev-color").value = d.color;
+  body.querySelector("#dev-x").textContent = d.x.toFixed(0);
+  body.querySelector("#dev-y").textContent = d.y.toFixed(0);
+  body.querySelector("#dev-w").textContent = d.width.toFixed(0);
+  body.querySelector("#dev-h").textContent = d.height.toFixed(0);
+  body.querySelector("#dev-frame").textContent = frame ? frame.name : "—";
+
+  bindDebouncedRename(body.querySelector("#dev-name"), async (name) => {
+    if (!state.active) return;
+    const updated = await patchDevice(state.active.id, d.id, { name });
+    Object.assign(d, updated);
+    renderCanvas();
+  });
+
+  // Colour changes need no debounce — the native colour picker only fires
+  // `change` on commit.
+  body.querySelector("#dev-color").addEventListener("change", async (e) => {
+    if (!state.active) return;
+    const color = /** @type {HTMLInputElement} */ (e.target).value;
+    try {
+      const updated = await patchDevice(state.active.id, d.id, { color });
+      Object.assign(d, updated);
+      renderCanvas();
+    } catch (err) {
+      alert(`Colour update failed: ${err.message}`);
+    }
+  });
+
+  body.querySelector("#dev-delete").addEventListener("click", () => {
+    if (!state.active) return;
+    if (!confirm(`Delete device "${d.name}"?`)) return;
+    deleteDevice(state.active.id, d.id).then(() => {
+      state.devices = state.devices.filter((x) => x.id !== d.id);
+      state.selection = null;
+      render();
+    }).catch((e) => alert(`Delete failed: ${e.message}`));
+  });
+}
+
+function bindDebouncedRename(input, persist) {
+  let timer = null;
+  input.addEventListener("input", () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      const v = input.value.trim();
+      if (v) persist(v).catch((e) => alert(`Save failed: ${e.message}`));
+    }, 400);
+  });
+  input.addEventListener("blur", () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+    const v = input.value.trim();
+    if (v && v !== input.dataset.last) {
+      persist(v).catch((e) => alert(`Save failed: ${e.message}`));
+      input.dataset.last = v;
+    }
+  });
 }
 
 function render() {
   renderProjectPicker();
   renderLegend();
+  renderCanvas();
   renderEmptyHint();
+  renderInspector();
 }
 
 // ---------- active project ---------- //
@@ -143,6 +393,9 @@ function render() {
 async function activateProject(id) {
   if (id == null) {
     state.active = null;
+    state.frames = [];
+    state.devices = [];
+    state.selection = null;
     setActiveInURL(null);
     render();
     return;
@@ -150,15 +403,17 @@ async function activateProject(id) {
   try {
     const snap = await getSnapshot(id);
     state.active = snap.project;
-    // The snapshot also returns the global cable types — refresh from
-    // the source of truth so a stale state.cableTypes can never linger.
+    state.frames = snap.frames || [];
+    state.devices = snap.devices || [];
     state.cableTypes = snap.cable_types || [];
+    state.selection = null;
     setActiveInURL(id);
     render();
   } catch (err) {
     if (err.status === 404) {
-      // The id in the URL points to a deleted project — clear it.
       state.active = null;
+      state.frames = [];
+      state.devices = [];
       setActiveInURL(null);
       render();
     } else {
@@ -167,7 +422,265 @@ async function activateProject(id) {
   }
 }
 
-// ---------- modals ---------- //
+// ---------- tools ---------- //
+
+function armTool(tool) {
+  if (state.tool === tool) tool = null; // toggle off
+  state.tool = tool;
+  const wrap = $(".canvas-wrap");
+  wrap.classList.toggle("tool-frame",  tool === "frame");
+  wrap.classList.toggle("tool-device", tool === "device");
+  for (const btn of document.querySelectorAll("[data-tool]")) {
+    btn.classList.toggle("armed", btn.getAttribute("data-tool") === tool);
+  }
+}
+
+function bindTools() {
+  for (const btn of document.querySelectorAll("[data-tool]")) {
+    btn.addEventListener("click", () => armTool(btn.getAttribute("data-tool")));
+  }
+
+  document.addEventListener("keydown", (e) => {
+    // Avoid stealing keys while user is typing into an input.
+    const tag = (e.target instanceof HTMLElement) ? e.target.tagName : "";
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+    if (e.key === "Escape") { armTool(null); cancelInlineNamer(); state.selection = null; render(); }
+    else if (e.key === "f" || e.key === "F") armTool("frame");
+    else if (e.key === "d" || e.key === "D") armTool("device");
+  });
+
+  // Canvas-level pointerdown handles tool activation + selection clearing.
+  $("#canvas").addEventListener("pointerdown", onCanvasPointerDown);
+}
+
+let rubberBand = /** @type {SVGRectElement|null} */ (null);
+let rubberStart = /** @type {{x:number,y:number}|null} */ (null);
+
+function onCanvasPointerDown(e) {
+  if (!state.active) return;
+
+  const p = svgPoint(e);
+
+  // Armed tool wins: a click anywhere on the canvas — including on top
+  // of an existing frame or device — fires the tool. The +Dev tool needs
+  // this so m can drop a device inside a frame; without it the frame's
+  // own pointerdown handler would steal the click and start a drag.
+  if (state.tool === "frame") {
+    startFrameRubberBand(e, p);
+    return;
+  }
+  if (state.tool === "device") {
+    placeDeviceAt(p);
+    return;
+  }
+
+  // No tool armed: clicks that started on a device/frame go to their
+  // own handlers (drag / select). Leave them alone.
+  if (e.target instanceof Element && e.target.closest("[data-device-id], [data-frame-id]")) return;
+
+  // Plain canvas click = clear selection.
+  if (state.selection) { state.selection = null; render(); }
+}
+
+function startFrameRubberBand(e, p0) {
+  if (!state.active) return;
+  rubberStart = p0;
+  rubberBand = svgEl("rect", {
+    x: p0.x, y: p0.y, width: 0, height: 0,
+    class: "rubber-band", rx: 6, ry: 6,
+  });
+  $("#canvas").append(rubberBand);
+  const svg = /** @type {SVGSVGElement} */ ($("#canvas"));
+  svg.setPointerCapture(e.pointerId);
+
+  const onMove = (ev) => {
+    if (!rubberBand || !rubberStart) return;
+    const p = svgPoint(ev);
+    const x = Math.min(rubberStart.x, p.x);
+    const y = Math.min(rubberStart.y, p.y);
+    rubberBand.setAttribute("x", String(x));
+    rubberBand.setAttribute("y", String(y));
+    rubberBand.setAttribute("width",  String(Math.abs(p.x - rubberStart.x)));
+    rubberBand.setAttribute("height", String(Math.abs(p.y - rubberStart.y)));
+  };
+  const onUp = async (ev) => {
+    svg.removeEventListener("pointermove", onMove);
+    svg.removeEventListener("pointerup",   onUp);
+    svg.releasePointerCapture(e.pointerId);
+    const rect = rubberBand;
+    const start = rubberStart;
+    rubberBand = null;
+    rubberStart = null;
+    if (!rect || !start) return;
+    const w = Number(rect.getAttribute("width"));
+    const h = Number(rect.getAttribute("height"));
+    const x = Number(rect.getAttribute("x"));
+    const y = Number(rect.getAttribute("y"));
+    rect.remove();
+    if (w < 80 || h < 60) { armTool(null); return; }
+    armTool(null);
+    const name = await promptInline("Frame name", x + w / 2, y + 16);
+    if (!name || !state.active) return;
+    try {
+      const f = await createFrame(state.active.id, { name, x, y, width: w, height: h });
+      state.frames.push(f);
+      state.selection = { kind: "frame", id: f.id };
+      render();
+    } catch (err) {
+      alert(`Create frame failed: ${err.message}`);
+    }
+  };
+  svg.addEventListener("pointermove", onMove);
+  svg.addEventListener("pointerup",   onUp);
+}
+
+async function placeDeviceAt(p) {
+  if (!state.active) return;
+  armTool(null);
+  const W = 100, H = 35;
+  const x = p.x - W / 2;
+  const y = p.y - H / 2;
+  const name = await promptInline("Device name", p.x, p.y);
+  if (!name || !state.active) return;
+  const frame = frameAt(p.x, p.y);
+  try {
+    const d = await createDevice(state.active.id, {
+      name, x, y, width: W, height: H,
+      frame_id: frame ? frame.id : undefined,
+    });
+    state.devices.push(d);
+    state.selection = { kind: "device", id: d.id };
+    render();
+  } catch (err) {
+    alert(`Create device failed: ${err.message}`);
+  }
+}
+
+// ---------- inline namer (foreignObject overlay) ---------- //
+
+let activeNamer = /** @type {SVGForeignObjectElement|null} */ (null);
+
+function cancelInlineNamer() {
+  if (activeNamer) { activeNamer.remove(); activeNamer = null; }
+}
+
+function promptInline(placeholder, cx, cy) {
+  cancelInlineNamer();
+  return new Promise((resolve) => {
+    const fo = document.createElementNS(SVG_NS, "foreignObject");
+    fo.setAttribute("x", String(cx - 110));
+    fo.setAttribute("y", String(cy - 14));
+    fo.setAttribute("width", "220");
+    fo.setAttribute("height", "28");
+    fo.innerHTML = `
+      <div class="inline-namer" xmlns="http://www.w3.org/1999/xhtml">
+        <input type="text" placeholder="${placeholder}" />
+      </div>
+    `;
+    $("#canvas").append(fo);
+    activeNamer = fo;
+    const input = fo.querySelector("input");
+    input.focus();
+    const done = (val) => {
+      if (activeNamer === fo) { fo.remove(); activeNamer = null; }
+      resolve(val);
+    };
+    input.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") done(input.value.trim());
+      else if (e.key === "Escape") done(null);
+    });
+    input.addEventListener("blur", () => done(input.value.trim() || null));
+  });
+}
+
+// ---------- drag ---------- //
+
+function startDrag(e, kind, id) {
+  if (!state.active) return;
+  if (state.tool) return; // a tool is armed; don't hijack
+  e.stopPropagation();
+  state.selection = { kind, id };
+
+  const svg = /** @type {SVGSVGElement} */ ($("#canvas"));
+  const start = svgPoint(e);
+  /** @type {Frame|Device|undefined} */
+  const obj = kind === "frame"
+    ? state.frames.find((f) => f.id === id)
+    : state.devices.find((d) => d.id === id);
+  if (!obj) return;
+  const startX = obj.x;
+  const startY = obj.y;
+
+  // For frame drags, remember the contained devices + their offsets so
+  // they follow the frame visually + persist on release.
+  let trackedDevices = /** @type {{d: Device, sx: number, sy: number}[]} */ ([]);
+  if (kind === "frame") {
+    for (const d of state.devices) {
+      if (d.frame_id === obj.id) {
+        trackedDevices.push({ d, sx: d.x, sy: d.y });
+      }
+    }
+  }
+
+  e.currentTarget.classList.add("dragging");
+  svg.setPointerCapture(e.pointerId);
+
+  let dragged = false;
+
+  const onMove = (ev) => {
+    const p = svgPoint(ev);
+    const dx = p.x - start.x;
+    const dy = p.y - start.y;
+    if (!dragged && (Math.abs(dx) + Math.abs(dy) > 1)) dragged = true;
+    obj.x = startX + dx;
+    obj.y = startY + dy;
+    if (kind === "frame") {
+      for (const t of trackedDevices) { t.d.x = t.sx + dx; t.d.y = t.sy + dy; }
+    }
+    renderCanvas();
+  };
+  const onUp = async (ev) => {
+    svg.removeEventListener("pointermove", onMove);
+    svg.removeEventListener("pointerup",   onUp);
+    svg.releasePointerCapture(e.pointerId);
+    e.currentTarget.classList.remove("dragging");
+
+    if (!dragged) { render(); return; } // click only — re-render to apply selection halo
+    if (!state.active) return;
+
+    try {
+      if (kind === "frame") {
+        const f = /** @type {Frame} */ (obj);
+        await patchFrame(state.active.id, f.id, { x: f.x, y: f.y });
+        // Persist contained devices too.
+        await Promise.all(
+          trackedDevices.map((t) =>
+            patchDevice(state.active.id, t.d.id, { x: t.d.x, y: t.d.y })),
+        );
+      } else {
+        const d = /** @type {Device} */ (obj);
+        // Recompute frame_id from drop point (centre of device).
+        const cx = d.x + d.width / 2;
+        const cy = d.y + d.height / 2;
+        const targetFrame = frameAt(cx, cy);
+        const newFrameID = targetFrame ? targetFrame.id : null;
+        const patchBody = { x: d.x, y: d.y };
+        if ((d.frame_id ?? null) !== newFrameID) {
+          patchBody.frame_id = newFrameID; // explicit null = clear
+          d.frame_id = newFrameID;
+        }
+        await patchDevice(state.active.id, d.id, patchBody);
+      }
+    } catch (err) {
+      alert(`Save failed: ${err.message}`);
+    }
+    render();
+  };
+  svg.addEventListener("pointermove", onMove);
+  svg.addEventListener("pointerup",   onUp);
+}
+
+// ---------- modals (project / cable type) ---------- //
 
 function bindCloseButtons(dialog) {
   dialog.querySelectorAll("[data-close]").forEach((btn) =>
@@ -226,7 +739,6 @@ function openCableTypeModal(existing) {
     form.elements.namedItem("color").value = "#1971c2";
   }
 
-  // Slot in a Delete button when editing an existing type.
   const actions = form.querySelector(".actions");
   actions.querySelector(".btn-delete-type")?.remove();
   if (existing) {
@@ -314,6 +826,8 @@ async function boot() {
     activateProject(v ? Number(v) : null);
   });
 
+  bindTools();
+
   try {
     [state.projects, state.cableTypes] = await Promise.all([
       listProjects(),

web/static/style.css

@@ -165,6 +165,128 @@ body {
 
 .muted { color: var(--text-muted); }
 
+/* ---------- canvas elements ---------- */
+
+.frame-rect {
+  fill: rgba(25, 113, 194, 0.04);
+  stroke: var(--accent);
+  stroke-width: 1.5;
+  stroke-dasharray: 6 4;
+}
+.frame-rect.selected,
+.frame-rect:hover { stroke-width: 2.5; }
+
+.frame-label {
+  fill: var(--accent);
+  font-size: 13px;
+  font-weight: 600;
+  pointer-events: none;
+}
+
+.device-rect {
+  fill: #fff;
+  stroke: var(--text);
+  stroke-width: 1.5;
+}
+.device-rect.selected { stroke-width: 3; }
+.device-rect:hover { filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.15)); }
+
+.device-label {
+  fill: var(--text);
+  font-size: 12px;
+  text-anchor: middle;
+  dominant-baseline: central;
+  pointer-events: none;
+  user-select: none;
+}
+
+.svg-draggable { cursor: grab; }
+.svg-draggable.dragging { cursor: grabbing; }
+
+/* Tool cursor while a tool is armed. The `* { ... !important }` descendant
+   rule is the load-bearing part: without it, the `.svg-draggable` rules
+   on individual frame/device rects win by element specificity and
+   override the SVG-root cursor — so hovering a frame with +Dev armed
+   shows `grab`, which lies about what a click will do. */
+.canvas-wrap.tool-frame  #canvas,
+.canvas-wrap.tool-frame  #canvas *,
+.canvas-wrap.tool-device #canvas,
+.canvas-wrap.tool-device #canvas * { cursor: crosshair !important; }
+
+.rubber-band {
+  fill: rgba(25, 113, 194, 0.08);
+  stroke: var(--accent);
+  stroke-width: 1;
+  stroke-dasharray: 4 4;
+  pointer-events: none;
+}
+
+/* tool buttons toggle armed-state */
+.btn[data-tool].armed {
+  background: var(--accent);
+  color: #fff;
+  border-color: var(--accent);
+}
+
+/* ---------- inspector ---------- */
+
+.inspector dl {
+  margin: 0;
+  display: grid;
+  grid-template-columns: 80px 1fr;
+  gap: 4px 8px;
+  font-size: 12px;
+}
+.inspector dt { color: var(--text-muted); }
+.inspector dd { margin: 0; }
+
+.inspector .inline-input {
+  font: inherit;
+  width: 100%;
+  padding: 4px 6px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: #fff;
+}
+.inspector .inline-input:focus {
+  outline: 2px solid var(--accent);
+  outline-offset: -1px;
+  border-color: var(--accent);
+}
+.inspector .section-title {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-muted);
+  margin: 12px 0 6px 0;
+}
+.inspector .inspector-actions {
+  display: flex;
+  gap: 6px;
+  margin-top: 12px;
+}
+
+/* foreignObject used to inline-name a freshly-placed frame/device */
+.inline-namer {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+}
+.inline-namer input {
+  font: inherit;
+  font-size: 12px;
+  padding: 2px 4px;
+  border: 2px solid var(--accent);
+  border-radius: var(--radius);
+  background: #fff;
+  width: calc(100% - 8px);
+  max-width: 200px;
+  text-align: center;
+}
+
 /* ---------- buttons ---------- */
 
 .btn {