Implement VFO store with hardware bandwidth constraint validation (#292)

* Initial plan

* Implement VFO store with type definitions, validation, and comprehensive tests

Co-authored-by: alexthemitchell <5687158+alexthemitchell@users.noreply.github.com>

* Fix VFO overlap detection logic to treat edge-adjacent VFOs as non-overlapping

Co-authored-by: alexthemitchell <5687158+alexthemitchell@users.noreply.github.com>

* Fix formatting in VFO implementation memory file

Co-authored-by: alexthemitchell <5687158+alexthemitchell@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: alexthemitchell <5687158+alexthemitchell@users.noreply.github.com>
Co-authored-by: Alex Mitchell <alex+github@alexmitchelltech.com>

Author: Copilot

.serena/memories/VFO_STORE_IMPLEMENTATION_2025-11-21.md

@@ -0,0 +1,82 @@
+# VFO Store Implementation - Phase 2 Complete
+
+## Overview
+
+Implemented Phase 2 of Multi-VFO architecture: Core data structures and Zustand store with constraint enforcement.
+
+## File Structure
+
+### Type Definitions
+
+- **Location**: `src/types/vfo.ts`
+- **Exports**: VfoConfig, VfoState, VfoStatus enum, VfoMetrics, MIN_VFO_SPACING_HZ
+
+### Store Slice
+
+- **Location**: `src/store/slices/vfoSlice.ts`
+- **Pattern**: Follows existing Zustand slice pattern (frequencySlice, markerSlice, etc.)
+- **Exports**: VfoSlice interface, vfoSlice StateCreator, VfoValidationError, validateVfoConfig, detectVfoOverlap
+
+### Integration
+
+- **Location**: `src/store/index.ts`
+- **Additions**: VfoSlice added to RootState, useVfo convenience hook created
+
+### Tests
+
+- **Location**: `src/store/slices/__tests__/vfoSlice.test.ts`
+- **Coverage**: 36 tests covering all operations and constraints
+
+## Key Implementation Details
+
+### Validation Pattern
+
+All VFO mutations (add, update) require a VfoValidationContext:
+
+```typescript
+{
+  hardwareCenterHz: number,
+  sampleRateHz: number,
+}
+```
+
+Store automatically adds existingVfos and maxVfos to build full context.
+
+### Constraint Enforcement
+
+1. **Max VFO count**: Throws VfoValidationError when maxVfos exceeded
+2. **Hardware bandwidth**: Validates center frequency and bandwidth edges are within capture range
+3. **Spacing warnings**: Console.warn for VFOs closer than MIN_VFO_SPACING_HZ (per spec: "allow overlap for now but warn")
+
+### Resource Cleanup Pattern
+
+removeVfo logs cleanup intentions but doesn't call dispose() - actual cleanup will be handled by MultiVfoProcessor (Phase 3).
+
+### State Management
+
+- VFO state is ephemeral (runtime-only, not persisted)
+- Default values: audioGain=1.0, priority=5, status=IDLE
+- Metrics initialized with rssi=-100, samplesProcessed=0
+
+## Testing Approach
+
+Test categories:
+
+1. Initialization and basic CRUD
+2. Constraint validation (hardware bandwidth, max count, negative frequencies)
+3. Spacing warnings (console.warn spy)
+4. Edge cases (non-existent VFOs, boundary conditions)
+5. Helper functions (getAllVfos, getActiveVfos, detectVfoOverlap)
+
+## Quality Gates Passed
+
+- ✅ All 3112 unit tests pass (including 36 new VFO tests)
+- ✅ ESLint passes (import ordering, prettier formatting)
+- ✅ TypeScript type checking passes
+- ✅ Webpack build succeeds
+
+## Next Phases
+
+Phase 3: DSP Pipeline (MultiVfoProcessor, channelization, audio mixing)
+Phase 4: UI Components (useMultiVfo hook, VfoManager, VfoCard)
+Phase 5: Integration with useReception hook

src/store/index.ts

@@ -49,6 +49,7 @@ import {
   signalLevelSlice,
   type SignalLevelSlice,
 } from "./slices/signalLevelSlice";
+import { vfoSlice, type VfoSlice } from "./slices/vfoSlice";
 import type { SignalLevel } from "../lib/measurement/types";
 import type { ISDRDevice } from "../models/SDRDevice";
 
@@ -61,7 +62,8 @@ export type RootState = SettingsSlice &
   DeviceSlice &
   DiagnosticsSlice &
   MarkerSlice &
-  SignalLevelSlice;
+  SignalLevelSlice &
+  VfoSlice;
 
 /**
  * Create the root store with all slices
@@ -79,6 +81,7 @@ export const useStore = create<RootState>()(
       ...diagnosticsSlice(...args),
       ...markerSlice(...args),
       ...signalLevelSlice(...args),
+      ...vfoSlice(...args),
     }),
     { name: "rad.io-store" },
   ),
@@ -317,6 +320,40 @@ export const useSignalLevel = (): {
   return { signalLevel, setSignalLevel, clearSignalLevel };
 };
 
+// VFO slice selectors
+export const useVfo = (): Pick<
+  RootState,
+  | "vfos"
+  | "maxVfos"
+  | "addVfo"
+  | "removeVfo"
+  | "updateVfo"
+  | "updateVfoState"
+  | "setVfoAudio"
+  | "clearVfos"
+  | "getVfo"
+  | "getAllVfos"
+  | "getActiveVfos"
+  | "setMaxVfos"
+> => {
+  return useStore(
+    useShallow((state: RootState) => ({
+      vfos: state.vfos,
+      maxVfos: state.maxVfos,
+      addVfo: state.addVfo,
+      removeVfo: state.removeVfo,
+      updateVfo: state.updateVfo,
+      updateVfoState: state.updateVfoState,
+      setVfoAudio: state.setVfoAudio,
+      clearVfos: state.clearVfos,
+      getVfo: state.getVfo,
+      getAllVfos: state.getAllVfos,
+      getActiveVfos: state.getActiveVfos,
+      setMaxVfos: state.setMaxVfos,
+    })),
+  );
+};
+
 // Export types
 export type { SettingsState, VizMode } from "./slices/settingsSlice";
 export type { Marker } from "./slices/markerSlice";
@@ -332,3 +369,6 @@ export type {
   DecoderMetrics,
   SignalQualityMetrics,
 } from "./slices/diagnosticsSlice";
+export type { VfoValidationContext } from "./slices/vfoSlice";
+export type { VfoConfig, VfoState, VfoMetrics } from "../types/vfo";
+export { VfoStatus, MIN_VFO_SPACING_HZ } from "../types/vfo";