feat: admin-defined focus range for recordings (#306)

* feat: add focus_start/focus_end columns (migration v9)

* feat: update all queries and scan for focus_start/focus_end columns

* feat: extend edit endpoint for focus range (set/clear)

* feat: accept focusStart/focusEnd in upload endpoint

* feat: add focusStart/focusEnd to Recording type and API client

* feat: add focus range icons and CSS styles

* feat: implement focus range UI (toolbar, timeline overlays, shortcuts)

Add FocusToolbar component for editing in/out points, timeline scrubber
overlays with drag handles, FOCUS/FULL toggle, and I/O/Esc keyboard
shortcuts. Admins can set, save, clear, and cancel focus ranges that
persist via the edit API.

* fix: match focus range UI to design concept

- Move Panel button from left to right in controls row
- Focus toolbar: space-between layout with label left, buttons right
- Gold-styled Set In / Set Out buttons (matching design)
- Add gold border-bottom on focus toolbar row
- Dynamic --pb-bottom-height when editing (fixes overflow)
- Return 400 on malformed focus values instead of silent ignore
- Consistent 1-frame min gap for handle drag and keyboard

* fix: focus range time color, handle style, keyboard hints

- Time range text color #887744 matching design
- Handles: 8px wide, extend beyond track, rounded outside edge,
  inner grip line, gold glow shadow
- Add kbd hints: Set In [I], Set Out [O], Cancel [Esc], Panel [E]

* feat: constrain playback to focus range in FOCUS mode

When FOCUS toggle is active (not FULL, not editing):
- Scrubber zooms into focus range (full width = inFrame..outFrame)
- Heatmap and kill markers only show events within range
- Playback pauses when reaching outFrame
- Seeking via scrubber is clamped to focus range
- Dim overlays hidden (entire scrubber IS the focus range)

Switch to FULL mode to see/seek the entire recording.

* fix: smooth transition on all elements using --pb-bottom-height

Add transition: bottom 0.15s ease to MapControls, SidePanel,
FollowIndicator, and leaflet controls so they animate together
with the bottom bar when focus toolbar toggles.

* refactor: extract gold accent color to --accent-gold CSS variable

Replace all hardcoded #D4A843 and rgba(212,168,67,...) in focus
range styles with var(--accent-gold) and color-mix() derivations.

* docs: add --accent-focus to customization reference

* fix: address PR review feedback (error handling, SQL DRY)

- Check json.Unmarshal errors for missionName/tag/date fields
- Check I/O errors in test helper (gw.Write, gw.Close, writer.Close)
- Check repo.db.Close() error in test cleanup
- Extract duplicated SQL column list to operationColumns constant
- Log errors in saveFocus/clearFocus catch blocks

* test: add coverage for focus range feature

- FocusToolbar: 11 tests (rendering, callbacks, styling, kbd hints)
- TimelineScrubber constrained mode: 5 tests (progress mapping,
  dim overlay suppression, kill marker filtering)
- Go handler: table-driven test for invalid field types (missionName,
  tag, date, focusStart, focusEnd)

* test: cover remaining focus range gaps across all files

- shortcuts.ts: 5 tests for focus editing keys (i, o, Escape)
- BottomBar.tsx: 8 tests for FocusToolbar visibility, Focus button,
  FOCUS toggle, admin gating
- TimelineScrubber.tsx: 9 tests for focus overlays, accent line,
  edit mode handles/labels/border, heatmap dimming
- RecordingPlayback.tsx: 2 tests for focus range initialization
  from metadata and admin Focus button rendering

* fix: address 3 bugs found during focus range testing

Bug 1: Deduplicate setFocusIn/setFocusOut/cancelFocus — shortcuts
registered in onMount used inline lambdas duplicating the named
functions. Now defined once above onMount and referenced by name.

Bug 2: Remove fragile focusRange()! null assertions — replaced with
defensive null checks in the clamping effect and startFocusEdit.

Bug 3: Reject inverted focus ranges server-side — both EditOperation
and StoreOperation now return 400 when focusStart >= focusEnd.
Includes regression test (TestEditOperation_InvertedFocusRange).

* test: add coverage for focus handle dragging, kill nav, and edit flow

- TimelineScrubber: 5 tests for handle drag (pointerDown/Move/Up on
  in/out handles, draft change callbacks, drag state reset)
- BottomBar: 2 tests for prev-kill and next-kill button navigation
- RecordingPlayback: 3 integration tests for focus edit flow
  (open+cancel, save with API call, clear with null values)

Total: 1403 tests passing

* test: close remaining coverage gaps for focus range feature

Go:
- TestStoreOperation_InvertedFocusRange: validates upload endpoint
  rejects focusStart >= focusEnd

UI (RecordingPlayback):
- toggleBlacklist un-blacklist path (DELETE API call)
- saveFocus API error handling (console.error, edit mode stays open)
- clearFocus API error handling (console.error logged)

Total: 1406 tests passing

* test: cover showFullTimeline toggle and FOCUS/FULL switch

- BottomBar: 2 tests for showFullTimeline=true (FULL text, null
  focusRange passed to scrubber)
- RecordingPlayback: FOCUS toggle integration test (click switches
  to FULL text)

Total: 1409 tests passing

* fix: clamp navigation to focus range, reject partial focus in API, extract constrainToFocus prop

- Clamp frame to focus bounds on any seek (not just during playback)
- Reject partial focusStart/focusEnd in both upload and edit endpoints
- Extract constrainToFocus as BottomBar prop to eliminate DRY violation
- Add tests reproducing all three bugs before fixing

* fix: use undefined instead of null for optional entity fields in tests

* test: cover setFocusIn, setFocusOut, and pause-at-outFrame paths

Author: fank

docs/customization.md

@@ -42,6 +42,7 @@ Return ALL of these keys with appropriate values:
 --accent-success          Success/positive state color
 --accent-success-dark     Darker success variant
 --accent-warning          Warning/caution color
+--accent-focus            Focus range accent (handles, toolbar, toggle)
 --text-primary            Brightest text (headings, body)
 --text-secondary          Slightly dimmer text
 --text-muted              Muted labels, placeholders
@@ -70,6 +71,7 @@ This is the built-in blue theme. Your output should differ from this:
   "--accent-success": "#2DD4A0",
   "--accent-success-dark": "#1a9a74",
   "--accent-warning": "#FFB84A",
+  "--accent-focus": "#D4A843",
   "--text-primary": "#e5ebf1",
   "--text-secondary": "#cfd9e4",
   "--text-muted": "#96a7b8",
@@ -183,7 +185,8 @@ You only need to override the variables you want to change — everything else k
       "--bg-surface-hover": "#3a4a3a",
       "--bg-interactive": "rgba(255, 255, 255, 0.04)",
       "--bg-interactive-hover": "rgba(255, 255, 255, 0.08)",
-      "--bg-modal-header": "rgba(107, 142, 35, 0.9)"
+      "--bg-modal-header": "rgba(107, 142, 35, 0.9)",
+      "--accent-focus": "#B8962E"
     }
   }
 }
