feat: move car speeds to main-process channel (#660)

Author: tariknz

docs/ARCHITECTURE_RULES.md

@@ -66,12 +66,12 @@ Imports flow **downward** in this list. A layer may import from any layer below
 | Time delta display (0.1 s)                     | `useTelemetryValuesRounded` | 2dp       |
 | Reference-lap interpolation                    | `useTelemetryValuesRounded` | 4dp       |
 | Throttle / Brake / Clutch / SteeringWheelAngle | `useTelemetryValues`        | —         |
-| `CarSpeedsStore` inputs                        | `useTelemetryValues`        | —         |
+| `CarSpeedsProcessor` inputs                    | full precision              | —         |
 | `FuelLevel` / `SessionTime` thresholds         | `useTelemetryValues`        | —         |
 
 ### 2.3 No-round list (do not round, ever)
 
-`Throttle`, `Brake`, `Clutch`, `SteeringWheelAngle`, `FuelLevel`, `FuelLevelPct`, `SessionTime`, anything fed into `CarSpeedsStore`, anything fed into a fuel-projection threshold.
+`Throttle`, `Brake`, `Clutch`, `SteeringWheelAngle`, `FuelLevel`, `FuelLevelPct`, `SessionTime`, anything fed into `CarSpeedsProcessor`, anything fed into a fuel-projection threshold.
 
 **Enforcement:** `grep -rn "useTelemetryValues(['\"]CarIdx" src/frontend` should return only no-round-list entries.
 
@@ -154,9 +154,7 @@ Imports flow **downward** in this list. A layer may import from any layer below
      id: 'mywidget',
      component: MyWidget,
      settingsComponent: MyWidgetSettings,
-     defaultConfig: {
-       /* ... */
-     },
+     defaultConfig: {/* ... */},
      displayName: 'My Widget',
      alwaysEnabled: false,
      settingsVersion: 1,

docs/IMPLEMENTATION_PLAN.md

@@ -266,7 +266,7 @@ Today every renderer wakes 25 times/sec regardless of what's mounted. A weather
 ### Phase 4 — Main-process processors
 
 - [x] LapTimesProcessor
-- [ ] CarSpeedsProcessor
+- [x] CarSpeedsProcessor
 - [ ] RelativeGapProcessor
 - [ ] ReferenceLapProcessor
 - [ ] SectorTimingProcessor

src/app/bridge/iracingSdk/iracingSdkBridge.ts

@@ -11,6 +11,7 @@ import type { SessionLifecycle } from '../../sessionLifecycle';
 import type { ChannelBus } from '../channelBridge';
 import { FuelProjectionRuntime } from '../../processors/fuelProjectionRuntime';
 import { LapTimesRuntime } from '../../processors/lapTimesRuntime';
+import { CarSpeedsRuntime } from '../../processors/carSpeedsRuntime';
 
 // Keys consumed by the renderer. Anything outside this set is dropped before
 // the telemetry object crosses the IPC boundary — reducing structured-clone
@@ -155,6 +156,10 @@ export async function publishIRacingSDKEvents(
     lifecycle && channelBus
       ? new LapTimesRuntime(channelBus, lifecycle, perfMetrics, isTapeReplay)
       : undefined;
+  const carSpeedsRuntime =
+    lifecycle && channelBus
+      ? new CarSpeedsRuntime(channelBus, lifecycle, perfMetrics, isTapeReplay)
+      : undefined;
 
   let shouldStop = false;
   let lastRunningState: boolean | undefined = undefined;
@@ -253,6 +258,7 @@ export async function publishIRacingSDKEvents(
           perfMetrics.markEnd('lifecycleTelemetry');
           fuelProjectionRuntime?.onFrame(telemetry);
           lapTimesRuntime?.onFrame(telemetry);
+          carSpeedsRuntime?.onFrame(telemetry);
           if (
             perfTelemetryDeliveryEnabled &&
             overlayManager.hasLegacyStreamSubscribers('telemetry')
@@ -282,6 +288,7 @@ export async function publishIRacingSDKEvents(
             latestSession = session;
             lifecycle?._onSession(session);
             fuelProjectionRuntime?.onSession(session);
+            carSpeedsRuntime?.onSession(session);
             overlayManager.publishMessage('sessionData', session);
             sessionCallbacks.forEach((callback) => callback(session));
             perfMetrics.markEnd('sessionPublish');
@@ -340,6 +347,7 @@ export async function publishIRacingSDKEvents(
       runningStateCallbacks.clear();
       fuelProjectionRuntime?.dispose();
       lapTimesRuntime?.dispose();
+      carSpeedsRuntime?.dispose();
       perfMetrics.stopReporting();
     },
   };

src/app/bridge/iracingSdk/mock-data/mockSdkBridge.spec.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IrSdkBridge, Session, Telemetry } from '@irdashies/types';
+import { ChannelBus } from '../../channelBridge';
+
+const callbacks = vi.hoisted(() => ({
+  telemetry: undefined as ((value: Telemetry) => void) | undefined,
+  session: undefined as ((value: Session) => void) | undefined,
+}));
+const stop = vi.hoisted(() => vi.fn());
+
+vi.mock('./generateMockData', () => ({
+  generateMockData: (): IrSdkBridge => ({
+    onTelemetry(callback) {
+      callbacks.telemetry = callback;
+      return () => undefined;
+    },
+    onSessionData(callback) {
+      callbacks.session = callback;
+      return () => undefined;
+    },
+    onRunningState() {
+      return () => undefined;
+    },
+    stop,
+  }),
+}));
+
+vi.mock('../../../perfMetrics', () => ({
+  TelemetryPerfMetrics: class {
+    startReporting = vi.fn();
+    stopReporting = vi.fn();
+    markStart = vi.fn();
+    markEnd = vi.fn();
+    tick = vi.fn();
+  },
+}));
+
+import { publishIRacingSDKEvents } from './mockSdkBridge';
+
+const telemetry = (pct: number, time: number) =>
+  ({
+    CarIdxLapDistPct: { value: [pct] },
+    SessionTime: { value: [time] },
+    SessionNum: { value: [1] },
+  }) as unknown as Telemetry;
+
+describe('mockSdkBridge car-speed channel', () => {
+  beforeEach(() => {
+    callbacks.telemetry = undefined;
+    callbacks.session = undefined;
+    stop.mockReset();
+  });
+
+  it('feeds mock session and telemetry through the car-speed runtime', async () => {
+    const bus = new ChannelBus();
+    const publish = vi.spyOn(bus, 'publish');
+    const target = {
+      id: 1,
+      isDestroyed: () => false,
+      isVisible: () => true,
+      send: vi.fn(),
+    };
+    bus.subscribe(target, 'car-speeds.snapshot');
+    const overlayManager = { publishMessage: vi.fn() };
+    const bridge = await publishIRacingSDKEvents(
+      overlayManager as never,
+      undefined,
+      bus
+    );
+
+    callbacks.session?.({
+      WeekendInfo: { TrackLength: '1 km' },
+    } as Session);
+    callbacks.telemetry?.(telemetry(0.1, 1));
+    callbacks.telemetry?.(telemetry(0.11, 1.1));
+
+    expect(publish).toHaveBeenCalledWith(
+      'car-speeds.snapshot',
+      expect.objectContaining({ carSpeeds: [360] })
+    );
+    bridge.stop();
+    expect(publish).toHaveBeenLastCalledWith(
+      'car-speeds.snapshot',
+      expect.objectContaining({ carSpeeds: [] })
+    );
+  });
+});

src/app/bridge/iracingSdk/mock-data/mockSdkBridge.ts

@@ -1,19 +1,31 @@
 import { generateMockData } from './generateMockData';
 import { OverlayManager } from '../../../overlayManager';
 import { TelemetryPerfMetrics } from '../../../perfMetrics';
+import type { SessionLifecycle } from '../../../sessionLifecycle';
+import type { ChannelBus } from '../../channelBridge';
+import { CarSpeedsRuntime } from '../../../processors/carSpeedsRuntime';
 
-export async function publishIRacingSDKEvents(overlayManager: OverlayManager) {
+export async function publishIRacingSDKEvents(
+  overlayManager: OverlayManager,
+  lifecycle?: SessionLifecycle,
+  channelBus?: ChannelBus
+) {
   const perfMetrics = new TelemetryPerfMetrics();
   perfMetrics.startReporting();
 
   const bridge = generateMockData();
+  const carSpeedsRuntime = channelBus
+    ? new CarSpeedsRuntime(channelBus, lifecycle, perfMetrics)
+    : undefined;
 
   bridge.onSessionData((session) => {
+    carSpeedsRuntime?.onSession(session);
     overlayManager.publishMessage('sessionData', session);
   });
 
   bridge.onTelemetry((telemetry) => {
     perfMetrics.markStart('processTelemetry');
+    carSpeedsRuntime?.onFrame(telemetry);
     perfMetrics.markStart('broadcast');
     overlayManager.publishMessage('telemetry', telemetry);
     perfMetrics.markEnd('broadcast');
@@ -29,6 +41,7 @@ export async function publishIRacingSDKEvents(overlayManager: OverlayManager) {
   return {
     ...bridge,
     stop: () => {
+      carSpeedsRuntime?.dispose();
       perfMetrics.stopReporting();
       originalStop();
     },

src/app/processors/CarSpeedsProcessor.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import type { Session, Telemetry } from '@irdashies/types';
+import { CarSpeedsProcessor } from './CarSpeedsProcessor';
+
+const session = (trackLength = '1 km') =>
+  ({ WeekendInfo: { TrackLength: trackLength } }) as Session;
+
+const frame = (lapDistPct: number[], sessionTime: number, sessionNum = 1) =>
+  ({
+    CarIdxLapDistPct: { value: lapDistPct },
+    SessionTime: { value: [sessionTime] },
+    SessionNum: { value: [sessionNum] },
+  }) as unknown as Telemetry;
+
+describe('CarSpeedsProcessor', () => {
+  it('derives smoothed km/h speeds at 10 Hz', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.init(session());
+    processor.onFrame(frame([0.1], 1));
+    processor.onFrame(frame([0.11], 1.05));
+    expect(processor.snapshot().carSpeeds).toEqual([0]);
+    processor.onFrame(frame([0.11], 1.1));
+    expect(processor.snapshot().carSpeeds[0]).toBe(360);
+    processor.onFrame(frame([0.125], 1.2));
+    expect(processor.snapshot().carSpeeds[0]).toBe(450);
+  });
+
+  it('handles start-finish wrap-around', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.init(session());
+    processor.onFrame(frame([0.99], 1));
+    processor.onFrame(frame([0.01], 1.2));
+    expect(processor.snapshot().carSpeeds[0]).toBe(360);
+  });
+
+  it('keeps speeds aligned when the driver array grows', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.init(session());
+    processor.onFrame(frame([0.1], 1));
+    processor.onFrame(frame([0.11], 1.1));
+    processor.onFrame(frame([0.12, 0.5], 1.2));
+    expect(processor.snapshot().carSpeeds).toEqual([360, 0]);
+  });
+
+  it('resets on an in-frame session change', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.init(session());
+    processor.onFrame(frame([0.1], 1));
+    processor.onFrame(frame([0.11], 1.1));
+    processor.onFrame(frame([0.2], 2, 2));
+    expect(processor.snapshot()).toMatchObject({
+      carSpeeds: [0],
+      sessionNum: 2,
+    });
+  });
+
+  it('clears on disconnect and suppresses replay scrubbing', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.init(session());
+    processor.onFrame(frame([0.1], 1));
+    processor.onLifecycle({ type: 'disconnect' });
+    processor.onFrame(frame([0.2], 2));
+    expect(processor.snapshot().carSpeeds).toEqual([]);
+
+    processor.onLifecycle({ type: 'enter', replay: true });
+    processor.onFrame(frame([0.3], 3));
+    expect(processor.snapshot().carSpeeds).toEqual([]);
+  });
+
+  it('emits zero speeds until session track length is available', () => {
+    const processor = new CarSpeedsProcessor();
+    processor.onFrame(frame([0.1, 0.2], 1));
+    expect(processor.snapshot().carSpeeds).toEqual([0, 0]);
+  });
+});