test: cover runtime update gating and colour parsing

Adds unit tests for two pure modules which had no coverage:

- `runtime.utils.ts` gates every websocket broadcast and the
  `onUpdate` / `onClock` automation triggers. The tests pin the
  second-boundary rounding, the documented cases where a field is
  deliberately *not* broadcast (`elapsed`, `expectedFinish`), and the
  wrap-around behaviour of the load-next / load-previous / go-to-cue
  lookups.

- `colour.utils.ts` parses user supplied colour strings for both the
  Google Sheets export and the cuesheet rows. The tests cover the
  hex/CSS-name parsing, the null returns for invalid input, and the
  hexToColour <-> colourToHex round trip.

Both files are pure, so neither test uses a mock.

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

apps/client/src/features/app-settings/panel-utils/PanelUtils.module.scss

@@ -200,8 +200,7 @@ $card-padding: 2rem;
 .overlay {
   position: absolute;
   z-index: $zindex-backdrop;
-  width: 100%;
-  height: 100%;
+  inset: 0;
   backdrop-filter: blur(2px);
   display: grid;
   place-content: center;

apps/client/src/features/app-settings/panel/about-panel/AppVersion.module.scss

@@ -0,0 +1,7 @@
+.updateIndicator {
+  width: 0.5em;
+  height: 0.5em;
+  flex: 0 0 auto;
+  border-radius: 99px;
+  background-color: $red-400;
+}

apps/client/src/features/app-settings/panel/about-panel/AppVersion.tsx

@@ -3,6 +3,8 @@ import useAppVersion from '../../../../common/hooks-query/useAppVersion';
 import { appVersion, isOntimeCloud, websiteUrl } from '../../../../externals';
 import * as Panel from '../../panel-utils/PanelUtils';
 
+import style from './AppVersion.module.scss';
+
 export default function AppVersion() {
   const { data, isError } = useAppVersion();
 
@@ -18,7 +20,12 @@ export default function AppVersion() {
     return (
       <Panel.ListItem>
         <Panel.Field
-          title={`Ontime ${appVersion}`}
+          title={
+            <>
+              <span className={style.updateIndicator} aria-hidden='true' />
+              {`Ontime ${appVersion}`}
+            </>
+          }
           description={
             isOntimeCloud
               ? `Version ${data.version} is available. Restart your stage to update.`
@@ -26,7 +33,7 @@ export default function AppVersion() {
           }
         />
         {!isOntimeCloud && (
-          <ExternalLink href={websiteUrl}>Visit Ontime's page to download the latest version.</ExternalLink>
+          <ExternalLink href={websiteUrl}>Download the latest version from Ontime's page</ExternalLink>
         )}
       </Panel.ListItem>
     );

apps/client/src/features/app-settings/panel/settings-panel/ServerPortSettings.tsx

@@ -85,10 +85,10 @@ export default function ServerPortSettings() {
             </Button>
           </Panel.InlineElements>
         </Panel.SubHeader>
-        <Panel.Loader isLoading={status === 'pending'} />
         {rootError && <Panel.Error>{rootError}</Panel.Error>}
         <Panel.Divider />
         <Panel.Section>
+          <Panel.Loader isLoading={status === 'pending'} />
           {data.pendingRestart && (
             <Info type='warning'>A port change is pending and will happen on the next restart.</Info>
           )}

apps/electron/src/menu/applicationMenu.js

@@ -100,7 +100,7 @@ function makeFileMenu(askToQuit, serverUrl, redirectWindow, showDialog, download
     submenu: [
       {
         label: 'New project...',
-        click: () => redirectWindow('/editor?settings=project__manage&new=true'),
+        click: () => redirectWindow('/editor?settings=project__create'),
       },
       {
         label: 'Load...',
@@ -202,6 +202,18 @@ function makeSettingsMenu(redirectWindow) {
             label: 'View settings',
             click: () => redirectWindow('/editor?settings=settings__view'),
           },
+          {
+            label: 'Custom views',
+            click: () => redirectWindow('/editor?settings=settings__custom-views'),
+          },
+          {
+            label: 'MCP Server',
+            click: () => redirectWindow('/editor?settings=settings__mcp'),
+          },
+          {
+            label: 'Server port',
+            click: () => redirectWindow('/editor?settings=settings__port'),
+          },
         ],
       },
       {

apps/server/src/services/runtime-service/__tests__/runtime.utils.test.ts

@@ -0,0 +1,226 @@
+import { Offset, OffsetMode, Playback, TimerPhase, TimerState, TimerType } from 'ontime-types';
+
+import { makeOntimeEvent, makeRundown } from '../../../api-data/rundown/__mocks__/rundown.mocks.js';
+import {
+  findNextPlayableId,
+  findNextPlayableWithCue,
+  findPreviousPlayableId,
+  getEventAtIndex,
+  getShouldClockUpdate,
+  getShouldOffsetUpdate,
+  getShouldTimerUpdate,
+  isNewSecond,
+} from '../runtime.utils.js';
+
+describe('isNewSecond()', () => {
+  it('is false while the value moves within the same second', () => {
+    // count down rounds up, so both resolve to second 2
+    expect(isNewSecond(1500, 1200)).toBe(false);
+  });
+
+  it('is true once the value crosses a second boundary', () => {
+    expect(isNewSecond(1001, 1000)).toBe(true);
+  });
+
+  it('rounds according to the given direction', () => {
+    // 1200 -> ceil 2 / floor 1, 1800 -> ceil 2 / floor 1
+    expect(isNewSecond(1200, 1800, TimerType.CountDown)).toBe(false);
+    expect(isNewSecond(1200, 1800, TimerType.CountUp)).toBe(false);
+    // 1200 -> ceil 2 / floor 1, 2200 -> ceil 3 / floor 2
+    expect(isNewSecond(1200, 2200, TimerType.CountDown)).toBe(true);
+    expect(isNewSecond(1200, 2200, TimerType.CountUp)).toBe(true);
+  });
+
+  it('treats null and undefined as second zero', () => {
+    expect(isNewSecond(undefined, null)).toBe(false);
+    expect(isNewSecond(null, 0)).toBe(false);
+    expect(isNewSecond(undefined, 500)).toBe(true);
+  });
+});
+
+describe('getShouldClockUpdate()', () => {
+  it('is false within the same second and true across the boundary', () => {
+    expect(getShouldClockUpdate(1000, 1999)).toBe(false);
+    expect(getShouldClockUpdate(1000, 2000)).toBe(true);
+  });
+});
+
+describe('getShouldTimerUpdate()', () => {
+  const baseTimer: TimerState = {
+    addedTime: 0,
+    current: 10000,
+    duration: 10000,
+    elapsed: 0,
+    expectedFinish: 10000,
+    phase: TimerPhase.Default,
+    playback: Playback.Play,
+    secondaryTimer: null,
+    startedAt: 0,
+  };
+
+  it('always updates when there is no previous state', () => {
+    expect(getShouldTimerUpdate(undefined, baseTimer)).toBe(true);
+  });
+
+  it('does not update while the timer ticks within the same second', () => {
+    expect(getShouldTimerUpdate(baseTimer, { ...baseTimer, current: 9500 })).toBe(false);
+  });
+
+  it('updates when the timer crosses a second', () => {
+    expect(getShouldTimerUpdate(baseTimer, { ...baseTimer, current: 8999 })).toBe(true);
+  });
+
+  it('updates when the secondary timer crosses a second', () => {
+    const previous = { ...baseTimer, secondaryTimer: 2000 };
+    // counting down rounds up, so 1999 is still second 2
+    expect(getShouldTimerUpdate(previous, { ...previous, secondaryTimer: 1999 })).toBe(false);
+    expect(getShouldTimerUpdate(previous, { ...previous, secondaryTimer: 1000 })).toBe(true);
+  });
+
+  it.each([
+    ['addedTime', { addedTime: 1 }],
+    ['duration', { duration: 1 }],
+    ['phase', { phase: TimerPhase.Warning }],
+    ['playback', { playback: Playback.Pause }],
+    ['startedAt', { startedAt: 1 }],
+  ])('updates immediately when %s changes', (_label, patch) => {
+    expect(getShouldTimerUpdate(baseTimer, { ...baseTimer, ...patch })).toBe(true);
+  });
+
+  it.each([
+    ['elapsed', { elapsed: 1 }],
+    ['expectedFinish', { expectedFinish: 1 }],
+  ])('does not update on %s alone, since it is derived', (_label, patch) => {
+    expect(getShouldTimerUpdate(baseTimer, { ...baseTimer, ...patch })).toBe(false);
+  });
+});
+
+describe('getShouldOffsetUpdate()', () => {
+  const baseOffset: Offset = {
+    absolute: 0,
+    relative: 0,
+    mode: OffsetMode.Absolute,
+    expectedGroupEnd: null,
+    expectedRundownEnd: null,
+    expectedFlagStart: null,
+  };
+
+  it('always updates when there is no previous state', () => {
+    expect(getShouldOffsetUpdate(undefined, baseOffset, false)).toBe(true);
+  });
+
+  it('updates on a mode change even when no dependency ticked', () => {
+    expect(getShouldOffsetUpdate(baseOffset, { ...baseOffset, mode: OffsetMode.Relative }, false)).toBe(true);
+  });
+
+  it('holds back value changes until a dependency ticks', () => {
+    const next = { ...baseOffset, absolute: 1000 };
+    expect(getShouldOffsetUpdate(baseOffset, next, false)).toBe(false);
+    expect(getShouldOffsetUpdate(baseOffset, next, true)).toBe(true);
+  });
+
+  it('does not update when a dependency ticked but nothing changed', () => {
+    expect(getShouldOffsetUpdate(baseOffset, { ...baseOffset }, true)).toBe(false);
+  });
+});
+
+describe('findPreviousPlayableId()', () => {
+  const order = ['1', '2', '3'];
+
+  it('returns undefined when there is nothing to play', () => {
+    expect(findPreviousPlayableId([])).toBeUndefined();
+  });
+
+  it('returns the first event when nothing is loaded', () => {
+    expect(findPreviousPlayableId(order)).toBe('1');
+  });
+
+  it('returns the preceding event', () => {
+    expect(findPreviousPlayableId(order, '3')).toBe('2');
+  });
+
+  it('stays on the first event when already at the top', () => {
+    expect(findPreviousPlayableId(order, '1')).toBe('1');
+  });
+
+  it('falls back to the first event when the loaded id is unknown', () => {
+    expect(findPreviousPlayableId(order, 'not-in-rundown')).toBe('1');
+  });
+});
+
+describe('findNextPlayableId()', () => {
+  const order = ['1', '2', '3'];
+
+  it('returns undefined when there is nothing to play', () => {
+    expect(findNextPlayableId([])).toBeUndefined();
+  });
+
+  it('returns the first event when nothing is loaded', () => {
+    expect(findNextPlayableId(order)).toBe('1');
+  });
+
+  it('returns the following event', () => {
+    expect(findNextPlayableId(order, '1')).toBe('2');
+  });
+
+  it('wraps to the first event from the last', () => {
+    expect(findNextPlayableId(order, '3')).toBe('1');
+  });
+
+  it('falls back to the first event when the loaded id is unknown', () => {
+    expect(findNextPlayableId(order, 'not-in-rundown')).toBe('1');
+  });
+});
+
+describe('findNextPlayableWithCue()', () => {
+  const rundown = makeRundown({
+    order: ['1', '2', '3', '4'],
+    entries: {
+      '1': makeOntimeEvent({ id: '1', cue: 'a' }),
+      '2': makeOntimeEvent({ id: '2', cue: 'b' }),
+      '3': makeOntimeEvent({ id: '3', cue: 'b', skip: true }),
+      '4': makeOntimeEvent({ id: '4', cue: 'b' }),
+    },
+  });
+  const order = ['1', '2', '3', '4'];
+
+  it('finds the next event with the given cue', () => {
+    expect(findNextPlayableWithCue(rundown, order, 'b')?.id).toBe('2');
+  });
+
+  it('skips events which are not playable', () => {
+    expect(findNextPlayableWithCue(rundown, order, 'b', 2)?.id).toBe('4');
+  });
+
+  it('wraps around to the start of the rundown', () => {
+    expect(findNextPlayableWithCue(rundown, order, 'a', 2)?.id).toBe('1');
+  });
+
+  it('excludes the current event unless allowCurrent is set', () => {
+    expect(findNextPlayableWithCue(rundown, order, 'b', 1)?.id).toBe('4');
+    expect(findNextPlayableWithCue(rundown, order, 'b', 1, true)?.id).toBe('2');
+  });
+
+  it('returns undefined when no event carries the cue', () => {
+    expect(findNextPlayableWithCue(rundown, order, 'missing')).toBeUndefined();
+  });
+});
+
+describe('getEventAtIndex()', () => {
+  const rundown = makeRundown({
+    order: ['1', '2'],
+    entries: {
+      '1': makeOntimeEvent({ id: '1' }),
+      '2': makeOntimeEvent({ id: '2' }),
+    },
+  });
+
+  it('returns the event at the given index', () => {
+    expect(getEventAtIndex(rundown, ['1', '2'], 1)?.id).toBe('2');
+  });
+
+  it('returns undefined when the index is out of range', () => {
+    expect(getEventAtIndex(rundown, ['1', '2'], 5)).toBeUndefined();
+    expect(getEventAtIndex(rundown, [], 0)).toBeUndefined();
+  });
+});

packages/utils/src/colour/colour.utils.test.ts

@@ -0,0 +1,89 @@
+import { colourToHex, cssOrHexToColour, hexToColour, isLightColour, mixColours } from './colour.utils';
+
+describe('hexToColour()', () => {
+  it('parses a full length hex', () => {
+    expect(hexToColour('#ff8800')).toStrictEqual({ red: 255, green: 136, blue: 0, alpha: 1 });
+  });
+
+  it('parses a compressed hex by duplicating each digit', () => {
+    expect(hexToColour('#f80')).toStrictEqual(hexToColour('#ff8800'));
+  });
+
+  it('parses the alpha channel of a full length hex', () => {
+    expect(hexToColour('#ff880000')).toStrictEqual({ red: 255, green: 136, blue: 0, alpha: 0 });
+    expect(hexToColour('#ff8800ff')).toStrictEqual({ red: 255, green: 136, blue: 0, alpha: 1 });
+  });
+
+  it('parses the alpha channel of a compressed hex', () => {
+    expect(hexToColour('#f800')).toStrictEqual(hexToColour('#ff880000'));
+  });
+
+  it('is case insensitive', () => {
+    expect(hexToColour('#FF8800')).toStrictEqual(hexToColour('#ff8800'));
+  });
+
+  it('returns null for values which are not a hex colour', () => {
+    // these are the values which reach us from user input
+    for (const invalid of ['', 'red', '#', '#ff', '#fffff', '#ffg', 'ff8800']) {
+      expect(hexToColour(invalid)).toBeNull();
+    }
+  });
+});
+
+describe('colourToHex()', () => {
+  it('pads single digit channels', () => {
+    expect(colourToHex({ red: 0, green: 1, blue: 2, alpha: 1 })).toBe('#000102ff');
+  });
+
+  it('round trips with hexToColour', () => {
+    for (const hex of ['#000000ff', '#ff8800ff', '#ffffffff', '#12345600']) {
+      expect(colourToHex(hexToColour(hex)!)).toBe(hex);
+    }
+  });
+});
+
+describe('cssOrHexToColour()', () => {
+  it('resolves named css colours', () => {
+    expect(cssOrHexToColour('red')).toStrictEqual({ red: 255, green: 0, blue: 0, alpha: 1 });
+  });
+
+  it('resolves named css colours regardless of casing', () => {
+    expect(cssOrHexToColour('CornflowerBlue')).toStrictEqual(cssOrHexToColour('cornflowerblue'));
+  });
+
+  it('delegates hex values to the hex parser', () => {
+    expect(cssOrHexToColour('#f80')).toStrictEqual(hexToColour('#f80'));
+  });
+
+  it('returns null for an unknown colour name', () => {
+    expect(cssOrHexToColour('not-a-colour')).toBeNull();
+    expect(cssOrHexToColour('')).toBeNull();
+  });
+});
+
+describe('mixColours()', () => {
+  const black = { red: 0, green: 0, blue: 0, alpha: 1 };
+  const white = { red: 255, green: 255, blue: 255, alpha: 1 };
+
+  it('defaults to an even mix', () => {
+    expect(mixColours(black, white)).toStrictEqual({ red: 128, green: 128, blue: 128, alpha: 1 });
+  });
+
+  it('weights the first colour by the given proportion', () => {
+    expect(mixColours(black, white, 1)).toStrictEqual({ ...black, alpha: 1 });
+    expect(mixColours(black, white, 0)).toStrictEqual({ ...white, alpha: 1 });
+  });
+});
+
+describe('isLightColour()', () => {
+  it('detects light and dark colours', () => {
+    expect(isLightColour({ red: 255, green: 255, blue: 255, alpha: 1 })).toBe(true);
+    expect(isLightColour({ red: 0, green: 0, blue: 0, alpha: 1 })).toBe(false);
+  });
+
+  it('weights green most heavily, as per the YIQ calculation', () => {
+    // pure green is considered light, pure blue is not
+    expect(isLightColour({ red: 0, green: 255, blue: 0, alpha: 1 })).toBe(true);
+    expect(isLightColour({ red: 0, green: 0, blue: 255, alpha: 1 })).toBe(false);
+  });
+});