feat(blueprints): Add T-Timer duration/timing methods and expose rundown timing

Add comprehensive T-Timer manipulation methods to IPlaylistTTimer interface:
- setDuration(duration) - Reset timer to a specific duration
- setDuration(options) - Independently update original and/or current duration
  - original: Duration timer resets to on restart()
  - current: Current countdown value
  - Preserves elapsed time when only original is provided

Add T-Timer query methods:
- getCurrentDuration() - Get current timer value in milliseconds
- getZeroTime() - Get absolute timestamp of timer's zero point
- getProjectedDuration() - Get projected countdown value (for over/under calculation)
- getProjectedZeroTime() - Get projected zero time timestamp

Add shared utility functions in corelib:
- timerStateToDuration() - Calculate current duration from TimerState (already existed)
- timerStateToZeroTime() - Calculate zero time from TimerState (new)
- Both shared between backend and frontend for consistent calculations

Expose timing information to blueprints:
- Add timing field to IBlueprintSegmentRundown interface
- Exposes RundownPlaylistTiming via context.rundown.timing
- Removes need for accessing private _rundown property

Implementation:
- PlaylistTTimerImpl implements all new methods using shared utilities
- Update convertRundownToBlueprintSegmentRundown() to include timing
- All methods properly handle paused/running states and edge cases

Related to BBC-SOFIE-454

Author: rjmunro

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

@@ -150,6 +150,29 @@ export interface IPlaylistTTimer {
 	 */
 	restart(): boolean
 
+	/**
+	 * Set the duration of a countdown timer
+	 * This resets both the original duration (what restart() resets to) and the current countdown value.
+	 * @param duration New duration in milliseconds
+	 * @throws If timer is not in countdown mode or not initialized
+	 */
+	setDuration(duration: number): void
+
+	/**
+	 * Update the original duration (reset-to value) and/or current duration of a countdown timer
+	 * This allows you to independently update:
+	 * - `original`: The duration the timer resets to when restart() is called
+	 * - `current`: The current countdown value (what's displayed now)
+	 *
+	 * If only `original` is provided, the current duration is recalculated to preserve elapsed time.
+	 * If only `current` is provided, just the current countdown is updated.
+	 * If both are provided, both values are updated independently.
+	 *
+	 * @param options Object with optional `original` and/or `current` duration in milliseconds
+	 * @throws If timer is not in countdown mode or not initialized
+	 */
+	setDuration(options: { original?: number; current?: number }): void
+
 	/**
 	 * Clear any projection (manual or anchor-based) for this timer
 	 * This removes both manual projections set via setProjectedTime/setProjectedDuration
@@ -194,4 +217,38 @@ export interface IPlaylistTTimer {
 	 *               If false (default), we're progressing normally (projection counts down in real-time).
 	 */
 	setProjectedDuration(duration: number, paused?: boolean): void
+
+	/**
+	 * Get the current duration of the timer in milliseconds
+	 * For countdown timers, this returns how much time is remaining (can be negative if past zero)
+	 * For timeOfDay timers, this returns time until/since the target time
+	 * For freeRun timers, this returns how much time has elapsed
+	 * @returns Current duration in milliseconds, or null if timer is not initialized
+	 */
+	getDuration(): number | null
+
+	/**
+	 * Get the zero time (reference point) for the timer
+	 * - For countdown/timeOfDay timers: the absolute timestamp when the timer reaches zero
+	 * - For freeRun timers: the absolute timestamp when the timer started (what it counts from)
+	 * For paused timers, calculates when zero would be if resumed now.
+	 * @returns Unix timestamp in milliseconds, or null if timer is not initialized
+	 */
+	getZeroTime(): number | null
+
+	/**
+	 * Get the projected duration in milliseconds
+	 * This returns the projected timer value when we expect to reach the anchor part.
+	 * Used to calculate over/under (how far ahead or behind schedule we are).
+	 * @returns Projected duration in milliseconds, or null if no projection is set
+	 */
+	getProjectedDuration(): number | null
+
+	/**
+	 * Get the projected zero time (reference point)
+	 * This returns when we project the timer will reach zero based on scheduled durations.
+	 * For paused projections (when pushing/delayed), calculates when zero would be if resumed now.
+	 * @returns Unix timestamp in milliseconds, or null if no projection is set
+	 */
+	getProjectedZeroTime(): number | null
 }

packages/blueprints-integration/src/documents/rundown.ts