@@ -217,7 +220,8 @@ You only need to override the variables you want to change — everything else k
       "--bg-surface-hover": "#2A2A2F",
       "--bg-interactive": "rgba(212, 106, 46, 0.06)",
       "--bg-interactive-hover": "rgba(212, 106, 46, 0.12)",
-      "--bg-modal-header": "rgba(180, 80, 30, 0.85)"
+      "--bg-modal-header": "rgba(180, 80, 30, 0.85)",
+      "--accent-focus": "#C44040"
     }
   }
 }
@@ -265,6 +269,7 @@ Every field can also be set via environment variables with the `OCAP_` prefix. E
 | `--accent-warning` | `#FFB84A` | Warning indicators |
 | `--accent-danger` | `#FF4A4A` | Error states, delete actions |
 | `--accent-danger-dark` | `#CC3333` | Hover states for danger elements |
+| `--accent-focus` | `#D4A843` | Focus range UI (handles, toolbar, toggle) |
 
 ### CSS Variables — Text Colors
 

internal/server/handler.go

@@ -347,6 +347,29 @@ func (h *Handler) StoreOperation(c echo.Context) error {
 		return err
 	}
 
+	if fs := c.FormValue("focusStart"); fs != "" {
+		v, err := strconv.ParseInt(fs, 10, 64)
+		if err != nil {
+			return echo.ErrBadRequest
+		}
+		op.FocusStart = &v
+	}
+	if fe := c.FormValue("focusEnd"); fe != "" {
+		v, err := strconv.ParseInt(fe, 10, 64)
+		if err != nil {
+			return echo.ErrBadRequest
+		}
+		op.FocusEnd = &v
+	}
+
+	// Validate focus range: both must be present or both absent, and start < end
+	if (op.FocusStart == nil) != (op.FocusEnd == nil) {
+		return echo.ErrBadRequest
+	}
+	if op.FocusStart != nil && op.FocusEnd != nil && *op.FocusStart >= *op.FocusEnd {
+		return echo.ErrBadRequest
+	}
+
 	if err = h.repoOperation.Store(ctx, &op); err != nil {
 		return err
 	}

