feat(blueprints): Add blueprint interface methods for T-Timer estimate management

Add three new methods to IPlaylistTTimer interface:
- clearEstimate() - Clear both manual estimates and anchor parts
- setEstimateAnchorPart(partId) - Set anchor part for automatic calculation
- setEstimateTime(time, paused?) - Manually set estimate as timestamp
- setEstimateDuration(duration, paused?) - Manually set estimate as duration

When anchor part is set, automatically queues RecalculateTTimerEstimates job.
Manual estimates clear anchor parts and vice versa.

Updated TTimersService to accept JobContext for job queueing capability.
Updated all blueprint context instantiations and tests.

Author: rjmunro

packages/blueprints-integration/src/context/tTimersContext.ts

@@ -71,6 +71,42 @@ export interface IPlaylistTTimer {
 	 * @returns True if the timer was restarted, false if it could not be restarted
 	 */
 	restart(): boolean
+
+	/**
+	 * Clear any estimate (manual or anchor-based) for this timer
+	 * This removes both manual estimates set via setEstimateTime/setEstimateDuration
+	 * and automatic estimates based on anchor parts set via setEstimateAnchorPart.
+	 */
+	clearEstimate(): void
+
+	/**
+	 * Set the anchor part for automatic estimate calculation
+	 * When set, the server automatically calculates when we expect to reach this part
+	 * based on remaining part durations, and updates the estimate accordingly.
+	 * Clears any manual estimate set via setEstimateTime/setEstimateDuration.
+	 * @param partId The ID of the part to use as timing anchor
+	 */
+	setEstimateAnchorPart(partId: string): void
+
+	/**
+	 * Manually set the estimate as an absolute timestamp
+	 * Use this when you have custom logic for calculating when you expect to reach a timing point.
+	 * Clears any anchor part set via setAnchorPart.
+	 * @param time Unix timestamp (milliseconds) when we expect to reach the timing point
+	 * @param paused If true, we're currently delayed/pushing (estimate won't update with time passing).
+	 *               If false (default), we're progressing normally (estimate counts down in real-time).
+	 */
+	setEstimateTime(time: number, paused?: boolean): void
+
+	/**
+	 * Manually set the estimate as a relative duration from now
+	 * Use this when you want to express the estimate as "X milliseconds from now".
+	 * Clears any anchor part set via setAnchorPart.
+	 * @param duration Milliseconds until we expect to reach the timing point
+	 * @param paused If true, we're currently delayed/pushing (estimate won't update with time passing).
+	 *               If false (default), we're progressing normally (estimate counts down in real-time).
+	 */
+	setEstimateDuration(duration: number, paused?: boolean): void
 }
 
 export type IPlaylistTTimerState =

packages/job-worker/src/blueprints/context/OnSetAsNextContext.ts

