refactor(runtime): derive the group timer on the server

The group timer was derived in the client, which meant every view that wanted it
had to depend on the rundown query. That coupling was already awkward for the PiP
timer, whose separate react root needed its own query client, and it would have
spread to every remaining view.

Moving the derivation to the server removes the coupling. The value is still the
running event timer offset by the content scheduled around it, so the group keeps
behaving as if it were a single event containing all its children.

Because the group timer is the event timer offset by a constant, it changes exactly
when the event timer does and can share its broadcast throttling.

- add RuntimeStore.groupTimer, null unless the running group opted in
- split the group around the loaded event when the group is loaded, so the per tick
  cost is an addition rather than a walk of the rundown
- derive on the getState() projection so it cannot drift from the timer it is built on
- reduce the client to a plain selector, dropping the PiP query client workaround

Also fixes elapsed time, which was calculated from the group duration and so clamped
to zero for as long as time added to an event kept the group in credit. It is now
derived symmetrically with the remaining time, and the two always add up to the total.

Timer and PiP shared eight identical branches for choosing between the two timers.
These now go through a single resolver. A group has no warning or danger thresholds,
so it only reports as running or overtime, and feeding that phase through the existing
modifiers makes the suppression of warning and danger a consequence of what a group is
rather than something each view has to remember.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Kniqs443KUNCRABwVJwT7K

apps/server/src/app.ts