internal/server/handler_admin.go

@@ -1,6 +1,8 @@
 package server
 
 import (
+	"encoding/json"
+	"fmt"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -13,6 +15,69 @@ type editOperationRequest struct {
 	MissionName string `json:"missionName"`
 	Tag         string `json:"tag"`
 	Date        string `json:"date"`
+
+	// Focus range fields use json.RawMessage to distinguish
+	// "field absent" (don't change) from "field is null" (clear value).
+	// Populated manually from raw JSON; not decoded by struct tags.
+	FocusStart json.RawMessage `json:"-"`
+	FocusEnd   json.RawMessage `json:"-"`
+
+	hasFocusStart bool
+	hasFocusEnd   bool
+}
+
+// parseFocusField parses a nullable int64 from a json.RawMessage that is known to be present.
+// Returns nil for JSON null, or the parsed int64 value.
+func parseFocusField(raw json.RawMessage) (*int64, bool) {
+	if string(raw) == "null" {
+		return nil, true // explicitly null — clear the value
+	}
+	var v int64
+	if err := json.Unmarshal(raw, &v); err != nil {
+		return nil, false
+	}
+	return &v, true
+}
+
+// decodeEditRequest decodes the JSON body into an editOperationRequest,
+// tracking whether focusStart/focusEnd keys were present.
+func decodeEditRequest(c echo.Context) (editOperationRequest, error) {
+	var req editOperationRequest
+
+	// Decode into a raw map to detect key presence
+	var rawMap map[string]json.RawMessage
+	if err := json.NewDecoder(c.Request().Body).Decode(&rawMap); err != nil {
+		return req, err
+	}
+
+	// Decode standard string fields from the raw map
+	if v, ok := rawMap["missionName"]; ok {
+		if err := json.Unmarshal(v, &req.MissionName); err != nil {
+			return req, fmt.Errorf("invalid missionName: %w", err)
+		}
+	}
+	if v, ok := rawMap["tag"]; ok {
+		if err := json.Unmarshal(v, &req.Tag); err != nil {
+			return req, fmt.Errorf("invalid tag: %w", err)
+		}
+	}
+	if v, ok := rawMap["date"]; ok {
+		if err := json.Unmarshal(v, &req.Date); err != nil {
+			return req, fmt.Errorf("invalid date: %w", err)
+		}
+	}
+
+	// Track focus field presence (key exists in JSON, even if value is null)
+	if v, ok := rawMap["focusStart"]; ok {
+		req.FocusStart = v
+		req.hasFocusStart = true
+	}
+	if v, ok := rawMap["focusEnd"]; ok {
+		req.FocusEnd = v
+		req.hasFocusEnd = true
+	}
+
+	return req, nil
 }
 
 // EditOperation updates the editable metadata of an operation.
@@ -22,8 +87,8 @@ func (h *Handler) EditOperation(c echo.Context) error {
 		return echo.ErrBadRequest
 	}
 
-	var req editOperationRequest
-	if err := c.Bind(&req); err != nil {
+	req, err := decodeEditRequest(c)
+	if err != nil {
 		return echo.ErrBadRequest
 	}
 
@@ -43,13 +108,41 @@ func (h *Handler) EditOperation(c echo.Context) error {
 		date = current.Date
 	}
 
-	if err := h.repoOperation.UpdateOperation(c.Request().Context(), id, name, tag, date); err != nil {
+	// Focus range: only update if the field was present in the JSON body
+	focusStart := current.FocusStart
+	focusEnd := current.FocusEnd
+	if req.hasFocusStart {
+		val, ok := parseFocusField(req.FocusStart)
+		if !ok {
+			return echo.ErrBadRequest
+		}
+		focusStart = val
+	}
+	if req.hasFocusEnd {
+		val, ok := parseFocusField(req.FocusEnd)
+		if !ok {
+			return echo.ErrBadRequest
+		}
+		focusEnd = val
+	}
+
+	// Validate focus range: both must be present or both absent, and start < end
+	if (focusStart == nil) != (focusEnd == nil) {
+		return echo.ErrBadRequest
+	}
+	if focusStart != nil && focusEnd != nil && *focusStart >= *focusEnd {
+		return echo.ErrBadRequest
+	}
+
+	if err := h.repoOperation.UpdateOperation(c.Request().Context(), id, name, tag, date, focusStart, focusEnd); err != nil {
 		return err
 	}
 
 	current.MissionName = name
 	current.Tag = tag
 	current.Date = date
+	current.FocusStart = focusStart
+	current.FocusEnd = focusEnd
 
 	return c.JSON(http.StatusOK, current)
 }

internal/server/handler_admin_test.go

@@ -635,6 +635,190 @@ func TestDeleteOperation_DBDeleteError(t *testing.T) {
 	assert.Equal(t, http.StatusNoContent, rec.Code)
 }
 
+func TestEditOperation_FocusRange(t *testing.T) {
+	hdlr, op := setupAdminTest(t)
+	token, err := hdlr.jwt.Create("")
+	require.NoError(t, err)
+
+	e := echo.New()
+	body := `{"focusStart":50,"focusEnd":420}`
+	req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+	c.SetParamNames("id")
+	c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+	err = hdlr.EditOperation(c)
+	require.NoError(t, err)
+	assert.Equal(t, http.StatusOK, rec.Code)
+
+	updated, err := hdlr.repoOperation.GetByID(t.Context(), fmt.Sprintf("%d", op.ID))
+	require.NoError(t, err)
+	require.NotNil(t, updated.FocusStart)
+	require.NotNil(t, updated.FocusEnd)
+	assert.Equal(t, int64(50), *updated.FocusStart)
+	assert.Equal(t, int64(420), *updated.FocusEnd)
+
+	var result Operation
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &result))
+	require.NotNil(t, result.FocusStart)
+	assert.Equal(t, int64(50), *result.FocusStart)
+}
+
+func TestEditOperation_ClearFocusRange(t *testing.T) {
+	hdlr, op := setupAdminTest(t)
+	token, err := hdlr.jwt.Create("")
+	require.NoError(t, err)
+	ctx := t.Context()
+
+	// First set a focus range directly in DB
+	start, end := int64(10), int64(100)
+	_, err = hdlr.repoOperation.db.ExecContext(ctx,
+		`UPDATE operations SET focus_start = ?, focus_end = ? WHERE id = ?`,
+		start, end, op.ID)
+	require.NoError(t, err)
+
+	// Clear via API with explicit nulls
+	e := echo.New()
+	body := `{"focusStart":null,"focusEnd":null}`
+	req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+	c.SetParamNames("id")
+	c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+	err = hdlr.EditOperation(c)
+	require.NoError(t, err)
+	assert.Equal(t, http.StatusOK, rec.Code)
+
+	updated, err := hdlr.repoOperation.GetByID(ctx, fmt.Sprintf("%d", op.ID))
+	require.NoError(t, err)
+	assert.Nil(t, updated.FocusStart)
+	assert.Nil(t, updated.FocusEnd)
+}
+
+func TestEditOperation_PreservesFocusRange(t *testing.T) {
+	hdlr, op := setupAdminTest(t)
+	token, err := hdlr.jwt.Create("")
+	require.NoError(t, err)
+	ctx := t.Context()
+
+	// Set focus range directly
+	start, end := int64(10), int64(100)
+	_, err = hdlr.repoOperation.db.ExecContext(ctx,
+		`UPDATE operations SET focus_start = ?, focus_end = ? WHERE id = ?`,
+		start, end, op.ID)
+	require.NoError(t, err)
+
+	// Edit only missionName — focus range should be preserved
+	e := echo.New()
+	body := `{"missionName":"Renamed"}`
+	req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+	c.SetParamNames("id")
+	c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+	err = hdlr.EditOperation(c)
+	require.NoError(t, err)
+
+	updated, err := hdlr.repoOperation.GetByID(ctx, fmt.Sprintf("%d", op.ID))
+	require.NoError(t, err)
+	assert.Equal(t, "Renamed", updated.MissionName)
+	require.NotNil(t, updated.FocusStart)
+	assert.Equal(t, int64(10), *updated.FocusStart)
+	assert.Equal(t, int64(100), *updated.FocusEnd)
+}
+
+func TestEditOperation_InvertedFocusRange(t *testing.T) {
+	hdlr, op := setupAdminTest(t)
+	token, err := hdlr.jwt.Create("")
+	require.NoError(t, err)
+
+	e := echo.New()
+	// focusStart > focusEnd — this is an invalid range
+	body := `{"focusStart":420,"focusEnd":50}`
+	req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+token)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+	c.SetParamNames("id")
+	c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+	err = hdlr.EditOperation(c)
+	assert.Error(t, err, "inverted focus range should be rejected")
+}
+
+func TestEditOperation_PartialFocusRange(t *testing.T) {
+	hdlr, op := setupAdminTest(t)
+	token, err := hdlr.jwt.Create("")
+	require.NoError(t, err)
+
+	tests := []struct {
+		name string
+		body string
+	}{
+		{"focusStart without focusEnd", `{"focusStart":50}`},
+		{"focusEnd without focusStart", `{"focusEnd":100}`},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			e := echo.New()
+			req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(tc.body))
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("Authorization", "Bearer "+token)
+			rec := httptest.NewRecorder()
+			c := e.NewContext(req, rec)
+			c.SetParamNames("id")
+			c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+			err := hdlr.EditOperation(c)
+			assert.Error(t, err, "partial focus range should be rejected: %s", tc.name)
+		})
+	}
+}
+
+func TestEditOperation_InvalidFieldTypes(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+	}{
+		{"invalid missionName type", `{"missionName": 123}`},
+		{"invalid tag type", `{"tag": []}`},
+		{"invalid date type", `{"date": {"nested": true}}`},
+		{"invalid focusStart type", `{"focusStart": "not-a-number"}`},
+		{"invalid focusEnd type", `{"focusEnd": ["array"]}`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			hdlr, op := setupAdminTest(t)
+			token, err := hdlr.jwt.Create("")
+			require.NoError(t, err)
+
+			e := echo.New()
+			req := httptest.NewRequest(http.MethodPatch, "/", strings.NewReader(tt.body))
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("Authorization", "Bearer "+token)
+			rec := httptest.NewRecorder()
+			c := e.NewContext(req, rec)
+			c.SetParamNames("id")
+			c.SetParamValues(fmt.Sprintf("%d", op.ID))
+
+			err = hdlr.EditOperation(c)
+			assert.Error(t, err, "expected error for %s", tt.name)
+		})
+	}
+}
+
 func TestDeleteOperation_ReadOnlyFileCleanup(t *testing.T) {
 	dir := t.TempDir()
 	dataDir := filepath.Join(dir, "data")