/** * The Timers app's clock engine: a main-thread singleton that owns the * timers / stopwatch / alarms state, persists it, schedules the durable * phone alarms behind every expiry, rings the glasses buzzer, and tells * listeners (the window, the tray icon, the assistant tools) when anything * changes. It is booted at shell start, so everything here works with the * window closed; the window is only a view on it. * * Two expiry paths run side by side: a JS deadline for prompt on-glasses * ringing while the process is awake, and an AlarmManager alarm-clock alarm * (FaceclawAlarms.kt) that rings on the phone at the right moment even if * the process is asleep or dead. The phone shows the item silently first * and adds its own sound when the glasses cannot carry it (not connected, * not worn, charging, not shown within seconds, or not acknowledged within * 30 s); this engine keeps the phone told about the glasses, reports * delivery and acknowledgement, and replays what the wearer did on the * phone (dismiss / snooze) into its own state. */ import { ConfigSettingBoolean, ConfigSettingEnum, timeFormatSetting } from "../../ui/dashboard-settings"; import { getStringSetting, setStringSetting } from "../../native/settings-store"; import { acknowledgePhoneAlarm, cancelPhoneAlarm, checkPhoneAlarmReliability, drainPhoneAlarmJournal, onPhoneAlarmAction, openPhoneAlarmReliabilityFix, phoneAlarmDeliveredToGlasses, ringPhoneAlarm, schedulePhoneAlarm, setPhoneAlarmGlassesStatus, type AlarmReliabilityIssue, type PhoneAlarmAction, } from "../../native/alarms"; import { getGlassesPresence, glassesCanCarryAlert, onGlassesPresenceChanged } from "../../g2/glasses-presence"; import { buildSoundSequencePayload, findSoundEffect, effectPhrases } from "../../ui/sound-effects"; import { alarmNextRingMs, createAlarm, createTimer, emptyTimersState, formatDurationWords, formatTimeOfDay, parseTimersState, pushRecentDuration, serializeTimersState, soonestRunningTimer, stopwatchElapsedMs, timerRemainingMs, type Alarm, type CountdownTimer, type TimersState, } from "./timer-model"; const STATE_KEY = "timers.state"; /** * An expiry that passed longer ago than this while the process was down * (phone off, app killed) is marked rung silently rather than blaring on * the glasses hours late; the phone notification already fired on time. */ const RING_GRACE_MS = 5 * 60_000; /** How often the buzzer repeats while something is ringing. */ const RING_REPEAT_MS = 3_000; /** Stop buzzing an item this long after it started ringing (it stays "rung"). */ const RING_MAX_MS = 2 * 60_000; /** * Upper bound between deadline checks even with nothing due, so a JS timer * delayed by Doze or a clock jump can't leave a due item unnoticed for long. */ const MAX_ARM_MS = 30_000; /** How often the phone is reminded of the glasses' status (it distrusts stale reports). */ const GLASSES_STATUS_HEARTBEAT_MS = 60_000; /** How often the phone-side reliability self-check reruns while something is armed. */ const RELIABILITY_CHECK_MS = 5 * 60_000; export const timersSoundSetting = new ConfigSettingBoolean({ id: "timersSound", label: "Sound on glasses", storageKey: "timers.soundOnGlasses", defaultValue: true, description: "Play the glasses buzzer while a timer or alarm is ringing.", }); export const timersWakeSetting = new ConfigSettingBoolean({ id: "timersWake", label: "Wake glasses when ringing", storageKey: "timers.wakeGlasses", defaultValue: true, description: "Turn the display on and show the Timers app when a timer or alarm goes off.", }); export type SnoozeMinutes = "5" | "10" | "15"; export const timersSnoozeSetting = new ConfigSettingEnum({ id: "timersSnooze", label: "Snooze length", storageKey: "timers.snoozeMinutes", defaultValue: "10", values: ["5", "10", "15"], formatValue: (value) => `${value} min`, }); export type RingingItem = { kind: "timer"; timer: CountdownTimer } | { kind: "alarm"; alarm: Alarm }; export type TimerEngineHooks = { /** Play one buzzer sequencer payload on the glasses (no-op when disconnected). */ playBuzzer: (payload: Uint8Array) => Promise | void; /** Something started ringing audibly: bring the app forward, wake the glasses. */ onRing: (item: RingingItem) => void; }; const noopHooks: TimerEngineHooks = { playBuzzer: () => {}, onRing: () => {} }; export class TimerEngine { state: TimersState; private hooks: TimerEngineHooks = noopHooks; private readonly listeners = new Set<() => void>(); private deadlineTimer: ReturnType | null = null; private ringTimer: ReturnType | null = null; private booted = false; private reliabilityIssues: AlarmReliabilityIssue[] = []; private reliabilityCheckedAtMs = 0; constructor(private readonly now: () => number = () => Date.now()) { this.state = emptyTimersState(); } /** * Install the side-effect hooks and reconcile persisted state against the * clock: anything that came due while the process was down rings (or is * marked rung silently past the grace window), and the Android alarms are * re-armed for what is still pending. */ boot(hooks: TimerEngineHooks): void { this.hooks = hooks; if (this.booted) return; this.booted = true; // Loaded here rather than at module evaluation, so the settings store is // certainly up before the first read. this.state = parseTimersState(getStringSetting(STATE_KEY, "")); // What the wearer did on the phone while this side was down comes first, // so a dismissed alarm is not rung again by the check below. for (const action of drainPhoneAlarmJournal()) this.applyPhoneAction(action); onPhoneAlarmAction((action) => { this.applyPhoneAction(action); this.commit(); }); this.pushGlassesStatus(); onGlassesPresenceChanged(() => this.pushGlassesStatus()); setInterval(() => this.pushGlassesStatus(), GLASSES_STATUS_HEARTBEAT_MS); this.check(); for (const timer of this.state.timers) { if (timer.endsAtMs !== null && timer.rungAtMs === null) this.schedulePhoneNotification(timer); } for (const alarm of this.state.alarms) this.schedulePhoneAlarm(alarm); this.save(); this.refreshReliability(true); setInterval(() => this.refreshReliability(false), RELIABILITY_CHECK_MS); } /** * The glasses are showing a ringing item (the window is up and the screen * on). The phone's 30-second acknowledgement clock starts from here; without * this, the phone adds its sound within seconds. */ markDeliveredToGlasses(item: RingingItem): void { if (!glassesCanCarryAlert()) return; phoneAlarmDeliveredToGlasses(item.kind === "timer" ? item.timer.id : item.alarm.id); } private pushGlassesStatus(): void { const presence = getGlassesPresence(); setPhoneAlarmGlassesStatus(presence.connected, presence.worn === true, presence.charging); } /** * Replay a phone-side dismiss or snooze. The item may be ringing here too, * may not have been noticed yet (the phone rang it while this side slept), * or may already be gone; each case lands on the same end state. */ private applyPhoneAction(action: PhoneAlarmAction): void { const at = action.atMs || this.now(); const timer = this.findTimer(action.id); if (timer) { if (action.action === "dismiss") { this.state.timers = this.state.timers.filter((candidate) => candidate.id !== timer.id); } else { const extra = Math.max(1, action.minutes) * 60_000; timer.rungAtMs = null; timer.pausedRemainingMs = null; timer.durationMs = extra; timer.endsAtMs = at + extra; } return; } const alarm = this.findAlarm(action.id); if (!alarm) return; alarm.ringingSinceMs = null; alarm.lastFiredAtMs = Math.max(alarm.lastFiredAtMs ?? 0, at); if (action.action === "dismiss") { alarm.snoozedUntilMs = null; if (alarm.days === 0) alarm.enabled = false; } else { alarm.snoozedUntilMs = at + Math.max(1, action.minutes) * 60_000; } } // ------------------------------------------------------------------------- // Phone reliability /** Conditions under which the phone may fail to ring, most serious first (cached). */ phoneReliabilityIssues(): AlarmReliabilityIssue[] { return this.reliabilityIssues; } /** * One-line warning for the UI, or "" when nothing is armed that could * suffer (no enabled alarm, no running timer) or nothing is wrong. */ phoneReliabilityMessage(): string { if (this.reliabilityIssues.length === 0) return ""; const armed = this.state.alarms.some((alarm) => alarm.enabled) || this.state.timers.some((timer) => timer.endsAtMs !== null && timer.rungAtMs === null); if (!armed) return ""; return `The phone may not ring for alarms: ${this.reliabilityIssues[0]!.message}`; } /** Open the system screen for the most serious fixable issue, if any. */ openPhoneReliabilityFix(): void { const issue = this.reliabilityIssues.find((candidate) => candidate.fixable); if (issue) openPhoneAlarmReliabilityFix(issue.code); } /** Re-run the phone self-check (rate-limited unless forced) and notify on change. */ refreshReliability(force: boolean): void { const now = this.now(); if (!force && now - this.reliabilityCheckedAtMs < 30_000) return; this.reliabilityCheckedAtMs = now; let issues: AlarmReliabilityIssue[]; try { issues = checkPhoneAlarmReliability(); } catch (error) { console.warn(`alarm reliability check failed: ${error}`); return; } const changed = issues.length !== this.reliabilityIssues.length || issues.some((issue, index) => issue.code !== this.reliabilityIssues[index]?.code); this.reliabilityIssues = issues; if (changed) this.notify(); } onChange(listener: () => void): () => void { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; } /** True while anything on screen changes by itself once a second. */ isDynamic(): boolean { return ( this.state.stopwatch.runningSinceMs !== null || this.state.timers.some((timer) => timer.endsAtMs !== null && timer.rungAtMs === null) || this.ringingItems().length > 0 ); } /** Every countdown timer (running, paused or rung), unsorted. */ timers(): readonly CountdownTimer[] { return this.state.timers; } ringingItems(): RingingItem[] { const items: RingingItem[] = []; for (const timer of this.state.timers) { if (timer.rungAtMs !== null) items.push({ kind: "timer", timer }); } for (const alarm of this.state.alarms) { if (alarm.ringingSinceMs !== null) items.push({ kind: "alarm", alarm }); } return items; } // ------------------------------------------------------------------------- // Timers findTimer(id: number): CountdownTimer | undefined { return this.state.timers.find((timer) => timer.id === id); } startTimer(durationMs: number, label = ""): CountdownTimer { const timer = createTimer(durationMs, label, this.now()); this.state.timers.push(timer); this.state.recentDurationsMs = pushRecentDuration(this.state.recentDurationsMs, durationMs); this.schedulePhoneNotification(timer); this.commit(); return timer; } pauseTimer(id: number): void { const timer = this.findTimer(id); if (!timer || timer.endsAtMs === null || timer.rungAtMs !== null) return; timer.pausedRemainingMs = Math.max(0, timer.endsAtMs - this.now()); timer.endsAtMs = null; cancelPhoneAlarm(timer.id); this.commit(); } resumeTimer(id: number): void { const timer = this.findTimer(id); if (!timer || timer.pausedRemainingMs === null) return; timer.endsAtMs = this.now() + timer.pausedRemainingMs; timer.pausedRemainingMs = null; this.schedulePhoneNotification(timer); this.commit(); } /** Add time to a timer; a rung timer becomes a running one with just the added time. */ addTimerTime(id: number, deltaMs: number): void { const timer = this.findTimer(id); if (!timer) return; if (timer.rungAtMs !== null) { timer.rungAtMs = null; timer.durationMs = deltaMs; timer.endsAtMs = this.now() + deltaMs; cancelPhoneAlarm(timer.id); this.schedulePhoneNotification(timer); } else if (timer.pausedRemainingMs !== null) { timer.pausedRemainingMs += deltaMs; timer.durationMs += deltaMs; } else if (timer.endsAtMs !== null) { timer.endsAtMs += deltaMs; timer.durationMs += deltaMs; this.schedulePhoneNotification(timer); } this.commit(); } /** Start the timer over at its set duration ("Again" on a rung timer). */ restartTimer(id: number): void { const timer = this.findTimer(id); if (!timer) return; timer.rungAtMs = null; timer.pausedRemainingMs = null; timer.endsAtMs = this.now() + timer.durationMs; cancelPhoneAlarm(timer.id); this.schedulePhoneNotification(timer); this.commit(); } setTimerLabel(id: number, label: string): void { const timer = this.findTimer(id); if (!timer) return; timer.label = label.trim(); if (timer.endsAtMs !== null && timer.rungAtMs === null) this.schedulePhoneNotification(timer); this.commit(); } /** Cancel a timer, or dismiss a rung one. */ removeTimer(id: number): void { const index = this.state.timers.findIndex((timer) => timer.id === id); if (index < 0) return; acknowledgePhoneAlarm(id); this.state.timers.splice(index, 1); this.commit(); } // ------------------------------------------------------------------------- // Stopwatch stopwatchToggle(): void { const stopwatch = this.state.stopwatch; const now = this.now(); if (stopwatch.runningSinceMs === null) { stopwatch.runningSinceMs = now; } else { stopwatch.accumulatedMs += Math.max(0, now - stopwatch.runningSinceMs); stopwatch.runningSinceMs = null; } this.commit(); } stopwatchStart(): void { if (this.state.stopwatch.runningSinceMs === null) this.stopwatchToggle(); } stopwatchStop(): void { if (this.state.stopwatch.runningSinceMs !== null) this.stopwatchToggle(); } stopwatchLap(): void { const stopwatch = this.state.stopwatch; if (stopwatch.runningSinceMs === null) return; stopwatch.lapsMs.push(stopwatchElapsedMs(stopwatch, this.now())); this.commit(); } stopwatchReset(): void { this.state.stopwatch = { accumulatedMs: 0, runningSinceMs: null, lapsMs: [] }; this.commit(); } // ------------------------------------------------------------------------- // Alarms findAlarm(id: number): Alarm | undefined { return this.state.alarms.find((alarm) => alarm.id === id); } addAlarm(hour: number, minute: number, days: number, label = ""): Alarm { const alarm = createAlarm(hour, minute, days, label, this.now()); this.state.alarms.push(alarm); this.schedulePhoneAlarm(alarm); this.commit(); return alarm; } setAlarmTime(id: number, hour: number, minute: number): void { const alarm = this.findAlarm(id); if (!alarm) return; alarm.hour = hour; alarm.minute = minute; alarm.enabled = true; alarm.snoozedUntilMs = null; alarm.ringingSinceMs = null; alarm.lastFiredAtMs = null; this.schedulePhoneAlarm(alarm); this.commit(); } setAlarmDays(id: number, days: number): void { const alarm = this.findAlarm(id); if (!alarm) return; alarm.days = days; this.schedulePhoneAlarm(alarm); this.commit(); } setAlarmEnabled(id: number, enabled: boolean): void { const alarm = this.findAlarm(id); if (!alarm) return; alarm.enabled = enabled; alarm.snoozedUntilMs = null; alarm.ringingSinceMs = null; if (enabled) alarm.lastFiredAtMs = null; this.schedulePhoneAlarm(alarm); this.commit(); } setAlarmLabel(id: number, label: string): void { const alarm = this.findAlarm(id); if (!alarm) return; alarm.label = label.trim(); this.schedulePhoneAlarm(alarm); this.commit(); } deleteAlarm(id: number): void { const index = this.state.alarms.findIndex((alarm) => alarm.id === id); if (index < 0) return; cancelPhoneAlarm(id); this.state.alarms.splice(index, 1); this.commit(); } snoozeAlarm(id: number, minutes = Number(timersSnoozeSetting.get())): void { const alarm = this.findAlarm(id); if (!alarm || alarm.ringingSinceMs === null) return; alarm.ringingSinceMs = null; alarm.snoozedUntilMs = this.now() + minutes * 60_000; acknowledgePhoneAlarm(alarm.id); this.schedulePhoneAlarm(alarm); this.commit(); } /** Stop a ringing alarm; a one-off alarm switches itself off. */ dismissAlarm(id: number): void { const alarm = this.findAlarm(id); if (!alarm || alarm.ringingSinceMs === null) return; alarm.ringingSinceMs = null; alarm.snoozedUntilMs = null; if (alarm.days === 0) alarm.enabled = false; acknowledgePhoneAlarm(alarm.id); this.schedulePhoneAlarm(alarm); this.commit(); } /** Dismiss whatever is ringing (timers and alarms alike). Returns how many. */ dismissAllRinging(): number { const items = this.ringingItems(); for (const item of items) { if (item.kind === "timer") this.removeTimer(item.timer.id); else this.dismissAlarm(item.alarm.id); } return items.length; } // ------------------------------------------------------------------------- // Deadlines and ringing /** * Fire anything due and re-arm for the next deadline. Called on every * change, on the deadline timer, and by the window before it paints, so a * timer never shows 0:00 without also being rung. */ check(): void { const now = this.now(); let changed = false; for (const timer of this.state.timers) { if (timer.endsAtMs === null || timer.rungAtMs !== null || timer.endsAtMs > now) continue; timer.rungAtMs = timer.endsAtMs; timer.endsAtMs = null; changed = true; // Late (found due after a restart): the phone rang or missed it on // its own schedule; only a fresh expiry starts the phone flow here. const late = now - timer.rungAtMs > RING_GRACE_MS; if (!late) { ringPhoneAlarm(timer.id, "Timer finished", timerNotificationText(timer), "timer", snoozeMinutes()); this.startRinging({ kind: "timer", timer }); } } for (const alarm of this.state.alarms) { if (alarm.ringingSinceMs !== null) continue; const due = this.alarmDueMs(alarm, now); if (due === null || due > now) continue; alarm.ringingSinceMs = now; alarm.snoozedUntilMs = null; alarm.lastFiredAtMs = due; changed = true; const late = now - due > RING_GRACE_MS; if (late) { // Missed by too much to ring now: fall through to the next occurrence. alarm.ringingSinceMs = null; if (alarm.days === 0) alarm.enabled = false; this.schedulePhoneAlarm(alarm); } else { ringPhoneAlarm(alarm.id, "Alarm", alarmNotificationText(alarm), "alarm", snoozeMinutes()); this.startRinging({ kind: "alarm", alarm }); } } this.arm(now); this.syncRingLoop(now); if (changed) this.commit(); } /** * The occurrence an alarm should ring for next: the pending snooze, or the * first occurrence after (now - grace) that it has not already rung for. * Inside the grace window this returns a time in the past, which check() * fires; beyond it the missed occurrence is skipped. */ private alarmDueMs(alarm: Alarm, now: number): number | null { return alarmNextRingMs(alarm, now - RING_GRACE_MS); } private startRinging(item: RingingItem): void { try { this.hooks.onRing(item); } catch (error) { console.warn(`timers onRing hook failed: ${error}`); } } /** Re-arm the single deadline timer for the soonest pending expiry. */ private arm(now: number): void { if (this.deadlineTimer !== null) { clearTimeout(this.deadlineTimer); this.deadlineTimer = null; } const deadlines: number[] = []; for (const timer of this.state.timers) { if (timer.rungAtMs === null && timer.endsAtMs !== null) deadlines.push(timer.endsAtMs); } for (const alarm of this.state.alarms) { if (alarm.ringingSinceMs !== null) continue; const due = this.alarmDueMs(alarm, now); if (due !== null) deadlines.push(due); } if (deadlines.length === 0) return; const delay = Math.min(MAX_ARM_MS, Math.max(0, Math.min(...deadlines) - now)); this.deadlineTimer = setTimeout(() => { this.deadlineTimer = null; this.check(); }, delay); } /** Run the buzzer repeat loop while anything is (still audibly) ringing. */ private syncRingLoop(now: number): void { const audible = this.ringingItems().some((item) => this.ringAgeMs(item, now) < RING_MAX_MS); if (audible && this.ringTimer === null) { this.playRingSound(); this.ringTimer = setInterval(() => { const at = this.now(); if (!this.ringingItems().some((item) => this.ringAgeMs(item, at) < RING_MAX_MS)) { this.syncRingLoop(at); return; } this.playRingSound(); }, RING_REPEAT_MS); } else if (!audible && this.ringTimer !== null) { clearInterval(this.ringTimer); this.ringTimer = null; } } private ringAgeMs(item: RingingItem, now: number): number { const since = item.kind === "timer" ? item.timer.rungAtMs : item.alarm.ringingSinceMs; return since === null ? Infinity : Math.max(0, now - since); } private playRingSound(): void { if (!timersSoundSetting.get()) return; const effect = findSoundEffect("alarm"); if (!effect) return; const phrase = effectPhrases(effect.make())[0]; if (!phrase) return; try { void this.hooks.playBuzzer(buildSoundSequencePayload(phrase)); } catch (error) { console.warn(`timers buzzer failed: ${error}`); } } // ------------------------------------------------------------------------- // Phone notifications private schedulePhoneNotification(timer: CountdownTimer): void { if (timer.endsAtMs === null) return; schedulePhoneAlarm(timer.id, timer.endsAtMs, "Timer finished", timerNotificationText(timer), "timer", snoozeMinutes()); } /** (Re)arm or cancel the phone alarm for an alarm's next occurrence. */ private schedulePhoneAlarm(alarm: Alarm): void { const due = alarm.ringingSinceMs === null ? this.alarmDueMs(alarm, this.now()) : null; if (due === null) { cancelPhoneAlarm(alarm.id); return; } schedulePhoneAlarm(alarm.id, due, "Alarm", alarmNotificationText(alarm), "alarm", snoozeMinutes()); } // ------------------------------------------------------------------------- // Change plumbing private commit(): void { this.save(); this.check(); this.notify(); if (this.booted) this.refreshReliability(false); } private save(): void { try { setStringSetting(STATE_KEY, serializeTimersState(this.state)); } catch (error) { console.warn(`timers state save failed: ${error}`); } } private notify(): void { for (const listener of Array.from(this.listeners)) { try { listener(); } catch (error) { console.warn(`timers listener failed: ${error}`); } } } } function snoozeMinutes(): number { return Number(timersSnoozeSetting.get()) || 10; } function timerNotificationText(timer: CountdownTimer): string { const duration = formatDurationWords(timer.durationMs); return timer.label ? `${timer.label} (${duration}) is up` : `${duration} timer is up`; } function alarmNotificationText(alarm: Alarm): string { const time = formatTimeOfDay(alarm.hour, alarm.minute, timeFormatSetting.get() === "12h"); return alarm.label ? `${time} ยท ${alarm.label}` : time; } /** Remaining time of the timer that ends soonest, for the tray icon; null when none runs. */ export function soonestRunningTimerRemainingMs(engine: TimerEngine, now = Date.now()): number | null { const timer = soonestRunningTimer(engine.state.timers, now); return timer ? timerRemainingMs(timer, now) : null; } export const timerEngine = new TimerEngine();