@@ -55,6 +55,9 @@ export interface IBlueprintRundownDBData {
 export interface IBlueprintSegmentRundown<TPrivateData = unknown, TPublicData = unknown> {
 	externalId: string
 
+	/** Rundown timing information */
+	timing: RundownPlaylistTiming
+
 	/** Arbitraty data storage for internal use in the blueprints */
 	privateData?: TPrivateData
 	/** Arbitraty data relevant for other systems, made available to them through APIs */

packages/corelib/src/dataModel/RundownPlaylist.ts

@@ -121,6 +121,29 @@ export function timerStateToDuration(state: TimerState, now: number): number {
 	}
 }
 
+/**
+ * Get the zero time (reference timestamp) for a timer state.
+ * - For countdown/timeOfDay timers: when the timer reaches zero
+ * - For freeRun timers: when the timer started (what it counts from)
+ * For paused timers, calculates when zero would be if resumed now.
+ *
+ * @param state The timer state
+ * @param now Current timestamp in milliseconds
+ * @returns The zero time timestamp in milliseconds
+ */
+export function timerStateToZeroTime(state: TimerState, now: number): number {
+	if (state.paused) {
+		// Calculate when zero would be if we resumed now
+		return now + state.duration
+	} else if (state.pauseTime && now >= state.pauseTime) {
+		// Auto-pause at overrun (current part ended)
+		return state.zeroTime - state.pauseTime + now
+	} else {
+		// Already have the zero time
+		return state.zeroTime
+	}
+}
+
 export type RundownTTimerIndex = 1 | 2 | 3
 
 export interface RundownTTimer {

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

@@ -443,6 +443,7 @@ export function convertRundownToBlueprintSegmentRundown(
 ): IBlueprintSegmentRundown {
 	const obj: Complete<IBlueprintSegmentRundown> = {
 		externalId: rundown.externalId,
+		timing: rundown.timing,
 		privateData: skipClone ? rundown.privateData : clone(rundown.privateData),
 		publicData: skipClone ? rundown.publicData : clone(rundown.publicData),
 	}

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

@@ -7,6 +7,10 @@ import type {
 	RundownTTimer,
 	RundownTTimerIndex,
 } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
+import {
+	timerStateToDuration,
+	timerStateToZeroTime,
+} from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
 import type { PartId } from '@sofie-automation/corelib/dist/dataModel/Ids'
 import { literal } from '@sofie-automation/corelib/dist/lib'
 import { protectString, unprotectString } from '@sofie-automation/corelib/dist/protectedString'
@@ -165,6 +169,75 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		return true
 	}
 
+	setDuration(durationOrOptions: number | { original?: number; current?: number }): void {
+		// Handle overloaded signatures
+		if (typeof durationOrOptions === 'number') {
+			// Simple case: reset timer to this duration
+			return this.setDuration({ original: durationOrOptions, current: durationOrOptions })
+		}
+
+		// Options case: independently update original and/or current
+		const options = durationOrOptions
+
+		if (options.original !== undefined && options.original <= 0) {
+			throw new Error('Original duration must be greater than zero')
+		}
+		if (options.current !== undefined && options.current <= 0) {
+			throw new Error('Current duration must be greater than zero')
+		}
+
+		if (!this.#timer.mode || this.#timer.mode.type !== 'countdown') {
+			throw new Error('Timer must be in countdown mode to update duration')
+		}
+
+		if (!this.#timer.state) {
+			throw new Error('Timer is not initialized')
+		}
+
+		if (!options.original && !options.current) {
+			throw new Error('At least one of original or current duration must be provided')
+		}
+
+		const now = getCurrentTime()
+		const state = this.#timer.state
+
+		// Calculate current elapsed time
+		const elapsed = state.paused
+			? this.#timer.mode.duration - state.duration
+			: now - (state.zeroTime - this.#timer.mode.duration)
+
+		let newOriginalDuration: number
+		let newCurrentRemaining: number
+
+		if (options.original !== undefined && options.current !== undefined) {
+			// Both specified: use both values independently
+			newOriginalDuration = options.original
+			newCurrentRemaining = options.current
+		} else if (options.original !== undefined) {
+			// Only original specified: preserve elapsed time
+			newOriginalDuration = options.original
+			newCurrentRemaining = Math.max(0, newOriginalDuration - elapsed)
+		} else {
+			// Only current specified: keep original unchanged
+			newOriginalDuration = this.#timer.mode.duration
+			newCurrentRemaining = options.current!
+		}
+
+		// Update both mode and state
+		this.#timer = {
+			...this.#timer,
+			mode: {
+				...this.#timer.mode,
+				duration: newOriginalDuration,
+			},
+			state: state.paused
+				? { paused: true, duration: newCurrentRemaining }
+				: { paused: false, zeroTime: now + newCurrentRemaining },
+		}
+
+		this.#emitChange(this.#timer)
+	}
+
 	clearProjected(): void {
 		this.#timer = {
 			...this.#timer,
@@ -218,4 +291,36 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		}
 		this.#emitChange(this.#timer)
 	}
+
+	getDuration(): number | null {
+		if (!this.#timer.state) {
+			return null
+		}
+
+		return timerStateToDuration(this.#timer.state, getCurrentTime())
+	}
+
+	getZeroTime(): number | null {
+		if (!this.#timer.state) {
+			return null
+		}
+
+		return timerStateToZeroTime(this.#timer.state, getCurrentTime())
+	}
+
+	getProjectedDuration(): number | null {
+		if (!this.#timer.projectedState) {
+			return null
+		}
+
+		return timerStateToDuration(this.#timer.projectedState, getCurrentTime())
+	}
+
+	getProjectedZeroTime(): number | null {
+		if (!this.#timer.projectedState) {
+			return null
+		}
+
+		return timerStateToZeroTime(this.#timer.projectedState, getCurrentTime())
+	}
 }