fix(timer): address review findings on the group timer

- keep the pending and none phases when showing the group timer. These describe the
  playback state rather than a threshold, so collapsing them made roll standby render
  as a running countdown and silently dropped user styling keyed on the phase
- only show the group indicator for timer types which render the running timer. It was
  labelling the wall clock, and the invisible display of the none timer type, as a group
- accept useGroupTimer in the MCP group patch. It was documented in the group shape but
  dropped on write, which reported success without applying the change
- narrow the timer preview tooltip, which claimed all views follow the group timer when
  only the timer views do

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

apps/client/src/common/hooks/useSocket.ts

@@ -154,6 +154,9 @@ export const useTimer = createSelector((state: RuntimeStore) => ({
   ...state.timer,
 }));
 
+/** Shared timer for the running group, null unless the group opted in */
+export const useGroupTimer = createSelector((state: RuntimeStore) => state.groupTimer);
+
 export const useNextFlag = createSelector((state: RuntimeStore) => ({
   id: state.eventFlag?.id ?? null,
   expectedStart: state.offset.expectedFlagStart,

apps/client/src/features/control/message/TimerPreview.tsx

@@ -1,11 +1,11 @@
 import { TimerPhase, TimerType } from 'ontime-types';
-import { IoArrowDown, IoArrowUp, IoBan, IoTime } from 'react-icons/io5';
+import { IoArrowDown, IoArrowUp, IoBan, IoFolderOutline, IoTime } from 'react-icons/io5';
 import { LuArrowDownToLine } from 'react-icons/lu';
 
 import { CornerWithPip } from '../../../common/components/editor-utils/EditorUtils';
 import Tooltip from '../../../common/components/tooltip/Tooltip';
 import useViewSettings from '../../../common/hooks-query/useViewSettings';
-import { useMessagePreview } from '../../../common/hooks/useSocket';
+import { useGroupTimer, useMessagePreview } from '../../../common/hooks/useSocket';
 import { handleLinks } from '../../../common/utils/linkUtils';
 import { cx, timerPlaceholder } from '../../../common/utils/styleUtils';
 import PipRoot from '../../../views/editor/pip-timer/PipRoot';
@@ -22,6 +22,7 @@ const secondarySourceLabels: Record<string, string> = {
 export default function TimerPreview() {
   const { blink, blackout, countToEnd, phase, secondarySource, showTimerMessage, timerType } = useMessagePreview();
   const { data } = useViewSettings();
+  const isGroupTimerActive = useGroupTimer() !== null;
 
   const main = (() => {
     if (showTimerMessage) return 'Message';
@@ -105,6 +106,14 @@ export default function TimerPreview() {
         >
           <LuArrowDownToLine />
         </Tooltip>
+        <Tooltip
+          text={`Timer views are showing the ${isGroupTimerActive ? 'shared group timer' : 'event timer'}`}
+          render={<span />}
+          className={style.statusIcon}
+          data-active={isGroupTimerActive}
+        >
+          <IoFolderOutline />
+        </Tooltip>
       </div>
     </div>
   );

apps/client/src/features/rundown/entry-editor/GroupEditor.tsx

@@ -5,6 +5,8 @@ import { useCallback } from 'react';
 import * as Editor from '../../../common/components/editor-utils/EditorUtils';
 import SwatchSelect from '../../../common/components/input/colour-input/SwatchSelect';
 import AppLink from '../../../common/components/link/app-link/AppLink';
+import Switch from '../../../common/components/switch/Switch';
+import Tooltip from '../../../common/components/tooltip/Tooltip';
 import { useEntryActionsContext } from '../../../common/context/EntryActionsContext';
 import useCustomFields from '../../../common/hooks-query/useCustomFields';
 import { getOffsetState } from '../../../common/utils/offset';
@@ -95,6 +97,22 @@ export default function GroupEditor({ group }: GroupEditorProps) {
             submitHandler={handleSubmit}
           />
         </div>
+        <div>
+          <Tooltip
+            text='Timer views count the scheduled duration of the whole group instead of the running event'
+            render={<Editor.Label htmlFor='useGroupTimer' />}
+          >
+            Group timer
+          </Tooltip>
+          <Editor.Label className={style.switchLabel}>
+            <Switch
+              id='useGroupTimer'
+              checked={group.useGroupTimer}
+              onCheckedChange={(value) => updateEntry({ id: group.id, useGroupTimer: value })}
+            />
+            {group.useGroupTimer ? 'On' : 'Off'}
+          </Editor.Label>
+        </div>
       </div>
 
       <div className={style.column}>

apps/client/src/features/rundown/rundown-group/RundownGroup.tsx

@@ -15,6 +15,7 @@ import {
 
 import IconButton from '../../../common/components/buttons/IconButton';
 import Tag from '../../../common/components/tag/Tag';
+import Tooltip from '../../../common/components/tooltip/Tooltip';
 import { useEntryActionsContext } from '../../../common/context/EntryActionsContext';
 import { useContextMenu } from '../../../common/hooks/useContextMenu';
 import { useEntryCopy } from '../../../common/stores/entryCopyStore';
@@ -189,6 +190,13 @@ export default function RundownGroup({ data, hasCursor, collapsed, onCollapse }:
               {data.targetDuration !== null && <IoLockClosed className={style.lockIcon} />}
             </div>
           </div>
+          {data.useGroupTimer && (
+            <div className={style.metaEntry}>
+              <Tooltip text='Views show a shared timer for this group instead of the event timer'>
+                <Tag>Group timer</Tag>
+              </Tooltip>
+            </div>
+          )}
         </div>
       </div>
     </div>

apps/client/src/views/editor/pip-timer/PipTimer.scss

@@ -68,6 +68,18 @@
         opacity: 0;
       }
     }
+
+    // signals that the displayed timer belongs to the group, not to the running event
+    .group-indicator {
+      text-align: center;
+      text-transform: uppercase;
+      letter-spacing: 0.25em;
+      font-weight: 600;
+      font-size: 2.5vw;
+      line-height: 1;
+      opacity: 0.7;
+      color: var(--timer-colour, $ui-white);
+    }
   }
 
   .secondary {

apps/client/src/views/editor/pip-timer/PipTimer.tsx

@@ -2,7 +2,7 @@ import { ViewSettings } from 'ontime-types';
 
 import { FitText } from '../../../common/components/fit-text/FitText';
 import MultiPartProgressBar from '../../../common/components/multi-part-progress-bar/MultiPartProgressBar';
-import { useTimerSocket } from '../../../common/hooks/useSocket';
+import { useGroupTimer, useTimerSocket } from '../../../common/hooks/useSocket';
 import { cx } from '../../../common/utils/styleUtils';
 import { getFormattedTimer, getTimerByType } from '../../common/viewUtils';
 import {
@@ -10,9 +10,8 @@ import {
   getIsPlaying,
   getSecondaryDisplay,
   getShowMessage,
-  getShowModifiers,
-  getShowProgressBar,
-  getTotalTime,
+  getShowsTimerValue,
+  resolveTimerDisplay,
 } from '../../timer/timer.utils';
 import { getTimerColour } from '../../utils/presentation.utils';
 
@@ -24,23 +23,28 @@ interface PipTimerProps {
 
 export function PipTimer({ viewSettings }: PipTimerProps) {
   const { eventNow, message, time, clock, timerTypeNow, countToEndNow, auxTimer } = useTimerSocket();
+  const groupTimer = useGroupTimer();
 
   // gather modifiers
   const showOverlay = getShowMessage(message.timer);
-  const { showFinished, showWarning, showDanger } = getShowModifiers(
-    timerTypeNow,
-    countToEndNow,
-    time.phase,
-    false,
-    '',
-    false,
-  );
+  const timerDisplay = resolveTimerDisplay({
+    time,
+    groupTimer,
+    event: eventNow,
+    timerType: timerTypeNow,
+    countToEnd: countToEndNow,
+    freezeOvertime: false,
+    freezeMessage: '',
+    hidePhase: false,
+  });
+  const { showFinished, showWarning, showDanger } = timerDisplay;
+
   const isPlaying = getIsPlaying(time.playback);
-  const showProgressBar = getShowProgressBar(timerTypeNow);
+  const showsTimerValue = getShowsTimerValue(timerTypeNow);
+  const showProgressBar = showsTimerValue;
 
   // gather timer data
-  const totalTime = getTotalTime(time.duration, time.addedTime);
-  const stageTimer = getTimerByType(false, timerTypeNow, clock, time, timerTypeNow);
+  const stageTimer = getTimerByType(false, timerTypeNow, clock, timerDisplay.source, timerTypeNow);
   const display = getFormattedTimer(stageTimer, timerTypeNow, 'min', {
     removeSeconds: false,
     removeLeadingZero: false,
@@ -80,10 +84,11 @@ export function PipTimer({ viewSettings }: PipTimerProps) {
         <div
           className={cx(['timer', !isPlaying && 'timer--paused', showFinished && 'timer--finished'])}
           style={{ fontSize: `${timerFontSize}vw` }}
-          data-phase={time.phase}
+          data-phase={timerDisplay.phase}
         >
           {display}
         </div>
+        {timerDisplay.isGroup && showsTimerValue && <div className='group-indicator'>group</div>}
         <div className={cx(['secondary', !secondaryContent && 'secondary--hidden'])}>
           <FitText mode='multi' min={12} max={256}>
             {secondaryContent}
@@ -94,12 +99,12 @@ export function PipTimer({ viewSettings }: PipTimerProps) {
       {showProgressBar && (
         <MultiPartProgressBar
           className={cx(['progress-container', !isPlaying && 'progress-container--paused'])}
-          now={time.current}
-          complete={totalTime}
+          now={timerDisplay.source.current}
+          complete={timerDisplay.total}
           normalColor={viewSettings.normalColor}
-          warning={eventNow?.timeWarning}
+          warning={timerDisplay.warning}
           warningColor={viewSettings.warningColor}
-          danger={eventNow?.timeDanger}
+          danger={timerDisplay.danger}
           dangerColor={viewSettings.dangerColor}
           hideOvertime={!showFinished}
         />

apps/client/src/views/timer/Timer.scss

@@ -131,6 +131,18 @@
         opacity: 0;
       }
     }
+
+    // signals that the displayed timer belongs to the group, not to the running event
+    .group-indicator {
+      text-align: center;
+      text-transform: uppercase;
+      letter-spacing: 0.25em;
+      font-weight: 600;
+      font-size: 1.5vw;
+      line-height: 1;
+      opacity: 0.7;
+      color: var(--timer-colour, var(--timer-color-override, $ui-white));
+    }
   }
 
   .secondary {

apps/client/src/views/timer/Timer.tsx

@@ -8,7 +8,7 @@ import TitleCard from '../../common/components/title-card/TitleCard';
 import ViewLogo from '../../common/components/view-logo/ViewLogo';
 import ViewParamsEditor from '../../common/components/view-params-editor/ViewParamsEditor';
 import { useAutoTickingClock } from '../../common/hooks/useAutoTickingClock';
-import { useTimerSocket } from '../../common/hooks/useSocket';
+import { useGroupTimer, useTimerSocket } from '../../common/hooks/useSocket';
 import { useWindowTitle } from '../../common/hooks/useWindowTitle';
 import { cx } from '../../common/utils/styleUtils';
 import { formatTime, getDefaultFormat } from '../../common/utils/time';
@@ -25,9 +25,8 @@ import {
   getSecondaryDisplay,
   getShowClock,
   getShowMessage,
-  getShowModifiers,
-  getShowProgressBar,
-  getTotalTime,
+  getShowsTimerValue,
+  resolveTimerDisplay,
 } from './timer.utils';
 import { TimerData, useTimerData } from './useTimerData';
 
@@ -72,23 +71,29 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
     timeformat,
   } = useTimerOptions();
 
+  const groupTimer = useGroupTimer();
+
   const { getLocalizedString } = useTranslation();
   const localisedMinutes = getLocalizedString('common.minutes');
 
   // gather modifiers
   const viewTimerType = timerType ?? timerTypeNow;
   const showOverlay = getShowMessage(message.timer);
-  const { showEndMessage, showFinished, showWarning, showDanger } = getShowModifiers(
-    timerTypeNow,
-    countToEndNow,
-    time.phase,
+  const timerDisplay = resolveTimerDisplay({
+    time,
+    groupTimer,
+    event: eventNow,
+    timerType: timerTypeNow,
+    countToEnd: countToEndNow,
     freezeOvertime,
     freezeMessage,
     hidePhase,
-  );
+  });
+  const { showEndMessage, showFinished, showWarning, showDanger } = timerDisplay;
   const isPlaying = getIsPlaying(time.playback);
   const showClock = !hideClock && getShowClock(viewTimerType);
-  const showProgressBar = !hideProgress && getShowProgressBar(viewTimerType);
+  const showsTimerValue = getShowsTimerValue(viewTimerType);
+  const showProgressBar = !hideProgress && showsTimerValue;
 
   // gather card data
   const { showNow, nowMain, nowSecondary, showNext, nextMain, nextSecondary } = getCardData(
@@ -102,8 +107,7 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
   );
 
   // gather timer data
-  const totalTime = getTotalTime(time.duration, time.addedTime);
-  const stageTimer = getTimerByType(freezeOvertime, timerTypeNow, clock, time, timerType);
+  const stageTimer = getTimerByType(freezeOvertime, timerTypeNow, clock, timerDisplay.source, timerType);
   const display = getFormattedTimer(stageTimer, viewTimerType, localisedMinutes, {
     removeSeconds: hideTimerSeconds,
     removeLeadingZero: removeLeadingZeros,
@@ -178,11 +182,14 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
             className={cx(['timer', subduePaused && 'timer--paused', showFinished && 'timer--finished'])}
             style={{ fontSize: `${timerFontSize}vw` }}
             data-type={viewTimerType}
-            data-phase={time.phase}
+            data-phase={timerDisplay.phase}
           >
             {display}
           </div>
         )}
+        {timerDisplay.isGroup && showsTimerValue && !showEndMessage && (
+          <div className='group-indicator'>group</div>
+        )}
         <div className={cx(['secondary', !secondaryContent && 'secondary--hidden'])}>
           <FitText mode='multi' min={64} max={256}>
             {secondaryContent}
@@ -193,12 +200,12 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
       {showProgressBar && (
         <MultiPartProgressBar
           className={cx(['progress-container', !isPlaying && 'progress-container--paused'])}
-          now={time.current}
-          complete={totalTime}
+          now={timerDisplay.source.current}
+          complete={timerDisplay.total}
           normalColor={viewSettings.normalColor}
-          warning={eventNow?.timeWarning}
+          warning={timerDisplay.warning}
           warningColor={viewSettings.warningColor}
-          danger={eventNow?.timeDanger}
+          danger={timerDisplay.danger}
           dangerColor={viewSettings.dangerColor}
           hideOvertime={!showFinished}
         />

apps/client/src/views/timer/__tests__/timer.utils.test.ts

@@ -0,0 +1,110 @@
+import { GroupTimerState, Playback, TimerPhase, TimerState, TimerType } from 'ontime-types';
+
+import { getShowsTimerValue, resolveTimerDisplay } from '../timer.utils';
+
+const makeTime = (patch: Partial<TimerState> = {}): TimerState => ({
+  addedTime: 0,
+  current: 10000,
+  duration: 60000,
+  elapsed: 50000,
+  expectedFinish: null,
+  phase: TimerPhase.Default,
+  playback: Playback.Play,
+  secondaryTimer: null,
+  startedAt: null,
+  ...patch,
+});
+
+const makeGroupTimer = (patch: Partial<GroupTimerState> = {}): GroupTimerState => ({
+  current: 100000,
+  elapsed: 80000,
+  duration: 180000,
+  ...patch,
+});
+
+const resolve = (time: TimerState, groupTimer: GroupTimerState | null) =>
+  resolveTimerDisplay({
+    time,
+    groupTimer,
+    event: { timeWarning: 120000, timeDanger: 60000 },
+    timerType: TimerType.CountDown,
+    countToEnd: false,
+    freezeOvertime: false,
+    freezeMessage: '',
+    hidePhase: false,
+  });
+
+describe('resolveTimerDisplay()', () => {
+  it('uses the event timer when there is no group timer', () => {
+    const time = makeTime();
+    const result = resolve(time, null);
+
+    expect(result.isGroup).toBe(false);
+    expect(result.source).toBe(time);
+    expect(result.total).toBe(60000);
+    expect(result.warning).toBe(120000);
+    expect(result.danger).toBe(60000);
+  });
+
+  it('adds the time added to an event into the event total', () => {
+    expect(resolve(makeTime({ addedTime: 30000 }), null).total).toBe(90000);
+  });
+
+  it('uses the group timer when one is present', () => {
+    const groupTimer = makeGroupTimer();
+    const result = resolve(makeTime(), groupTimer);
+
+    expect(result.isGroup).toBe(true);
+    expect(result.source).toBe(groupTimer);
+    expect(result.total).toBe(180000);
+  });
+
+  it('drops the event thresholds while showing the group', () => {
+    const result = resolve(makeTime({ phase: TimerPhase.Danger }), makeGroupTimer());
+
+    expect(result.warning).toBeUndefined();
+    expect(result.danger).toBeUndefined();
+  });
+
+  it.each([TimerPhase.Warning, TimerPhase.Danger])(
+    'reports the group as running while the event is in %s',
+    (phase) => {
+      const result = resolve(makeTime({ phase }), makeGroupTimer());
+
+      expect(result.phase).toBe(TimerPhase.Default);
+      expect(result.showWarning).toBe(false);
+      expect(result.showDanger).toBe(false);
+      expect(result.showFinished).toBe(false);
+    },
+  );
+
+  it('reports overtime only once the group itself has run out of time', () => {
+    const overrunningEvent = makeTime({ current: -5000, phase: TimerPhase.Overtime });
+
+    // the event is over, but the group still has time left
+    const stillRunning = resolve(overrunningEvent, makeGroupTimer({ current: 60000 }));
+    expect(stillRunning.phase).toBe(TimerPhase.Default);
+    expect(stillRunning.showFinished).toBe(false);
+
+    const overtime = resolve(overrunningEvent, makeGroupTimer({ current: -1000 }));
+    expect(overtime.phase).toBe(TimerPhase.Overtime);
+    expect(overtime.showFinished).toBe(true);
+  });
+
+  it.each([TimerPhase.Pending, TimerPhase.None])('keeps the %s playback phase on the group', (phase) => {
+    // these describe the playback state rather than a threshold, so they are true of the group too
+    expect(resolve(makeTime({ phase }), makeGroupTimer()).phase).toBe(phase);
+  });
+});
+
+describe('getShowsTimerValue()', () => {
+  it('is true for timer types which render the running timer', () => {
+    expect(getShowsTimerValue(TimerType.CountDown)).toBe(true);
+    expect(getShowsTimerValue(TimerType.CountUp)).toBe(true);
+  });
+
+  it('is false for timer types which do not reflect what is loaded', () => {
+    expect(getShowsTimerValue(TimerType.Clock)).toBe(false);
+    expect(getShowsTimerValue(TimerType.None)).toBe(false);
+  });
+});

apps/client/src/views/timer/timer.utils.ts

@@ -1,4 +1,5 @@
 import {
+  GroupTimerState,
   MaybeNumber,
   MessageState,
   OntimeEvent,
@@ -6,6 +7,7 @@ import {
   RundownEntries,
   TimerMessage,
   TimerPhase,
+  TimerState,
   TimerType,
 } from 'ontime-types';
 import { isPlaybackActive } from 'ontime-utils';
@@ -34,9 +36,11 @@ export function getTotalTime(duration: MaybeNumber, addedTime: MaybeNumber): num
 }
 
 /**
- * Whether the progress bar should be shown for this timer type
+ * Whether this timer type renders a value derived from the running timer.
+ * Clock shows the time of day and none shows nothing, so neither reflects what is loaded,
+ * which also means neither can carry a progress bar or a group timer indicator
  */
-export function getShowProgressBar(timerType: TimerType) {
+export function getShowsTimerValue(timerType: TimerType) {
   return timerType !== TimerType.None && timerType !== TimerType.Clock;
 }
 
@@ -114,6 +118,59 @@ export function getShowModifiers(
   };
 }
 
+interface ResolveTimerDisplayOptions {
+  time: TimerState;
+  /** when present, views show the group instead of the running event */
+  groupTimer: GroupTimerState | null;
+  event: Pick<OntimeEvent, 'timeWarning' | 'timeDanger'> | null;
+  timerType: TimerType;
+  countToEnd: boolean;
+  freezeOvertime: boolean;
+  freezeMessage: string;
+  hidePhase: boolean;
+}
+
+/**
+ * Resolves which timer a view should display, and the modifiers that go with it.
+ *
+ * A group has no warning or danger thresholds of its own, so it only ever reports as
+ * running or overtime. Feeding that phase through `getShowModifiers` means the warning
+ * and danger states are suppressed as a consequence of what a group is, rather than
+ * every view having to remember to special case them.
+ */
+export function resolveTimerDisplay({
+  time,
+  groupTimer,
+  event,
+  timerType,
+  countToEnd,
+  freezeOvertime,
+  freezeMessage,
+  hidePhase,
+}: ResolveTimerDisplayOptions) {
+  const isGroup = groupTimer !== null;
+  const phase = (() => {
+    if (!isGroup) return time.phase;
+    // pending and none describe the playback state rather than a threshold,
+    // they are just as true of the group as they are of the event
+    if (time.phase === TimerPhase.Pending || time.phase === TimerPhase.None) return time.phase;
+    return groupTimer.current <= 0 ? TimerPhase.Overtime : TimerPhase.Default;
+  })();
+
+  return {
+    isGroup,
+    phase,
+    /** the values to render, shaped for getTimerByType */
+    source: isGroup ? groupTimer : time,
+    /** the target of a progress bar */
+    total: isGroup ? groupTimer.duration : getTotalTime(time.duration, time.addedTime),
+    // thresholds belong to the event, they carry no meaning against a group duration
+    warning: isGroup ? undefined : event?.timeWarning,
+    danger: isGroup ? undefined : event?.timeDanger,
+    ...getShowModifiers(timerType, countToEnd, phase, freezeOvertime, freezeMessage, hidePhase),
+  };
+}
+
 /**
  * What, if anything, should be displayed in the secondary field
  */

apps/server/src/api-data/db/migration/db.migration.v3.ts

@@ -411,6 +411,7 @@ export function migrateRundown(
           targetDuration: null,
           colour: '', //leave default colour
           custom: {}, // leave empty
+          useGroupTimer: false, // opt-in feature, off for migrated projects
           // !==== RUNTIME METADATA ====! //
           revision: -1,
           timeStart: null,

apps/server/src/api-data/db/migration/migration.test.ts

@@ -316,6 +316,7 @@ describe('v3 to v4', () => {
           targetDuration: null,
           timeEnd: null,
           timeStart: null,
+          useGroupTimer: false,
         },
         event2: {
           id: 'event2',
@@ -392,6 +393,7 @@ describe('v3 to v4', () => {
           targetDuration: null,
           timeEnd: null,
           timeStart: null,
+          useGroupTimer: false,
         },
         delay: {
           type: SupportedEntry.Delay,

apps/server/src/api-data/rundown/__tests__/rundown.parser.test.ts

@@ -301,6 +301,23 @@ describe('parseRundown()', () => {
     expect(parsedRundown.entries.group).toMatchObject({ entries: ['1', '2'] });
     expect(Object.keys(parsedRundown.entries).length).toEqual(3);
   });
+
+  it('normalises groups from projects made before the group timer existed', () => {
+    const rundown = {
+      id: 'test',
+      title: '',
+      order: ['group'],
+      flatOrder: ['group'],
+      entries: {
+        // a group as it would have been persisted by a previous version
+        group: { id: 'group', type: SupportedEntry.Group, title: 'legacy', entries: [] },
+      },
+      revision: 1,
+    } as unknown as Rundown;
+
+    const parsedRundown = parseRundown(rundown, {});
+    expect(parsedRundown.entries.group).toMatchObject({ id: 'group', useGroupTimer: false });
+  });
 });
 
 describe('sanitiseCustomFields()', () => {

apps/server/src/api-data/rundown/__tests__/rundown.utils.test.ts

@@ -15,6 +15,7 @@ import { makeOntimeEvent, makeOntimeGroup, makeOntimeMilestone, makeRundown } fr
 import { parseRundown } from '../rundown.parser.js';
 import {
   calculateDayOffset,
+  createGroupPatch,
   deleteById,
   doesInvalidateMetadata,
   getIntegerAndFraction,
@@ -610,3 +611,25 @@ describe('isLoadedPlayable()', () => {
     expect(isLoadedPlayable('keynote', rundown)).toBe(false);
   });
 });
+
+describe('createGroupPatch()', () => {
+  it('preserves useGroupTimer when it is not part of the patch', () => {
+    const original = makeOntimeGroup({ id: 'group', useGroupTimer: true });
+    const patched = createGroupPatch(original, { title: 'Morning sessions' });
+
+    expect(patched.title).toBe('Morning sessions');
+    expect(patched.useGroupTimer).toBe(true);
+  });
+
+  it('updates useGroupTimer when it is part of the patch', () => {
+    const original = makeOntimeGroup({ id: 'group', useGroupTimer: false });
+    expect(createGroupPatch(original, { useGroupTimer: true }).useGroupTimer).toBe(true);
+    expect(createGroupPatch(original, { useGroupTimer: false }).useGroupTimer).toBe(false);
+  });
+
+  it('ignores non boolean values for useGroupTimer', () => {
+    const original = makeOntimeGroup({ id: 'group', useGroupTimer: true });
+    // @ts-expect-error -- testing a value coming from an unvalidated request
+    expect(createGroupPatch(original, { useGroupTimer: 'nope' }).useGroupTimer).toBe(true);
+  });
+});

apps/server/src/api-data/rundown/rundown.utils.ts

@@ -179,6 +179,8 @@ export function createGroupPatch(originalGroup: OntimeGroup, patchGroup: Partial
     entries: patchGroup.entries ?? originalGroup.entries,
     targetDuration: maybeTargetDuration(),
     colour: makeString(patchGroup.colour, originalGroup.colour),
+    useGroupTimer:
+      typeof patchGroup.useGroupTimer === 'boolean' ? patchGroup.useGroupTimer : originalGroup.useGroupTimer,
     revision: originalGroup.revision,
     timeStart: originalGroup.timeStart,
     timeEnd: originalGroup.timeEnd,

apps/server/src/api-mcp/mcp.schema.ts

@@ -147,6 +147,7 @@ There are four entry types discriminated by \`type\`:
   note: string
   entries: EntryId[]
   targetDuration: number | null
+  useGroupTimer: boolean       // views show a shared timer for the whole group
   custom: { [key: string]: string }
   timeStart: number | null     // calculated from nested entries (runtime)
   timeEnd: number | null       // calculated from nested entries (runtime)

apps/server/src/api-mcp/mcp.service.ts

@@ -54,7 +54,9 @@ export type EventFieldArgs = Partial<
 >;
 export type MilestoneFieldArgs = Partial<Pick<OntimeMilestone, 'cue' | 'title' | 'note' | 'colour' | 'custom'>>;
 export type DelayFieldArgs = Partial<Pick<OntimeDelay, 'duration'>>;
-export type GroupFieldArgs = Partial<Pick<OntimeGroup, 'title' | 'note' | 'colour' | 'targetDuration' | 'custom'>>;
+export type GroupFieldArgs = Partial<
+  Pick<OntimeGroup, 'title' | 'note' | 'colour' | 'targetDuration' | 'custom' | 'useGroupTimer'>
+>;
 
 export type EntryFieldArgs = EventFieldArgs & MilestoneFieldArgs & DelayFieldArgs & GroupFieldArgs;
 export type TargetRundownArgs = { rundownId?: string };
@@ -170,6 +172,7 @@ function toGroupPatch(args: CreateEntryArgs, id: EntryId): PatchWithId<OntimeGro
   if (args.colour !== undefined) patch.colour = args.colour;
   if (args.targetDuration !== undefined) patch.targetDuration = args.targetDuration;
   if (args.custom !== undefined) patch.custom = args.custom;
+  if (args.useGroupTimer !== undefined) patch.useGroupTimer = args.useGroupTimer;
 
   return Object.keys(patch).length > 1 ? patch : null;
 }

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/models/demoRundowns.ts

@@ -39,6 +39,7 @@ export const stageRundown: Rundown = {
       note: '',
       entries: ['9bf60f', 'bf71a2', 'c2697f', 'fa593e', 'a8b0b3'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,
@@ -172,6 +173,7 @@ export const stageRundown: Rundown = {
       note: '',
       entries: ['0aaa7d'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#3E75E8',
       custom: {},
       revision: 0,
@@ -219,6 +221,7 @@ export const stageRundown: Rundown = {
       note: '',
       entries: ['02afca', '75ce86', 'e10ed9', '07df89'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,
@@ -360,6 +363,7 @@ export const backstageRundown: Rundown = {
       note: '',
       entries: ['bs0101', 'bs0102', 'bs0103', 'bs0104'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#A790F5',
       custom: {},
       revision: 0,
@@ -476,6 +480,7 @@ export const backstageRundown: Rundown = {
       note: '',
       entries: ['bs0201', 'bs0202', 'bs0203', 'bs0204'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,
@@ -588,6 +593,7 @@ export const backstageRundown: Rundown = {
       note: '',
       entries: ['bs0301'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#3E75E8',
       custom: {},
       revision: 0,
@@ -634,6 +640,7 @@ export const backstageRundown: Rundown = {
       note: '',
       entries: ['bs0401', 'bs0402', 'bs0403', 'bs0404'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,
@@ -768,6 +775,7 @@ export const broadcastRundown: Rundown = {
       note: '',
       entries: ['br0101', 'br0102', 'br0103'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#ED3333',
       custom: {},
       revision: 0,
@@ -851,6 +859,7 @@ export const broadcastRundown: Rundown = {
       note: '',
       entries: ['br0201', 'br0202', 'br0203', 'br0204'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,
@@ -959,6 +968,7 @@ export const broadcastRundown: Rundown = {
       note: '',
       entries: ['br0301', 'br0302'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#3E75E8',
       custom: {},
       revision: 0,
@@ -1029,6 +1039,7 @@ export const broadcastRundown: Rundown = {
       note: '',
       entries: ['br0401', 'br0402', 'br0403'],
       targetDuration: null,
+      useGroupTimer: false,
       colour: '#339E4E',
       custom: {},
       revision: 0,

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

packages/types/src/definitions/core/OntimeEntry.ts

@@ -46,6 +46,8 @@ export type OntimeGroup = OntimeBaseEvent & {
   targetDuration: MaybeNumber;
   colour: string;
   custom: EntryCustomFields;
+  /** whether views should display a shared timer for the group instead of the event timer */
+  useGroupTimer: boolean;
   // !==== RUNTIME METADATA ====! //
   revision: number;
   timeStart: MaybeNumber; // calculated at runtime

packages/types/src/definitions/runtime/RuntimeStore.ts

@@ -17,6 +17,7 @@ export const runtimeStorePlaceholder: Readonly<RuntimeStore> = {
     secondaryTimer: null, // change on every update
     startedAt: null, // change can only be initiated by user
   },
+  groupTimer: null, // derived from the timer, null unless the running group opted in
   message: {
     timer: {
       text: '',

packages/types/src/definitions/runtime/RuntimeStore.type.ts

@@ -3,12 +3,14 @@ import type { SimpleTimerState } from './AuxTimer.type.js';
 import type { MessageState } from './MessageControl.type.js';
 import type { Offset } from './Offset.type.js';
 import type { RundownState } from './RundownState.type.js';
-import type { TimerState } from './TimerState.type.js';
+import type { GroupTimerState, TimerState } from './TimerState.type.js';
 
 export type RuntimeStore = {
   // timer data
   clock: number;
   timer: TimerState;
+  /** shared timer for the running group, null unless the group opted in */
+  groupTimer: GroupTimerState | null;
 
   // messages service
   message: MessageState;

packages/types/src/definitions/runtime/TimerState.type.ts

@@ -11,6 +11,22 @@ export enum TimerPhase {
   Pending = 'pending',
 }
 
+/**
+ * Timer for the running group, present when the group opted into a shared timer.
+ *
+ * The group is treated as a single event containing all its children: the values are
+ * derived from the running event timer plus the content scheduled around it, so pause,
+ * added time, overtime and roll are inherited from the event timer rather than recalculated.
+ */
+export type GroupTimerState = {
+  /** Time remaining in the group */
+  current: number;
+  /** Time elapsed since the group started */
+  elapsed: number;
+  /** Total time in the group, includes time added to the running event */
+  duration: number;
+};
+
 /**
  * Gathers the current running timer state
  */

packages/types/src/index.ts

@@ -119,7 +119,7 @@ export type { Offset } from './definitions/runtime/Offset.type.js';
 export { OffsetMode } from './definitions/runtime/Offset.type.js';
 export type { RuntimeStore } from './definitions/runtime/RuntimeStore.type.js';
 export { runtimeStorePlaceholder } from './definitions/runtime/RuntimeStore.js';
-export { type TimerState, TimerPhase } from './definitions/runtime/TimerState.type.js';
+export { type GroupTimerState, type TimerState, TimerPhase } from './definitions/runtime/TimerState.type.js';
 
 // ---> Extra Timer
 export { type SimpleTimerState, SimplePlayback, SimpleDirection } from './definitions/runtime/AuxTimer.type.js';

packages/utils/src/rundown-utils/entryDefinitions.ts

@@ -54,6 +54,7 @@ export const group: Omit<OntimeGroup, 'id'> = {
   targetDuration: null,
   colour: '',
   custom: {},
+  useGroupTimer: false,
   // !==== RUNTIME METADATA ====! //
   revision: 0, // calculated at runtime
   timeStart: null, // calculated at runtime

packages/utils/src/rundown-utils/entryUtils.ts

@@ -69,6 +69,7 @@ export function createGroup(patch?: Partial<OntimeGroup>): OntimeGroup {
     targetDuration: patch.targetDuration ?? null,
     colour: makeString(patch.colour, ''),
     custom: patch.custom ?? {},
+    useGroupTimer: typeof patch.useGroupTimer === 'boolean' ? patch.useGroupTimer : false,
     revision: 0,
     timeStart: null,
     timeEnd: null,