sarg3nt
diff --git a/‎CLAUDE.md‎
Lines changed: 35 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎gearbox/cmd/server/main.go‎
Lines changed: 21 additions & 13 deletions b/‎gearbox/cmd/server/main.go‎
Lines changed: 21 additions & 13 deletions
diff --git a/‎gearbox/internal/framework/database/database.go‎
Lines changed: 6 additions & 0 deletions b/‎gearbox/internal/framework/database/database.go‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎gearbox/internal/framework/database/metrics_layouts.go‎
Lines changed: 139 additions & 0 deletions b/‎gearbox/internal/framework/database/metrics_layouts.go‎
Lines changed: 139 additions & 0 deletions
@@ -175,6 +175,41 @@ await showAlertDialog({
 
 Existing reference usages: [user-pages/admin-user-detail.js](static/js/user-pages/admin-user-detail.js), [user-pages/profile-management.js](static/js/user-pages/profile-management.js), [haproxy_config/editor.js](static/js/haproxy_config/editor.js).
 
+**When editing any JS or templ file, grep for stray native popups before committing:**
+
+```bash
+rg -n '\b(window\.)?(alert|confirm|prompt)\(' gearbox/static/js gearbox/internal --type-add 'templ:*.templ' --type js --type templ
+```
+
+Treat any hit (outside `static/js/vendor/`) as a bug — replace with the dialog API above. The native primitives strip styling, dark mode, focus traps, and the Esc-handling chain we depend on.
+
+### Info tooltips — always use the shared `InfoTooltip` widget
+
+Any "what is this?" hover affordance — KPI labels, table column headers, settings rows with a non-obvious effect, etc. — must use the shared widget. The canonical look (filled info-circle "i" icon, dark hover bubble, no cursor change, no transition delay) is defined in two places that are kept in lock-step:
+
+- **Server-rendered (templ):** [`@components.InfoTooltip(text)`](gearbox/internal/framework/templates/components/info_tooltip.templ).
+- **Client-built (JS):** `window.createInfoTooltip(text)` / `window.appendInfoTooltipTo(parentEl, text)` from [info-tooltip.js](gearbox/static/js/common/info-tooltip.js), already wired into [base.templ](gearbox/internal/framework/templates/layouts/base.templ) so every page has them.
+
+```templ
+import "github.com/sarg3nt/gearbox/internal/framework/templates/components"
+
+<span class="font-medium">Error Rate</span>
+@components.InfoTooltip("Percentage of requests with 4xx or 5xx status in the selected window.")
+```
+
+```javascript
+// In a JS-built widget (e.g. a chart card or KPI band):
+const labelEl = card.querySelector('.kpi-label');
+window.appendInfoTooltipTo(labelEl, c.description);
+```
+
+**Rules of thumb:**
+
+- **Do not** roll your own `?`-button, `title=`-only tooltips, or `cursor: help` affordances — they look inconsistent with the HAProxy overview pattern, which is the visual reference for every other gear.
+- **Do not** put the rich tooltip text in a `title=` attribute on a card-body — users don't know to hover invisible regions. The widget is the visible cue.
+- If the text needs structure (bold lead-in + body paragraph, multiple paragraphs), drop the same wrapper markup inline rather than extending the component — see the "VPN Gateway Architecture" usage in [overview.templ](gearbox/internal/framework/templates/pages/overview.templ) for the pattern.
+- The widget is pure CSS — no JS event wiring needed and no cursor change. If you find yourself adding `onclick` or `cursor: help`, you've drifted from the standard.
+
 ### Toggle switches — never use a bare `<input type="checkbox">` in templates
 
 For every boolean input in a `.templ` file — feature opt-ins, settings, "enable this gear", "show all", per-row enable/disable — use the shared slider component in [internal/framework/ui/toggle.templ](gearbox/internal/framework/ui/toggle.templ):
 
@@ -15,19 +15,19 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	gearbox "github.com/sarg3nt/gearbox"
-	"github.com/sarg3nt/gearbox/internal/framework/collector"
-	"github.com/sarg3nt/gearbox/internal/framework/database"
 	"github.com/sarg3nt/gearbox/internal/framework/auth"
+	"github.com/sarg3nt/gearbox/internal/framework/collector"
 	"github.com/sarg3nt/gearbox/internal/framework/config"
+	"github.com/sarg3nt/gearbox/internal/framework/database"
 	"github.com/sarg3nt/gearbox/internal/framework/events"
 	"github.com/sarg3nt/gearbox/internal/framework/gear"
+	"github.com/sarg3nt/gearbox/internal/framework/handler"
+	gbmiddleware "github.com/sarg3nt/gearbox/internal/framework/middleware"
+	"github.com/sarg3nt/gearbox/internal/framework/models"
 	"github.com/sarg3nt/gearbox/internal/framework/services"
 	"github.com/sarg3nt/gearbox/internal/framework/services/alerts"
 	"github.com/sarg3nt/gearbox/internal/framework/services/crypto"
 	"github.com/sarg3nt/gearbox/internal/framework/services/email"
-	"github.com/sarg3nt/gearbox/internal/framework/handler"
-	gbmiddleware "github.com/sarg3nt/gearbox/internal/framework/middleware"
-	"github.com/sarg3nt/gearbox/internal/framework/models"
 
 	// Import gears - blank identifier triggers init() registration
 	_ "github.com/sarg3nt/gearbox/internal/gears/alerts"
@@ -383,13 +383,13 @@ func main() {
 	serverAdapter := services.NewServerAdapter(db, encryptor, servers, logger)
 
 	gearDeps := gear.Dependencies{
-		DB:             db.GetDB(), // Get the underlying *sql.DB
-		Logger:         logger,
-		EventHub:       eventsAdapter,
-		Auth:           authAdapter,
-		Servers:        serverAdapter,
-		HTTPClient:     http.DefaultClient,
-		Config:         make(map[string]any),
+		DB:         db.GetDB(), // Get the underlying *sql.DB
+		Logger:     logger,
+		EventHub:   eventsAdapter,
+		Auth:       authAdapter,
+		Servers:    serverAdapter,
+		HTTPClient: http.DefaultClient,
+		Config:     make(map[string]any),
 	}
 
 	// Create gear manager (no store for now - will add database-backed store later)
@@ -540,7 +540,7 @@ func main() {
 	r.Group(func(r chi.Router) {
 		r.Use(authManager.RequireAuth)
 		r.Use(authManager.RequirePasswordChange) // Enforce password change before any other action
-		r.Use(h.InjectIntegrationStatus) // Add integration status to context for sidebar rendering
+		r.Use(h.InjectIntegrationStatus)         // Add integration status to context for sidebar rendering
 		r.Use(middleware.Timeout(60 * time.Second))
 
 		// Logout
@@ -704,6 +704,14 @@ func main() {
 			r.Get("/{boxID}/metrics/source/{source}/summary", h.APIMetricsSourceSummaryHandler)
 			r.Get("/{boxID}/metrics/source/{source}/log-errors", h.APIMetricsSourceLogErrorsHandler)
 
+			// Per-user, per-box layout (issue #103). GET returns
+			// the user's saved GridStack positions for this box
+			// (or 204 = "use template defaults"); PATCH upserts;
+			// DELETE drops the saved row to reset to defaults.
+			r.Get("/{boxID}/metrics/layout", h.APIMetricsLayoutGetHandler)
+			r.Patch("/{boxID}/metrics/layout", h.APIMetricsLayoutPatchHandler)
+			r.Delete("/{boxID}/metrics/layout", h.APIMetricsLayoutDeleteHandler)
+
 			// Per-box capability manifest — exposes which agent gears probed
 			// available so the metrics gear (and future source-aware UI) can
 			// hide cards/KPIs that don't apply to this host.
 
@@ -102,6 +102,12 @@ func New(dbPath string, logger *slog.Logger) (*DB, error) {
 		return nil, fmt.Errorf("failed to initialize home schema: %w", err)
 	}
 
+	// Initialize metrics layouts (per-user, per-box GridStack
+	// positions for the metrics page — see issue #103).
+	if err := d.initMetricsLayoutsSchema(); err != nil {
+		return nil, fmt.Errorf("failed to initialize metrics layouts schema: %w", err)
+	}
+
 	// Run schema migrations AFTER all schemas are initialized
 	// (migrations may reference tables from any schema)
 	if err := d.runSchemaMigrations(); err != nil {
 
@@ -0,0 +1,139 @@
+// Package database — per-user, per-box layout persistence for the
+// Metrics gear's GridStack-driven page (issue #103).
+//
+// The Metrics page renders a fixed set of chart cards (HAProxy
+// stats, host metrics, plus capability-gated per-source cards).
+// Operators rearrange/resize those cards in edit mode; the saved
+// layout lives here. Storage shape: one JSON blob per (user, box)
+// holding GridStack's `save()` output verbatim — array of
+// `{id, x, y, w, h}` objects keyed by the stable tile DOM id
+// (card-cpu, card-memory, card-nginx, …). JSON beats per-tile rows
+// because the dashboard always reads/writes the whole layout at
+// once and there's no querying inside it; the JSON column keeps
+// the schema additive when we add tile shapes later.
+package database
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// MetricsLayout is one persisted layout — the GridStack `save()`
+// payload kept verbatim plus the (user, server) coordinates it
+// belongs to.
+//
+// Layout is stored as []byte rather than a typed struct because
+// GridStack's save format is the canonical form here: every field
+// it emits round-trips back through `load()` unchanged. Typing it
+// would mean keeping our Go shape in lockstep with GridStack's
+// minor-version changes — not worth the maintenance cost for a
+// JSON blob the dashboard never inspects.
+type MetricsLayout struct {
+	UserID    string    `json:"user_id"`
+	ServerID  string    `json:"server_id"`
+	Layout    []byte    `json:"layout"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// ErrNoMetricsLayout is returned by GetMetricsLayout when no row
+// exists for (userID, serverID). Callers translate this into "use
+// the default layout from the page template" rather than an HTTP
+// 500 — first-visit users hit this path every time.
+var ErrNoMetricsLayout = errors.New("no metrics_layouts row for the user/server pair")
+
+// initMetricsLayoutsSchema creates the per-user-per-box layout
+// table. Called from initSchema during database startup, alongside
+// the other gear schemas. No foreign keys to users(id) intentionally:
+// if a user is deleted we'd rather orphan their saved layouts than
+// take an FK cascade — the orphans are tiny (one JSON blob each) and
+// the simpler schema sidesteps a delete-cascade ordering question.
+//
+// (server_id is text because the dashboard's box / server addressing
+// is string-keyed — server_id matches the convention used by
+// stats_history, traffic_flows, etc.)
+func (d *DB) initMetricsLayoutsSchema() error {
+	schema := `
+	CREATE TABLE IF NOT EXISTS metrics_layouts (
+		user_id     TEXT NOT NULL,
+		server_id   TEXT NOT NULL,
+		layout_json TEXT NOT NULL,
+		updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+		PRIMARY KEY (user_id, server_id)
+	);
+
+	CREATE INDEX IF NOT EXISTS idx_metrics_layouts_user
+		ON metrics_layouts(user_id);
+	`
+	_, err := d.db.Exec(schema)
+	return err
+}
+
+// GetMetricsLayout returns the saved layout for one (user, box) pair.
+// Returns ErrNoMetricsLayout when nothing's saved yet — callers
+// (the handler) translate to "render the default layout from the
+// page template" so first visits work without an extra round trip.
+func (d *DB) GetMetricsLayout(userID string, serverID string) (*MetricsLayout, error) {
+	d.mu.RLock()
+	defer d.mu.RUnlock()
+
+	row := d.db.QueryRow(`
+		SELECT user_id, server_id, layout_json, updated_at
+		FROM metrics_layouts
+		WHERE user_id = ? AND server_id = ?`,
+		userID, serverID,
+	)
+	var (
+		out    MetricsLayout
+		layout string
+	)
+	if err := row.Scan(&out.UserID, &out.ServerID, &layout, &out.UpdatedAt); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, ErrNoMetricsLayout
+		}
+		return nil, fmt.Errorf("scan metrics_layouts: %w", err)
+	}
+	out.Layout = []byte(layout)
+	return &out, nil
+}
+
+// SaveMetricsLayout upserts the layout for one (user, box) pair.
+// `layoutJSON` must already be a valid JSON string — the handler
+// is responsible for shape-checking before calling. We don't
+// re-validate here because the canonical schema lives in
+// GridStack's JS, and our agnostic-blob approach intentionally
+// avoids tracking that schema in Go.
+//
+// updated_at is bumped server-side so the dashboard can show
+// "last edited X minutes ago" without trusting client clocks.
+func (d *DB) SaveMetricsLayout(userID string, serverID string, layoutJSON []byte) error {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	_, err := d.db.Exec(`
+		INSERT INTO metrics_layouts (user_id, server_id, layout_json, updated_at)
+		VALUES (?, ?, ?, ?)
+		ON CONFLICT(user_id, server_id) DO UPDATE SET
+			layout_json = excluded.layout_json,
+			updated_at  = excluded.updated_at`,
+		userID, serverID, string(layoutJSON), time.Now().UTC(),
+	)
+	return err
+}
+
+// DeleteMetricsLayout removes the saved layout for one (user, box)
+// pair, effectively reverting the user's view to the template
+// default on next render. Used by the "reset to default" button in
+// the edit-mode toolbar.
+func (d *DB) DeleteMetricsLayout(userID string, serverID string) error {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	_, err := d.db.Exec(`
+		DELETE FROM metrics_layouts
+		WHERE user_id = ? AND server_id = ?`,
+		userID, serverID,
+	)
+	return err
+}