@@ -207,6 +207,7 @@ export const startServer = async (): Promise<{ message: string; serverPort: numb
   eventStore.init({
     clock: state.clock,
     timer: state.timer,
+    groupTimer: state.groupTimer,
     message: { ...runtimeStorePlaceholder.message },
     offset: state.offset,
     rundown: state.rundown,

apps/server/src/services/__tests__/timerUtils.test.ts

@@ -1,4 +1,16 @@
-import { EndAction, Playback, TimeOfDay, TimeStrategy, TimerPhase, TimerType } from 'ontime-types';
+import {
+  EndAction,
+  MaybeNumber,
+  OntimeEvent,
+  OntimeGroup,
+  Playback,
+  Rundown,
+  SupportedEntry,
+  TimeOfDay,
+  TimeStrategy,
+  TimerPhase,
+  TimerType,
+} from 'ontime-types';
 import { MILLIS_PER_HOUR, MILLIS_PER_MINUTE, MILLIS_PER_SECOND, dayInMs, millisToString } from 'ontime-utils';
 
 import type { RuntimeState } from '../../stores/runtimeState.js';
@@ -7,6 +19,8 @@ import {
   getCurrent,
   getElapsed,
   getExpectedFinish,
+  getGroupTimer,
+  getGroupTiming,
   getRuntimeOffset,
   getTimerPhase,
   hasCrossedMidnight,
@@ -1452,3 +1466,138 @@ describe('findDay()', () => {
     expect(findDayOffset(22 * MILLIS_PER_HOUR, 23 * MILLIS_PER_HOUR)).toBe(0); //   -> 1
   });
 });
+
+describe('getGroupTiming()', () => {
+  const makeEvent = (id: string, duration: number, patch: object = {}) =>
+    ({ id, type: SupportedEntry.Event, duration, gap: 0, skip: false, parent: 'group', ...patch }) as OntimeEvent;
+
+  const makeGroup = (entries: string[]) => ({ id: 'group', type: SupportedEntry.Group, entries }) as OntimeGroup;
+
+  const makeEntries = (...entries: OntimeEvent[]) =>
+    Object.fromEntries(entries.map((entry) => [entry.id, entry])) as Rundown['entries'];
+
+  it('splits the scheduled content around the loaded event', () => {
+    const group = makeGroup(['1', '2', '3']);
+    const entries = makeEntries(makeEvent('1', 10), makeEvent('2', 20), makeEvent('3', 30));
+
+    expect(getGroupTiming(group, entries, '1')).toStrictEqual({ before: 0, after: 50 });
+    expect(getGroupTiming(group, entries, '2')).toStrictEqual({ before: 10, after: 30 });
+    expect(getGroupTiming(group, entries, '3')).toStrictEqual({ before: 30, after: 0 });
+  });
+
+  it('accounts for the gaps between events', () => {
+    const group = makeGroup(['1', '2', '3']);
+    const entries = makeEntries(makeEvent('1', 10), makeEvent('2', 20, { gap: 5 }), makeEvent('3', 30, { gap: 7 }));
+
+    expect(getGroupTiming(group, entries, '1')).toStrictEqual({ before: 0, after: 20 + 5 + 30 + 7 });
+    // the gap before the loaded event has already passed, so it counts as time spent
+    expect(getGroupTiming(group, entries, '2')).toStrictEqual({ before: 10 + 5, after: 30 + 7 });
+  });
+
+  it('splits into values which add up to the group duration', () => {
+    const group = makeGroup(['1', '2', '3']);
+    const entries = makeEntries(makeEvent('1', 10), makeEvent('2', 20, { gap: 5 }), makeEvent('3', 30));
+    const groupDuration = 10 + 20 + 5 + 30;
+
+    for (const id of ['1', '2', '3']) {
+      const timing = getGroupTiming(group, entries, id)!;
+      expect(timing.before + entries[id].duration + timing.after).toBe(groupDuration);
+    }
+  });
+
+  it('skips entries which are not playable events', () => {
+    const group = makeGroup(['1', '2', '3', '4']);
+    const entries = {
+      ...makeEntries(makeEvent('1', 10), makeEvent('2', 20, { skip: true }), makeEvent('4', 40)),
+      '3': { id: '3', type: SupportedEntry.Milestone, parent: 'group' },
+    } as Rundown['entries'];
+
+    expect(getGroupTiming(group, entries, '1')).toStrictEqual({ before: 0, after: 40 });
+  });
+
+  it('returns null when the loaded event is not part of the group', () => {
+    const group = makeGroup(['1', '2']);
+    const entries = makeEntries(makeEvent('1', 10), makeEvent('2', 20));
+
+    expect(getGroupTiming(group, entries, 'elsewhere')).toBeNull();
+  });
+});
+
+describe('getGroupTimer()', () => {
+  const makeState = (patch: {
+    useGroupTimer?: boolean;
+    duration?: number;
+    timing?: { before: number; after: number } | null;
+    current?: MaybeNumber;
+    elapsed?: MaybeNumber;
+    addedTime?: number;
+  }) =>
+    ({
+      groupNow: { duration: patch.duration ?? 100, useGroupTimer: patch.useGroupTimer ?? true },
+      _groupTiming: patch.timing === undefined ? { before: 0, after: 0 } : patch.timing,
+      timer: {
+        current: patch.current ?? null,
+        elapsed: patch.elapsed ?? null,
+        addedTime: patch.addedTime ?? 0,
+      },
+    }) as RuntimeState;
+
+  it('is null when there is no group running', () => {
+    expect(getGroupTimer({ groupNow: null, _groupTiming: null } as RuntimeState)).toBeNull();
+  });
+
+  it('is null when the group has not opted in', () => {
+    expect(getGroupTimer(makeState({ useGroupTimer: false, current: 10 }))).toBeNull();
+  });
+
+  it('is null when the loaded event is not part of the group', () => {
+    expect(getGroupTimer(makeState({ timing: null, current: 10 }))).toBeNull();
+  });
+
+  it('offsets the event timer by the content scheduled around it', () => {
+    const state = makeState({ duration: 100, timing: { before: 30, after: 50 }, current: 20, elapsed: 0 });
+
+    expect(getGroupTimer(state)).toStrictEqual({ current: 70, elapsed: 30, duration: 100 });
+  });
+
+  it('keeps elapsed and current adding up to the total', () => {
+    const state = makeState({ duration: 100, timing: { before: 30, after: 50 }, current: 12, elapsed: 8 });
+    const groupTimer = getGroupTimer(state)!;
+
+    expect(groupTimer.elapsed + groupTimer.current).toBe(groupTimer.duration);
+  });
+
+  it('grows the total with the time added to the running event', () => {
+    const state = makeState({
+      duration: 100,
+      timing: { before: 0, after: 0 },
+      current: 160,
+      elapsed: 0,
+      addedTime: 60,
+    });
+    const groupTimer = getGroupTimer(state)!;
+
+    expect(groupTimer.duration).toBe(160);
+    // elapsed keeps counting up rather than clamping at zero once time is added
+    expect(groupTimer.elapsed).toBe(0);
+    expect(groupTimer.elapsed + groupTimer.current).toBe(groupTimer.duration);
+  });
+
+  it('reports elapsed time while the group is in credit from added time', () => {
+    const state = makeState({
+      duration: 100,
+      timing: { before: 0, after: 0 },
+      current: 150,
+      elapsed: 10,
+      addedTime: 60,
+    });
+
+    expect(getGroupTimer(state)).toStrictEqual({ current: 150, elapsed: 10, duration: 160 });
+  });
+
+  it('goes negative when the group runs into overtime', () => {
+    const state = makeState({ duration: 100, timing: { before: 90, after: 0 }, current: -15, elapsed: 25 });
+
+    expect(getGroupTimer(state)?.current).toBe(-15);
+  });
+});

apps/server/src/services/runtime-service/runtime.service.ts

@@ -709,6 +709,18 @@ function broadcastResult(_target: any, _propertyKey: string, descriptor: Propert
       RuntimeService.previousState.timer = { ...state.timer };
     }
 
+    /**
+     * the group timer is the event timer offset by a constant, so it changes exactly when
+     * the event timer does and can share its throttling.
+     * entry changes are also considered since loading an event can move us between groups
+     */
+    if (updateTimer || entryChanged) {
+      if (!deepEqual(RuntimeService.previousState.groupTimer, state.groupTimer)) {
+        batch.add('groupTimer', state.groupTimer);
+        RuntimeService.previousState.groupTimer = state.groupTimer ? { ...state.groupTimer } : null;
+      }
+    }
+
     /**
      * clock has changed by a second or more.
      * or the timer updated so we ensure that the timer and clock ticks are in sync

apps/server/src/services/timerUtils.ts

@@ -1,7 +1,18 @@
-import { Day, MaybeNumber, TimeOfDay, TimerPhase } from 'ontime-types';
+import {
+  Day,
+  EntryId,
+  GroupTimerState,
+  MaybeNumber,
+  OntimeGroup,
+  Rundown,
+  TimeOfDay,
+  TimerPhase,
+  isOntimeEvent,
+  isPlayableEvent,
+} from 'ontime-types';
 import { MILLIS_PER_HOUR, checkIsNow, dayInMs, isPlaybackActive } from 'ontime-utils';
 
-import type { RuntimeState } from '../stores/runtimeState.js';
+import type { GroupTiming, RuntimeState } from '../stores/runtimeState.js';
 
 /**
  * handle events that span over midnight
@@ -231,3 +242,76 @@ export function findDayOffset(plannedStart: number, clock: number): Day {
   if (distance < -12 * MILLIS_PER_HOUR) return 1 as Day;
   return 0 as Day;
 }
+
+/**
+ * Splits a group's scheduled content around the loaded event.
+ *
+ * The result is stable for as long as the same event is loaded, so it is calculated
+ * when the group is loaded rather than on every update.
+ * The aggregation mirrors the group duration calculated in the rundown
+ * (see rundown.dao.ts): non playable entries are skipped and the gap is
+ * accounted for in every entry other than the first.
+ */
+export function getGroupTiming(
+  group: OntimeGroup,
+  entries: Rundown['entries'],
+  currentEventId: EntryId,
+): GroupTiming | null {
+  const currentIndex = group.entries.indexOf(currentEventId);
+  if (currentIndex === -1) {
+    return null;
+  }
+
+  let before = 0;
+  let after = 0;
+
+  for (let i = 0; i < group.entries.length; i++) {
+    const entry = entries[group.entries[i]];
+    if (!isOntimeEvent(entry) || !isPlayableEvent(entry)) {
+      continue;
+    }
+
+    // the first entry of the group has no gap to account for,
+    // any other entry could be preceded by idle time
+    const gap = i > 0 ? entry.gap : 0;
+
+    if (i < currentIndex) {
+      before += gap + entry.duration;
+    } else if (i === currentIndex) {
+      // the loaded event contributes its own duration through the event timer,
+      // but the idle time before it has already passed
+      before += gap;
+    } else {
+      after += gap + entry.duration;
+    }
+  }
+
+  return { before, after };
+}
+
+/**
+ * Derives the shared group timer from the event timer.
+ *
+ * Keeping this relative to the event timer is what makes the group behave as if it were
+ * a single event containing all its children: pause, added time, overtime, roll and
+ * midnight rollovers are all inherited instead of being recalculated.
+ */
+export function getGroupTimer(state: RuntimeState): GroupTimerState | null {
+  const { groupNow, _groupTiming } = state;
+
+  if (groupNow === null || !groupNow.useGroupTimer || _groupTiming === null) {
+    return null;
+  }
+
+  const { current, elapsed, addedTime } = state.timer;
+  if (current === null) {
+    return null;
+  }
+
+  return {
+    current: current + _groupTiming.after,
+    elapsed: (elapsed ?? 0) + _groupTiming.before,
+    // mirrors the total time of an event, which grows with the time added to it
+    duration: groupNow.duration + addedTime,
+  };
+}

apps/server/src/stores/__mocks__/runtimeState.mocks.ts

@@ -9,6 +9,8 @@ const baseState: RuntimeState = {
   eventNext: null,
   eventFlag: null,
   groupNow: null,
+  groupTimer: null,
+  _groupTiming: null,
   rundown: {
     selectedEventIndex: null,
     numEvents: 0,

apps/server/src/stores/runtimeState.ts

@@ -16,6 +16,7 @@ import {
   TimeOfDay,
   TimerPhase,
   TimerState,
+  GroupTimerState,
   isOntimeEvent,
   runtimeStorePlaceholder,
 } from 'ontime-types';
@@ -39,6 +40,8 @@ import {
   getCurrent,
   getElapsed,
   getExpectedFinish,
+  getGroupTimer,
+  getGroupTiming,
   getRuntimeOffset,
   getTimerPhase,
   hasCrossedMidnight,
@@ -51,6 +54,12 @@ type ExpectedMetadata = {
   isLinkedToLoaded: boolean;
 } | null;
 
+/** scheduled content of the running group, split around the loaded event */
+export type GroupTiming = {
+  before: number;
+  after: number;
+};
+
 export type RuntimeState = {
   clock: TimeOfDay;
   groupNow: OntimeGroup | null;
@@ -59,6 +68,8 @@ export type RuntimeState = {
   eventFlag: PlayableEvent | null;
   offset: Offset;
   timer: TimerState;
+  /** derived from the timer, only refreshed on the getState() projection */
+  groupTimer: GroupTimerState | null;
   rundown: RundownState;
   // private properties of the timer calculations
   _timer: {
@@ -72,6 +83,7 @@ export type RuntimeState = {
     totalDelay: number; // this value comes from rundown service
   };
   _group: ExpectedMetadata;
+  _groupTiming: GroupTiming | null;
   _flag: ExpectedMetadata;
   _end: ExpectedMetadata;
   _startEpoch: Maybe<Instant>;
@@ -86,6 +98,7 @@ const runtimeState: RuntimeState = {
   eventFlag: null,
   offset: { ...runtimeStorePlaceholder.offset },
   timer: { ...runtimeStorePlaceholder.timer },
+  groupTimer: null,
   rundown: { ...runtimeStorePlaceholder.rundown },
   _timer: {
     forceFinish: null,
@@ -98,6 +111,7 @@ const runtimeState: RuntimeState = {
     totalDelay: 0,
   },
   _group: null,
+  _groupTiming: null,
   _flag: null,
   _end: null,
   _startEpoch: null,
@@ -115,6 +129,8 @@ export function getState(): Readonly<RuntimeState> {
     offset: { ...runtimeState.offset },
     rundown: { ...runtimeState.rundown },
     timer: { ...runtimeState.timer },
+    // derived here so it can never drift from the timer values it is built on
+    groupTimer: getGroupTimer(runtimeState),
     _timer: { ...runtimeState._timer },
     _rundown: { ...runtimeState._rundown },
   };
@@ -156,6 +172,7 @@ export function clearState() {
 
   runtimeState.groupNow = null;
   runtimeState._group = null;
+  runtimeState._groupTiming = null;
 
   runtimeState.rundown.actualStart = null;
   runtimeState.rundown.selectedEventIndex = null;
@@ -897,6 +914,7 @@ export function loadGroupFlagAndEnd(
   const previousGroup = state.groupNow?.id;
   state.groupNow = null;
   state._group = null;
+  state._groupTiming = null;
   state.eventFlag = null;
   state._flag = null;
   state._end = null;
@@ -920,6 +938,11 @@ export function loadGroupFlagAndEnd(
     state.rundown.actualGroupStart = null;
   }
 
+  // the split is stable while the same event is loaded, so we only calculate it here
+  if (state.groupNow !== null) {
+    state._groupTiming = getGroupTiming(state.groupNow, rundown.entries, state.eventNow.id);
+  }
+
   // if we don't have a any flags in the rundown then no need to look for it
   let foundFlag = !flagsPresent;
   // if we don't have a last event for the group there is no need to find its end time