feat(#103): metrics page — per-user, per-box draggable layout (GridStack)

[sarg3nt]

Summary

Closes #103. Metrics page chart grid becomes drag + resize editable, with the layout persisted per (user, box). Reuses the Home gear's GridStack vendor bundle — no new dependency. Default layout matches the row order proposed on the issue:

┌──────────────────┬──────────────────┐
│  CPU Load        │  Memory          │
├──────────────────┼──────────────────┤
│  Network         │  Response Time   │
├──────────────────┼──────────────────┤
│  Server Health   │  Error Rates     │
├──────────────────┴──────────────────┤
│  Sessions & Requests (full-width)   │
├──────────────────┬──────────────────┤
│  nginx*          │  Apache*         │
├──────────────────┼──────────────────┤
│  Caddy*          │  Traefik*        │
└──────────────────┴──────────────────┘

(* per-source tiles only appear when the agent's capability table reports the gear Available)

Files

New

Path	Purpose
internal/framework/database/metrics_layouts.go	metrics_layouts table (PK (user_id, server_id)) + GetMetricsLayout / SaveMetricsLayout / DeleteMetricsLayout + ErrNoMetricsLayout sentinel.
internal/framework/handler/api_metrics_layout.go	GET / PATCH / DELETE handlers. JSON body capped at 16 KiB and shape-validated as [{id,x,y,w,h}].
static/js/metrics-layout.js	GridStack init, edit-mode toggle, layout fetch/save (debounced PATCH), capability-driven reflow via a CustomEvent emitted by the existing applyCapabilities().

Modified

Path	Change
internal/framework/database/database.go	Wires initMetricsLayoutsSchema() into New() right after the Home schema.
cmd/server/main.go	Registers the three new layout routes alongside the existing /metrics/... endpoints.
internal/framework/templates/pages/metrics.templ	Wrapper panel removed; each chart card now sits inside a .grid-stack-item with default gs-* attrs. Cards reordered to the layout above. Edit toggle + Reset button added to the controls bar. GridStack vendor CSS + JS + metrics-layout.js script tags added. applyCapabilities() dispatches metrics:capabilities-applied so the JS layer can reflow without coupling.

How the per-user → per-box persistence works

• First visit → GET /api/{boxID}/metrics/layout returns 204 → JS keeps the template's default positions.
• Drag/resize in edit mode → no save during the drag; debounced 400 ms after the last change OR on edit-mode exit, a single PATCH writes the whole layout JSON.
• Switch box → fresh GET for the new (user, server) pair; layouts isolate per user AND per box.
• Reset → DELETE the row, page reloads, defaults return.

Layout stored as a JSON blob rather than per-tile rows because the access pattern is always "fetch / write the whole layout"; there's no querying inside it. The blob is GridStack's save() output verbatim — the storage layer never inspects it, which keeps it agnostic to GridStack version changes.

Capability-driven reflow

PR #102 added per-source chart cards that hide via a .hidden class when the agent reports the gear as Unavailable. GridStack doesn't know about those classes — without coordination, an unavailable source would leave a permanent gap in the grid.

The fix is event-driven:

1. applyCapabilities() in metrics.templ's inline script toggles .hidden per card as today, then dispatches a metrics:capabilities-applied CustomEvent on window.
2. metrics-layout.js listens for that event and per-card decides whether to call gs.removeWidget(item, false) (keep DOM, drop the grid slot — surrounding tiles compact up) or gs.makeWidget(item) (re-add to the grid).
3. The change-event handler in metrics-layout.js is suppressed during this reflow so the capability-driven moves don't accidentally PATCH the user's saved layout.

Decoupling via CustomEvent means neither file needs to know about the other's globals.

Test plan

• go test ./... clean on gearbox.
• go vet ./... clean.
• gofmt -l clean on every file added or modified.
• templ generate clean — generated metrics_templ.go regenerates with the new structure (gitignored as expected).
• Manual smoke: load metrics page on a box, confirm default layout matches the design.
• Manual smoke: edit mode → drag CPU below Memory → exit edit mode → reload → CPU stays below Memory.
• Manual smoke: switch user (logout / re-login as a different operator) → layout doesn't follow them.
• Manual smoke: switch box → fresh layout for that box.
• Manual smoke: HAProxy-not-available host (mjolnir) — HAProxy tiles disappear, host tiles compact up to fill the grid with no gaps.
• Manual smoke: Reset Layout → confirm dialog → page reloads with template defaults.

Backwards compatibility

Purely additive.

• New table — no impact on existing schemas.
• New endpoints under fresh /metrics/layout paths — no changes to existing /metrics/... endpoints.
• Older sessions without GridStack support (e.g. browser with JS disabled) render the page in its default order via the template attributes; drag/resize is silently disabled but no functional regression.

Out of scope

• Layout import/export.
• Sharing layouts between users.
• Mobile-specific layouts (GridStack auto-compacts on narrow viewports — same behaviour Home relies on).
• Default-layout customisation (every user starts with the same template positions; edit mode + persistence covers the personalisation case).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a GridStack-driven, per-user/per-box persisted layout system for the Metrics page in the Gearbox dashboard, enabling operators to drag/resize chart tiles and save/reset their personal layout per server.

Changes:

• Introduces a new metrics_layouts DB table plus read/write/delete helpers for storing GridStack save() JSON per (user_id, server_id).
• Adds new JSON API endpoints under /api/{boxID}/metrics/layout (GET/PATCH/DELETE) to load, persist, and reset layouts.
• Updates the Metrics page template + frontend JS to render charts as GridStack widgets, toggle edit mode, and reflow tiles when capability-gated cards appear/disappear.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
gearbox/static/js/metrics-layout.js	Initializes GridStack on the Metrics chart grid, handles edit mode, capability-driven widget removal/re-add, and debounced persistence/reset calls.
gearbox/internal/framework/templates/pages/metrics.templ	Converts the chart grid to GridStack markup, adds edit/reset controls, wires capability reflow event, and includes GridStack vendor assets + new JS.
gearbox/internal/framework/handler/api_metrics_layout.go	Implements GET/PATCH/DELETE handlers for per-user per-box metrics layout persistence.
gearbox/internal/framework/database/metrics_layouts.go	Adds schema init and DB methods for saving/loading/deleting the metrics layout JSON blob.
gearbox/internal/framework/database/database.go	Wires initMetricsLayoutsSchema() into DB initialization.
gearbox/cmd/server/main.go	Registers the new metrics layout API routes.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

gearbox/static/js/common/shortcut-help.js:251

• The global Esc handler relies on other dialogs calling preventDefault() (it bails out on e.defaultPrevented). The built-in Confirm/Prompt/Alert dialogs’ Esc handler in base.templ closes those overlays but does not call e.preventDefault(), so a single Esc can close the dialog and then fall through here to history.back() in the same keypress. Update the dialog Esc handler(s) to call e.preventDefault() when they close something (or add an equivalent guard here) so Esc never triggers back-navigation immediately after dismissing a dialog.

        document.addEventListener('keydown', function (e) {
            if (e.key !== 'Escape') return;
            if (e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
            // A per-modal handler already consumed it (cmdk, help,
            // icon-picker, etc. all call preventDefault).
            if (e.defaultPrevented) return;
            if (closeTopmostDialog()) { e.preventDefault(); return; }
            if (exitGearEditMode())   { e.preventDefault(); return; }
            const el = document.activeElement;
            if (isBlurrableTarget(el)) {
                el.blur();
                e.preventDefault();
                return;
            }
            // Same-origin back nav only — `document.referrer` is empty
            // on direct loads, so checking history.length > 1 is the
            // best proxy we have in-browser.
            if (window.history.length > 1) {
                e.preventDefault();
                window.history.back();
            }