From bb8f1475756bf731c4996777ca65072fcedd20fa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 18 Aug 2026 18:24:05 +0000
Subject: [PATCH] fix(teleprompter): keep the transport row fixed and label
 every control

The follow control was rendered only while the follow could be re-engaged,
so it appeared and vanished mid show and moved every control after it. An
operator reaching for pause would press whatever had slid under their
finger. It is now always present and goes disabled when there is nothing to
re-engage, which is how the rest of the row already behaved.

The controls also could not explain themselves: the follow target in
particular is not a guessable icon. Each one now carries a tooltip naming
the action and its key, using the shared Tooltip the editor uses.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cb8RVPNQ2ETPJxdy4b8CHf
---
 .../src/views/teleprompter/Teleprompter.tsx   |   2 +-
 .../control-overlay/ControlOverlay.tsx        | 123 ++++++++++++------
 e2e/tests/features/215-teleprompter.spec.ts   |  21 +++
 3 files changed, 105 insertions(+), 41 deletions(-)

diff --git a/apps/client/src/views/teleprompter/Teleprompter.tsx b/apps/client/src/views/teleprompter/Teleprompter.tsx
index c2f71ea2a..747576f37 100644
--- a/apps/client/src/views/teleprompter/Teleprompter.tsx
+++ b/apps/client/src/views/teleprompter/Teleprompter.tsx
@@ -161,7 +161,7 @@ function Teleprompter({ rundown, rundownMetadata, customFields }: TeleprompterDa
           <ControlOverlay
             isRunning={isRunning}
             speed={speed}
-            followLocked={followLocked && options.followLoaded}
+            canReengageFollow={followLocked && options.followLoaded}
             atEnd={atEnd}
             controller={controller}
             onToggleHelp={handleToggleHelp}
diff --git a/apps/client/src/views/teleprompter/control-overlay/ControlOverlay.tsx b/apps/client/src/views/teleprompter/control-overlay/ControlOverlay.tsx
index af18e612f..d8eeb2a0e 100644
--- a/apps/client/src/views/teleprompter/control-overlay/ControlOverlay.tsx
+++ b/apps/client/src/views/teleprompter/control-overlay/ControlOverlay.tsx
@@ -2,6 +2,7 @@ import type { MouseEvent } from 'react';
 import { IoAdd, IoArrowUp, IoHelpCircleOutline, IoLocate, IoPause, IoPlay, IoRemove } from 'react-icons/io5';
 
 import IconButton from '../../../common/components/buttons/IconButton';
+import Tooltip from '../../../common/components/tooltip/Tooltip';
 import { useFadeOutOnInactivity } from '../../../common/hooks/useFadeOutOnInactivity';
 import { cx } from '../../../common/utils/styleUtils';
 import { SPEED_STEP } from '../teleprompter.scroll';
@@ -10,7 +11,8 @@ import type { TeleprompterController } from '../teleprompter.types';
 interface ControlOverlayProps {
   isRunning: boolean;
   speed: number;
-  followLocked: boolean;
+  /** whether the follow can be re-engaged: it is off while already following */
+  canReengageFollow: boolean;
   atEnd: boolean;
   controller: TeleprompterController;
   onToggleHelp: () => void;
@@ -23,11 +25,16 @@ interface ControlOverlayProps {
  * Visibility follows the same rule as the rest of Ontime's floating chrome: it
  * fades once the operator stops moving, so it leaves the talent's eyeline
  * without needing to know whether the script happens to be rolling.
+ *
+ * Every control is present for the life of the view and goes disabled when it
+ * has nothing to do. A control which comes and goes moves every control after
+ * it, so the operator reaches for pause during a show and presses whatever slid
+ * under their finger instead.
  */
 export default function ControlOverlay({
   isRunning,
   speed,
-  followLocked,
+  canReengageFollow,
   atEnd,
   controller,
   onToggleHelp,
@@ -50,47 +57,67 @@ export default function ControlOverlay({
 
   return (
     <div className={cx(['teleprompter__controls', !isActive && 'teleprompter__controls--idle'])}>
-      <IconButton
-        variant='subtle-white'
-        size='large'
-        onClick={press(controller.togglePlay)}
-        data-testid='teleprompter-play'
-        aria-label={isRunning ? 'Pause' : 'Play'}
+      <Tooltip
+        text={isRunning ? 'Pause (Space)' : 'Play (Space)'}
+        render={
+          <IconButton
+            variant='subtle-white'
+            size='large'
+            onClick={press(controller.togglePlay)}
+            data-testid='teleprompter-play'
+            aria-label={isRunning ? 'Pause' : 'Play'}
+          />
+        }
       >
         {isRunning ? <IoPause /> : <IoPlay />}
-      </IconButton>
+      </Tooltip>
 
-      <IconButton
-        variant='subtle-white'
-        size='large'
-        onClick={press(() => controller.changeSpeed(-SPEED_STEP))}
-        aria-label='Slow down'
+      <Tooltip
+        text='Slow down (Left arrow)'
+        render={
+          <IconButton
+            variant='subtle-white'
+            size='large'
+            onClick={press(() => controller.changeSpeed(-SPEED_STEP))}
+            aria-label='Slow down'
+          />
+        }
       >
         <IoRemove />
-      </IconButton>
+      </Tooltip>
 
       <div className='teleprompter__speed' data-testid='teleprompter-speed'>
         {speed}
         <span className='teleprompter__speed-unit'>lpm</span>
       </div>
 
-      <IconButton
-        variant='subtle-white'
-        size='large'
-        onClick={press(() => controller.changeSpeed(SPEED_STEP))}
-        aria-label='Speed up'
+      <Tooltip
+        text='Speed up (Right arrow)'
+        render={
+          <IconButton
+            variant='subtle-white'
+            size='large'
+            onClick={press(() => controller.changeSpeed(SPEED_STEP))}
+            aria-label='Speed up'
+          />
+        }
       >
         <IoAdd />
-      </IconButton>
+      </Tooltip>
 
-      <IconButton
-        variant={atEnd ? 'primary' : 'subtle-white'}
-        size='large'
-        onClick={press(() => controller.rewind())}
-        aria-label='Rewind to top'
+      <Tooltip
+        text='Rewind to the top (Home)'
+        render={
+          <IconButton
+            variant={atEnd ? 'primary' : 'subtle-white'}
+            size='large'
+            onClick={press(() => controller.rewind())}
+            aria-label='Rewind to top'
+          />
+        }
       >
         <IoArrowUp />
-      </IconButton>
+      </Tooltip>
 
       {/*
         The operator view solves this with its own FollowButton, a labelled pill
@@ -98,21 +125,37 @@ export default function ControlOverlay({
         two would land on top of each other. Same icon and same job, folded into
         the transport rather than floating separately.
       */}
-      {followLocked && (
-        <IconButton
-          variant='primary'
-          size='large'
-          onClick={press(controller.reengageFollow)}
-          data-testid='teleprompter-follow'
-          aria-label='Follow the loaded event'
-        >
-          <IoLocate />
-        </IconButton>
-      )}
+      <Tooltip
+        text={
+          canReengageFollow ? 'Jump back to the loaded event and follow it again (L)' : 'Following the loaded event'
+        }
+        render={
+          <IconButton
+            variant={canReengageFollow ? 'primary' : 'subtle-white'}
+            size='large'
+            disabled={!canReengageFollow}
+            onClick={press(controller.reengageFollow)}
+            data-testid='teleprompter-follow'
+            aria-label='Follow the loaded event'
+          />
+        }
+      >
+        <IoLocate />
+      </Tooltip>
 
-      <IconButton variant='subtle-white' size='large' onClick={press(onToggleHelp)} aria-label='Keyboard shortcuts'>
+      <Tooltip
+        text='Keyboard shortcuts (?)'
+        render={
+          <IconButton
+            variant='subtle-white'
+            size='large'
+            onClick={press(onToggleHelp)}
+            aria-label='Keyboard shortcuts'
+          />
+        }
+      >
         <IoHelpCircleOutline />
-      </IconButton>
+      </Tooltip>
     </div>
   );
 }
diff --git a/e2e/tests/features/215-teleprompter.spec.ts b/e2e/tests/features/215-teleprompter.spec.ts
index 73a877e25..e612f223c 100644
--- a/e2e/tests/features/215-teleprompter.spec.ts
+++ b/e2e/tests/features/215-teleprompter.spec.ts
@@ -116,6 +116,27 @@ test.describe('teleprompter', () => {
     expect(slower).toBe(before);
   });
 
+  test('keeps every transport control in place', async ({ page }) => {
+    // a control which appears mid show moves the ones after it, and the operator
+    // reaches for pause and presses whatever slid under their finger instead
+    await page.goto(teleprompterUrl);
+    await expect(scroller(page)).toBeVisible();
+
+    const controls = page.locator('.teleprompter__controls button');
+    const follow = page.getByTestId('teleprompter-follow');
+
+    await expect(controls).toHaveCount(6);
+    await expect(follow).toBeVisible();
+    await expect(follow).toBeDisabled();
+
+    // taking over by hand offers the follow back, without restacking the row
+    await page.mouse.move(640, 300);
+    await page.mouse.wheel(0, 200);
+
+    await expect(controls).toHaveCount(6);
+    await expect(follow).toBeVisible();
+  });
+
   test('f mirrors the view for a beam splitter rig', async ({ page }) => {
     await page.goto(teleprompterUrl);
     await expect(scroller(page)).toBeVisible();