fix: keep group visible as header for the running event

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

@@ -2,8 +2,8 @@ import { MaybeString } from 'ontime-types';
 import { RefObject, useCallback, useEffect } from 'react';
 
 function scrollToComponent<ComponentRef extends HTMLElement, ScrollRef extends HTMLElement>(
-  componentRef: RefObject<ComponentRef>,
+  componentRef: RefObject<ComponentRef | null>,
-  scrollRef: RefObject<ScrollRef>,
+  scrollRef: RefObject<ScrollRef | null>,
   topOffset: number,
 ) {
   if (!componentRef.current || !scrollRef.current) {
@@ -21,18 +21,16 @@ interface UseFollowComponentProps {
   followRef: RefObject<HTMLElement | null>;
   scrollRef: RefObject<HTMLElement | null>;
   doFollow: boolean;
-  topOffset?: number;
+  followTrigger: MaybeString; // this would be an entry id or null
-  setScrollFlag?: (newValue: boolean) => void;
+  getTopOffset: () => number;
-  followTrigger?: MaybeString; // this would be an entry id or null
 }
 
 export default function useFollowComponent({
   followRef,
   scrollRef,
   doFollow,
-  topOffset = 100,
-  setScrollFlag,
   followTrigger,
+  getTopOffset,
 }: UseFollowComponentProps) {
   // when trigger moves, view should follow
   useEffect(() => {
@@ -41,25 +39,17 @@ export default function useFollowComponent({
     }
 
     if (followRef.current && scrollRef.current) {
-      setScrollFlag?.(true);
       // Use requestAnimationFrame to ensure the component is fully loaded
       window.requestAnimationFrame(() => {
-        scrollToComponent(followRef as RefObject<HTMLElement>, scrollRef as RefObject<HTMLElement>, topOffset);
+        // resolve the offset after layout, so that measured values are up to date
-        setScrollFlag?.(false);
+        scrollToComponent(followRef, scrollRef, getTopOffset());
       });
     }
-  }, [followTrigger, doFollow, followRef, scrollRef, setScrollFlag, topOffset]);
+  }, [followTrigger, doFollow, followRef, scrollRef, getTopOffset]);
 
-  const scrollToRefComponent = useCallback(
+  const scrollToRefComponent = useCallback(() => {
-    (componentRef = followRef, containerRef = scrollRef, offset = topOffset) => {
+    scrollToComponent(followRef, scrollRef, getTopOffset());
-      if (componentRef && containerRef) {
+  }, [followRef, scrollRef, getTopOffset]);
-        // @ts-expect-error -- we know this are not null
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        scrollToComponent(componentRef!, containerRef!, offset);
-      }
-    },
-    [followRef, scrollRef, topOffset],
-  );
 
   return scrollToRefComponent;
 }

apps/client/src/features/operator/Operator.module.scss

@@ -18,6 +18,12 @@
   padding-bottom: 95vh;
 }
 