@@ -50,7 +50,7 @@ export class OnSetAsNextContext
 		public readonly manuallySelected: boolean
 	) {
 		super(contextInfo, context, showStyle, watchedPackages)
-		this.#tTimersService = new TTimersService(playoutModel)
+		this.#tTimersService = new TTimersService(playoutModel, context)
 	}
 
 	public get quickLoopInfo(): BlueprintQuickLookInfo | null {

packages/job-worker/src/blueprints/context/OnTakeContext.ts

@@ -66,7 +66,7 @@ export class OnTakeContext extends ShowStyleUserContext implements IOnTakeContex
 	) {
 		super(contextInfo, _context, showStyle, watchedPackages)
 		this.isTakeAborted = false
-		this.#tTimersService = new TTimersService(_playoutModel)
+		this.#tTimersService = new TTimersService(_playoutModel, _context)
 	}
 
 	async getUpcomingParts(limit: number = 5): Promise<ReadonlyDeep<IBlueprintPart[]>> {

packages/job-worker/src/blueprints/context/RundownActivationContext.ts

@@ -48,7 +48,7 @@ export class RundownActivationContext extends RundownEventContext implements IRu
 		this._previousState = options.previousState
 		this._currentState = options.currentState
 
-		this.#tTimersService = new TTimersService(this._playoutModel)
+		this.#tTimersService = new TTimersService(this._playoutModel, this._context)
 	}
 
 	get previousState(): IRundownActivationContextState {

packages/job-worker/src/blueprints/context/adlibActions.ts

@@ -117,7 +117,7 @@ export class ActionExecutionContext extends ShowStyleUserContext implements IAct
 		private readonly partAndPieceInstanceService: PartAndPieceInstanceActionService
 	) {
 		super(contextInfo, _context, showStyle, watchedPackages)
-		this.#tTimersService = new TTimersService(_playoutModel)
+		this.#tTimersService = new TTimersService(_playoutModel, _context)
 	}
 
 	async getUpcomingParts(limit: number = 5): Promise<ReadonlyDeep<IBlueprintPart[]>> {

packages/job-worker/src/blueprints/context/services/TTimersService.ts

@@ -3,7 +3,10 @@ import type {
 	IPlaylistTTimerState,
 } from '@sofie-automation/blueprints-integration/dist/context/tTimersContext'
 import type { RundownTTimer, RundownTTimerIndex } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
-import { assertNever } from '@sofie-automation/corelib/dist/lib'
+import type { TimerState } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
+import type { PartId } from '@sofie-automation/corelib/dist/dataModel/Ids'
+import { assertNever, literal } from '@sofie-automation/corelib/dist/lib'
+import { protectString } from '@sofie-automation/corelib/dist/protectedString'
 import type { PlayoutModel } from '../../../playout/model/PlayoutModel.js'
 import { ReadonlyDeep } from 'type-fest'
 import {
@@ -14,21 +17,25 @@ import {
 	restartTTimer,
 	resumeTTimer,
 	validateTTimerIndex,
+	recalculateTTimerEstimates,
 } from '../../../playout/tTimers.js'
 import { getCurrentTime } from '../../../lib/time.js'
+import type { JobContext } from '../../../jobs/index.js'
 
 export class TTimersService {
 	readonly playoutModel: PlayoutModel
+	readonly jobContext: JobContext
 
 	readonly timers: [PlaylistTTimerImpl, PlaylistTTimerImpl, PlaylistTTimerImpl]
 
-	constructor(playoutModel: PlayoutModel) {
+	constructor(playoutModel: PlayoutModel, jobContext: JobContext) {
 		this.playoutModel = playoutModel
+		this.jobContext = jobContext
 
 		this.timers = [
-			new PlaylistTTimerImpl(playoutModel, 1),
-			new PlaylistTTimerImpl(playoutModel, 2),
-			new PlaylistTTimerImpl(playoutModel, 3),
+			new PlaylistTTimerImpl(playoutModel, jobContext, 1),
+			new PlaylistTTimerImpl(playoutModel, jobContext, 2),
+			new PlaylistTTimerImpl(playoutModel, jobContext, 3),
 		]
 	}
 
@@ -45,6 +52,7 @@ export class TTimersService {
 
 export class PlaylistTTimerImpl implements IPlaylistTTimer {
 	readonly #playoutModel: PlayoutModel
+	readonly #jobContext: JobContext
 	readonly #index: RundownTTimerIndex
 
 	get #modelTimer(): ReadonlyDeep<RundownTTimer> {
@@ -94,8 +102,9 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		}
 	}
 
-	constructor(playoutModel: PlayoutModel, index: RundownTTimerIndex) {
+	constructor(playoutModel: PlayoutModel, jobContext: JobContext, index: RundownTTimerIndex) {
 		this.#playoutModel = playoutModel
+		this.#jobContext = jobContext
 		this.#index = index
 
 		validateTTimerIndex(index)
@@ -160,4 +169,47 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		this.#playoutModel.updateTTimer(newTimer)
 		return true
 	}
+
+	clearEstimate(): void {
+		this.#playoutModel.updateTTimer({
+			...this.#modelTimer,
+			anchorPartId: undefined,
+			estimateState: undefined,
+		})
+	}
+
+	setEstimateAnchorPart(partId: string): void {
+		this.#playoutModel.updateTTimer({
+			...this.#modelTimer,
+			anchorPartId: protectString<PartId>(partId),
+			estimateState: undefined, // Clear manual estimate
+		})
+
+		// Recalculate estimates immediately since we already have the playout model
+		recalculateTTimerEstimates(this.#jobContext, this.#playoutModel)
+	}
+
+	setEstimateTime(time: number, paused: boolean = false): void {
+		const estimateState: TimerState = paused
+			? literal<TimerState>({ paused: true, duration: time - getCurrentTime() })
+			: literal<TimerState>({ paused: false, zeroTime: time })
+
+		this.#playoutModel.updateTTimer({
+			...this.#modelTimer,
+			anchorPartId: undefined, // Clear automatic anchor
+			estimateState,
+		})
+	}
+
+	setEstimateDuration(duration: number, paused: boolean = false): void {
+		const estimateState: TimerState = paused
+			? literal<TimerState>({ paused: true, duration })
+			: literal<TimerState>({ paused: false, zeroTime: getCurrentTime() + duration })
+
+		this.#playoutModel.updateTTimer({
+			...this.#modelTimer,
+			anchorPartId: undefined, // Clear automatic anchor
+			estimateState,
+		})
+	}
 }