perf: condition legacy telemetry by widget (#656)

Author: tariknz

docs/PHASE_3_CHANNEL_BRIDGE_PLAN.md

@@ -218,6 +218,26 @@ Turn the completed Fuel migration into measurable renderer and IPC savings.
   - Renderer frames over 50 ms below 0.1%.
   - Steady-state app memory slope below 5 MB/min.
 
+#### Widget runtime metadata and rate guidance
+
+Runtime transport metadata is discovered from
+`src/frontend/components/*/widgetRuntimeDefinition.ts`. A migrated widget must
+explicitly set `legacyTelemetry: false` and list every typed channel it needs.
+Widgets without runtime metadata remain legacy consumers so incremental
+migrations fail safe.
+
+Choose the lowest named preset that preserves the widget's observable behavior:
+
+- `driverFocused` — 25 Hz for positional or rapidly changing driver data.
+- `gapTiming` — 5 Hz for projections, gaps, and sortable timing data.
+- `informational` — 1 Hz for weather and slowly changing labels.
+- `static` — event/snapshot delivery with no polling-rate request.
+
+Use `channelRates` on the widget runtime definition when one channel needs a
+different rate from the preset. Multiple consumers in one renderer are still
+coalesced at the highest requested rate. Full-rate input and precision-sensitive
+calculation paths must not be moved to a lower preset.
+
 ## 4. Validation Strategy
 
 ### Every PR

src/app/bridge/channelRendererBridge.ts

@@ -10,6 +10,10 @@ import {
   CHANNEL_SUBSCRIBE,
   CHANNEL_UNSUBSCRIBE,
 } from './channelBridge';
+import {
+  isRendererPerfMetricsEnabled,
+  recordChannelCallback,
+} from '../rendererPerfMetrics';
 
 interface LocalConsumer {
   callback: (payload: never) => void;
@@ -31,7 +35,13 @@ export const createChannelRendererBridge = (): ChannelBridge => {
       const subscription = subscriptions.get(channel);
       if (!subscription) return;
       for (const consumer of subscription.consumers) {
+        if (!isRendererPerfMetricsEnabled()) {
+          consumer.callback(payload as never);
+          continue;
+        }
+        const start = performance.now();
         consumer.callback(payload as never);
+        recordChannelCallback(performance.now() - start);
       }
     }
   );

src/app/bridge/defineBridge.spec.ts

@@ -0,0 +1,80 @@
+import { EventEmitter } from 'node:events';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const handlers = vi.hoisted(
+  () => new Map<string, (event: unknown, key: unknown) => void>()
+);
+const removeHandler = vi.hoisted(() => vi.fn());
+
+vi.mock('electron', () => ({
+  contextBridge: { exposeInMainWorld: vi.fn() },
+  ipcRenderer: { invoke: vi.fn() },
+  ipcMain: {
+    handle: (
+      channel: string,
+      handler: (event: unknown, key: unknown) => void
+    ) => handlers.set(channel, handler),
+    removeHandler,
+  },
+}));
+
+import { defineRendererSubscriptionBridge } from './defineBridge';
+
+class FakeSender extends EventEmitter {
+  constructor(readonly id: number) {
+    super();
+  }
+}
+
+describe('defineRendererSubscriptionBridge', () => {
+  beforeEach(() => {
+    handlers.clear();
+    removeHandler.mockClear();
+  });
+
+  const setup = () =>
+    defineRendererSubscriptionBridge<'telemetry' | 'sessionData'>({
+      name: 'legacy-test',
+      isValidKey: (value): value is 'telemetry' | 'sessionData' =>
+        value === 'telemetry' || value === 'sessionData',
+    });
+
+  it('validates keys and tracks subscriptions by sender identity', () => {
+    const bridge = setup();
+    const sender = new FakeSender(7);
+    const subscribe = handlers.get('legacy-test:subscribe');
+
+    expect(() => subscribe?.({ sender }, 'invalid')).toThrow(
+      'Invalid legacy-test subscription'
+    );
+    subscribe?.({ sender }, 'telemetry');
+
+    expect(bridge.registry.has(7, 'telemetry')).toBe(true);
+    expect(bridge.registry.hasAny('telemetry')).toBe(true);
+  });
+
+  it.each(['did-start-loading', 'destroyed'])(
+    'cleans renderer state on %s',
+    (eventName) => {
+      const bridge = setup();
+      const sender = new FakeSender(9);
+      handlers.get('legacy-test:subscribe')?.({ sender }, 'sessionData');
+
+      sender.emit(eventName);
+
+      expect(bridge.registry.hasAny('sessionData')).toBe(false);
+    }
+  );
+
+  it('unregisters handlers and clears state when disposed', () => {
+    const bridge = setup();
+    const sender = new FakeSender(11);
+    handlers.get('legacy-test:subscribe')?.({ sender }, 'telemetry');
+
+    bridge.dispose();
+
+    expect(removeHandler).toHaveBeenCalledWith('legacy-test:subscribe');
+    expect(removeHandler).toHaveBeenCalledWith('legacy-test:unsubscribe');
+    expect(bridge.registry.hasAny('telemetry')).toBe(false);
+  });
+});

src/app/bridge/defineBridge.ts

@@ -1,7 +1,106 @@
-import { contextBridge } from 'electron';
+import { contextBridge, ipcMain, ipcRenderer } from 'electron';
 
 /** Exposes a typed preload API through Electron's isolated world boundary. */
 export const defineBridge = <I>(name: string, implementation: I): I => {
   contextBridge.exposeInMainWorld(name, implementation);
   return implementation;
 };
+
+export class RendererSubscriptionRegistry<K extends string> {
+  private readonly subscriptions = new Map<number, Set<K>>();
+
+  subscribe(rendererId: number, key: K): void {
+    let keys = this.subscriptions.get(rendererId);
+    if (!keys) {
+      keys = new Set();
+      this.subscriptions.set(rendererId, keys);
+    }
+    keys.add(key);
+  }
+
+  unsubscribe(rendererId: number, key: K): void {
+    const keys = this.subscriptions.get(rendererId);
+    keys?.delete(key);
+    if (keys?.size === 0) this.subscriptions.delete(rendererId);
+  }
+
+  removeRenderer(rendererId: number): void {
+    this.subscriptions.delete(rendererId);
+  }
+
+  has(rendererId: number, key: K): boolean {
+    return this.subscriptions.get(rendererId)?.has(key) ?? false;
+  }
+
+  hasAny(key: K): boolean {
+    for (const keys of this.subscriptions.values()) {
+      if (keys.has(key)) return true;
+    }
+    return false;
+  }
+
+  clear(): void {
+    this.subscriptions.clear();
+  }
+}
+
+const subscriptionChannels = (name: string) => ({
+  subscribe: `${name}:subscribe`,
+  unsubscribe: `${name}:unsubscribe`,
+});
+
+export const createSubscriptionBridgeClient = <K extends string>(
+  name: string
+) => {
+  const channels = subscriptionChannels(name);
+  return {
+    subscribe: (key: K) => ipcRenderer.invoke(channels.subscribe, key),
+    unsubscribe: (key: K) => ipcRenderer.invoke(channels.unsubscribe, key),
+  };
+};
+
+export const defineRendererSubscriptionBridge = <K extends string>(options: {
+  name: string;
+  isValidKey: (value: unknown) => value is K;
+}) => {
+  const channels = subscriptionChannels(options.name);
+  const registry = new RendererSubscriptionRegistry<K>();
+  const rendererCleanup = new Map<number, () => void>();
+
+  ipcMain.handle(channels.subscribe, (event, key: unknown) => {
+    if (!options.isValidKey(key)) {
+      throw new Error(`Invalid ${options.name} subscription`);
+    }
+    const rendererId = event.sender.id;
+    if (!rendererCleanup.has(rendererId)) {
+      const cleanup = () => {
+        event.sender.removeListener('destroyed', cleanup);
+        event.sender.removeListener('did-start-loading', cleanup);
+        rendererCleanup.delete(rendererId);
+        registry.removeRenderer(rendererId);
+      };
+      rendererCleanup.set(rendererId, cleanup);
+      event.sender.once('destroyed', cleanup);
+      event.sender.once('did-start-loading', cleanup);
+    }
+    registry.subscribe(rendererId, key);
+  });
+
+  ipcMain.handle(channels.unsubscribe, (event, key: unknown) => {
+    if (!options.isValidKey(key)) {
+      throw new Error(`Invalid ${options.name} unsubscribe`);
+    }
+    registry.unsubscribe(event.sender.id, key);
+  });
+
+  return {
+    registry,
+    dispose: () => {
+      ipcMain.removeHandler(channels.subscribe);
+      ipcMain.removeHandler(channels.unsubscribe);
+      for (const cleanup of rendererCleanup.values()) cleanup();
+      rendererCleanup.clear();
+      registry.clear();
+    },
+  };
+};

src/app/bridge/iracingSdk/iracingSdkBridge.ts

@@ -247,7 +247,10 @@ export async function publishIRacingSDKEvents(
           lifecycle?._onTelemetry(telemetry);
           perfMetrics.markEnd('lifecycleTelemetry');
           fuelProjectionRuntime?.onFrame(telemetry);
-          if (perfTelemetryDeliveryEnabled) {
+          if (
+            perfTelemetryDeliveryEnabled &&
+            overlayManager.hasLegacyStreamSubscribers('telemetry')
+          ) {
             perfMetrics.markStart('telemetryProjection');
             const rendererTelemetry = telemetryForRenderer(telemetry);
             perfMetrics.markEnd('telemetryProjection');

src/app/bridge/legacyRendererSubscriptions.ts

@@ -0,0 +1,16 @@
+import { defineRendererSubscriptionBridge } from './defineBridge';
+
+export const LEGACY_STREAM_BRIDGE = 'legacy-stream';
+
+export type LegacyRendererStream = 'telemetry' | 'sessionData';
+
+export const isLegacyRendererStream = (
+  value: unknown
+): value is LegacyRendererStream =>
+  value === 'telemetry' || value === 'sessionData';
+
+export const setupLegacyRendererSubscriptions = () =>
+  defineRendererSubscriptionBridge<LegacyRendererStream>({
+    name: LEGACY_STREAM_BRIDGE,
+    isValidKey: isLegacyRendererStream,
+  });

src/app/bridge/rendererExposeBridge.ts

@@ -23,9 +23,31 @@ import {
   isRendererPerfMetricsEnabled,
   recordTelemetryCallback,
 } from '../rendererPerfMetrics';
+import {
+  LEGACY_STREAM_BRIDGE,
+  type LegacyRendererStream,
+} from './legacyRendererSubscriptions';
+import { createSubscriptionBridgeClient, defineBridge } from './defineBridge';
 
 export function exposeBridge() {
-  contextBridge.exposeInMainWorld('irsdkBridge', {
+  const legacySubscriptions =
+    createSubscriptionBridgeClient<LegacyRendererStream>(LEGACY_STREAM_BRIDGE);
+  const legacyListenerCounts = new Map<LegacyRendererStream, number>();
+  const addLegacyListener = (stream: LegacyRendererStream) => {
+    const count = legacyListenerCounts.get(stream) ?? 0;
+    legacyListenerCounts.set(stream, count + 1);
+    if (count === 0) void legacySubscriptions.subscribe(stream);
+  };
+  const removeLegacyListener = (stream: LegacyRendererStream) => {
+    const count = legacyListenerCounts.get(stream) ?? 0;
+    if (count <= 1) {
+      legacyListenerCounts.delete(stream);
+      void legacySubscriptions.unsubscribe(stream);
+      return;
+    }
+    legacyListenerCounts.set(stream, count - 1);
+  };
+  defineBridge<IrSdkBridge>('irsdkBridge', {
     onTelemetry: (callback: (value: Telemetry) => void) => {
       const handler = (_: Electron.IpcRendererEvent, value: Telemetry) => {
         if (!isRendererPerfMetricsEnabled()) {
@@ -36,15 +58,23 @@ export function exposeBridge() {
         callback(value);
         recordTelemetryCallback(performance.now() - start);
       };
+      addLegacyListener('telemetry');
       ipcRenderer.on('telemetry', handler);
-      return () => ipcRenderer.removeListener('telemetry', handler);
+      return () => {
+        ipcRenderer.removeListener('telemetry', handler);
+        removeLegacyListener('telemetry');
+      };
     },
     onSessionData: (callback: (value: Session) => void) => {
       const handler = (_: Electron.IpcRendererEvent, value: Session) => {
         callback(value);
       };
+      addLegacyListener('sessionData');
       ipcRenderer.on('sessionData', handler);
-      return () => ipcRenderer.removeListener('sessionData', handler);
+      return () => {
+        ipcRenderer.removeListener('sessionData', handler);
+        removeLegacyListener('sessionData');
+      };
     },
     onRunningState: (callback: (value: boolean) => void) => {
       const handler = (_: Electron.IpcRendererEvent, value: boolean) => {
@@ -54,11 +84,15 @@ export function exposeBridge() {
       return () => ipcRenderer.removeListener('runningState', handler);
     },
     stop: () => {
+      for (const stream of legacyListenerCounts.keys()) {
+        void legacySubscriptions.unsubscribe(stream);
+      }
+      legacyListenerCounts.clear();
       ipcRenderer.removeAllListeners('telemetry');
       ipcRenderer.removeAllListeners('sessionData');
       ipcRenderer.removeAllListeners('runningState');
     },
-  } as IrSdkBridge);
+  });
 
   contextBridge.exposeInMainWorld('dashboardBridge', {
     onEditModeToggled: (callback: (value: boolean) => void) => {