+.groupSection {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
 .editPrompt {
   position: fixed;
   z-index: $zindex-dialog;

apps/client/src/features/operator/Operator.tsx

@@ -1,5 +1,5 @@
 import { OntimeView, isOntimeEvent, isOntimeGroup } from 'ontime-types';
-import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import EmptyFill from '../../common/components/state/EmptyFill';
 import EmptyPage from '../../common/components/state/EmptyPage';
@@ -25,7 +25,10 @@ import { OperatorData, useOperatorData } from './useOperatorData';
 
 import style from './Operator.module.scss';
 
-const selectedOffset = 50;
+/** Keeps the running event clear of the list edge when no group header is pinned above it */
+const edgeOffset = 50;
+/** How far the running event may drift from where we placed it before we stop following */
+const followTolerance = 50;
 
 export default function OperatorLoader() {
   const { data, status } = useOperatorData();
@@ -54,11 +57,20 @@ function Operator({ rundown, rundownMetadata, customFields, settings }: Operator
   const [lockAutoScroll, setLockAutoScroll] = useState(false);
   const selectedRef = useRef<HTMLDivElement | null>(null);
   const scrollRef = useRef<HTMLDivElement | null>(null);
+  const stickyHeaderRef = useRef<HTMLDivElement | null>(null);
+
+  // The header height varies with the viewport, so measure it at scroll time.
+  const getTopOffset = useCallback(() => {
+    const header = stickyHeaderRef.current;
+    // Sit right under the pinned header, so it covers the previous event instead of half of it.
+    return header ? header.offsetHeight + 2 : edgeOffset;
+  }, []);
+
   const scrollToComponent = useFollowComponent({
     followRef: selectedRef,
     scrollRef,
     doFollow: !lockAutoScroll,
-    topOffset: selectedOffset,
+    getTopOffset,
     followTrigger: selectedEventId,
   });
 
@@ -82,15 +94,16 @@ function Operator({ rundown, rundownMetadata, customFields, settings }: Operator
 
   // prevent considering automated scrolls as user scrolls
   const handleUserScroll = () => {
-    if (selectedRef?.current && scrollRef?.current) {
+    if (!selectedRef.current || !scrollRef.current) {
-      const selectedRect = selectedRef.current.getBoundingClientRect();
+      return;
-      const scrollerRect = scrollRef.current.getBoundingClientRect();
-      if (selectedRect && scrollerRect) {
-        const distanceFromTop = selectedRect.top - scrollerRect.top;
-        const hasScrolledOutOfThreshold = distanceFromTop < -8 || distanceFromTop > selectedOffset;
-        setLockAutoScroll(hasScrolledOutOfThreshold);
-      }
     }
+
+    const selectedRect = selectedRef.current.getBoundingClientRect();
+    const scrollerRect = scrollRef.current.getBoundingClientRect();
+    // Measure the drift from where an automated scroll would place the event.
+    const distanceFromTop = selectedRect.top - scrollerRect.top - getTopOffset();
+    const hasScrolledOutOfThreshold = distanceFromTop < -8 || distanceFromTop > followTolerance;
+    setLockAutoScroll(hasScrolledOutOfThreshold);
   };
   const throttledHandleScroll = throttle(handleUserScroll, 1000);
 
@@ -186,9 +199,9 @@ function Operator({ rundown, rundownMetadata, customFields, settings }: Operator
               }
 
               return (
-                <Fragment key={entry.id}>
+                <div className={style.groupSection} key={entry.id}>
                   <OperatorGroup
-                    key={entry.id}
+                    ref={isCurrentParent ? stickyHeaderRef : undefined}
                     title={entry.title}
                     colour={entry.colour}
                     count={entry.entries.length}
@@ -239,7 +252,7 @@ function Operator({ rundown, rundownMetadata, customFields, settings }: Operator
                       />
                     );
                   })}
-                </Fragment>
+                </div>
               );
             }
             return null;

apps/client/src/features/operator/operator-group/OperatorGroup.module.scss

@@ -1,6 +1,7 @@
 .group {
   width: 100%;
-  min-height: 2.5rem;
+  /* Fixed: title and meta never wrap, and the group wrapper keeps the list from shrinking the header. */
+  height: 2.5rem;
   padding: 0.4rem 0.75rem;
   border-left: 0.35rem solid var(--group-colour, $gray-500);
   background-color: $gray-1350;
@@ -8,6 +9,11 @@
   font-size: 1.25rem;
   font-weight: 600;
 
+  position: sticky;
+  /* Cover the list padding so rows cannot scroll above the header. */
+  top: -0.25rem;
+  z-index: 1;
+
   display: flex;
   align-items: center;
   gap: 1rem;

apps/client/src/features/operator/operator-group/OperatorGroup.tsx

@@ -1,4 +1,4 @@
-import { CSSProperties, memo } from 'react';
+import { type CSSProperties, type Ref, memo } from 'react';
 
 import { getAccessibleColour } from '../../../common/utils/styleUtils';
 import { formatDuration } from '../../../common/utils/time';
@@ -10,15 +10,16 @@ interface OperatorGroup {
   colour: string;
   count: number;
   duration: number;
+  ref?: Ref<HTMLDivElement>;
 }
 
 export default memo(OperatorGroup);
-function OperatorGroup({ title, colour, count, duration }: OperatorGroup) {
+function OperatorGroup({ title, colour, count, duration, ref }: OperatorGroup) {
   const groupColour = colour || '#929292';
   const groupColours = getAccessibleColour(groupColour);
 
   return (
-    <div className={style.group} style={{ ...groupColours, '--group-colour': groupColour } as CSSProperties}>
+    <div className={style.group} style={{ ...groupColours, '--group-colour': groupColour } as CSSProperties} ref={ref}>
       <span className={style.title}>{title}</span>
       <span className={style.meta}>
         <span>{`${count} ${count === 1 ? 'event' : 'events'}`}</span>

apps/client/src/views/countdown/Countdown.scss

@@ -100,7 +100,20 @@ $item-height: 3.5rem;
     flex-direction: column;
     overflow-y: auto;
 
-    padding-bottom: max(8rem, calc(5rem + env(safe-area-inset-bottom)));
+    padding-bottom: 95vh;
+  }
+
+  /* Flex prevents row margins collapsing and bounds the sticky header to its group. */
+  .sub-section {
+    display: flex;
+    flex-direction: column;
+
+    /* The select view renders the same cards in a flat list. */
+    .sub--group {
+      position: sticky;
+      top: 0;
+      z-index: 1;
+    }
   }
 
   /* ====================== LIST-ITEM ======================*/
@@ -196,9 +209,14 @@ $item-height: 3.5rem;
 
   .sub--group {
     box-shadow: inset 0 0 0 1px var(--user-color, $gray-1325);
-    background:
+    /* The opaque base prevents rows showing through; background shorthand cannot layer this colour. */
+    background-color: var(--background-color-override, $viewer-background-color);
+    background-image:
       linear-gradient(90deg, color-mix(in srgb, var(--user-color, transparent) 18%, transparent), transparent 42%),
-      var(--card-background-color-override, $viewer-card-bg-color);
+      linear-gradient(
+        var(--card-background-color-override, $viewer-card-bg-color),
+        var(--card-background-color-override, $viewer-card-bg-color)
+      );
 
     .sub__binder {
       background: var(--user-color, var(--card-background-color-override, $viewer-card-bg-color));
@@ -230,6 +248,16 @@ $item-height: 3.5rem;
     }
   }
 
+  /* Reserve the green fill for the running event. */
+  .sub--group.sub--live {
+    box-shadow: inset 0 0 0 2px $active-green;
+  }
+
+  /* Keep the armed state quieter than the live ring. */
+  .sub--group.sub--armed {
+    box-shadow: inset 0 0 0 2px $gray-1000;
+  }
+
   .sub__title {
     grid-area: title;
     padding-bottom: 0.5rem;

apps/client/src/views/countdown/CountdownSubscriptions.tsx

@@ -1,6 +1,6 @@
 import { MaybeNumber, OntimeEvent } from 'ontime-types';
 import { dayInMs } from 'ontime-utils';
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { IoPencil } from 'react-icons/io5';
 
 import Button from '../../common/components/buttons/Button';
@@ -22,6 +22,7 @@ import {
   CountdownTarget,
   extendEventData,
   getIsLive,
+  groupSubscriptionTargets,
   isOutsideRange,
   preferredFormat12,
   preferredFormat24,
@@ -48,11 +49,22 @@ export default function CountdownSubscriptions({ subscribedEvents, goToEditMode
   const [lockAutoScroll, setLockAutoScroll] = useState(false);
   const selectedRef = useRef<HTMLDivElement | null>(null);
   const scrollRef = useRef<HTMLDivElement | null>(null);
+  const stickyHeaderRef = useRef<HTMLDivElement | null>(null);
+
+  const sections = useMemo(() => groupSubscriptionTargets(subscribedEvents), [subscribedEvents]);
+
+  // Responsive sizing and wrapped titles make the sticky header height variable, so measure it at scroll time.
+  const getStickyOffset = useCallback(() => {
+    const header = stickyHeaderRef.current;
+    // Preserve the combined margins between the header and running event.
+    return header ? header.offsetHeight + 4 : 0;
+  }, []);
+
   const scrollToComponent = useFollowComponent({
     followRef: selectedRef,
     scrollRef,
     doFollow: !lockAutoScroll,
-    topOffset: 0,
+    getTopOffset: getStickyOffset,
     followTrigger: selectedEventId,
   });
 
@@ -75,15 +87,16 @@ export default function CountdownSubscriptions({ subscribedEvents, goToEditMode
 
   // prevent considering automated scrolls as user scrolls
   const handleUserScroll = () => {
-    if (selectedRef?.current && scrollRef?.current) {
+    if (!selectedRef.current || !scrollRef.current) {
-      const selectedRect = selectedRef.current.getBoundingClientRect();
+      return;
-      const scrollerRect = scrollRef.current.getBoundingClientRect();
-      if (selectedRect && scrollerRect) {
-        const distanceFromTop = selectedRect.top - scrollerRect.top;
-        const hasScrolledOutOfThreshold = distanceFromTop < -8 || distanceFromTop > 50;
-        setLockAutoScroll(hasScrolledOutOfThreshold);
-      }
     }
+
+    const selectedRect = selectedRef.current.getBoundingClientRect();
+    const scrollerRect = scrollRef.current.getBoundingClientRect();
+    // Keep the threshold relative to the visible rows below the sticky header.
+    const distanceFromTop = selectedRect.top - scrollerRect.top - getStickyOffset();
+    const hasScrolledOutOfThreshold = distanceFromTop < -8 || distanceFromTop > 50;
+    setLockAutoScroll(hasScrolledOutOfThreshold);
   };
   const throttledHandleScroll = throttle(handleUserScroll, 1000);
 
@@ -98,41 +111,63 @@ export default function CountdownSubscriptions({ subscribedEvents, goToEditMode
 
   return (
     <div className='list-container' onWheel={handleScroll} onTouchMove={handleScroll} ref={scrollRef}>
-      {subscribedEvents.map((event) => {
+      {sections.map((section) => {
-        // while a group is live, surface the running event's title as the secondary line
+        const rows = section.group ? [section.group, ...section.events] : section.events;
-        const liveTitle = event.isGroup && event.liveEntry ? event.liveEntry.title : undefined;
+        // the running event anchors the scroll, the group header stays pinned above it
-        const secondaryData = liveTitle ?? getPropertyValue(event, secondarySource);
+        const anchorId = section.events.find((event) => getIsLive(event.id, selectedEventId, playback))?.id ?? null;
-        const isGroupedEvent = !event.isGroup && Boolean(event.parent);
+
-        const activeEntryId = event.isGroup ? (event.liveEntry?.id ?? event.targetId) : event.id;
-        // a subscribed group is live when any of its children is the selected/running event
-        const isLive = activeEntryId ? getIsLive(activeEntryId, selectedEventId, playback) : false;
-        const isArmed = !isLive && activeEntryId === selectedEventId;
-        const countdownEvent = extendEventData(event, currentDay, actualStart, plannedStart, offset, mode, reportData);
-        const displayTitle = getPropertyValue(event, mainSource ?? 'title');
         return (
-          <div
+          <div key={section.group?.id ?? rows[0].id} className='sub-section'>
-            key={event.id}
+            {rows.map((event) => {
-            ref={isLive ? selectedRef : undefined}
+              // while a group is live, surface the running event's title as the secondary line
-            className={cx([
+              const liveTitle = event.isGroup && event.liveEntry ? event.liveEntry.title : undefined;
-              'sub',
+              const secondaryData = liveTitle ?? getPropertyValue(event, secondarySource);
-              isLive && 'sub--live',
+              const isGroupedEvent = !event.isGroup && Boolean(event.parent);
-              isArmed && 'sub--armed',
+              const activeEntryId = event.isGroup ? (event.liveEntry?.id ?? event.targetId) : event.id;
-              event.isGroup && 'sub--group',
+              // a subscribed group is live when any of its children is the selected/running event
-              isGroupedEvent && 'sub--in-group',
+              const isLive = activeEntryId ? getIsLive(activeEntryId, selectedEventId, playback) : false;
-            ])}
+              const isArmed = !isLive && activeEntryId === selectedEventId;
-            data-testid={event.cue}
+              // only ever hand the ref to a single row, sharing it would null it out on the next commit
-          >
+              const isAnchor = isLive && (anchorId === null || event.id === anchorId);
-            <div
+              const rowRef = isAnchor ? selectedRef : event.isGroup && anchorId ? stickyHeaderRef : undefined;
-              className='sub__binder'
+              const countdownEvent = extendEventData(
-              style={{ '--user-color': event.colour, '--group-color': event.groupColour ?? 'transparent' }}
+                event,
-            />
+                currentDay,
-            <ScheduleTime event={countdownEvent} showExpected={showExpected} />
+                actualStart,
-            <SubscriptionStatus event={countdownEvent} />
+                plannedStart,
-            <div className={cx(['sub__title', !displayTitle && 'subdued'])}>
+                offset,
-              {event.isGroup && <span className='sub__eyebrow'>Group</span>}
+                mode,
-              {displayTitle}
+                reportData,
-            </div>
+              );
-            {secondaryData && <div className='sub__secondary'>{secondaryData}</div>}
+              const displayTitle = getPropertyValue(event, mainSource ?? 'title');
+
+              return (
+                <div
+                  key={event.id}
+                  ref={rowRef}
+                  className={cx([
+                    'sub',
+                    isLive && 'sub--live',
+                    isArmed && 'sub--armed',
+                    event.isGroup && 'sub--group',
+                    isGroupedEvent && 'sub--in-group',
+                  ])}
+                  data-testid={event.cue}
+                >
+                  <div
+                    className='sub__binder'
+                    style={{ '--user-color': event.colour, '--group-color': event.groupColour ?? 'transparent' }}
+                  />
+                  <ScheduleTime event={countdownEvent} showExpected={showExpected} />
+                  <SubscriptionStatus event={countdownEvent} />
+                  <div className={cx(['sub__title', !displayTitle && 'subdued'])}>
+                    {event.isGroup && <span className='sub__eyebrow'>Group</span>}
+                    {displayTitle}
+                  </div>
+                  {secondaryData && <div className='sub__secondary'>{secondaryData}</div>}
+                </div>
+              );
+            })}
           </div>
         );
       })}

apps/client/src/views/countdown/countdown.utils.test.ts

@@ -1,7 +1,7 @@
 import { OntimeEntry, OntimeEvent, OntimeGroup, SupportedEntry } from 'ontime-types';
 
 import { ExtendedEntry } from '../../common/utils/rundownMetadata';
-import { resolveSubscriptionTarget } from './countdown.utils';
+import { CountdownTarget, groupSubscriptionTargets, resolveSubscriptionTarget } from './countdown.utils';
 
 /**
  * Minimal builders for the extended (metadata enriched) entries the countdown view consumes.
@@ -126,3 +126,89 @@ describe('resolveSubscriptionTarget()', () => {
     expect(result?.liveEntry).toBeNull();
   });
 });
+
+describe('groupSubscriptionTargets()', () => {
+  /**
+   * Resolves a group the same way the view does, so that the tests exercise the real target shape
+   * (a resolved group carries type Event, so the helper cannot rely on the entry type)
+   */
+  function resolveGroup(group: ExtendedEntry<OntimeGroup>, flat: ExtendedEntry<OntimeEntry>[]): CountdownTarget {
+    const resolved = resolveSubscriptionTarget(group, flat);
+    if (resolved === null) {
+      throw new Error('test setup: group has no playable children');
+    }
+    return resolved;
+  }
+
+  it('returns no sections for an empty subscription list', () => {
+    expect(groupSubscriptionTargets([])).toEqual([]);
+  });
+
+  it('gives each ungrouped event its own section', () => {
+    const e1 = makeEvent({ id: 'e1' });
+    const e2 = makeEvent({ id: 'e2' });
+
+    expect(groupSubscriptionTargets([e1, e2])).toEqual([
+      { group: null, events: [e1] },
+      { group: null, events: [e2] },
+    ]);
+  });
+
+  it('absorbs the children of a subscribed group into its section', () => {
+    const group = makeGroup({ id: 'g1' });
+    const c1 = makeEvent({ id: 'c1', parent: 'g1' });
+    const c2 = makeEvent({ id: 'c2', parent: 'g1' });
+    const resolved = resolveGroup(group, [group, c1, c2]);
+
+    expect(groupSubscriptionTargets([resolved, c1, c2])).toEqual([{ group: resolved, events: [c1, c2] }]);
+  });
+
+  it('keeps a subscribed group with no subscribed children as an empty section', () => {
+    const group = makeGroup({ id: 'g1' });
+    const c1 = makeEvent({ id: 'c1', parent: 'g1' });
+    const resolved = resolveGroup(group, [group, c1]);
+
+    expect(groupSubscriptionTargets([resolved])).toEqual([{ group: resolved, events: [] }]);
+  });
+
+  it('does not absorb an event which belongs to a different group', () => {
+    const group1 = makeGroup({ id: 'g1' });
+    const c1 = makeEvent({ id: 'c1', parent: 'g1' });
+    const group2 = makeGroup({ id: 'g2' });
+    const c2 = makeEvent({ id: 'c2', parent: 'g2' });
+    const flat = [group1, c1, group2, c2];
+    const resolved1 = resolveGroup(group1, flat);
+    const resolved2 = resolveGroup(group2, flat);
+
+    expect(groupSubscriptionTargets([resolved1, c1, resolved2, c2])).toEqual([
+      { group: resolved1, events: [c1] },
+      { group: resolved2, events: [c2] },
+    ]);
+  });
+
+  it('does not absorb an event whose parent group is not subscribed', () => {
+    const group1 = makeGroup({ id: 'g1' });
+    const c1 = makeEvent({ id: 'c1', parent: 'g1' });
+    const group2 = makeGroup({ id: 'g2' });
+    const c2 = makeEvent({ id: 'c2', parent: 'g2' });
+    const resolved1 = resolveGroup(group1, [group1, c1, group2, c2]);
+
+    // only the first group is subscribed, so the second group's child stands alone
+    expect(groupSubscriptionTargets([resolved1, c1, c2])).toEqual([
+      { group: resolved1, events: [c1] },
+      { group: null, events: [c2] },
+    ]);
+  });
+
+  it('closes a section when an ungrouped event follows a group', () => {
+    const group = makeGroup({ id: 'g1' });
+    const c1 = makeEvent({ id: 'c1', parent: 'g1' });
+    const e1 = makeEvent({ id: 'e1' });
+    const resolved = resolveGroup(group, [group, c1]);
+
+    expect(groupSubscriptionTargets([resolved, c1, e1])).toEqual([
+      { group: resolved, events: [c1] },
+      { group: null, events: [e1] },
+    ]);
+  });
+});

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

@@ -252,6 +252,42 @@ export function resolveSubscriptionTarget(
   };
 }
 
+/**
+ * A subscribed group along with the subscribed events which belong to it.
+ * Events without a subscribed parent group form their own section with no group.
+ */
+export type CountdownSection = {
+  group: CountdownTarget | null;
+  events: CountdownTarget[];
+};
+
+/**
+ * Folds the flat, rundown ordered subscription targets into sections.
+ * A group opens a section which absorbs the following targets that declare it as parent,
+ * which allows the group to be rendered as a sticky header for its own events.
+ */
+export function groupSubscriptionTargets(targets: CountdownTarget[]): CountdownSection[] {
+  const sections: CountdownSection[] = [];
+
+  for (const target of targets) {
+    // resolveSubscriptionTarget spreads the first child, so we cannot rely on the entry type here
+    if (target.isGroup) {
+      sections.push({ group: target, events: [] });
+      continue;
+    }
+
+    const previousSection = sections.at(-1);
+    if (previousSection?.group?.id === target.parent) {
+      previousSection.events.push(target);
+      continue;
+    }
+
+    sections.push({ group: null, events: [target] });
+  }
+
+  return sections;
+}
+
 export function extendEventData(
   event: CountdownTarget,
   currentDay: number,

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

@@ -195,24 +195,6 @@
     font-weight: 600;
   }
 
-  .sound-prompt {
-    position: absolute;
-    bottom: $view-block-padding;
-    left: $view-inline-padding;
-    padding: 0.5em 0.75em;
-    border-radius: $element-border-radius;
-    background-color: $viewer-card-bg-color;
-    color: $viewer-secondary-color;
-    font-size: $timer-label-size;
-    text-transform: uppercase;
-    pointer-events: none;
-    transition: opacity $viewer-transition-time;
-
-    &--hidden {
-      opacity: 0;
-    }
-  }
-
   /* =================== LOGO ===================*/
   .logo {
     position: absolute;

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

@@ -8,7 +8,6 @@ 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 { useFadeOutOnInactivity } from '../../common/hooks/useFadeOutOnInactivity';
 import { useTimerSocket } from '../../common/hooks/useSocket';
 import { useWindowTitle } from '../../common/hooks/useWindowTitle';
 import { cx } from '../../common/utils/styleUtils';
@@ -31,7 +30,6 @@ import {
   getTotalTime,
 } from './timer.utils';
 import { TimerData, useTimerData } from './useTimerData';
-import { useTimerSound } from './useTimerSound';
 
 import './Timer.scss';
 
@@ -68,7 +66,6 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
     freezeOvertime,
     freezeMessage,
     hidePhase,
-    endSound,
     font,
     keyColour,
     timerColour,
@@ -78,8 +75,6 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
   const { getLocalizedString } = useTranslation();
   const localisedMinutes = getLocalizedString('common.minutes');
 
-  const showSoundPrompt = useTimerSound(time.phase, endSound);
-
   // gather modifiers
   const viewTimerType = timerType ?? timerTypeNow;
   const showOverlay = getShowMessage(message.timer);
@@ -161,8 +156,6 @@ function Timer({ customFields, projectData, isMirrored, settings, viewSettings,
 
       <ViewParamsEditor target={OntimeView.Timer} viewOptions={timerOptions} />
 
-      {showSoundPrompt && <SoundPermissionPrompt />}
-
       <div className={cx(['blackout', message.timer.blackout && 'blackout--active'])} />
 
       {!hideMessage && (
@@ -234,13 +227,3 @@ function TimerAutoTickingClock({ clockFormat }: { clockFormat: MaybeString }) {
     </div>
   );
 }
-
-function SoundPermissionPrompt() {
-  const isUserActive = useFadeOutOnInactivity(true);
-
-  return (
-    <div className={cx(['sound-prompt', !isUserActive && 'sound-prompt--hidden'])} aria-live='polite'>
-      Interact with the page (click/tap or press any key) to enable sound
-    </div>
-  );
-}

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

@@ -1,34 +0,0 @@
-import { TimerPhase } from 'ontime-types';
-
-import { shouldPlayEndSound } from '../timer.utils';
-
-describe('shouldPlayEndSound()', () => {
-  test.each([TimerPhase.Default, TimerPhase.Warning, TimerPhase.Danger])(
-    'sounds when a running timer goes into overtime from %s',
-    (previousPhase) => {
-      expect(shouldPlayEndSound(previousPhase, TimerPhase.Overtime)).toBe(true);
-    },
-  );
-
-  it('stays silent on the first phase we see, a client could be joining mid-overtime', () => {
-    expect(shouldPlayEndSound(null, TimerPhase.Overtime)).toBe(false);
-  });
-
-  it('stays silent when the phase was reset, a reload during overtime starts from none', () => {
-    expect(shouldPlayEndSound(TimerPhase.None, TimerPhase.Overtime)).toBe(false);
-  });
-
-  it('stays silent for a roll timer waiting to start', () => {
-    expect(shouldPlayEndSound(TimerPhase.Pending, TimerPhase.Overtime)).toBe(false);
-  });
-
-  it('sounds once, not on every update while in overtime', () => {
-    expect(shouldPlayEndSound(TimerPhase.Overtime, TimerPhase.Overtime)).toBe(false);
-  });
-
-  it('stays silent on phases which are not the end of the timer', () => {
-    expect(shouldPlayEndSound(TimerPhase.Default, TimerPhase.Warning)).toBe(false);
-    expect(shouldPlayEndSound(TimerPhase.Warning, TimerPhase.Danger)).toBe(false);
-    expect(shouldPlayEndSound(TimerPhase.Overtime, TimerPhase.None)).toBe(false);
-  });
-});

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

@@ -16,7 +16,6 @@ import { ViewOption } from '../../common/components/view-params-editor/viewParam
 import { makeOptionsFromCustomFields } from '../../common/components/view-params-editor/viewParams.utils';
 import { PresetContext } from '../../common/context/PresetContext';
 import { isStringBoolean, makeColourString } from '../common/viewUtils';
-import { endSoundOptions, isEndSound, type EndSound } from './timer.sound';
 
 // manually match the properties of TimerType excluding the None
 const timerDisplayOptions: SelectOption[] = [
@@ -77,15 +76,6 @@ export const getTimerOptions = (timeFormat: string, customFields: CustomFields):
           type: 'boolean',
           defaultValue: false,
         },
-        {
-          id: 'endSound',
-          title: 'Play sound on timer end',
-          description:
-            'Plays a sound in this screen when the timer reaches zero. The screen must be interacted with once before it can play',
-          type: 'option',
-          values: endSoundOptions,
-          defaultValue: 'none',
-        },
       ],
     },
     {
@@ -203,7 +193,6 @@ type TimerOptions = {
   freezeOvertime: boolean;
   freezeMessage: string;
   hidePhase: boolean;
-  endSound: EndSound;
   font?: string;
   keyColour?: string;
   timerColour?: string;
@@ -219,7 +208,6 @@ function getOptionsFromParams(searchParams: URLSearchParams, defaultValues?: URL
 
   // Get timerType from either source
   const timerType = validateTimerType(getValue('timerType'), TimerType.None);
-  const endSoundValue = getValue('endSound');
 
   return {
     hideClock: isStringBoolean(getValue('hideClock')),
@@ -239,7 +227,6 @@ function getOptionsFromParams(searchParams: URLSearchParams, defaultValues?: URL
     freezeOvertime: isStringBoolean(getValue('freezeOvertime')),
     freezeMessage: getValue('freezeMessage') ?? '',
     hidePhase: isStringBoolean(getValue('hidePhase')),
-    endSound: isEndSound(endSoundValue) ? endSoundValue : 'none',
 
     font: getValue('font') ?? undefined,
     keyColour: makeColourString(getValue('keyColour')),

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

@@ -1,20 +0,0 @@
-import arpeggio from '../../assets/sounds/arpeggio.wav';
-import bell from '../../assets/sounds/bell.wav';
-import chime from '../../assets/sounds/chime.wav';
-import type { SelectOption } from '../../common/components/select/Select';
-
-// synthesised tones bundled with the app, no external source or licence to track
-export const endSoundSources = { chime, bell, arpeggio } as const;
-
-export type EndSound = 'none' | keyof typeof endSoundSources;
-
-export const endSoundOptions: SelectOption[] = [
-  { value: 'none', label: 'None' },
-  { value: 'chime', label: 'Chime' },
-  { value: 'bell', label: 'Bell' },
-  { value: 'arpeggio', label: 'Arpeggio' },
-];
-
-export function isEndSound(value: string | null): value is EndSound {
-  return value === 'none' || value === 'chime' || value === 'bell' || value === 'arpeggio';
-}

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

@@ -189,18 +189,3 @@ export function getCardData(
     nextSecondary,
   };
 }
-
-/**
- * Whether the end of timer sound should play for a given phase transition
- * We only sound the transition into overtime from a phase that was already counting,
- * which keeps a client that connects or reloads mid-overtime silent
- */
-export function shouldPlayEndSound(previousPhase: TimerPhase | null, phase: TimerPhase): boolean {
-  if (phase !== TimerPhase.Overtime) {
-    return false;
-  }
-
-  return (
-    previousPhase === TimerPhase.Default || previousPhase === TimerPhase.Warning || previousPhase === TimerPhase.Danger
-  );
-}

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

@@ -1,99 +0,0 @@
-import { TimerPhase } from 'ontime-types';
-import { useEffect, useRef, useState } from 'react';
-
-import { endSoundSources, type EndSound } from './timer.sound';
-import { shouldPlayEndSound } from './timer.utils';
-
-/**
- * Plays a sound when the timer reaches its end
- *
- * Browsers reject playback until the document has been interacted with, and that permission
- * is lost on every page load. Since a timer screen is typically left unattended, we prime the
- * audio element on the first interaction and let the view prompt for one if it never comes.
- * Safari grants the permission per element, so priming has to call play() on this element from
- * inside the event handler, it is not enough to know that an interaction happened.
- */
-export function useTimerSound(phase: TimerPhase, sound: EndSound): boolean {
-  const audioRef = useRef<HTMLAudioElement | null>(null);
-  const previousPhaseRef = useRef<TimerPhase | null>(null);
-  const [isArmed, setIsArmed] = useState(false);
-
-  const enabled = sound !== 'none';
-
-  // Create and clean up the audio element; changing sounds requires re-arming it in Safari.
-  useEffect(() => {
-    setIsArmed(false);
-
-    if (sound === 'none') {
-      return;
-    }
-
-    const audio = new Audio(endSoundSources[sound]);
-    audioRef.current = audio;
-
-    return () => {
-      audio.pause();
-      audioRef.current = null;
-    };
-  }, [sound]);
-
-  // Listen for user interaction until muted playback succeeds and arms the selected audio element.
-  useEffect(() => {
-    if (!enabled || isArmed) {
-      return;
-    }
-
-    const controller = new AbortController();
-    const prime = () => {
-      const audio = audioRef.current;
-      if (!audio) {
-        return;
-      }
-
-      const wasMuted = audio.muted;
-      audio.muted = true;
-      audio
-        .play()
-        .then(() => {
-          if (audioRef.current !== audio) {
-            return;
-          }
-          audio.pause();
-          audio.currentTime = 0;
-          setIsArmed(true);
-        })
-        .catch(() => {
-          // playback is still blocked, a later interaction will try again
-        })
-        .finally(() => {
-          audio.muted = wasMuted;
-        });
-    };
-
-    document.addEventListener('pointerdown', prime, { capture: true, signal: controller.signal });
-    document.addEventListener('keydown', prime, { capture: true, signal: controller.signal });
-
-    return () => {
-      controller.abort();
-    };
-  }, [enabled, isArmed]);
-
-  // Track phase transitions and play only when a running timer enters overtime.
-  useEffect(() => {
-    const previousPhase = previousPhaseRef.current;
-    previousPhaseRef.current = phase;
-
-    if (!enabled || !shouldPlayEndSound(previousPhase, phase)) {
-      return;
-    }
-    const audio = audioRef.current;
-    if (!audio) return;
-
-    audio.currentTime = 0;
-    audio.play().catch(() => {
-      // the screen has not been interacted with, the view shows a prompt for it
-    });
-  }, [enabled, phase]);
-
-  return enabled && !isArmed;
-}

docs/agent-guides/code-quality.md

@@ -36,10 +36,6 @@ Remove comments that:
 
 Update adjacent comments with code. Stale comments are defects.
 
-Add a short comment immediately above every React `useEffect` describing the external synchronization or lifecycle
-responsibility it owns. Explain non-obvious reasons or constraints when they matter; for files with multiple effects, a
-brief responsibility label is useful even when the mechanics are straightforward.
-
 ## Naming and types
 
 - Prefer Ontime terms over vague `data`, `result`, `item`.