From edb3d1e425cf8e2cc9720d5fc128ee0dd2eb0b76 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Mon, 28 Apr 2025 15:03:51 +0000
Subject: [PATCH 01/29] fix: migrate over time changes

---
 site/src/App.tsx                              |  23 +-
 .../components/SignInLayout/SignInLayout.tsx  |   8 +-
 site/src/hooks/useTime.ts                     |  43 ---
 site/src/hooks/useTimeSync.tsx                | 326 ++++++++++++++++++
 .../CliInstallPage/CliInstallPageView.tsx     |   8 +-
 .../LicensesSettingsPage/LicenseCard.tsx      |   8 +-
 site/src/pages/LoginPage/LoginPageView.tsx    |   9 +-
 .../TemplateInsightsPage/DateRange.tsx        |   4 +-
 .../TemplateInsightsPage.tsx                  | 183 +++++-----
 site/src/pages/WorkspacePage/AppStatuses.tsx  |  11 +-
 .../WorkspaceScheduleControls.tsx             |   7 +-
 site/src/pages/WorkspacesPage/LastUsed.tsx    |  50 +--
 12 files changed, 497 insertions(+), 183 deletions(-)
 delete mode 100644 site/src/hooks/useTime.ts
 create mode 100644 site/src/hooks/useTimeSync.tsx

diff --git a/site/src/App.tsx b/site/src/App.tsx
index e4e6d4a665996..8c1c692ecf3e9 100644
--- a/site/src/App.tsx
+++ b/site/src/App.tsx
@@ -14,6 +14,7 @@ import { GlobalSnackbar } from "./components/GlobalSnackbar/GlobalSnackbar";
 import { ThemeProvider } from "./contexts/ThemeProvider";
 import { AuthProvider } from "./contexts/auth/AuthProvider";
 import { router } from "./router";
+import { TimeSyncProvider } from "hooks/useTimeSync";
 
 const defaultQueryClient = new QueryClient({
 	defaultOptions: {
@@ -37,6 +38,8 @@ declare global {
 	}
 }
 
+const initialDatetime = new Date();
+
 export const AppProviders: FC<AppProvidersProps> = ({
 	children,
 	queryClient = defaultQueryClient,
@@ -64,15 +67,17 @@ export const AppProviders: FC<AppProvidersProps> = ({
 
 	return (
 		<HelmetProvider>
-			<QueryClientProvider client={queryClient}>
-				<AuthProvider>
-					<ThemeProvider>
-						{children}
-						<GlobalSnackbar />
-					</ThemeProvider>
-				</AuthProvider>
-				{showDevtools && <ReactQueryDevtools initialIsOpen={showDevtools} />}
-			</QueryClientProvider>
+			<TimeSyncProvider options={{ initialDatetime }}>
+				<QueryClientProvider client={queryClient}>
+					<AuthProvider>
+						<ThemeProvider>
+							{children}
+							<GlobalSnackbar />
+						</ThemeProvider>
+					</AuthProvider>
+					{showDevtools && <ReactQueryDevtools initialIsOpen={showDevtools} />}
+				</QueryClientProvider>
+			</TimeSyncProvider>
 		</HelmetProvider>
 	);
 };
diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
index 6a0d4f5865ea1..751e58224adc2 100644
--- a/site/src/components/SignInLayout/SignInLayout.tsx
+++ b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -1,13 +1,19 @@
 import type { Interpolation, Theme } from "@emotion/react";
+import { useTimeSync } from "hooks/useTimeSync";
 import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
+	const year = useTimeSync({
+		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		select: (date) => date.getFullYear(),
+	});
+
 	return (
 		<div css={styles.container}>
 			<div css={styles.content}>
 				<div css={styles.signIn}>{children}</div>
 				<div css={styles.copyright}>
-					{"\u00a9"} {new Date().getFullYear()} Coder Technologies, Inc.
+					{"\u00a9"} {year} Coder Technologies, Inc.
 				</div>
 			</div>
 		</div>
diff --git a/site/src/hooks/useTime.ts b/site/src/hooks/useTime.ts
deleted file mode 100644
index 7f03c05225017..0000000000000
--- a/site/src/hooks/useTime.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { useEffect, useState } from "react";
-import { useEffectEvent } from "./hookPolyfills";
-
-interface UseTimeOptions {
-	/**
-	 * Can be set to `true` to disable checking for updates in circumstances where it is known
-	 * that there is no work to do.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * The amount of time in milliseconds that should pass between checking for updates.
-	 */
-	interval?: number;
-}
-
-/**
- * useTime allows a component to rerender over time without a corresponding state change.
- * An example could be a relative timestamp (eg. "in 5 minutes") that should count down as it
- * approaches.
- */
-export function useTime<T>(func: () => T, options: UseTimeOptions = {}): T {
-	const [computedValue, setComputedValue] = useState(() => func());
-	const { disabled = false, interval = 1000 } = options;
-
-	const thunk = useEffectEvent(func);
-
-	useEffect(() => {
-		if (disabled) {
-			return;
-		}
-
-		const handle = setInterval(() => {
-			setComputedValue(() => thunk());
-		}, interval);
-
-		return () => {
-			clearInterval(handle);
-		};
-	}, [thunk, disabled, interval]);
-
-	return computedValue;
-}
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
new file mode 100644
index 0000000000000..af1358059a9d6
--- /dev/null
+++ b/site/src/hooks/useTimeSync.tsx
@@ -0,0 +1,326 @@
+/**
+ * @todo Things that still need to be done before this can be called done:
+ * 1. Finish up the interval reconciliation method
+ * 2. Update the class to respect the resyncOnNewSubscription option
+ * 3. Add tests
+ */
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useId,
+	useState,
+	useSyncExternalStore,
+	type FC,
+	type PropsWithChildren,
+} from "react";
+
+export const MAX_REFRESH_ONE_SECOND = 1_000;
+export const MAX_REFRESH_ONE_MINUTE = 60 * 1_000;
+export const MAX_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
+export const MAX_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
+
+type SetInterval = (fn: () => void, intervalMs: number) => number;
+type ClearInterval = (id: number | undefined) => void;
+
+type TimeSyncInitOptions = Readonly<{
+	/**
+	 * Configures whether adding a new subscription will immediately create a new
+	 * time snapshot and use it to update all other subscriptions.
+	 */
+	resyncOnNewSubscription: boolean;
+
+	/**
+	 * The Date value to use when initializing a TimeSync instance.
+	 */
+	initialDatetime: Date;
+
+	/**
+	 * The function to use when creating a new datetime snapshot when a TimeSync
+	 * needs to update on an interval.
+	 */
+	createNewDatetime: (prevDatetime: Date) => Date;
+
+	/**
+	 * The function to use when creating new intervals.
+	 */
+	setInterval: SetInterval;
+
+	/**
+	 * The function to use when clearing intervals.
+	 *
+	 * (i.e., Clearing a previous interval because the TimeSync needs to make a
+	 * new interval to increase/decrease its update speed.)
+	 */
+	clearInterval: ClearInterval;
+}>;
+
+const defaultOptions: TimeSyncInitOptions = {
+	initialDatetime: new Date(),
+	resyncOnNewSubscription: true,
+	createNewDatetime: () => new Date(),
+	setInterval: window.setInterval,
+	clearInterval: window.clearInterval,
+};
+
+type SubscriptionEntry = Readonly<{
+	id: string;
+	maxRefreshIntervalMs: number;
+	onUpdate: (newDatetime: Date) => void;
+}>;
+
+interface TimeSyncApi {
+	getLatestDatetimeSnapshot: () => Date;
+	subscribe: (entry: SubscriptionEntry) => () => void;
+	unsubscribe: (id: string) => void;
+}
+
+/**
+ * TimeSync provides a centralized authority for working with time values in a
+ * more structured, "pure function-ish" way, where all dependents for the time
+ * values must stay in sync with each other. (e.g., in a React codebase, you
+ * want multiple components that rely on time values to update together, to
+ * avoid screen tearing and stale data for only some parts of the screen).
+ *
+ * It lets any number of consumers subscribe to it, requiring that subscribers
+ * define the slowest possible update interval they need to receive new time
+ * values for. A value of positive Infinity indicates that a subscriber doesn't
+ * need updates; if all subscriptions have an update interval of Infinity, the
+ * class may not dispatch updates.
+ *
+ * The class aggregates all the update intervals, and will dispatch updates to
+ * all consumers based on the fastest refresh interval needed. (e.g., if
+ * subscriber A needs no updates, but subscriber B needs updates every second,
+ * BOTH will update every second until subscriber B unsubscribes. After that,
+ * TimeSync will stop dispatching updates until subscription C gets added, and C
+ * has a non-Infinite update interval).
+ *
+ * By design, there is no way to make one subscriber disable updates. That
+ * defeats the goal of needing to keep everything in sync with each other. If
+ * updates are happening too frequently in React, restructure how you're
+ * composing your components to minimize the costs of re-renders.
+ */
+export class TimeSync implements TimeSyncApi {
+	readonly #resyncOnNewSubscription: boolean;
+	readonly #createNewDatetime: (prev: Date) => Date;
+	readonly #setInterval: SetInterval;
+	readonly #clearInterval: ClearInterval;
+
+	#latestSnapshot: Date;
+	#subscriptions: SubscriptionEntry[];
+	#latestIntervalId: number | undefined;
+
+	constructor(options: Partial<TimeSyncInitOptions>) {
+		const {
+			initialDatetime = defaultOptions.initialDatetime,
+			resyncOnNewSubscription = defaultOptions.resyncOnNewSubscription,
+			createNewDatetime = defaultOptions.createNewDatetime,
+			setInterval = defaultOptions.setInterval,
+			clearInterval = defaultOptions.clearInterval,
+		} = options;
+
+		this.#setInterval = setInterval;
+		this.#clearInterval = clearInterval;
+		this.#createNewDatetime = createNewDatetime;
+		this.#resyncOnNewSubscription = resyncOnNewSubscription;
+
+		this.#latestSnapshot = initialDatetime;
+		this.#subscriptions = [];
+		this.#latestIntervalId = undefined;
+	}
+
+	#reconcileRefreshIntervals(): void {
+		if (this.#subscriptions.length === 0) {
+			this.#clearInterval(this.#latestIntervalId);
+			return;
+		}
+
+		const prevFastestInterval =
+			this.#subscriptions[0]?.maxRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+		if (this.#subscriptions.length > 1) {
+			this.#subscriptions.sort(
+				(e1, e2) => e1.maxRefreshIntervalMs - e2.maxRefreshIntervalMs,
+			);
+		}
+
+		const newFastestInterval =
+			this.#subscriptions[0]?.maxRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+		if (prevFastestInterval === newFastestInterval) {
+			return;
+		}
+		if (newFastestInterval === Number.POSITIVE_INFINITY) {
+			this.#clearInterval(this.#latestIntervalId);
+			return;
+		}
+
+		/**
+		 * @todo Figure out the conditions when the interval should be set up, and
+		 * when/how it should be updated
+		 */
+		this.#latestIntervalId = this.#setInterval(() => {
+			this.#latestSnapshot = this.#createNewDatetime(this.#latestSnapshot);
+			this.#notifySubscriptions();
+		}, newFastestInterval);
+	}
+
+	#notifySubscriptions(): void {
+		for (const subEntry of this.#subscriptions) {
+			subEntry.onUpdate(this.#latestSnapshot);
+		}
+	}
+
+	// All functions that are part of the public interface must be defined as
+	// arrow functions, so that they work properly with React
+
+	getLatestDatetimeSnapshot = (): Date => {
+		return this.#latestSnapshot;
+	};
+
+	unsubscribe = (id: string): void => {
+		const updated = this.#subscriptions.filter((s) => s.id !== id);
+		if (updated.length === this.#subscriptions.length) {
+			return;
+		}
+
+		this.#subscriptions = updated;
+		this.#reconcileRefreshIntervals();
+	};
+
+	subscribe = (entry: SubscriptionEntry): (() => void) => {
+		if (entry.maxRefreshIntervalMs <= 0) {
+			throw new Error(
+				`Refresh interval ${entry.maxRefreshIntervalMs} must be a positive integer (or Infinity)`,
+			);
+		}
+
+		const unsub = () => this.unsubscribe(entry.id);
+		const subIndex = this.#subscriptions.findIndex((s) => s.id === entry.id);
+		if (subIndex === -1) {
+			this.#subscriptions.push(entry);
+			this.#reconcileRefreshIntervals();
+			return unsub;
+		}
+
+		const prev = this.#subscriptions[subIndex];
+		if (prev === undefined) {
+			throw new Error("Went out of bounds");
+		}
+
+		this.#subscriptions[subIndex] = entry;
+		if (prev.maxRefreshIntervalMs !== entry.maxRefreshIntervalMs) {
+			this.#reconcileRefreshIntervals();
+		}
+		return unsub;
+	};
+}
+
+const timeSyncContext = createContext<TimeSync | null>(null);
+
+function useTimeSyncContext(): TimeSync {
+	const timeSync = useContext(timeSyncContext);
+	if (timeSync === null) {
+		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
+	}
+
+	return timeSync;
+}
+
+type TimeSyncProviderProps = Readonly<
+	PropsWithChildren<{
+		options?: Partial<TimeSyncInitOptions>;
+	}>
+>;
+
+/**
+ * TimeSyncProvider provides an easy way to dependency-inject a TimeSync
+ * instance throughout a React application.
+ *
+ * Note that whatever options are provided on the first render will be locked in
+ * for the lifetime of the provider. There is no way to reconfigure options on
+ * re-renders.
+ */
+export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
+	children,
+	options,
+}) => {
+	// Making the TimeSync instance be initialized via React State, so that it's
+	// easy to mock it out for component and story tests. TimeSync itself should
+	// be treated like a pseudo-ref value, where its values can only be used in
+	// very specific, React-approved ways (e.g., not directly in a render path)
+	const [readonlySync] = useState(
+		() => new TimeSync(options ?? defaultOptions),
+	);
+
+	return (
+		<timeSyncContext.Provider value={readonlySync}>
+			{children}
+		</timeSyncContext.Provider>
+	);
+};
+
+type UseTimeSyncOptions<T = Date> = Readonly<{
+	maxRefreshIntervalMs: number;
+
+	/**
+	 * Allows you to transform any date values received from the TimeSync class.
+	 *
+	 * Note that select functions are not memoized and will run on every render
+	 * (similar to the ones in React Query and Redux Toolkit's default selectors).
+	 * Select functions should be kept cheap to recalculate.
+	 *
+	 * Select functions must not be async. The hook will error out at the type
+	 * level if you provide one by mistake.
+	 */
+	select?: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
+}>;
+
+type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
+
+/**
+ * useTimeSync provides React bindings for the TimeSync class, letting a React
+ * component bind its update lifecycles to interval updates from TimeSync. This
+ * hook should be used anytime you would want to use a Date instance directly in
+ * a component render path.
+ *
+ * By default, it returns the raw Date value from the most recent update, but
+ * by providing a `select` callback in the options, you can get a transformed
+ * version of the time value, using 100% pure functions.
+ *
+ * By specifying a value of positive Infinity, that indicates that the hook will
+ * not update by itself. But if another component is mounted with a more
+ * frequent update interval, both component instances will update on that
+ * interval.
+ */
+export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
+	const { select, maxRefreshIntervalMs } = options;
+
+	// Abusing useId a little bit here. It's mainly meant to be used for
+	// accessibility, but it also gives us a globally unique ID associated with
+	// whichever component instance is consuming this hook
+	const hookId = useId();
+	const timeSync = useTimeSyncContext();
+
+	// We need to define this callback using useCallback instead of useEffectEvent
+	// because we want the memoization to be invaliated when the refresh interval
+	// changes. (When the subscription callback changes by reference, that causes
+	// useSyncExternalStore to redo the subscription with the new callback). All
+	// other values need to be included in the dependency array for correctness,
+	// but their memory references should always be stable
+	const subscribe = useCallback<ReactSubscriptionCallback>(
+		(notifyReact) => {
+			return timeSync.subscribe({
+				maxRefreshIntervalMs,
+				onUpdate: notifyReact,
+				id: hookId,
+			});
+		},
+		[timeSync, hookId, maxRefreshIntervalMs],
+	);
+
+	const currentTime = useSyncExternalStore(subscribe, () =>
+		timeSync.getLatestDatetimeSnapshot(),
+	);
+
+	const recast = currentTime as T & Date;
+	return select?.(recast) ?? recast;
+}
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
index 9356cee6153b3..a4ac1486f19e3 100644
--- a/site/src/pages/CliInstallPage/CliInstallPageView.tsx
+++ b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -1,6 +1,7 @@
 import type { Interpolation, Theme } from "@emotion/react";
 import { CodeExample } from "components/CodeExample/CodeExample";
 import { Welcome } from "components/Welcome/Welcome";
+import { useTimeSync } from "hooks/useTimeSync";
 import type { FC } from "react";
 import { Link as RouterLink } from "react-router-dom";
 
@@ -9,6 +10,11 @@ type CliInstallPageViewProps = {
 };
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
+	const year = useTimeSync({
+		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		select: (date) => date.getFullYear(),
+	});
+
 	return (
 		<div css={styles.container}>
 			<Welcome>Install the Coder CLI</Welcome>
@@ -30,7 +36,7 @@ export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
 				</RouterLink>
 			</div>
 			<div css={styles.copyright}>
-				{"\u00a9"} {new Date().getFullYear()} Coder Technologies, Inc.
+				{"\u00a9"} {year} Coder Technologies, Inc.
 			</div>
 		</div>
 	);
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
index 30ea89c72fdc6..d9c8cd48ed512 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
@@ -7,6 +7,7 @@ import { Pill } from "components/Pill/Pill";
 import { Stack } from "components/Stack/Stack";
 import { compareAsc } from "date-fns";
 import dayjs from "dayjs";
+import { useTimeSync } from "hooks/useTimeSync";
 import { type FC, useState } from "react";
 
 type LicenseCardProps = {
@@ -24,6 +25,7 @@ export const LicenseCard: FC<LicenseCardProps> = ({
 	onRemove,
 	isRemoving,
 }) => {
+	const time = useTimeSync({ maxRefreshIntervalMs: 30_000 });
 	const [licenseIDMarkedForRemoval, setLicenseIDMarkedForRemoval] = useState<
 		number | undefined
 	>(undefined);
@@ -92,10 +94,8 @@ export const LicenseCard: FC<LicenseCardProps> = ({
 						alignItems="center"
 						width="134px" // standardize width of date column
 					>
-						{compareAsc(
-							new Date(license.claims.license_expires * 1000),
-							new Date(),
-						) < 1 ? (
+						{compareAsc(new Date(license.claims.license_expires * 1000), time) <
+						1 ? (
 							<Pill css={styles.expiredBadge} type="error">
 								Expired
 							</Pill>
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index 0c9b54e273963..cb5bc3d648725 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -7,6 +7,7 @@ import { type FC, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { SignInForm } from "./SignInForm";
 import { TermsOfServiceLink } from "./TermsOfServiceLink";
+import { useTimeSync } from "hooks/useTimeSync";
 
 export interface LoginPageViewProps {
 	authMethods: AuthMethods | undefined;
@@ -27,6 +28,10 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	onSignIn,
 	redirectTo,
 }) => {
+	const year = useTimeSync({
+		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		select: (date) => date.getFullYear(),
+	});
 	const location = useLocation();
 	// This allows messages to be displayed at the top of the sign in form.
 	// Helpful for any redirects that want to inform the user of something.
@@ -57,9 +62,7 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 					/>
 				)}
 				<footer css={styles.footer}>
-					<div>
-						Copyright &copy; {new Date().getFullYear()} Coder Technologies, Inc.
-					</div>
+					<div>Copyright &copy; {year} Coder Technologies, Inc.</div>
 					<div>{buildInfo?.version}</div>
 					{tosAccepted && (
 						<TermsOfServiceLink
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index 4a3dba65cacaa..291c7a68fe452 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -19,6 +19,7 @@ import {
 } from "date-fns";
 import { type ComponentProps, type FC, useRef, useState } from "react";
 import { DateRangePicker, createStaticRanges } from "react-date-range";
+import { useTimeSync } from "hooks/useTimeSync";
 
 // The type definition from @types is wrong
 declare module "react-date-range" {
@@ -42,6 +43,7 @@ interface DateRangeProps {
 }
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
+	const currentTime = useTimeSync({ maxRefreshIntervalMs: 60_000 });
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
 		{
@@ -91,7 +93,7 @@ export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
 					moveRangeOnFirstSelection={false}
 					months={2}
 					ranges={ranges}
-					maxDate={new Date()}
+					maxDate={currentTime}
 					direction="horizontal"
 					staticRanges={createStaticRanges([
 						{
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 097b8fce513e7..9872b38ed680e 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -62,6 +62,7 @@ import { DateRange as DailyPicker, type DateRangeValue } from "./DateRange";
 import { type InsightsInterval, IntervalMenu } from "./IntervalMenu";
 import { WeekPicker, numberOfWeeksOptions } from "./WeekPicker";
 import { lastWeeks } from "./utils";
+import { MAX_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
 
 const DEFAULT_NUMBER_OF_WEEKS = numberOfWeeksOptions[0];
 
@@ -69,11 +70,22 @@ export default function TemplateInsightsPage() {
 	const { template } = useTemplateLayoutContext();
 	const [searchParams, setSearchParams] = useSearchParams();
 
-	const defaultInterval = getDefaultInterval(template);
-	const interval =
-		(searchParams.get("interval") as InsightsInterval) || defaultInterval;
-
-	const dateRange = getDateRange(searchParams, interval);
+	const insightsInterval = useTimeSync<InsightsInterval>({
+		maxRefreshIntervalMs: MAX_REFRESH_ONE_DAY,
+		select: (newDatetime) => {
+			const templateCreateDate = new Date(template.created_at);
+			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDatetime;
+			const defaultInterval = hasFiveWeeksOrMore ? "week" : "day";
+
+			const paramsValue = searchParams.get("interval");
+			if (paramsValue === "week" || paramsValue === "day") {
+				return paramsValue;
+			}
+			return defaultInterval;
+		},
+	});
+
+	const dateRange = getDateRange(searchParams, insightsInterval);
 	const setDateRange = (newDateRange: DateRangeValue) => {
 		searchParams.set("startDate", newDateRange.startDate.toISOString());
 		searchParams.set("endDate", newDateRange.endDate.toISOString());
@@ -89,7 +101,7 @@ export default function TemplateInsightsPage() {
 		end_time: toISOLocal(dateRange.endDate, baseOffset),
 	};
 
-	const insightsFilter = { ...commonFilters, interval };
+	const insightsFilter = { ...commonFilters, interval: insightsInterval };
 	const { data: templateInsights } = useQuery(insightsTemplate(insightsFilter));
 	const { data: userLatency } = useQuery(insightsUserLatency(commonFilters));
 	const { data: userActivity } = useQuery(insightsUserActivity(commonFilters));
@@ -108,7 +120,7 @@ export default function TemplateInsightsPage() {
 				controls={
 					<>
 						<IntervalMenu
-							value={interval}
+							value={insightsInterval}
 							onChange={(interval) => {
 								// When going from daily to week we need to set a safe week range
 								if (interval === "week") {
@@ -118,7 +130,7 @@ export default function TemplateInsightsPage() {
 								setSearchParams(searchParams);
 							}}
 						/>
-						{interval === "day" ? (
+						{insightsInterval === "day" ? (
 							<DailyPicker value={dateRange} onChange={setDateRange} />
 						) : (
 							<WeekPicker value={dateRange} onChange={setDateRange} />
@@ -128,20 +140,13 @@ export default function TemplateInsightsPage() {
 				templateInsights={templateInsights}
 				userLatency={userLatency}
 				userActivity={userActivity}
-				interval={interval}
+				interval={insightsInterval}
 				entitlements={entitlementsQuery}
 			/>
 		</>
 	);
 }
 
-const getDefaultInterval = (template: Template) => {
-	const now = new Date();
-	const templateCreateDate = new Date(template.created_at);
-	const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < now;
-	return hasFiveWeeksOrMore ? "week" : "day";
-};
-
 const getDateRange = (
 	searchParams: URLSearchParams,
 	interval: InsightsInterval,
@@ -412,7 +417,9 @@ const TemplateUsagePanel: FC<TemplateUsagePanelProps> = ({
 	...panelProps
 }) => {
 	const theme = useTheme();
-	const validUsage = data?.filter((u) => u.seconds > 0);
+	const validUsage = data
+		?.filter((u) => u.seconds > 0)
+		.sort((a, b) => b.seconds - a.seconds);
 	const totalInSeconds =
 		validUsage?.reduce((total, usage) => total + usage.seconds, 0) ?? 1;
 	const usageColors = chroma
@@ -438,86 +445,82 @@ const TemplateUsagePanel: FC<TemplateUsagePanelProps> = ({
 							gap: 24,
 						}}
 					>
-						{validUsage
-							.sort((a, b) => b.seconds - a.seconds)
-							.map((usage, i) => {
-								const percentage = (usage.seconds / totalInSeconds) * 100;
-								return (
-									<div
-										key={usage.slug}
-										css={{ display: "flex", gap: 24, alignItems: "center" }}
-									>
+						{validUsage.map((usage, i) => {
+							const percentage = (usage.seconds / totalInSeconds) * 100;
+							return (
+								<div
+									key={usage.slug}
+									css={{ display: "flex", gap: 24, alignItems: "center" }}
+								>
+									<div css={{ display: "flex", alignItems: "center", gap: 8 }}>
 										<div
-											css={{ display: "flex", alignItems: "center", gap: 8 }}
-										>
-											<div
-												css={{
-													width: 20,
-													height: 20,
-													display: "flex",
-													alignItems: "center",
-													justifyContent: "center",
-												}}
-											>
-												<img
-													src={usage.icon}
-													alt=""
-													style={{
-														objectFit: "contain",
-														width: "100%",
-														height: "100%",
-													}}
-												/>
-											</div>
-											<div css={{ fontSize: 13, fontWeight: 500, width: 200 }}>
-												{usage.display_name}
-											</div>
-										</div>
-										<Tooltip
-											title={`${Math.floor(percentage)}%`}
-											placement="top"
-											arrow
+											css={{
+												width: 20,
+												height: 20,
+												display: "flex",
+												alignItems: "center",
+												justifyContent: "center",
+											}}
 										>
-											<LinearProgress
-												value={percentage}
-												variant="determinate"
-												css={{
+											<img
+												src={usage.icon}
+												alt=""
+												style={{
+													objectFit: "contain",
 													width: "100%",
-													height: 8,
-													backgroundColor: theme.palette.divider,
-													"& .MuiLinearProgress-bar": {
-														backgroundColor: usageColors[i],
-														borderRadius: 999,
-													},
+													height: "100%",
 												}}
 											/>
-										</Tooltip>
-										<Stack
-											spacing={0}
+										</div>
+										<div css={{ fontSize: 13, fontWeight: 500, width: 200 }}>
+											{usage.display_name}
+										</div>
+									</div>
+									<Tooltip
+										title={`${Math.floor(percentage)}%`}
+										placement="top"
+										arrow
+									>
+										<LinearProgress
+											value={percentage}
+											variant="determinate"
 											css={{
-												fontSize: 13,
-												color: theme.palette.text.secondary,
-												width: 120,
-												flexShrink: 0,
-												lineHeight: "1.5",
+												width: "100%",
+												height: 8,
+												backgroundColor: theme.palette.divider,
+												"& .MuiLinearProgress-bar": {
+													backgroundColor: usageColors[i],
+													borderRadius: 999,
+												},
 											}}
-										>
-											{formatTime(usage.seconds)}
-											{usage.times_used > 0 && (
-												<span
-													css={{
-														fontSize: 12,
-														color: theme.palette.text.disabled,
-													}}
-												>
-													Opened {usage.times_used.toLocaleString()}{" "}
-													{usage.times_used === 1 ? "time" : "times"}
-												</span>
-											)}
-										</Stack>
-									</div>
-								);
-							})}
+										/>
+									</Tooltip>
+									<Stack
+										spacing={0}
+										css={{
+											fontSize: 13,
+											color: theme.palette.text.secondary,
+											width: 120,
+											flexShrink: 0,
+											lineHeight: "1.5",
+										}}
+									>
+										{formatTime(usage.seconds)}
+										{usage.times_used > 0 && (
+											<span
+												css={{
+													fontSize: 12,
+													color: theme.palette.text.disabled,
+												}}
+											>
+												Opened {usage.times_used.toLocaleString()}{" "}
+												{usage.times_used === 1 ? "time" : "times"}
+											</span>
+										)}
+									</Stack>
+								</div>
+							);
+						})}
 					</div>
 				)}
 			</PanelContent>
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index cee2ed33069ae..256fd11854646 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -19,6 +19,7 @@ import type {
 } from "api/typesGenerated";
 import { useProxy } from "contexts/ProxyContext";
 import { formatDistance, formatDistanceToNow } from "date-fns";
+import { MAX_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import type { FC } from "react";
 import { createAppLinkHref } from "utils/apps";
 
@@ -152,6 +153,10 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	agents,
 	referenceDate,
 }) => {
+	const comparisonDate = useTimeSync({
+		maxRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
+		select: (dateState) => referenceDate ?? dateState,
+	});
 	const theme = useTheme();
 	const { proxy } = useProxy();
 	const preferredPathBase = proxy.preferredPathAppURL;
@@ -165,15 +170,13 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 		})),
 	);
 
-	// 2. Sort statuses chronologically (newest first)
+	// 2. Sort statuses chronologically (newest first) - mutating the value is
+	// fine since it's not an outside parameter
 	allStatuses.sort(
 		(a, b) =>
 			new Date(b.created_at).getTime() - new Date(a.created_at).getTime(),
 	);
 
-	// Determine the reference point for time calculation
-	const comparisonDate = referenceDate ?? new Date();
-
 	if (allStatuses.length === 0) {
 		return null;
 	}
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
index 607ab4d86e4d1..36f7b99cc0d55 100644
--- a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
+++ b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -15,7 +15,7 @@ import type { Template, Workspace } from "api/typesGenerated";
 import { TopbarData, TopbarIcon } from "components/FullPageLayout/Topbar";
 import { displayError, displaySuccess } from "components/GlobalSnackbar/utils";
 import dayjs, { type Dayjs } from "dayjs";
-import { useTime } from "hooks/useTime";
+import { useTimeSync } from "hooks/useTimeSync";
 import { getWorkspaceActivityStatus } from "modules/workspaces/activity";
 import { type FC, type ReactNode, forwardRef, useRef, useState } from "react";
 import { useMutation, useQueryClient } from "react-query";
@@ -162,7 +162,10 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 		}, 500);
 	};
 
-	const activityStatus = useTime(() => getWorkspaceActivityStatus(workspace));
+	const activityStatus = useTimeSync({
+		maxRefreshIntervalMs: 1_000,
+		select: () => getWorkspaceActivityStatus(workspace),
+	});
 	const { message, tooltip, danger } = autostopDisplay(
 		workspace,
 		activityStatus,
diff --git a/site/src/pages/WorkspacesPage/LastUsed.tsx b/site/src/pages/WorkspacesPage/LastUsed.tsx
index a53ea5ed5ba01..6f96f3f67b142 100644
--- a/site/src/pages/WorkspacesPage/LastUsed.tsx
+++ b/site/src/pages/WorkspacesPage/LastUsed.tsx
@@ -1,9 +1,8 @@
-import { useTheme } from "@emotion/react";
 import { Stack } from "components/Stack/Stack";
 import { StatusIndicatorDot } from "components/StatusIndicator/StatusIndicator";
 import dayjs from "dayjs";
 import relativeTime from "dayjs/plugin/relativeTime";
-import { useTime } from "hooks/useTime";
+import { useTimeSync } from "hooks/useTimeSync";
 import type { FC } from "react";
 
 dayjs.extend(relativeTime);
@@ -12,35 +11,36 @@ interface LastUsedProps {
 }
 
 export const LastUsed: FC<LastUsedProps> = ({ lastUsedAt }) => {
-	const theme = useTheme();
+	const [circle, message] = useTimeSync({
+		maxRefreshIntervalMs: 1_000,
+		select: (date) => {
+			const t = dayjs(lastUsedAt);
+			const now = dayjs(date);
+			let message = t.fromNow();
+			let circle = <StatusIndicatorDot variant="inactive" />;
 
-	const [circle, message] = useTime(() => {
-		const t = dayjs(lastUsedAt);
-		const now = dayjs();
-		let message = t.fromNow();
-		let circle = <StatusIndicatorDot variant="inactive" />;
+			if (t.isAfter(now.subtract(1, "hour"))) {
+				circle = <StatusIndicatorDot variant="success" />;
+				// Since the agent reports on a 10m interval,
+				// the last_used_at can be inaccurate when recent.
+				message = "Now";
+			} else if (t.isAfter(now.subtract(3, "day"))) {
+				circle = <StatusIndicatorDot variant="pending" />;
+			} else if (t.isAfter(now.subtract(1, "month"))) {
+				circle = <StatusIndicatorDot variant="warning" />;
+			} else if (t.isAfter(now.subtract(100, "year"))) {
+				circle = <StatusIndicatorDot variant="failed" />;
+			} else {
+				message = "Never";
+			}
 
-		if (t.isAfter(now.subtract(1, "hour"))) {
-			circle = <StatusIndicatorDot variant="success" />;
-			// Since the agent reports on a 10m interval,
-			// the last_used_at can be inaccurate when recent.
-			message = "Now";
-		} else if (t.isAfter(now.subtract(3, "day"))) {
-			circle = <StatusIndicatorDot variant="pending" />;
-		} else if (t.isAfter(now.subtract(1, "month"))) {
-			circle = <StatusIndicatorDot variant="warning" />;
-		} else if (t.isAfter(now.subtract(100, "year"))) {
-			circle = <StatusIndicatorDot variant="failed" />;
-		} else {
-			message = "Never";
-		}
-
-		return [circle, message];
+			return [circle, message] as const;
+		},
 	});
 
 	return (
 		<Stack
-			style={{ color: theme.palette.text.secondary }}
+			className="text-content-secondary"
 			direction="row"
 			spacing={1}
 			alignItems="center"

From 93f85c4ea5d0bb106a2c2360763cfacad02138c8 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Mon, 28 Apr 2025 15:54:44 +0000
Subject: [PATCH 02/29] docs: add one more todo

---
 site/src/hooks/useTimeSync.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index af1358059a9d6..d7b8ecdf977ca 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -3,6 +3,8 @@
  * 1. Finish up the interval reconciliation method
  * 2. Update the class to respect the resyncOnNewSubscription option
  * 3. Add tests
+ * 4. See if there's a way to make sure that if you provide a type parameter to
+ *    the hook, you must also provide a select function
  */
 import {
 	createContext,

From ba92d7821fcd152f58766d55437fc246ba6b8d3a Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 18:52:25 +0000
Subject: [PATCH 03/29] fix: resolve memoization wonkiness

---
 .../components/SignInLayout/SignInLayout.tsx  |  2 +-
 site/src/hooks/useTimeSync.tsx                | 64 +++++++++++--------
 .../CliInstallPage/CliInstallPageView.tsx     |  2 +-
 .../LicensesSettingsPage/LicenseCard.tsx      |  2 +-
 site/src/pages/LoginPage/LoginPageView.tsx    |  2 +-
 .../TemplateInsightsPage/DateRange.tsx        |  2 +-
 .../TemplateInsightsPage.tsx                  |  2 +-
 site/src/pages/WorkspacePage/AppStatuses.tsx  |  2 +-
 .../WorkspaceScheduleControls.tsx             |  2 +-
 site/src/pages/WorkspacesPage/LastUsed.tsx    |  2 +-
 10 files changed, 45 insertions(+), 37 deletions(-)

diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
index 751e58224adc2..1a45a7ecbe807 100644
--- a/site/src/components/SignInLayout/SignInLayout.tsx
+++ b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -4,7 +4,7 @@ import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
 	const year = useTimeSync({
-		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index af1358059a9d6..7a2b810216382 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -49,7 +49,7 @@ type TimeSyncInitOptions = Readonly<{
 	/**
 	 * The function to use when clearing intervals.
 	 *
-	 * (i.e., Clearing a previous interval because the TimeSync needs to make a
+	 * (e.g., Clearing a previous interval because the TimeSync needs to make a
 	 * new interval to increase/decrease its update speed.)
 	 */
 	clearInterval: ClearInterval;
@@ -65,7 +65,7 @@ const defaultOptions: TimeSyncInitOptions = {
 
 type SubscriptionEntry = Readonly<{
 	id: string;
-	maxRefreshIntervalMs: number;
+	idealRefreshIntervalMs: number;
 	onUpdate: (newDatetime: Date) => void;
 }>;
 
@@ -136,15 +136,15 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		const prevFastestInterval =
-			this.#subscriptions[0]?.maxRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.idealRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
 		if (this.#subscriptions.length > 1) {
 			this.#subscriptions.sort(
-				(e1, e2) => e1.maxRefreshIntervalMs - e2.maxRefreshIntervalMs,
+				(e1, e2) => e1.idealRefreshIntervalMs - e2.idealRefreshIntervalMs,
 			);
 		}
 
 		const newFastestInterval =
-			this.#subscriptions[0]?.maxRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.idealRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
 		if (prevFastestInterval === newFastestInterval) {
 			return;
 		}
@@ -187,9 +187,9 @@ export class TimeSync implements TimeSyncApi {
 	};
 
 	subscribe = (entry: SubscriptionEntry): (() => void) => {
-		if (entry.maxRefreshIntervalMs <= 0) {
+		if (entry.idealRefreshIntervalMs <= 0) {
 			throw new Error(
-				`Refresh interval ${entry.maxRefreshIntervalMs} must be a positive integer (or Infinity)`,
+				`Refresh interval ${entry.idealRefreshIntervalMs} must be a positive integer (or Infinity)`,
 			);
 		}
 
@@ -207,7 +207,7 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		this.#subscriptions[subIndex] = entry;
-		if (prev.maxRefreshIntervalMs !== entry.maxRefreshIntervalMs) {
+		if (prev.idealRefreshIntervalMs !== entry.idealRefreshIntervalMs) {
 			this.#reconcileRefreshIntervals();
 		}
 		return unsub;
@@ -246,7 +246,7 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 	// Making the TimeSync instance be initialized via React State, so that it's
 	// easy to mock it out for component and story tests. TimeSync itself should
 	// be treated like a pseudo-ref value, where its values can only be used in
-	// very specific, React-approved ways (e.g., not directly in a render path)
+	// very specific, React-approved ways
 	const [readonlySync] = useState(
 		() => new TimeSync(options ?? defaultOptions),
 	);
@@ -259,14 +259,13 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 };
 
 type UseTimeSyncOptions<T = Date> = Readonly<{
-	maxRefreshIntervalMs: number;
+	idealRefreshIntervalMs: number;
 
 	/**
 	 * Allows you to transform any date values received from the TimeSync class.
-	 *
-	 * Note that select functions are not memoized and will run on every render
-	 * (similar to the ones in React Query and Redux Toolkit's default selectors).
-	 * Select functions should be kept cheap to recalculate.
+	 * Select functions work similarly to the selects from React Query and Redux
+	 * Toolkit – you don't need to memoize them, and they will only run when the
+	 * underlying TimeSync state has changed.
 	 *
 	 * Select functions must not be async. The hook will error out at the type
 	 * level if you provide one by mistake.
@@ -292,7 +291,7 @@ type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
  * interval.
  */
 export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const { select, maxRefreshIntervalMs } = options;
+	const { select, idealRefreshIntervalMs } = options;
 
 	// Abusing useId a little bit here. It's mainly meant to be used for
 	// accessibility, but it also gives us a globally unique ID associated with
@@ -300,27 +299,36 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	const hookId = useId();
 	const timeSync = useTimeSyncContext();
 
-	// We need to define this callback using useCallback instead of useEffectEvent
-	// because we want the memoization to be invaliated when the refresh interval
-	// changes. (When the subscription callback changes by reference, that causes
-	// useSyncExternalStore to redo the subscription with the new callback). All
-	// other values need to be included in the dependency array for correctness,
-	// but their memory references should always be stable
+	// We need to define this callback using useCallback instead of
+	// useEffectEvent because we want the memoization to be invaliated when the
+	// refresh interval changes. (When the subscription callback changes by
+	// reference, that causes useSyncExternalStore to redo the subscription with
+	// the new callback). All other values need to be included in the dependency
+	// array for correctness, but their memory references should always be
+	// stable
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
-				maxRefreshIntervalMs,
+				idealRefreshIntervalMs,
 				onUpdate: notifyReact,
 				id: hookId,
 			});
 		},
-		[timeSync, hookId, maxRefreshIntervalMs],
+		[timeSync, hookId, idealRefreshIntervalMs],
 	);
 
-	const currentTime = useSyncExternalStore(subscribe, () =>
-		timeSync.getLatestDatetimeSnapshot(),
-	);
+	// Unlike subscribe, getNewState doesn't need to be memoized, because React
+	// doesn't actually care about its memory reference. Whenever React gets
+	// notified, it just calls the latest state function it received (whatever
+	// it happens to be). React will only re-render if the value returned by the
+	// function is different from what it got back last time (using === as the
+	// comparison). This function ONLY gets called when the subscription is
+	// first created, or when React gets notified via a subscription update.
+	const getNewState = (): T => {
+		const latestDate = timeSync.getLatestDatetimeSnapshot() as T & Date;
+		const selected = (select?.(latestDate) ?? latestDate) as T;
+		return selected;
+	};
 
-	const recast = currentTime as T & Date;
-	return select?.(recast) ?? recast;
+	return useSyncExternalStore<T>(subscribe, getNewState);
 }
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
index a4ac1486f19e3..08e04651a74ef 100644
--- a/site/src/pages/CliInstallPage/CliInstallPageView.tsx
+++ b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -11,7 +11,7 @@ type CliInstallPageViewProps = {
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
 	const year = useTimeSync({
-		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
index d9c8cd48ed512..0b27f99f2094b 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
@@ -25,7 +25,7 @@ export const LicenseCard: FC<LicenseCardProps> = ({
 	onRemove,
 	isRemoving,
 }) => {
-	const time = useTimeSync({ maxRefreshIntervalMs: 30_000 });
+	const time = useTimeSync({ idealRefreshIntervalMs: 30_000 });
 	const [licenseIDMarkedForRemoval, setLicenseIDMarkedForRemoval] = useState<
 		number | undefined
 	>(undefined);
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index cb5bc3d648725..6c25f41c21e38 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -29,7 +29,7 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	redirectTo,
 }) => {
 	const year = useTimeSync({
-		maxRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index 291c7a68fe452..a897bfc4d9be5 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -43,7 +43,7 @@ interface DateRangeProps {
 }
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
-	const currentTime = useTimeSync({ maxRefreshIntervalMs: 60_000 });
+	const currentTime = useTimeSync({ idealRefreshIntervalMs: 60_000 });
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
 		{
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 9872b38ed680e..b678530de40f8 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -71,7 +71,7 @@ export default function TemplateInsightsPage() {
 	const [searchParams, setSearchParams] = useSearchParams();
 
 	const insightsInterval = useTimeSync<InsightsInterval>({
-		maxRefreshIntervalMs: MAX_REFRESH_ONE_DAY,
+		idealRefreshIntervalMs: MAX_REFRESH_ONE_DAY,
 		select: (newDatetime) => {
 			const templateCreateDate = new Date(template.created_at);
 			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDatetime;
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index 256fd11854646..e8b58c1cef4e2 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -154,7 +154,7 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	referenceDate,
 }) => {
 	const comparisonDate = useTimeSync({
-		maxRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
+		idealRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
index 36f7b99cc0d55..05a653d26943b 100644
--- a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
+++ b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -163,7 +163,7 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 	};
 
 	const activityStatus = useTimeSync({
-		maxRefreshIntervalMs: 1_000,
+		idealRefreshIntervalMs: 1_000,
 		select: () => getWorkspaceActivityStatus(workspace),
 	});
 	const { message, tooltip, danger } = autostopDisplay(
diff --git a/site/src/pages/WorkspacesPage/LastUsed.tsx b/site/src/pages/WorkspacesPage/LastUsed.tsx
index 6ae04533e1307..447480c337e67 100644
--- a/site/src/pages/WorkspacesPage/LastUsed.tsx
+++ b/site/src/pages/WorkspacesPage/LastUsed.tsx
@@ -15,7 +15,7 @@ export const LastUsed: FC<LastUsedProps> = ({ lastUsedAt }) => {
 	 * @todo Verify that this is equivalent
 	 */
 	const [circle, message] = useTimeSync({
-		maxRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
+		idealRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
 		select: (date) => {
 			const t = dayjs(lastUsedAt);
 			const deltaMsg = t.from(dayjs(date));

From e64229383062aec9cdfbbeaa9adf44a011a1eca4 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 18:54:35 +0000
Subject: [PATCH 04/29] docs: rewrite comment for clarity

---
 site/src/hooks/useTimeSync.tsx | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 7a2b810216382..0e27bc0629459 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -317,13 +317,10 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 		[timeSync, hookId, idealRefreshIntervalMs],
 	);
 
-	// Unlike subscribe, getNewState doesn't need to be memoized, because React
-	// doesn't actually care about its memory reference. Whenever React gets
-	// notified, it just calls the latest state function it received (whatever
-	// it happens to be). React will only re-render if the value returned by the
-	// function is different from what it got back last time (using === as the
-	// comparison). This function ONLY gets called when the subscription is
-	// first created, or when React gets notified via a subscription update.
+	// This function ONLY gets called when the subscription is first created, or
+	// when React gets notified via a subscription update. It doesn't need to be
+	// memoized – useSyncExternalStore treats it similar to a useEffectEvent
+	// callback, except that unlike with useEffectEvent, it's render-safe.
 	const getNewState = (): T => {
 		const latestDate = timeSync.getLatestDatetimeSnapshot() as T & Date;
 		const selected = (select?.(latestDate) ?? latestDate) as T;

From 1bc946355fc03f2bd59493d49dde13aeb4d80c6d Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 20:07:56 +0000
Subject: [PATCH 05/29] refactor: slight cleanup

---
 site/src/hooks/useTimeSync.tsx                | 35 +++++++++----------
 .../TemplateInsightsPage.tsx                  |  4 +--
 site/src/pages/WorkspacePage/AppStatuses.tsx  |  4 +--
 site/src/pages/WorkspacesPage/LastUsed.tsx    |  4 +--
 4 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 0e27bc0629459..4ddecd3fa618e 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,8 +1,11 @@
 /**
  * @todo Things that still need to be done before this can be called done:
+ *
  * 1. Finish up the interval reconciliation method
  * 2. Update the class to respect the resyncOnNewSubscription option
- * 3. Add tests
+ * 3. Make it so that if you provide an explicit type parameter to the hook
+ *    call, you must provide a runtime select function
+ * 4. Add tests
  */
 import {
 	createContext,
@@ -15,18 +18,18 @@ import {
 	type PropsWithChildren,
 } from "react";
 
-export const MAX_REFRESH_ONE_SECOND = 1_000;
-export const MAX_REFRESH_ONE_MINUTE = 60 * 1_000;
-export const MAX_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
-export const MAX_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
+export const IDEAL_REFRESH_ONE_SECOND = 1_000;
+export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
+export const IDEAL_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
+export const IDEAL_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
 
 type SetInterval = (fn: () => void, intervalMs: number) => number;
 type ClearInterval = (id: number | undefined) => void;
 
 type TimeSyncInitOptions = Readonly<{
 	/**
-	 * Configures whether adding a new subscription will immediately create a new
-	 * time snapshot and use it to update all other subscriptions.
+	 * Configures whether adding a new subscription will immediately create a
+	 * new time snapshot and use it to update all other subscriptions.
 	 */
 	resyncOnNewSubscription: boolean;
 
@@ -216,15 +219,6 @@ export class TimeSync implements TimeSyncApi {
 
 const timeSyncContext = createContext<TimeSync | null>(null);
 
-function useTimeSyncContext(): TimeSync {
-	const timeSync = useContext(timeSyncContext);
-	if (timeSync === null) {
-		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
-	}
-
-	return timeSync;
-}
-
 type TimeSyncProviderProps = Readonly<
 	PropsWithChildren<{
 		options?: Partial<TimeSyncInitOptions>;
@@ -297,7 +291,10 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// accessibility, but it also gives us a globally unique ID associated with
 	// whichever component instance is consuming this hook
 	const hookId = useId();
-	const timeSync = useTimeSyncContext();
+	const timeSync = useContext(timeSyncContext);
+	if (timeSync === null) {
+		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
+	}
 
 	// We need to define this callback using useCallback instead of
 	// useEffectEvent because we want the memoization to be invaliated when the
@@ -322,8 +319,8 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// memoized – useSyncExternalStore treats it similar to a useEffectEvent
 	// callback, except that unlike with useEffectEvent, it's render-safe.
 	const getNewState = (): T => {
-		const latestDate = timeSync.getLatestDatetimeSnapshot() as T & Date;
-		const selected = (select?.(latestDate) ?? latestDate) as T;
+		const newSnapshot = timeSync.getLatestDatetimeSnapshot() as T & Date;
+		const selected = (select?.(newSnapshot) ?? newSnapshot) as T;
 		return selected;
 	};
 
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index b678530de40f8..711e523b87e8c 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -62,7 +62,7 @@ import { DateRange as DailyPicker, type DateRangeValue } from "./DateRange";
 import { type InsightsInterval, IntervalMenu } from "./IntervalMenu";
 import { WeekPicker, numberOfWeeksOptions } from "./WeekPicker";
 import { lastWeeks } from "./utils";
-import { MAX_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
+import { IDEAL_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
 
 const DEFAULT_NUMBER_OF_WEEKS = numberOfWeeksOptions[0];
 
@@ -71,7 +71,7 @@ export default function TemplateInsightsPage() {
 	const [searchParams, setSearchParams] = useSearchParams();
 
 	const insightsInterval = useTimeSync<InsightsInterval>({
-		idealRefreshIntervalMs: MAX_REFRESH_ONE_DAY,
+		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_DAY,
 		select: (newDatetime) => {
 			const templateCreateDate = new Date(template.created_at);
 			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDatetime;
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index e8b58c1cef4e2..b8ea09cbb36ae 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -19,7 +19,7 @@ import type {
 } from "api/typesGenerated";
 import { useProxy } from "contexts/ProxyContext";
 import { formatDistance, formatDistanceToNow } from "date-fns";
-import { MAX_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import type { FC } from "react";
 import { createAppLinkHref } from "utils/apps";
 
@@ -154,7 +154,7 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	referenceDate,
 }) => {
 	const comparisonDate = useTimeSync({
-		idealRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
+		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacesPage/LastUsed.tsx b/site/src/pages/WorkspacesPage/LastUsed.tsx
index 447480c337e67..c0817b0d1da6c 100644
--- a/site/src/pages/WorkspacesPage/LastUsed.tsx
+++ b/site/src/pages/WorkspacesPage/LastUsed.tsx
@@ -2,7 +2,7 @@ import { Stack } from "components/Stack/Stack";
 import { StatusIndicatorDot } from "components/StatusIndicator/StatusIndicator";
 import dayjs from "dayjs";
 import relativeTime from "dayjs/plugin/relativeTime";
-import { MAX_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import type { FC } from "react";
 
 dayjs.extend(relativeTime);
@@ -15,7 +15,7 @@ export const LastUsed: FC<LastUsedProps> = ({ lastUsedAt }) => {
 	 * @todo Verify that this is equivalent
 	 */
 	const [circle, message] = useTimeSync({
-		idealRefreshIntervalMs: MAX_REFRESH_ONE_MINUTE,
+		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
 		select: (date) => {
 			const t = dayjs(lastUsedAt);
 			const deltaMsg = t.from(dayjs(date));

From ee76345aff600b69b1236d12cf242d94c337acb1 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 21:20:21 -0400
Subject: [PATCH 06/29] fix: revamp the API design to remove risks of infinite
 renders

---
 site/src/App.tsx                              |  2 +-
 site/src/hooks/useTimeSync.tsx                | 89 ++++++++++++-------
 site/src/pages/LoginPage/LoginPageView.tsx    |  2 +-
 .../TemplateInsightsPage/DateRange.tsx        |  2 +-
 .../TemplateInsightsPage.tsx                  |  2 +-
 5 files changed, 61 insertions(+), 36 deletions(-)

diff --git a/site/src/App.tsx b/site/src/App.tsx
index 8c1c692ecf3e9..75e14a5ee71c1 100644
--- a/site/src/App.tsx
+++ b/site/src/App.tsx
@@ -1,5 +1,6 @@
 import "./theme/globalFonts";
 import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { TimeSyncProvider } from "hooks/useTimeSync";
 import {
 	type FC,
 	type ReactNode,
@@ -14,7 +15,6 @@ import { GlobalSnackbar } from "./components/GlobalSnackbar/GlobalSnackbar";
 import { ThemeProvider } from "./contexts/ThemeProvider";
 import { AuthProvider } from "./contexts/auth/AuthProvider";
 import { router } from "./router";
-import { TimeSyncProvider } from "hooks/useTimeSync";
 
 const defaultQueryClient = new QueryClient({
 	defaultOptions: {
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 4ddecd3fa618e..cf9ad10363391 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,22 +1,23 @@
 /**
  * @todo Things that still need to be done before this can be called done:
  *
- * 1. Finish up the interval reconciliation method
+ * 1. Revamp the entire class definition, and fill out all missing methods
  * 2. Update the class to respect the resyncOnNewSubscription option
  * 3. Make it so that if you provide an explicit type parameter to the hook
  *    call, you must provide a runtime select function
  * 4. Add tests
  */
 import {
+	type FC,
+	type PropsWithChildren,
 	createContext,
 	useCallback,
 	useContext,
 	useId,
 	useState,
 	useSyncExternalStore,
-	type FC,
-	type PropsWithChildren,
 } from "react";
+import { useEffectEvent } from "./hookPolyfills";
 
 export const IDEAL_REFRESH_ONE_SECOND = 1_000;
 export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
@@ -70,12 +71,14 @@ type SubscriptionEntry = Readonly<{
 	id: string;
 	idealRefreshIntervalMs: number;
 	onUpdate: (newDatetime: Date) => void;
+	select?: (newSnapshot: Date) => unknown;
 }>;
 
 interface TimeSyncApi {
-	getLatestDatetimeSnapshot: () => Date;
 	subscribe: (entry: SubscriptionEntry) => () => void;
 	unsubscribe: (id: string) => void;
+	getTimeSnapshot: () => Date;
+	getSelectionSnapshot: <T = unknown>(id: string) => T;
 }
 
 /**
@@ -109,8 +112,9 @@ export class TimeSync implements TimeSyncApi {
 	readonly #setInterval: SetInterval;
 	readonly #clearInterval: ClearInterval;
 
-	#latestSnapshot: Date;
+	#latestDateSnapshot: Date;
 	#subscriptions: SubscriptionEntry[];
+	#selectionCache: Map<string, unknown>;
 	#latestIntervalId: number | undefined;
 
 	constructor(options: Partial<TimeSyncInitOptions>) {
@@ -127,8 +131,9 @@ export class TimeSync implements TimeSyncApi {
 		this.#createNewDatetime = createNewDatetime;
 		this.#resyncOnNewSubscription = resyncOnNewSubscription;
 
-		this.#latestSnapshot = initialDatetime;
+		this.#latestDateSnapshot = initialDatetime;
 		this.#subscriptions = [];
+		this.#selectionCache = new Map();
 		this.#latestIntervalId = undefined;
 	}
 
@@ -139,7 +144,8 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		const prevFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.idealRefreshIntervalMs ??
+			Number.POSITIVE_INFINITY;
 		if (this.#subscriptions.length > 1) {
 			this.#subscriptions.sort(
 				(e1, e2) => e1.idealRefreshIntervalMs - e2.idealRefreshIntervalMs,
@@ -147,7 +153,8 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		const newFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.idealRefreshIntervalMs ??
+			Number.POSITIVE_INFINITY;
 		if (prevFastestInterval === newFastestInterval) {
 			return;
 		}
@@ -161,22 +168,28 @@ export class TimeSync implements TimeSyncApi {
 		 * when/how it should be updated
 		 */
 		this.#latestIntervalId = this.#setInterval(() => {
-			this.#latestSnapshot = this.#createNewDatetime(this.#latestSnapshot);
+			this.#latestDateSnapshot = this.#createNewDatetime(
+				this.#latestDateSnapshot,
+			);
 			this.#notifySubscriptions();
 		}, newFastestInterval);
 	}
 
 	#notifySubscriptions(): void {
 		for (const subEntry of this.#subscriptions) {
-			subEntry.onUpdate(this.#latestSnapshot);
+			subEntry.onUpdate(this.#latestDateSnapshot);
 		}
 	}
 
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
-	getLatestDatetimeSnapshot = (): Date => {
-		return this.#latestSnapshot;
+	getTimeSnapshot = (): Date => {
+		return this.#latestDateSnapshot;
+	};
+
+	getSelectionSnapshot = <T,>(id: string): T => {
+		return this.#selectionCache.get(id) as T;
 	};
 
 	unsubscribe = (id: string): void => {
@@ -267,8 +280,6 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
 	select?: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
 }>;
 
-type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
-
 /**
  * useTimeSync provides React bindings for the TimeSync class, letting a React
  * component bind its update lifecycles to interval updates from TimeSync. This
@@ -286,43 +297,57 @@ type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
  */
 export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	const { select, idealRefreshIntervalMs } = options;
+	const timeSync = useContext(timeSyncContext);
+	if (timeSync === null) {
+		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
+	}
 
 	// Abusing useId a little bit here. It's mainly meant to be used for
 	// accessibility, but it also gives us a globally unique ID associated with
 	// whichever component instance is consuming this hook
 	const hookId = useId();
-	const timeSync = useContext(timeSyncContext);
-	if (timeSync === null) {
-		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
-	}
+
+	// This is the one place where we're borderline breaking the React rules.
+	// useEffectEvent is meant to be used only in useEffect calls, and normally
+	// shouldn't be called inside a render. But its behavior lines up with
+	// useSyncExternalStore, letting us cheat a little. useSyncExternalStore's
+	// state getter callback is called in two scenarios:
+	// (1) Mid-render on mount
+	// (2) Whenever React is notified of a state change (outside of React).
+	//
+	// Case 2 is basically an effect with extra steps (and single-threaded JS
+	// gives us assurance about correctness). And for (1), useEffectEvent will be
+	// initialized with whatever callback you give it on mount. So for the
+	// mounting render alone, it's safe to call a useEffectEvent callback from
+	// inside a render.
+	const stableSelect = useEffectEvent((date: Date): T => {
+		const recast = date as Date & T;
+		return select?.(recast) ?? recast;
+	});
 
 	// We need to define this callback using useCallback instead of
 	// useEffectEvent because we want the memoization to be invaliated when the
 	// refresh interval changes. (When the subscription callback changes by
 	// reference, that causes useSyncExternalStore to redo the subscription with
 	// the new callback). All other values need to be included in the dependency
-	// array for correctness, but their memory references should always be
-	// stable
+	// array for correctness, but they should always maintain stable memory
+	// addresses
+	type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
 				idealRefreshIntervalMs,
-				onUpdate: notifyReact,
 				id: hookId,
+				onUpdate: notifyReact,
+				select: stableSelect,
 			});
 		},
-		[timeSync, hookId, idealRefreshIntervalMs],
+		[timeSync, hookId, stableSelect, idealRefreshIntervalMs],
 	);
 
-	// This function ONLY gets called when the subscription is first created, or
-	// when React gets notified via a subscription update. It doesn't need to be
-	// memoized – useSyncExternalStore treats it similar to a useEffectEvent
-	// callback, except that unlike with useEffectEvent, it's render-safe.
-	const getNewState = (): T => {
-		const newSnapshot = timeSync.getLatestDatetimeSnapshot() as T & Date;
-		const selected = (select?.(newSnapshot) ?? newSnapshot) as T;
-		return selected;
-	};
+	const snapshot = useSyncExternalStore<T>(subscribe, () =>
+		timeSync.getSelectionSnapshot(hookId),
+	);
 
-	return useSyncExternalStore<T>(subscribe, getNewState);
+	return snapshot;
 }
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index 6c25f41c21e38..5c0cc69c2adbb 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -3,11 +3,11 @@ import Button from "@mui/material/Button";
 import type { AuthMethods, BuildInfoResponse } from "api/typesGenerated";
 import { CustomLogo } from "components/CustomLogo/CustomLogo";
 import { Loader } from "components/Loader/Loader";
+import { useTimeSync } from "hooks/useTimeSync";
 import { type FC, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { SignInForm } from "./SignInForm";
 import { TermsOfServiceLink } from "./TermsOfServiceLink";
-import { useTimeSync } from "hooks/useTimeSync";
 
 export interface LoginPageViewProps {
 	authMethods: AuthMethods | undefined;
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index a897bfc4d9be5..4a602329f15ff 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -17,9 +17,9 @@ import {
 	startOfHour,
 	subDays,
 } from "date-fns";
+import { useTimeSync } from "hooks/useTimeSync";
 import { type ComponentProps, type FC, useRef, useState } from "react";
 import { DateRangePicker, createStaticRanges } from "react-date-range";
-import { useTimeSync } from "hooks/useTimeSync";
 
 // The type definition from @types is wrong
 declare module "react-date-range" {
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 711e523b87e8c..3eeece8bed26b 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -45,6 +45,7 @@ import {
 	subDays,
 } from "date-fns";
 import { useEmbeddedMetadata } from "hooks/useEmbeddedMetadata";
+import { IDEAL_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
 import { useTemplateLayoutContext } from "pages/TemplatePage/TemplateLayout";
 import {
 	type FC,
@@ -62,7 +63,6 @@ import { DateRange as DailyPicker, type DateRangeValue } from "./DateRange";
 import { type InsightsInterval, IntervalMenu } from "./IntervalMenu";
 import { WeekPicker, numberOfWeeksOptions } from "./WeekPicker";
 import { lastWeeks } from "./utils";
-import { IDEAL_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
 
 const DEFAULT_NUMBER_OF_WEEKS = numberOfWeeksOptions[0];
 

From 0ca593b268c94a8490b95eb7231db06c0b00b636 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 21:47:21 -0400
Subject: [PATCH 07/29] fix: beef up subscription update method

---
 site/src/hooks/useTimeSync.tsx | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index cf9ad10363391..f6b73f7aeae1f 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -171,13 +171,25 @@ export class TimeSync implements TimeSyncApi {
 			this.#latestDateSnapshot = this.#createNewDatetime(
 				this.#latestDateSnapshot,
 			);
-			this.#notifySubscriptions();
+			this.#flushUpdateToSubscriptions();
 		}, newFastestInterval);
 	}
 
-	#notifySubscriptions(): void {
+	#flushUpdateToSubscriptions(): void {
 		for (const subEntry of this.#subscriptions) {
-			subEntry.onUpdate(this.#latestDateSnapshot);
+			if (subEntry.select === undefined) {
+				subEntry.onUpdate(this.#latestDateSnapshot);
+				continue;
+			}
+
+			// Keeping things simple by only comparing values React-style with ===.
+			// If that becomes a problem down the line, we can beef the class up
+			const prevSelection = this.#selectionCache.get(subEntry.id);
+			const newSelection = subEntry.select(this.#latestDateSnapshot);
+			if (prevSelection !== newSelection) {
+				this.#selectionCache.set(subEntry.id, newSelection);
+				subEntry.onUpdate(this.#latestDateSnapshot);
+			}
 		}
 	}
 

From fc0694c5a3bf8727069ccbf98b5a37bf561e6c7b Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 21:52:04 -0400
Subject: [PATCH 08/29] fix: add back logic that was removed during merge

---
 site/src/pages/WorkspacesPage/LastUsed.tsx | 29 +++++++++++++++++-----
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/site/src/pages/WorkspacesPage/LastUsed.tsx b/site/src/pages/WorkspacesPage/LastUsed.tsx
index c0817b0d1da6c..769967d58cc80 100644
--- a/site/src/pages/WorkspacesPage/LastUsed.tsx
+++ b/site/src/pages/WorkspacesPage/LastUsed.tsx
@@ -11,16 +11,33 @@ interface LastUsedProps {
 }
 
 export const LastUsed: FC<LastUsedProps> = ({ lastUsedAt }) => {
-	/**
-	 * @todo Verify that this is equivalent
-	 */
 	const [circle, message] = useTimeSync({
 		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
 		select: (date) => {
+			/**
+			 * @todo Verify that t.from(now) is equivalent to t.fromNow()
+			 */
 			const t = dayjs(lastUsedAt);
-			const deltaMsg = t.from(dayjs(date));
-			const circle = <StatusIndicatorDot variant="inactive" />;
-			return [circle, deltaMsg] as const;
+			const now = dayjs(date);
+			let message = t.from(now);
+			let circle = <StatusIndicatorDot variant="inactive" />;
+
+			if (t.isAfter(now.subtract(1, "hour"))) {
+				circle = <StatusIndicatorDot variant="success" />;
+				// Since the agent reports on a 10m interval,
+				// the last_used_at can be inaccurate when recent.
+				message = "Now";
+			} else if (t.isAfter(now.subtract(3, "day"))) {
+				circle = <StatusIndicatorDot variant="pending" />;
+			} else if (t.isAfter(now.subtract(1, "month"))) {
+				circle = <StatusIndicatorDot variant="warning" />;
+			} else if (t.isAfter(now.subtract(100, "year"))) {
+				circle = <StatusIndicatorDot variant="failed" />;
+			} else {
+				message = "Never";
+			}
+
+			return [circle, message] as const;
 		},
 	});
 

From ebe8821fa7103b6d5610f937aa2ee5400107a384 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 22:16:56 -0400
Subject: [PATCH 09/29] chore: add provider to base Storybook meta

---
 site/src/hooks/useTimeSync.tsx                  |  2 +-
 .../NotificationsPage/storybookUtils.ts         |  2 ++
 site/src/testHelpers/storybook.tsx              | 17 ++++++++++++++++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index f6b73f7aeae1f..33340233bf607 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -111,10 +111,10 @@ export class TimeSync implements TimeSyncApi {
 	readonly #createNewDatetime: (prev: Date) => Date;
 	readonly #setInterval: SetInterval;
 	readonly #clearInterval: ClearInterval;
+	readonly #selectionCache: Map<string, unknown>;
 
 	#latestDateSnapshot: Date;
 	#subscriptions: SubscriptionEntry[];
-	#selectionCache: Map<string, unknown>;
 	#latestIntervalId: number | undefined;
 
 	constructor(options: Partial<TimeSyncInitOptions>) {
diff --git a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
index 0ceac24520e1a..6caed65d1a3d7 100644
--- a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
+++ b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
@@ -14,6 +14,7 @@ import {
 	withDashboardProvider,
 	withGlobalSnackbar,
 	withOrganizationSettingsProvider,
+	withTimeSyncProvider,
 } from "testHelpers/storybook";
 import type { NotificationsPage } from "./NotificationsPage";
 
@@ -214,5 +215,6 @@ export const baseMeta = {
 		withAuthProvider,
 		withDashboardProvider,
 		withOrganizationSettingsProvider,
+		withTimeSyncProvider,
 	],
 } satisfies Meta<typeof NotificationsPage>;
diff --git a/site/src/testHelpers/storybook.tsx b/site/src/testHelpers/storybook.tsx
index b98f250012d08..8e102b5209661 100644
--- a/site/src/testHelpers/storybook.tsx
+++ b/site/src/testHelpers/storybook.tsx
@@ -6,11 +6,12 @@ import { hasFirstUserKey, meKey } from "api/queries/users";
 import type { Entitlements } from "api/typesGenerated";
 import { GlobalSnackbar } from "components/GlobalSnackbar/GlobalSnackbar";
 import { AuthProvider } from "contexts/auth/AuthProvider";
+import { TimeSyncProvider } from "hooks/useTimeSync";
 import { DashboardContext } from "modules/dashboard/DashboardProvider";
 import { DeploymentConfigContext } from "modules/management/DeploymentConfigProvider";
 import { OrganizationSettingsContext } from "modules/management/OrganizationSettingsLayout";
 import { permissionChecks } from "modules/permissions";
-import type { FC } from "react";
+import type { FC, ReactElement } from "react";
 import { useQueryClient } from "react-query";
 import {
 	MockAppearanceConfig,
@@ -156,6 +157,20 @@ export const withGlobalSnackbar = (Story: FC) => (
 	</>
 );
 
+const storyDate = new Date("March 15, 2022");
+export const withTimeSyncProvider = (Story: FC): ReactElement => {
+	return (
+		<TimeSyncProvider
+			options={{
+				initialDatetime: storyDate,
+				resyncOnNewSubscription: false,
+			}}
+		>
+			<Story />
+		</TimeSyncProvider>
+	);
+};
+
 export const withOrganizationSettingsProvider = (Story: FC) => {
 	return (
 		<OrganizationSettingsContext.Provider

From 90f21462d49b013ffba8fd5620685474f3f267d5 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 22:31:34 -0400
Subject: [PATCH 10/29] fix: add decorator to right place

---
 site/.storybook/preview.jsx                   | 23 ++++++++++++++++++-
 .../NotificationsPage/storybookUtils.ts       |  1 -
 site/src/testHelpers/storybook.tsx            | 17 +-------------
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/site/.storybook/preview.jsx b/site/.storybook/preview.jsx
index fb13f0e7af320..65e783fe616bf 100644
--- a/site/.storybook/preview.jsx
+++ b/site/.storybook/preview.jsx
@@ -32,11 +32,18 @@ import { QueryClient, QueryClientProvider, parseQueryArgs } from "react-query";
 import { withRouter } from "storybook-addon-remix-react-router";
 import "theme/globalFonts";
 import themes from "../src/theme";
+import { TimeSyncProvider } from "../src/hooks/useTimeSync";
 
 DecoratorHelpers.initializeThemeState(Object.keys(themes), "dark");
 
 /** @type {readonly Decorator[]} */
-export const decorators = [withRouter, withQuery, withHelmet, withTheme];
+export const decorators = [
+	withRouter,
+	withQuery,
+	withHelmet,
+	withTheme,
+	withTimeSyncProvider,
+];
 
 /** @type {Preview["parameters"]} */
 export const parameters = {
@@ -101,6 +108,20 @@ function withHelmet(Story) {
 	);
 }
 
+const storyDate = new Date("March 15, 2022");
+function withTimeSyncProvider(Story) {
+	return (
+		<TimeSyncProvider
+			options={{
+				initialDatetime: storyDate,
+				resyncOnNewSubscription: false,
+			}}
+		>
+			<Story />
+		</TimeSyncProvider>
+	);
+}
+
 /** @type {Decorator} */
 function withQuery(Story, { parameters }) {
 	const queryClient = new QueryClient({
diff --git a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
index 6caed65d1a3d7..7408e9f9aeb04 100644
--- a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
+++ b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
@@ -215,6 +215,5 @@ export const baseMeta = {
 		withAuthProvider,
 		withDashboardProvider,
 		withOrganizationSettingsProvider,
-		withTimeSyncProvider,
 	],
 } satisfies Meta<typeof NotificationsPage>;
diff --git a/site/src/testHelpers/storybook.tsx b/site/src/testHelpers/storybook.tsx
index 8e102b5209661..b98f250012d08 100644
--- a/site/src/testHelpers/storybook.tsx
+++ b/site/src/testHelpers/storybook.tsx
@@ -6,12 +6,11 @@ import { hasFirstUserKey, meKey } from "api/queries/users";
 import type { Entitlements } from "api/typesGenerated";
 import { GlobalSnackbar } from "components/GlobalSnackbar/GlobalSnackbar";
 import { AuthProvider } from "contexts/auth/AuthProvider";
-import { TimeSyncProvider } from "hooks/useTimeSync";
 import { DashboardContext } from "modules/dashboard/DashboardProvider";
 import { DeploymentConfigContext } from "modules/management/DeploymentConfigProvider";
 import { OrganizationSettingsContext } from "modules/management/OrganizationSettingsLayout";
 import { permissionChecks } from "modules/permissions";
-import type { FC, ReactElement } from "react";
+import type { FC } from "react";
 import { useQueryClient } from "react-query";
 import {
 	MockAppearanceConfig,
@@ -157,20 +156,6 @@ export const withGlobalSnackbar = (Story: FC) => (
 	</>
 );
 
-const storyDate = new Date("March 15, 2022");
-export const withTimeSyncProvider = (Story: FC): ReactElement => {
-	return (
-		<TimeSyncProvider
-			options={{
-				initialDatetime: storyDate,
-				resyncOnNewSubscription: false,
-			}}
-		>
-			<Story />
-		</TimeSyncProvider>
-	);
-};
-
 export const withOrganizationSettingsProvider = (Story: FC) => {
 	return (
 		<OrganizationSettingsContext.Provider

From 532ec85e00ce011786a88a03bd41fa4be7bcccb0 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 22:35:38 -0400
Subject: [PATCH 11/29] fix: remove ghost import

---
 site/.storybook/preview.jsx                                     | 2 +-
 .../DeploymentSettingsPage/NotificationsPage/storybookUtils.ts  | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/site/.storybook/preview.jsx b/site/.storybook/preview.jsx
index 65e783fe616bf..92b480bc76b7d 100644
--- a/site/.storybook/preview.jsx
+++ b/site/.storybook/preview.jsx
@@ -31,8 +31,8 @@ import { HelmetProvider } from "react-helmet-async";
 import { QueryClient, QueryClientProvider, parseQueryArgs } from "react-query";
 import { withRouter } from "storybook-addon-remix-react-router";
 import "theme/globalFonts";
-import themes from "../src/theme";
 import { TimeSyncProvider } from "../src/hooks/useTimeSync";
+import themes from "../src/theme";
 
 DecoratorHelpers.initializeThemeState(Object.keys(themes), "dark");
 
diff --git a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
index 7408e9f9aeb04..0ceac24520e1a 100644
--- a/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
+++ b/site/src/pages/DeploymentSettingsPage/NotificationsPage/storybookUtils.ts
@@ -14,7 +14,6 @@ import {
 	withDashboardProvider,
 	withGlobalSnackbar,
 	withOrganizationSettingsProvider,
-	withTimeSyncProvider,
 } from "testHelpers/storybook";
 import type { NotificationsPage } from "./NotificationsPage";
 

From 8c5c49dbc445e4b84e681ab38d2caf2316f1edd0 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Tue, 29 Apr 2025 22:40:28 -0400
Subject: [PATCH 12/29] fix: get rid of UMD import warnings

---
 site/.storybook/preview.jsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/site/.storybook/preview.jsx b/site/.storybook/preview.jsx
index 92b480bc76b7d..6525aa9e38b97 100644
--- a/site/.storybook/preview.jsx
+++ b/site/.storybook/preview.jsx
@@ -16,13 +16,13 @@
  * Storybook decorator function used to inject baseline data dependencies into
  * our React components during testing.
  */
+import React from "react";
 import "../src/index.css";
 import { ThemeProvider as EmotionThemeProvider } from "@emotion/react";
 import CssBaseline from "@mui/material/CssBaseline";
 import {
 	ThemeProvider as MuiThemeProvider,
 	StyledEngineProvider,
-	// biome-ignore lint/nursery/noRestrictedImports: we extend the MUI theme
 } from "@mui/material/styles";
 import { DecoratorHelpers } from "@storybook/addon-themes";
 import isChromatic from "chromatic/isChromatic";
@@ -109,6 +109,8 @@ function withHelmet(Story) {
 }
 
 const storyDate = new Date("March 15, 2022");
+
+/** @type {Decorator} */
 function withTimeSyncProvider(Story) {
 	return (
 		<TimeSyncProvider

From 62e5f8eb56fac9353e3d6302fbd845e6e9fc85e5 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 15:12:01 +0000
Subject: [PATCH 13/29] refactor: split up TimeSync into vanilla file and React
 file

---
 site/src/hooks/useTimeSync.tsx | 252 +++++++--------------------------
 site/src/utils/TimeSync.ts     | 195 +++++++++++++++++++++++++
 2 files changed, 248 insertions(+), 199 deletions(-)
 create mode 100644 site/src/utils/TimeSync.ts

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index afb85f646eefd..6aa2e6ddfedbd 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,252 +1,107 @@
 /**
  * @todo Things that still need to be done before this can be called done:
  *
- * 1. Revamp the entire class definition, and fill out all missing methods
- * 2. Update the class to respect the resyncOnNewSubscription option
+ * 1. Fill out all incomplete methods
+ * 2. Make sure the class respects the resyncOnNewSubscription option
  * 3. Add tests
  * 4. See if there's a way to make sure that if you provide a type parameter to
  *    the hook, you must also provide a select function
  */
 import {
+	createContext,
 	type FC,
 	type PropsWithChildren,
-	createContext,
 	useCallback,
 	useContext,
 	useId,
 	useState,
 	useSyncExternalStore,
 } from "react";
+import {
+	defaultOptions,
+	type SubscriptionEntry,
+	TimeSync,
+	type TimeSyncInitOptions,
+} from "utils/TimeSync";
 import { useEffectEvent } from "./hookPolyfills";
 
-export const IDEAL_REFRESH_ONE_SECOND = 1_000;
-export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
-export const IDEAL_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
-export const IDEAL_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
-
-type SetInterval = (fn: () => void, intervalMs: number) => number;
-type ClearInterval = (id: number | undefined) => void;
-
-type TimeSyncInitOptions = Readonly<{
-	/**
-	 * Configures whether adding a new subscription will immediately create a
-	 * new time snapshot and use it to update all other subscriptions.
-	 */
-	resyncOnNewSubscription: boolean;
-
-	/**
-	 * The Date value to use when initializing a TimeSync instance.
-	 */
-	initialDatetime: Date;
+export {
+	IDEAL_REFRESH_ONE_DAY,
+	IDEAL_REFRESH_ONE_HOUR,
+	IDEAL_REFRESH_ONE_MINUTE,
+	IDEAL_REFRESH_ONE_SECOND,
+} from "utils/TimeSync";
 
-	/**
-	 * The function to use when creating a new datetime snapshot when a TimeSync
-	 * needs to update on an interval.
-	 */
-	createNewDatetime: (prevDatetime: Date) => Date;
+type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 
-	/**
-	 * The function to use when creating new intervals.
-	 */
-	setInterval: SetInterval;
+type ReactTimeSyncSubscriptionEntry = Readonly<
+	SubscriptionEntry & {
+		select?: (newSnapshot: Date) => unknown;
+	}
+>;
 
-	/**
-	 * The function to use when clearing intervals.
-	 *
-	 * (e.g., Clearing a previous interval because the TimeSync needs to make a
-	 * new interval to increase/decrease its update speed.)
-	 */
-	clearInterval: ClearInterval;
-}>;
+type ReactTimeSyncInitOptions = Readonly<
+	TimeSyncInitOptions & {
+		/**
+		 * Configures whether adding a new subscription will immediately create
+		 * a new time snapshot and use it to update all other subscriptions.
+		 */
+		resyncOnNewSubscription: boolean;
+	}
+>;
 
-const defaultOptions: TimeSyncInitOptions = {
-	initialDatetime: new Date(),
+const defaultReactTimeSyncOptions: ReactTimeSyncInitOptions = {
+	...defaultOptions,
 	resyncOnNewSubscription: true,
-	createNewDatetime: () => new Date(),
-	setInterval: window.setInterval,
-	clearInterval: window.clearInterval,
 };
 
-type SubscriptionEntry = Readonly<{
-	id: string;
-	idealRefreshIntervalMs: number;
-	onUpdate: (newDatetime: Date) => void;
-	select?: (newSnapshot: Date) => unknown;
-}>;
-
-interface TimeSyncApi {
-	subscribe: (entry: SubscriptionEntry) => () => void;
-	unsubscribe: (id: string) => void;
-	getTimeSnapshot: () => Date;
+interface ReactTimeSyncApi {
+	subscribe: (entry: ReactTimeSyncSubscriptionEntry) => () => void;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
 }
 
-/**
- * TimeSync provides a centralized authority for working with time values in a
- * more structured, "pure function-ish" way, where all dependents for the time
- * values must stay in sync with each other. (e.g., in a React codebase, you
- * want multiple components that rely on time values to update together, to
- * avoid screen tearing and stale data for only some parts of the screen).
- *
- * It lets any number of consumers subscribe to it, requiring that subscribers
- * define the slowest possible update interval they need to receive new time
- * values for. A value of positive Infinity indicates that a subscriber doesn't
- * need updates; if all subscriptions have an update interval of Infinity, the
- * class may not dispatch updates.
- *
- * The class aggregates all the update intervals, and will dispatch updates to
- * all consumers based on the fastest refresh interval needed. (e.g., if
- * subscriber A needs no updates, but subscriber B needs updates every second,
- * BOTH will update every second until subscriber B unsubscribes. After that,
- * TimeSync will stop dispatching updates until subscription C gets added, and C
- * has a non-Infinite update interval).
- *
- * By design, there is no way to make one subscriber disable updates. That
- * defeats the goal of needing to keep everything in sync with each other. If
- * updates are happening too frequently in React, restructure how you're
- * composing your components to minimize the costs of re-renders.
- */
-export class TimeSync implements TimeSyncApi {
+class ReactTimeSync implements ReactTimeSyncApi {
+	readonly #timeSync: TimeSync;
 	readonly #resyncOnNewSubscription: boolean;
-	readonly #createNewDatetime: (prev: Date) => Date;
-	readonly #setInterval: SetInterval;
-	readonly #clearInterval: ClearInterval;
 	readonly #selectionCache: Map<string, unknown>;
 
-	#latestDateSnapshot: Date;
-	#subscriptions: SubscriptionEntry[];
-	#latestIntervalId: number | undefined;
-
-	constructor(options: Partial<TimeSyncInitOptions>) {
+	constructor(options: Partial<ReactTimeSyncInitOptions>) {
 		const {
+			resyncOnNewSubscription = defaultReactTimeSyncOptions.resyncOnNewSubscription,
 			initialDatetime = defaultOptions.initialDatetime,
-			resyncOnNewSubscription = defaultOptions.resyncOnNewSubscription,
 			createNewDatetime = defaultOptions.createNewDatetime,
 			setInterval = defaultOptions.setInterval,
 			clearInterval = defaultOptions.clearInterval,
 		} = options;
 
-		this.#setInterval = setInterval;
-		this.#clearInterval = clearInterval;
-		this.#createNewDatetime = createNewDatetime;
-		this.#resyncOnNewSubscription = resyncOnNewSubscription;
-
-		this.#latestDateSnapshot = initialDatetime;
-		this.#subscriptions = [];
 		this.#selectionCache = new Map();
-		this.#latestIntervalId = undefined;
-	}
-
-	#reconcileRefreshIntervals(): void {
-		if (this.#subscriptions.length === 0) {
-			this.#clearInterval(this.#latestIntervalId);
-			return;
-		}
-
-		const prevFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ??
-			Number.POSITIVE_INFINITY;
-		if (this.#subscriptions.length > 1) {
-			this.#subscriptions.sort(
-				(e1, e2) => e1.idealRefreshIntervalMs - e2.idealRefreshIntervalMs,
-			);
-		}
-
-		const newFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ??
-			Number.POSITIVE_INFINITY;
-		if (prevFastestInterval === newFastestInterval) {
-			return;
-		}
-		if (newFastestInterval === Number.POSITIVE_INFINITY) {
-			this.#clearInterval(this.#latestIntervalId);
-			return;
-		}
-
-		/**
-		 * @todo Figure out the conditions when the interval should be set up, and
-		 * when/how it should be updated
-		 */
-		this.#latestIntervalId = this.#setInterval(() => {
-			this.#latestDateSnapshot = this.#createNewDatetime(
-				this.#latestDateSnapshot,
-			);
-			this.#flushUpdateToSubscriptions();
-		}, newFastestInterval);
-	}
-
-	#flushUpdateToSubscriptions(): void {
-		for (const subEntry of this.#subscriptions) {
-			if (subEntry.select === undefined) {
-				subEntry.onUpdate(this.#latestDateSnapshot);
-				continue;
-			}
-
-			// Keeping things simple by only comparing values React-style with ===.
-			// If that becomes a problem down the line, we can beef the class up
-			const prevSelection = this.#selectionCache.get(subEntry.id);
-			const newSelection = subEntry.select(this.#latestDateSnapshot);
-			if (prevSelection !== newSelection) {
-				this.#selectionCache.set(subEntry.id, newSelection);
-				subEntry.onUpdate(this.#latestDateSnapshot);
-			}
-		}
+		this.#resyncOnNewSubscription = resyncOnNewSubscription;
+		this.#timeSync = new TimeSync({
+			initialDatetime,
+			createNewDatetime,
+			setInterval,
+			clearInterval,
+		});
 	}
 
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
-	getTimeSnapshot = (): Date => {
-		return this.#latestDateSnapshot;
+	subscribe = (entry: ReactTimeSyncSubscriptionEntry): (() => void) => {
+		this.#timeSync.subscribe(entry);
+		return () => this.#timeSync.unsubscribe(entry.id);
 	};
 
 	getSelectionSnapshot = <T,>(id: string): T => {
 		return this.#selectionCache.get(id) as T;
 	};
-
-	unsubscribe = (id: string): void => {
-		const updated = this.#subscriptions.filter((s) => s.id !== id);
-		if (updated.length === this.#subscriptions.length) {
-			return;
-		}
-
-		this.#subscriptions = updated;
-		this.#reconcileRefreshIntervals();
-	};
-
-	subscribe = (entry: SubscriptionEntry): (() => void) => {
-		if (entry.idealRefreshIntervalMs <= 0) {
-			throw new Error(
-				`Refresh interval ${entry.idealRefreshIntervalMs} must be a positive integer (or Infinity)`,
-			);
-		}
-
-		const unsub = () => this.unsubscribe(entry.id);
-		const subIndex = this.#subscriptions.findIndex((s) => s.id === entry.id);
-		if (subIndex === -1) {
-			this.#subscriptions.push(entry);
-			this.#reconcileRefreshIntervals();
-			return unsub;
-		}
-
-		const prev = this.#subscriptions[subIndex];
-		if (prev === undefined) {
-			throw new Error("Went out of bounds");
-		}
-
-		this.#subscriptions[subIndex] = entry;
-		if (prev.idealRefreshIntervalMs !== entry.idealRefreshIntervalMs) {
-			this.#reconcileRefreshIntervals();
-		}
-		return unsub;
-	};
 }
 
-const timeSyncContext = createContext<TimeSync | null>(null);
+const timeSyncContext = createContext<ReactTimeSync | null>(null);
 
 type TimeSyncProviderProps = Readonly<
 	PropsWithChildren<{
-		options?: Partial<TimeSyncInitOptions>;
+		options?: Partial<ReactTimeSyncInitOptions>;
 	}>
 >;
 
@@ -267,7 +122,7 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 	// be treated like a pseudo-ref value, where its values can only be used in
 	// very specific, React-approved ways
 	const [readonlySync] = useState(
-		() => new TimeSync(options ?? defaultOptions),
+		() => new ReactTimeSync(options ?? defaultReactTimeSyncOptions),
 	);
 
 	return (
@@ -328,8 +183,8 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// (2) Whenever React is notified of a state change (outside of React).
 	//
 	// Case 2 is basically an effect with extra steps (and single-threaded JS
-	// gives us assurance about correctness). And for (1), useEffectEvent will be
-	// initialized with whatever callback you give it on mount. So for the
+	// gives us assurance about correctness). And for (1), useEffectEvent will
+	// be initialized with whatever callback you give it on mount. So for the
 	// mounting render alone, it's safe to call a useEffectEvent callback from
 	// inside a render.
 	const stableSelect = useEffectEvent((date: Date): T => {
@@ -344,7 +199,6 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// the new callback). All other values need to be included in the dependency
 	// array for correctness, but they should always maintain stable memory
 	// addresses
-	type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
new file mode 100644
index 0000000000000..1f712b9ed7302
--- /dev/null
+++ b/site/src/utils/TimeSync.ts
@@ -0,0 +1,195 @@
+/**
+ * @todo What's left to do here:
+ * 1. Fill out all incomplete methods
+ * 2. Add tests
+ */
+export const IDEAL_REFRESH_ONE_SECOND = 1_000;
+export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
+export const IDEAL_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
+export const IDEAL_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
+
+export type SetInterval = (fn: () => void, intervalMs: number) => number;
+export type ClearInterval = (id: number | undefined) => void;
+
+export type TimeSyncInitOptions = Readonly<{
+	/**
+	 * The Date value to use when initializing a TimeSync instance.
+	 */
+	initialDatetime: Date;
+
+	/**
+	 * The function to use when creating a new datetime snapshot when a TimeSync
+	 * needs to update on an interval.
+	 */
+	createNewDatetime: (prevDatetime: Date) => Date;
+
+	/**
+	 * The function to use when creating new intervals.
+	 */
+	setInterval: SetInterval;
+
+	/**
+	 * The function to use when clearing intervals.
+	 *
+	 * (e.g., Clearing a previous interval because the TimeSync needs to make a
+	 * new interval to increase/decrease its update speed.)
+	 */
+	clearInterval: ClearInterval;
+}>;
+
+export const defaultOptions: TimeSyncInitOptions = {
+	initialDatetime: new Date(),
+	createNewDatetime: () => new Date(),
+	setInterval: window.setInterval,
+	clearInterval: window.clearInterval,
+};
+
+export type SubscriptionEntry = Readonly<{
+	id: string;
+	idealRefreshIntervalMs: number;
+	onUpdate: (newDatetime: Date) => void;
+}>;
+
+interface TimeSyncApi {
+	subscribe: (entry: SubscriptionEntry) => void;
+	unsubscribe: (id: string) => void;
+	getTimeSnapshot: () => Date;
+	invalidateSnapshot: () => void;
+}
+
+/**
+ * TimeSync provides a centralized authority for working with time values in a
+ * more structured, "pure function-ish" way, where all dependents for the time
+ * values must stay in sync with each other. (e.g., in a React codebase, you
+ * want multiple components that rely on time values to update together, to
+ * avoid screen tearing and stale data for only some parts of the screen).
+ *
+ * It lets any number of consumers subscribe to it, requiring that subscribers
+ * define the slowest possible update interval they need to receive new time
+ * values for. A value of positive Infinity indicates that a subscriber doesn't
+ * need updates; if all subscriptions have an update interval of Infinity, the
+ * class may not dispatch updates.
+ *
+ * The class aggregates all the update intervals, and will dispatch updates to
+ * all consumers based on the fastest refresh interval needed. (e.g., if
+ * subscriber A needs no updates, but subscriber B needs updates every second,
+ * BOTH will update every second until subscriber B unsubscribes. After that,
+ * TimeSync will stop dispatching updates until subscription C gets added, and C
+ * has a non-Infinite update interval).
+ *
+ * By design, there is no way to make one subscriber disable updates. That
+ * defeats the goal of needing to keep everything in sync with each other. If
+ * updates are happening too frequently in React, restructure how you're
+ * composing your components to minimize the costs of re-renders.
+ */
+export class TimeSync implements TimeSyncApi {
+	readonly #createNewDatetime: (prev: Date) => Date;
+	readonly #setInterval: SetInterval;
+	readonly #clearInterval: ClearInterval;
+
+	#latestDateSnapshot: Date;
+	#subscriptions: SubscriptionEntry[];
+	#latestIntervalId: number | undefined;
+
+	constructor(options: Partial<TimeSyncInitOptions>) {
+		const {
+			initialDatetime = defaultOptions.initialDatetime,
+			createNewDatetime = defaultOptions.createNewDatetime,
+			setInterval = defaultOptions.setInterval,
+			clearInterval = defaultOptions.clearInterval,
+		} = options;
+
+		this.#setInterval = setInterval;
+		this.#clearInterval = clearInterval;
+		this.#createNewDatetime = createNewDatetime;
+
+		this.#latestDateSnapshot = initialDatetime;
+		this.#subscriptions = [];
+		this.#latestIntervalId = undefined;
+	}
+
+	#reconcileRefreshIntervals(): void {
+		if (this.#subscriptions.length === 0) {
+			this.#clearInterval(this.#latestIntervalId);
+			return;
+		}
+
+		const prevFastestInterval =
+			this.#subscriptions[0]?.idealRefreshIntervalMs ??
+			Number.POSITIVE_INFINITY;
+		if (this.#subscriptions.length > 1) {
+			this.#subscriptions.sort(
+				(e1, e2) => e1.idealRefreshIntervalMs - e2.idealRefreshIntervalMs,
+			);
+		}
+
+		const newFastestInterval =
+			this.#subscriptions[0]?.idealRefreshIntervalMs ??
+			Number.POSITIVE_INFINITY;
+		if (prevFastestInterval === newFastestInterval) {
+			return;
+		}
+		if (newFastestInterval === Number.POSITIVE_INFINITY) {
+			this.#clearInterval(this.#latestIntervalId);
+			return;
+		}
+
+		/**
+		 * @todo Figure out the conditions when the interval should be set up,
+		 * and when/how it should be updated
+		 */
+		this.#latestIntervalId = this.#setInterval(() => {
+			this.#latestDateSnapshot = this.#createNewDatetime(
+				this.#latestDateSnapshot,
+			);
+			this.#flushUpdateToSubscriptions();
+		}, newFastestInterval);
+	}
+
+	#flushUpdateToSubscriptions(): void {
+		for (const subEntry of this.#subscriptions) {
+			subEntry.onUpdate(this.#latestDateSnapshot);
+		}
+	}
+
+	getTimeSnapshot(): Date {
+		return this.#latestDateSnapshot;
+	}
+
+	invalidateSnapshot(): void {}
+
+	unsubscribe(id: string): void {
+		const updated = this.#subscriptions.filter((s) => s.id !== id);
+		if (updated.length === this.#subscriptions.length) {
+			return;
+		}
+
+		this.#subscriptions = updated;
+		this.#reconcileRefreshIntervals();
+	}
+
+	subscribe(entry: SubscriptionEntry): void {
+		if (entry.idealRefreshIntervalMs <= 0) {
+			throw new Error(
+				`Refresh interval ${entry.idealRefreshIntervalMs} must be a positive integer (or Infinity)`,
+			);
+		}
+
+		const subIndex = this.#subscriptions.findIndex((s) => s.id === entry.id);
+		if (subIndex === -1) {
+			this.#subscriptions.push(entry);
+			this.#reconcileRefreshIntervals();
+			return;
+		}
+
+		const prev = this.#subscriptions[subIndex];
+		if (prev === undefined) {
+			throw new Error("Went out of bounds");
+		}
+
+		this.#subscriptions[subIndex] = entry;
+		if (prev.idealRefreshIntervalMs !== entry.idealRefreshIntervalMs) {
+			this.#reconcileRefreshIntervals();
+		}
+	}
+}

From 60b222089f2dd37320f4f8a946b567e9a3a5b00a Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 15:16:21 +0000
Subject: [PATCH 14/29] fix: move resync option back to base class

---
 site/src/hooks/useTimeSync.tsx | 28 ++++++----------------------
 site/src/utils/TimeSync.ts     | 13 ++++++++++++-
 2 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 6aa2e6ddfedbd..1fbaefd1182fb 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -2,9 +2,8 @@
  * @todo Things that still need to be done before this can be called done:
  *
  * 1. Fill out all incomplete methods
- * 2. Make sure the class respects the resyncOnNewSubscription option
- * 3. Add tests
- * 4. See if there's a way to make sure that if you provide a type parameter to
+ * 2. Add tests
+ * 3. See if there's a way to make sure that if you provide a type parameter to
  *    the hook, you must also provide a select function
  */
 import {
@@ -40,21 +39,6 @@ type ReactTimeSyncSubscriptionEntry = Readonly<
 	}
 >;
 
-type ReactTimeSyncInitOptions = Readonly<
-	TimeSyncInitOptions & {
-		/**
-		 * Configures whether adding a new subscription will immediately create
-		 * a new time snapshot and use it to update all other subscriptions.
-		 */
-		resyncOnNewSubscription: boolean;
-	}
->;
-
-const defaultReactTimeSyncOptions: ReactTimeSyncInitOptions = {
-	...defaultOptions,
-	resyncOnNewSubscription: true,
-};
-
 interface ReactTimeSyncApi {
 	subscribe: (entry: ReactTimeSyncSubscriptionEntry) => () => void;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
@@ -65,9 +49,9 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	readonly #resyncOnNewSubscription: boolean;
 	readonly #selectionCache: Map<string, unknown>;
 
-	constructor(options: Partial<ReactTimeSyncInitOptions>) {
+	constructor(options: Partial<TimeSyncInitOptions>) {
 		const {
-			resyncOnNewSubscription = defaultReactTimeSyncOptions.resyncOnNewSubscription,
+			resyncOnNewSubscription = defaultOptions.resyncOnNewSubscription,
 			initialDatetime = defaultOptions.initialDatetime,
 			createNewDatetime = defaultOptions.createNewDatetime,
 			setInterval = defaultOptions.setInterval,
@@ -101,7 +85,7 @@ const timeSyncContext = createContext<ReactTimeSync | null>(null);
 
 type TimeSyncProviderProps = Readonly<
 	PropsWithChildren<{
-		options?: Partial<ReactTimeSyncInitOptions>;
+		options?: Partial<TimeSyncInitOptions>;
 	}>
 >;
 
@@ -122,7 +106,7 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 	// be treated like a pseudo-ref value, where its values can only be used in
 	// very specific, React-approved ways
 	const [readonlySync] = useState(
-		() => new ReactTimeSync(options ?? defaultReactTimeSyncOptions),
+		() => new ReactTimeSync(options ?? defaultOptions),
 	);
 
 	return (
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index 1f712b9ed7302..114a24dc05848 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -1,7 +1,8 @@
 /**
  * @todo What's left to do here:
  * 1. Fill out all incomplete methods
- * 2. Add tests
+ * 2. Make sure the class respects the resyncOnNewSubscription option
+ * 3. Add tests
  */
 export const IDEAL_REFRESH_ONE_SECOND = 1_000;
 export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
@@ -35,10 +36,17 @@ export type TimeSyncInitOptions = Readonly<{
 	 * new interval to increase/decrease its update speed.)
 	 */
 	clearInterval: ClearInterval;
+
+	/**
+	 * Configures whether adding a new subscription will immediately create
+	 * a new time snapshot and use it to update all other subscriptions.
+	 */
+	resyncOnNewSubscription: boolean;
 }>;
 
 export const defaultOptions: TimeSyncInitOptions = {
 	initialDatetime: new Date(),
+	resyncOnNewSubscription: true,
 	createNewDatetime: () => new Date(),
 	setInterval: window.setInterval,
 	clearInterval: window.clearInterval,
@@ -83,6 +91,7 @@ interface TimeSyncApi {
  * composing your components to minimize the costs of re-renders.
  */
 export class TimeSync implements TimeSyncApi {
+	readonly #resyncOnNewSubscription: boolean;
 	readonly #createNewDatetime: (prev: Date) => Date;
 	readonly #setInterval: SetInterval;
 	readonly #clearInterval: ClearInterval;
@@ -94,6 +103,7 @@ export class TimeSync implements TimeSyncApi {
 	constructor(options: Partial<TimeSyncInitOptions>) {
 		const {
 			initialDatetime = defaultOptions.initialDatetime,
+			resyncOnNewSubscription = defaultOptions.resyncOnNewSubscription,
 			createNewDatetime = defaultOptions.createNewDatetime,
 			setInterval = defaultOptions.setInterval,
 			clearInterval = defaultOptions.clearInterval,
@@ -102,6 +112,7 @@ export class TimeSync implements TimeSyncApi {
 		this.#setInterval = setInterval;
 		this.#clearInterval = clearInterval;
 		this.#createNewDatetime = createNewDatetime;
+		this.#resyncOnNewSubscription = resyncOnNewSubscription;
 
 		this.#latestDateSnapshot = initialDatetime;
 		this.#subscriptions = [];

From 62b6f6edbdd0d2d791fcded53524ad96044a8402 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 15:56:14 +0000
Subject: [PATCH 15/29] chore: flesh out more of React class

---
 site/src/hooks/useTimeSync.tsx | 71 ++++++++++++++++++++++++----------
 site/src/utils/TimeSync.ts     |  3 --
 2 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 1fbaefd1182fb..2e91714402de6 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -39,6 +39,12 @@ type ReactTimeSyncSubscriptionEntry = Readonly<
 	}
 >;
 
+// Need to wrap each value that we put in the selection cache, so that when we
+// try to retrieve a value, it's easy to differentiate between a value being
+// undefined because that's an explicit selection value, versus it being
+// undefined because we forgot to set it in the cache
+type SelectionCacheEntry = Readonly<{ value: unknown }>;
+
 interface ReactTimeSyncApi {
 	subscribe: (entry: ReactTimeSyncSubscriptionEntry) => () => void;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
@@ -46,38 +52,61 @@ interface ReactTimeSyncApi {
 
 class ReactTimeSync implements ReactTimeSyncApi {
 	readonly #timeSync: TimeSync;
-	readonly #resyncOnNewSubscription: boolean;
-	readonly #selectionCache: Map<string, unknown>;
+	readonly #selectionCache: Map<string, SelectionCacheEntry>;
 
 	constructor(options: Partial<TimeSyncInitOptions>) {
-		const {
-			resyncOnNewSubscription = defaultOptions.resyncOnNewSubscription,
-			initialDatetime = defaultOptions.initialDatetime,
-			createNewDatetime = defaultOptions.createNewDatetime,
-			setInterval = defaultOptions.setInterval,
-			clearInterval = defaultOptions.clearInterval,
-		} = options;
-
+		this.#timeSync = new TimeSync(options);
 		this.#selectionCache = new Map();
-		this.#resyncOnNewSubscription = resyncOnNewSubscription;
-		this.#timeSync = new TimeSync({
-			initialDatetime,
-			createNewDatetime,
-			setInterval,
-			clearInterval,
-		});
 	}
 
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
 	subscribe = (entry: ReactTimeSyncSubscriptionEntry): (() => void) => {
-		this.#timeSync.subscribe(entry);
-		return () => this.#timeSync.unsubscribe(entry.id);
+		const { select, id, idealRefreshIntervalMs, onUpdate } = entry;
+
+		// Make sure that we subscribe first, in case TimeSync is configured to
+		// invalidate the snapshot on a new subscription. Want to remove risk of
+		// stale data
+		const patchedEntry: SubscriptionEntry = {
+			id,
+			idealRefreshIntervalMs,
+			onUpdate: (newDate) => {
+				const prevSelection = this.getSelectionSnapshot(id);
+				const newSelection: unknown = select?.(newDate) ?? newDate;
+				if (newSelection === prevSelection) {
+					return;
+				}
+
+				this.#selectionCache.set(id, { value: newSelection });
+				onUpdate(newDate);
+			},
+		};
+		this.#timeSync.subscribe(patchedEntry);
+
+		const date = this.#timeSync.getTimeSnapshot();
+		const cacheValue = select?.(date) ?? date;
+		this.#selectionCache.set(id, { value: cacheValue });
+
+		return () => this.#timeSync.unsubscribe(id);
 	};
 
+	/**
+	 * Allows you to grab the result of a selection that has been registered
+	 * with ReactTimeSync.
+	 *
+	 * If this method is called with an ID before a subscription has been
+	 * registered for that ID, that will cause the method to throw.
+	 */
 	getSelectionSnapshot = <T,>(id: string): T => {
-		return this.#selectionCache.get(id) as T;
+		const cacheEntry = this.#selectionCache.get(id);
+		if (cacheEntry === undefined) {
+			throw new Error(
+				"Trying to retrieve value from selection cache without it being initialized",
+			);
+		}
+
+		return cacheEntry.value as T;
 	};
 }
 
@@ -177,7 +206,7 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	});
 
 	// We need to define this callback using useCallback instead of
-	// useEffectEvent because we want the memoization to be invaliated when the
+	// useEffectEvent because we want the memoization to be invalidated when the
 	// refresh interval changes. (When the subscription callback changes by
 	// reference, that causes useSyncExternalStore to redo the subscription with
 	// the new callback). All other values need to be included in the dependency
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index 114a24dc05848..310b522664024 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -62,7 +62,6 @@ interface TimeSyncApi {
 	subscribe: (entry: SubscriptionEntry) => void;
 	unsubscribe: (id: string) => void;
 	getTimeSnapshot: () => Date;
-	invalidateSnapshot: () => void;
 }
 
 /**
@@ -167,8 +166,6 @@ export class TimeSync implements TimeSyncApi {
 		return this.#latestDateSnapshot;
 	}
 
-	invalidateSnapshot(): void {}
-
 	unsubscribe(id: string): void {
 		const updated = this.#subscriptions.filter((s) => s.id !== id);
 		if (updated.length === this.#subscriptions.length) {

From fe8b3efc95e60ea583a651ccd73b238313d4b510 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 17:25:38 +0000
Subject: [PATCH 16/29] fix: get initial solution in place for fixing stale
 closure issues

---
 site/src/hooks/useTimeSync.tsx                | 113 ++++++++++++++----
 .../TemplateInsightsPage/DateRange.tsx        |   6 +-
 .../TemplateInsightsPage.tsx                  |  11 +-
 3 files changed, 102 insertions(+), 28 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 2e91714402de6..5f29070ba16ee 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -31,11 +31,11 @@ export {
 	IDEAL_REFRESH_ONE_SECOND,
 } from "utils/TimeSync";
 
-type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
+type SelectCallback = (newSnapshot: Date) => unknown;
 
-type ReactTimeSyncSubscriptionEntry = Readonly<
+type ReactSubscriptionEntry = Readonly<
 	SubscriptionEntry & {
-		select?: (newSnapshot: Date) => unknown;
+		select?: SelectCallback;
 	}
 >;
 
@@ -43,11 +43,15 @@ type ReactTimeSyncSubscriptionEntry = Readonly<
 // try to retrieve a value, it's easy to differentiate between a value being
 // undefined because that's an explicit selection value, versus it being
 // undefined because we forgot to set it in the cache
-type SelectionCacheEntry = Readonly<{ value: unknown }>;
+type SelectionCacheEntry = Readonly<{
+	value: unknown;
+	select?: SelectCallback;
+}>;
 
 interface ReactTimeSyncApi {
-	subscribe: (entry: ReactTimeSyncSubscriptionEntry) => () => void;
+	subscribe: (entry: ReactSubscriptionEntry) => () => void;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
+	invalidateSelection: (id: string, select?: SelectCallback) => void;
 }
 
 class ReactTimeSync implements ReactTimeSyncApi {
@@ -62,9 +66,18 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
-	subscribe = (entry: ReactTimeSyncSubscriptionEntry): (() => void) => {
+	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
 		const { select, id, idealRefreshIntervalMs, onUpdate } = entry;
 
+		const updateCacheEntry = () => {
+			const date = this.#timeSync.getTimeSnapshot();
+			const cacheValue = select?.(date) ?? date;
+			this.#selectionCache.set(id, {
+				value: cacheValue,
+				select,
+			});
+		};
+
 		// Make sure that we subscribe first, in case TimeSync is configured to
 		// invalidate the snapshot on a new subscription. Want to remove risk of
 		// stale data
@@ -73,21 +86,18 @@ class ReactTimeSync implements ReactTimeSyncApi {
 			idealRefreshIntervalMs,
 			onUpdate: (newDate) => {
 				const prevSelection = this.getSelectionSnapshot(id);
-				const newSelection: unknown = select?.(newDate) ?? newDate;
+				const newSelection = select?.(newDate) ?? newDate;
 				if (newSelection === prevSelection) {
 					return;
 				}
 
-				this.#selectionCache.set(id, { value: newSelection });
+				updateCacheEntry();
 				onUpdate(newDate);
 			},
 		};
 		this.#timeSync.subscribe(patchedEntry);
 
-		const date = this.#timeSync.getTimeSnapshot();
-		const cacheValue = select?.(date) ?? date;
-		this.#selectionCache.set(id, { value: cacheValue });
-
+		updateCacheEntry();
 		return () => this.#timeSync.unsubscribe(id);
 	};
 
@@ -108,6 +118,23 @@ class ReactTimeSync implements ReactTimeSyncApi {
 
 		return cacheEntry.value as T;
 	};
+
+	invalidateSelection = (id: string, select?: SelectCallback): void => {
+		const cacheEntry = this.#selectionCache.get(id);
+		if (cacheEntry === undefined) {
+			return;
+		}
+
+		const dateSnapshot = this.#timeSync.getTimeSnapshot();
+		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
+
+		// Keep the old select callback, because only that version will be
+		// memoized via useEffectEvent
+		this.#selectionCache.set(id, {
+			value: newSelection,
+			select: cacheEntry.select,
+		});
+	};
 }
 
 const timeSyncContext = createContext<ReactTimeSync | null>(null);
@@ -147,6 +174,7 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 
 type UseTimeSyncOptions<T = Date> = Readonly<{
 	idealRefreshIntervalMs: number;
+	selectDeps?: readonly unknown[];
 
 	/**
 	 * Allows you to transform any date values received from the TimeSync class.
@@ -162,7 +190,7 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
 
 /**
  * useTimeSync provides React bindings for the TimeSync class, letting a React
- * component bind its update lifecycles to interval updates from TimeSync. This
+ * component bind its update life cycles to interval updates from TimeSync. This
  * hook should be used anytime you would want to use a Date instance directly in
  * a component render path.
  *
@@ -176,7 +204,7 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
  * interval.
  */
 export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const { select, idealRefreshIntervalMs } = options;
+	const { select, selectDeps, idealRefreshIntervalMs } = options;
 	const timeSync = useContext(timeSyncContext);
 	if (timeSync === null) {
 		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
@@ -200,7 +228,7 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// be initialized with whatever callback you give it on mount. So for the
 	// mounting render alone, it's safe to call a useEffectEvent callback from
 	// inside a render.
-	const stableSelect = useEffectEvent((date: Date): T => {
+	const selectForOutsideReact = useEffectEvent((date: Date): T => {
 		const recast = date as Date & T;
 		return select?.(recast) ?? recast;
 	});
@@ -212,21 +240,64 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// the new callback). All other values need to be included in the dependency
 	// array for correctness, but they should always maintain stable memory
 	// addresses
+	type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
 				idealRefreshIntervalMs,
 				id: hookId,
 				onUpdate: notifyReact,
-				select: stableSelect,
+				select: selectForOutsideReact,
 			});
 		},
-		[timeSync, hookId, stableSelect, idealRefreshIntervalMs],
+		[timeSync, hookId, selectForOutsideReact, idealRefreshIntervalMs],
 	);
 
-	const snapshot = useSyncExternalStore<T>(subscribe, () =>
-		timeSync.getSelectionSnapshot(hookId),
-	);
+	const [prevDeps, setPrevDeps] = useState(selectDeps);
+	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDeps);
+
+	const selection = useSyncExternalStore<T>(subscribe, () => {
+		if (depsAreInvalidated) {
+			// Need to make sure that we use the un-memoized version of select
+			// here because we need to call select callback mid-render to
+			// guarantee no stale data. The memoized version only syncs AFTER
+			// the current render has finished in full.
+			timeSync.invalidateSelection(hookId, select);
+		}
+		return timeSync.getSelectionSnapshot(hookId);
+	});
+
+	// Setting state mid-render like this is valid, but we just need to make
+	// sure that we wait until after the useSyncExternalStore state getter runs
+	if (depsAreInvalidated) {
+		setPrevDeps(selectDeps);
+	}
+
+	return selection;
+}
+
+function areDepsInvalidated(
+	oldDeps: readonly unknown[] | undefined,
+	newDeps: readonly unknown[] | undefined,
+): boolean {
+	if (oldDeps === undefined) {
+		if (newDeps === undefined) {
+			return false;
+		}
+		return true;
+	}
+
+	const oldRecast = oldDeps as readonly unknown[];
+	const newRecast = oldDeps as readonly unknown[];
+	if (oldRecast.length !== newRecast.length) {
+		return true;
+	}
+
+	for (const [index, el] of oldRecast.entries()) {
+		if (el !== newRecast[index]) {
+			return true;
+		}
+	}
 
-	return snapshot;
+	return false;
 }
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index 4a602329f15ff..7697d5e67bd3c 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -17,7 +17,7 @@ import {
 	startOfHour,
 	subDays,
 } from "date-fns";
-import { useTimeSync } from "hooks/useTimeSync";
+import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import { type ComponentProps, type FC, useRef, useState } from "react";
 import { DateRangePicker, createStaticRanges } from "react-date-range";
 
@@ -43,7 +43,9 @@ interface DateRangeProps {
 }
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
-	const currentTime = useTimeSync({ idealRefreshIntervalMs: 60_000 });
+	const currentTime = useTimeSync({
+		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
+	});
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
 		{
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 3eeece8bed26b..bf6ca7c8f592e 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -70,16 +70,17 @@ export default function TemplateInsightsPage() {
 	const { template } = useTemplateLayoutContext();
 	const [searchParams, setSearchParams] = useSearchParams();
 
+	const paramsInterval = searchParams.get("interval");
 	const insightsInterval = useTimeSync<InsightsInterval>({
 		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_DAY,
-		select: (newDatetime) => {
+		selectDeps: [paramsInterval],
+		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
-			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDatetime;
+			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDate;
 			const defaultInterval = hasFiveWeeksOrMore ? "week" : "day";
 
-			const paramsValue = searchParams.get("interval");
-			if (paramsValue === "week" || paramsValue === "day") {
-				return paramsValue;
+			if (paramsInterval === "week" || paramsInterval === "day") {
+				return paramsInterval;
 			}
 			return defaultInterval;
 		},

From 9d8671e77e8de27b0e809b90739301b28e3daa0e Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 17:46:20 +0000
Subject: [PATCH 17/29] refactor: make class less confusing

---
 site/src/hooks/useTimeSync.tsx | 29 +++++++----------------------
 1 file changed, 7 insertions(+), 22 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 5f29070ba16ee..fb7150dc06aea 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -43,10 +43,7 @@ type ReactSubscriptionEntry = Readonly<
 // try to retrieve a value, it's easy to differentiate between a value being
 // undefined because that's an explicit selection value, versus it being
 // undefined because we forgot to set it in the cache
-type SelectionCacheEntry = Readonly<{
-	value: unknown;
-	select?: SelectCallback;
-}>;
+type SelectionCacheEntry = Readonly<{ value: unknown }>;
 
 interface ReactTimeSyncApi {
 	subscribe: (entry: ReactSubscriptionEntry) => () => void;
@@ -69,15 +66,6 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
 		const { select, id, idealRefreshIntervalMs, onUpdate } = entry;
 
-		const updateCacheEntry = () => {
-			const date = this.#timeSync.getTimeSnapshot();
-			const cacheValue = select?.(date) ?? date;
-			this.#selectionCache.set(id, {
-				value: cacheValue,
-				select,
-			});
-		};
-
 		// Make sure that we subscribe first, in case TimeSync is configured to
 		// invalidate the snapshot on a new subscription. Want to remove risk of
 		// stale data
@@ -91,13 +79,16 @@ class ReactTimeSync implements ReactTimeSyncApi {
 					return;
 				}
 
-				updateCacheEntry();
+				this.#selectionCache.set(id, { value: newSelection });
 				onUpdate(newDate);
 			},
 		};
 		this.#timeSync.subscribe(patchedEntry);
 
-		updateCacheEntry();
+		const date = this.#timeSync.getTimeSnapshot();
+		const cacheValue = select?.(date) ?? date;
+		this.#selectionCache.set(id, { value: cacheValue });
+
 		return () => this.#timeSync.unsubscribe(id);
 	};
 
@@ -127,13 +118,7 @@ class ReactTimeSync implements ReactTimeSyncApi {
 
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
-
-		// Keep the old select callback, because only that version will be
-		// memoized via useEffectEvent
-		this.#selectionCache.set(id, {
-			value: newSelection,
-			select: cacheEntry.select,
-		});
+		this.#selectionCache.set(id, { value: newSelection });
 	};
 }
 

From 997c3da4b7a0e0ccb6d1b081f009a9ec5354011e Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 17:48:25 +0000
Subject: [PATCH 18/29] chore: format

---
 site/.storybook/preview.jsx                   | 20 +------------------
 site/src/hooks/useTimeSync.tsx                |  4 ++--
 .../TemplateInsightsPage.tsx                  |  1 -
 3 files changed, 3 insertions(+), 22 deletions(-)

diff --git a/site/.storybook/preview.jsx b/site/.storybook/preview.jsx
index 6525aa9e38b97..9dc51089668a4 100644
--- a/site/.storybook/preview.jsx
+++ b/site/.storybook/preview.jsx
@@ -1,28 +1,10 @@
-// @ts-check
-/**
- * @file Defines the main configuration file for all of our Storybook tests.
- * This file must be a JSX/JS file, but we can at least add some type safety via
- * the ts-check directive.
- * @see {@link https://storybook.js.org/docs/configure#configure-story-rendering}
- *
- * @typedef {import("react").ReactElement} ReactElement
- * @typedef {import("react").PropsWithChildren} PropsWithChildren
- * @typedef {import("react").FC<PropsWithChildren>} FC
- *
- * @typedef {import("@storybook/react").StoryContext} StoryContext
- * @typedef {import("@storybook/react").Preview} Preview
- *
- * @typedef {(Story: FC, Context: StoryContext) => React.JSX.Element} Decorator A
- * Storybook decorator function used to inject baseline data dependencies into
- * our React components during testing.
- */
-import React from "react";
 import "../src/index.css";
 import { ThemeProvider as EmotionThemeProvider } from "@emotion/react";
 import CssBaseline from "@mui/material/CssBaseline";
 import {
 	ThemeProvider as MuiThemeProvider,
 	StyledEngineProvider,
+	// biome-ignore lint/nursery/noRestrictedImports: we extend the MUI theme
 } from "@mui/material/styles";
 import { DecoratorHelpers } from "@storybook/addon-themes";
 import isChromatic from "chromatic/isChromatic";
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index fb7150dc06aea..1853d4811351b 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -7,9 +7,9 @@
  *    the hook, you must also provide a select function
  */
 import {
-	createContext,
 	type FC,
 	type PropsWithChildren,
+	createContext,
 	useCallback,
 	useContext,
 	useId,
@@ -17,10 +17,10 @@ import {
 	useSyncExternalStore,
 } from "react";
 import {
-	defaultOptions,
 	type SubscriptionEntry,
 	TimeSync,
 	type TimeSyncInitOptions,
+	defaultOptions,
 } from "utils/TimeSync";
 import { useEffectEvent } from "./hookPolyfills";
 
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index bf6ca7c8f592e..c92ee5062f65d 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -13,7 +13,6 @@ import {
 } from "api/queries/insights";
 import type {
 	Entitlements,
-	Template,
 	TemplateAppUsage,
 	TemplateInsightsResponse,
 	TemplateParameterUsage,

From d0a57de9fe1f73b8d77aa760e510280d6f22582a Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 18:04:48 +0000
Subject: [PATCH 19/29] docs: add more info about properties

---
 .../components/SignInLayout/SignInLayout.tsx  |  2 +-
 site/src/hooks/useTimeSync.tsx                | 30 +++++++++++++++++--
 .../CliInstallPage/CliInstallPageView.tsx     |  2 +-
 .../LicensesSettingsPage/LicenseCard.tsx      |  2 +-
 site/src/pages/LoginPage/LoginPageView.tsx    |  2 +-
 .../TemplateInsightsPage/DateRange.tsx        |  2 +-
 .../TemplateInsightsPage.tsx                  |  4 +--
 site/src/pages/WorkspacePage/AppStatuses.tsx  |  2 +-
 .../WorkspaceScheduleControls.tsx             |  2 +-
 9 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
index 1a45a7ecbe807..6037f02ac0f3f 100644
--- a/site/src/components/SignInLayout/SignInLayout.tsx
+++ b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -4,7 +4,7 @@ import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 1853d4811351b..1837b560c88ec 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -158,8 +158,28 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 };
 
 type UseTimeSyncOptions<T = Date> = Readonly<{
-	idealRefreshIntervalMs: number;
-	selectDeps?: readonly unknown[];
+	/**
+	 * targetRefreshInterval is the ideal interval of time, in milliseconds,
+	 * that defines how often the hook should refresh with the newest Date
+	 * value from TimeSync.
+	 *
+	 * Note that a refresh is not the same as a re-render. If the hook is
+	 * refreshed with a new datetime, but its select callback produces the same
+	 * value as before, the hook will skip re-rendering.
+	 *
+	 * The hook reserves the right to refresh MORE frequently than the
+	 * specified value if it would guarantee that the hook does not get out of
+	 * sync with other useTimeSync users that are currently mounted on screen.
+	 */
+	targetRefreshInterval: number;
+
+	/**
+	 * selectDependencies acts like the dependency array for a useMemo callback.
+	 * Whenever any of the elements in the array change by value, that will
+	 * cause the select callback to re-run synchronously and produce a new,
+	 * up-to-date value for the current render.
+	 */
+	selectDependencies?: readonly unknown[];
 
 	/**
 	 * Allows you to transform any date values received from the TimeSync class.
@@ -189,7 +209,11 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
  * interval.
  */
 export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const { select, selectDeps, idealRefreshIntervalMs } = options;
+	const {
+		select,
+		selectDependencies: selectDeps,
+		targetRefreshInterval: idealRefreshIntervalMs,
+	} = options;
 	const timeSync = useContext(timeSyncContext);
 	if (timeSync === null) {
 		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
index 08e04651a74ef..998e29b094d6e 100644
--- a/site/src/pages/CliInstallPage/CliInstallPageView.tsx
+++ b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -11,7 +11,7 @@ type CliInstallPageViewProps = {
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
index 0b27f99f2094b..814da2a3165a1 100644
--- a/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
+++ b/site/src/pages/DeploymentSettingsPage/LicensesSettingsPage/LicenseCard.tsx
@@ -25,7 +25,7 @@ export const LicenseCard: FC<LicenseCardProps> = ({
 	onRemove,
 	isRemoving,
 }) => {
-	const time = useTimeSync({ idealRefreshIntervalMs: 30_000 });
+	const time = useTimeSync({ targetRefreshInterval: 30_000 });
 	const [licenseIDMarkedForRemoval, setLicenseIDMarkedForRemoval] = useState<
 		number | undefined
 	>(undefined);
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index 5c0cc69c2adbb..daf70ae997bc9 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -29,7 +29,7 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	redirectTo,
 }) => {
 	const year = useTimeSync({
-		idealRefreshIntervalMs: Number.POSITIVE_INFINITY,
+		targetRefreshInterval: Number.POSITIVE_INFINITY,
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index 7697d5e67bd3c..b88161f100ba7 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -44,7 +44,7 @@ interface DateRangeProps {
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
 	const currentTime = useTimeSync({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
 	});
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index c92ee5062f65d..5ecae7a5fdb49 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -71,8 +71,8 @@ export default function TemplateInsightsPage() {
 
 	const paramsInterval = searchParams.get("interval");
 	const insightsInterval = useTimeSync<InsightsInterval>({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_DAY,
-		selectDeps: [paramsInterval],
+		targetRefreshInterval: IDEAL_REFRESH_ONE_DAY,
+		selectDependencies: [paramsInterval],
 		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
 			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDate;
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index ab6c3f2d53f9a..555441da3a14d 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -154,7 +154,7 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	referenceDate,
 }) => {
 	const comparisonDate = useTimeSync({
-		idealRefreshIntervalMs: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
index 343b0eb22763d..1f512a11e592f 100644
--- a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
+++ b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -163,7 +163,7 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 	};
 
 	const activityStatus = useTimeSync({
-		idealRefreshIntervalMs: 1_000,
+		targetRefreshInterval: 1_000,
 		select: () => getWorkspaceActivityStatus(workspace),
 	});
 	const { message, tooltip, danger } = autostopDisplay(

From da5803d69c1b5e42a164a21ea7365c77a2928dc7 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 18:45:28 +0000
Subject: [PATCH 20/29] refactor: split useTimeSync into two hooks

---
 .../components/SignInLayout/SignInLayout.tsx  |   5 +-
 site/src/hooks/useTimeSync.tsx                | 171 ++++++++++--------
 site/src/modules/workspaces/activity.ts       |   3 +-
 .../CliInstallPage/CliInstallPageView.tsx     |   5 +-
 site/src/pages/LoginPage/LoginPageView.tsx    |   5 +-
 .../TemplateInsightsPage/DateRange.tsx        |   4 +-
 .../TemplateInsightsPage.tsx                  |   6 +-
 site/src/pages/WorkspacePage/AppStatuses.tsx  |  10 +-
 .../WorkspaceScheduleControls.tsx             |   7 +-
 site/src/utils/TimeSync.ts                    |  24 ++-
 10 files changed, 138 insertions(+), 102 deletions(-)

diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
index 6037f02ac0f3f..550fc9f7c7464 100644
--- a/site/src/components/SignInLayout/SignInLayout.tsx
+++ b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -1,10 +1,11 @@
 import type { Interpolation, Theme } from "@emotion/react";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 1837b560c88ec..d58d384d2445f 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -25,12 +25,14 @@ import {
 import { useEffectEvent } from "./hookPolyfills";
 
 export {
-	IDEAL_REFRESH_ONE_DAY,
-	IDEAL_REFRESH_ONE_HOUR,
-	IDEAL_REFRESH_ONE_MINUTE,
-	IDEAL_REFRESH_ONE_SECOND,
+	TARGET_REFRESH_ONE_DAY,
+	TARGET_REFRESH_ONE_HOUR,
+	TARGET_REFRESH_ONE_MINUTE,
+	TARGET_REFRESH_ONE_SECOND,
 } from "utils/TimeSync";
 
+type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
+
 type SelectCallback = (newSnapshot: Date) => unknown;
 
 type ReactSubscriptionEntry = Readonly<
@@ -47,6 +49,7 @@ type SelectionCacheEntry = Readonly<{ value: unknown }>;
 
 interface ReactTimeSyncApi {
 	subscribe: (entry: ReactSubscriptionEntry) => () => void;
+	getTimeSnapshot: () => Date;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
 	invalidateSelection: (id: string, select?: SelectCallback) => void;
 }
@@ -63,15 +66,19 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
+	getTimeSnapshot = () => {
+		return this.#timeSync.getTimeSnapshot();
+	};
+
 	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
-		const { select, id, idealRefreshIntervalMs, onUpdate } = entry;
+		const { select, id, targetRefreshInterval, onUpdate } = entry;
 
 		// Make sure that we subscribe first, in case TimeSync is configured to
 		// invalidate the snapshot on a new subscription. Want to remove risk of
 		// stale data
 		const patchedEntry: SubscriptionEntry = {
 			id,
-			idealRefreshIntervalMs,
+			targetRefreshInterval,
 			onUpdate: (newDate) => {
 				const prevSelection = this.getSelectionSnapshot(id);
 				const newSelection = select?.(newDate) ?? newDate;
@@ -157,7 +164,15 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 	);
 };
 
-type UseTimeSyncOptions<T = Date> = Readonly<{
+function useTimeSyncContext(): ReactTimeSync {
+	const timeSync = useContext(timeSyncContext);
+	if (timeSync === null) {
+		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
+	}
+	return timeSync;
+}
+
+type UseTimeSyncOptions = Readonly<{
 	/**
 	 * targetRefreshInterval is the ideal interval of time, in milliseconds,
 	 * that defines how often the hook should refresh with the newest Date
@@ -172,26 +187,76 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
 	 * sync with other useTimeSync users that are currently mounted on screen.
 	 */
 	targetRefreshInterval: number;
+}>;
 
-	/**
-	 * selectDependencies acts like the dependency array for a useMemo callback.
-	 * Whenever any of the elements in the array change by value, that will
-	 * cause the select callback to re-run synchronously and produce a new,
-	 * up-to-date value for the current render.
-	 */
-	selectDependencies?: readonly unknown[];
+export function useTimeSync(options: UseTimeSyncOptions): Date {
+	const { targetRefreshInterval } = options;
+	const hookId = useId();
+	const timeSync = useTimeSyncContext();
 
-	/**
-	 * Allows you to transform any date values received from the TimeSync class.
-	 * Select functions work similarly to the selects from React Query and Redux
-	 * Toolkit – you don't need to memoize them, and they will only run when the
-	 * underlying TimeSync state has changed.
-	 *
-	 * Select functions must not be async. The hook will error out at the type
-	 * level if you provide one by mistake.
-	 */
-	select?: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
-}>;
+	const subscribe = useCallback<ReactSubscriptionCallback>(
+		(notifyReact) => {
+			return timeSync.subscribe({
+				targetRefreshInterval,
+				id: hookId,
+				onUpdate: notifyReact,
+			});
+		},
+		[hookId, timeSync, targetRefreshInterval],
+	);
+
+	const snapshot = useSyncExternalStore(subscribe, timeSync.getTimeSnapshot);
+	return snapshot;
+}
+
+function areDepsInvalidated(
+	oldDeps: readonly unknown[] | undefined,
+	newDeps: readonly unknown[] | undefined,
+): boolean {
+	if (oldDeps === undefined) {
+		if (newDeps === undefined) {
+			return false;
+		}
+		return true;
+	}
+
+	const oldRecast = oldDeps as readonly unknown[];
+	const newRecast = oldDeps as readonly unknown[];
+	if (oldRecast.length !== newRecast.length) {
+		return true;
+	}
+
+	for (const [index, el] of oldRecast.entries()) {
+		if (el !== newRecast[index]) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+type UseTimeSyncSelectOptions<T = Date> = Readonly<
+	UseTimeSyncOptions & {
+		/**
+		 * selectDependencies acts like the dependency array for a useMemo
+		 * callback. Whenever any of the elements in the array change by value,
+		 * that will cause the select callback to re-run synchronously and
+		 * produce a new, up-to-date value for the current render.
+		 */
+		selectDependencies: readonly unknown[];
+
+		/**
+		 * Allows you to transform any date values received from the TimeSync
+		 * class. Select functions work similarly to the selects from React
+		 * Query and Redux Toolkit – you don't need to memoize them, and they
+		 * will only run when the underlying TimeSync state has changed.
+		 *
+		 * Select functions must not be async. The hook will error out at the
+		 * type level if you provide one by mistake.
+		 */
+		select: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
+	}
+>;
 
 /**
  * useTimeSync provides React bindings for the TimeSync class, letting a React
@@ -208,21 +273,12 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
  * frequent update interval, both component instances will update on that
  * interval.
  */
-export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const {
-		select,
-		selectDependencies: selectDeps,
-		targetRefreshInterval: idealRefreshIntervalMs,
-	} = options;
-	const timeSync = useContext(timeSyncContext);
-	if (timeSync === null) {
-		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
-	}
-
-	// Abusing useId a little bit here. It's mainly meant to be used for
-	// accessibility, but it also gives us a globally unique ID associated with
-	// whichever component instance is consuming this hook
+export function useTimeSyncSelect<T = Date>(
+	options: UseTimeSyncSelectOptions<T>,
+): T {
+	const { select, selectDependencies, targetRefreshInterval } = options;
 	const hookId = useId();
+	const timeSync = useTimeSyncContext();
 
 	// This is the one place where we're borderline breaking the React rules.
 	// useEffectEvent is meant to be used only in useEffect calls, and normally
@@ -249,21 +305,20 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// the new callback). All other values need to be included in the dependency
 	// array for correctness, but they should always maintain stable memory
 	// addresses
-	type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
-				idealRefreshIntervalMs,
+				targetRefreshInterval: targetRefreshInterval,
 				id: hookId,
 				onUpdate: notifyReact,
 				select: selectForOutsideReact,
 			});
 		},
-		[timeSync, hookId, selectForOutsideReact, idealRefreshIntervalMs],
+		[timeSync, hookId, selectForOutsideReact, targetRefreshInterval],
 	);
 
-	const [prevDeps, setPrevDeps] = useState(selectDeps);
-	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDeps);
+	const [prevDeps, setPrevDeps] = useState(selectDependencies);
+	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDependencies);
 
 	const selection = useSyncExternalStore<T>(subscribe, () => {
 		if (depsAreInvalidated) {
@@ -279,34 +334,8 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// Setting state mid-render like this is valid, but we just need to make
 	// sure that we wait until after the useSyncExternalStore state getter runs
 	if (depsAreInvalidated) {
-		setPrevDeps(selectDeps);
+		setPrevDeps(selectDependencies);
 	}
 
 	return selection;
 }
-
-function areDepsInvalidated(
-	oldDeps: readonly unknown[] | undefined,
-	newDeps: readonly unknown[] | undefined,
-): boolean {
-	if (oldDeps === undefined) {
-		if (newDeps === undefined) {
-			return false;
-		}
-		return true;
-	}
-
-	const oldRecast = oldDeps as readonly unknown[];
-	const newRecast = oldDeps as readonly unknown[];
-	if (oldRecast.length !== newRecast.length) {
-		return true;
-	}
-
-	for (const [index, el] of oldRecast.entries()) {
-		if (el !== newRecast[index]) {
-			return true;
-		}
-	}
-
-	return false;
-}
diff --git a/site/src/modules/workspaces/activity.ts b/site/src/modules/workspaces/activity.ts
index 3f688efffcad3..53e2d17fc9da0 100644
--- a/site/src/modules/workspaces/activity.ts
+++ b/site/src/modules/workspaces/activity.ts
@@ -10,10 +10,11 @@ export type WorkspaceActivityStatus =
 
 export function getWorkspaceActivityStatus(
 	workspace: Workspace,
+	currentDatetime: Date,
 ): WorkspaceActivityStatus {
 	const builtAt = dayjs(workspace.latest_build.created_at);
 	const usedAt = dayjs(workspace.last_used_at);
-	const now = dayjs();
+	const now = dayjs(currentDatetime);
 
 	if (workspace.latest_build.status !== "running") {
 		return "notRunning";
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
index 998e29b094d6e..1ab756a379b33 100644
--- a/site/src/pages/CliInstallPage/CliInstallPageView.tsx
+++ b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -1,7 +1,7 @@
 import type { Interpolation, Theme } from "@emotion/react";
 import { CodeExample } from "components/CodeExample/CodeExample";
 import { Welcome } from "components/Welcome/Welcome";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import type { FC } from "react";
 import { Link as RouterLink } from "react-router-dom";
 
@@ -10,8 +10,9 @@ type CliInstallPageViewProps = {
 };
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index daf70ae997bc9..f59100c451570 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -3,7 +3,7 @@ import Button from "@mui/material/Button";
 import type { AuthMethods, BuildInfoResponse } from "api/typesGenerated";
 import { CustomLogo } from "components/CustomLogo/CustomLogo";
 import { Loader } from "components/Loader/Loader";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import { type FC, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { SignInForm } from "./SignInForm";
@@ -28,8 +28,9 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	onSignIn,
 	redirectTo,
 }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
index b88161f100ba7..d10a2c78da246 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -17,7 +17,7 @@ import {
 	startOfHour,
 	subDays,
 } from "date-fns";
-import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import { TARGET_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import { type ComponentProps, type FC, useRef, useState } from "react";
 import { DateRangePicker, createStaticRanges } from "react-date-range";
 
@@ -44,7 +44,7 @@ interface DateRangeProps {
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
 	const currentTime = useTimeSync({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: TARGET_REFRESH_ONE_MINUTE,
 	});
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 5ecae7a5fdb49..4b25d0284d58a 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -44,7 +44,7 @@ import {
 	subDays,
 } from "date-fns";
 import { useEmbeddedMetadata } from "hooks/useEmbeddedMetadata";
-import { IDEAL_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
+import { TARGET_REFRESH_ONE_DAY, useTimeSyncSelect } from "hooks/useTimeSync";
 import { useTemplateLayoutContext } from "pages/TemplatePage/TemplateLayout";
 import {
 	type FC,
@@ -70,8 +70,8 @@ export default function TemplateInsightsPage() {
 	const [searchParams, setSearchParams] = useSearchParams();
 
 	const paramsInterval = searchParams.get("interval");
-	const insightsInterval = useTimeSync<InsightsInterval>({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_DAY,
+	const insightsInterval = useTimeSyncSelect<InsightsInterval>({
+		targetRefreshInterval: TARGET_REFRESH_ONE_DAY,
 		selectDependencies: [paramsInterval],
 		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index 555441da3a14d..516c9d30d354c 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -19,7 +19,10 @@ import type {
 } from "api/typesGenerated";
 import { useProxy } from "contexts/ProxyContext";
 import { formatDistance, formatDistanceToNow } from "date-fns";
-import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import {
+	TARGET_REFRESH_ONE_MINUTE,
+	useTimeSyncSelect,
+} from "hooks/useTimeSync";
 import type { FC } from "react";
 import { createAppLinkHref } from "utils/apps";
 
@@ -153,8 +156,9 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	agents,
 	referenceDate,
 }) => {
-	const comparisonDate = useTimeSync({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
+	const comparisonDate = useTimeSyncSelect({
+		targetRefreshInterval: TARGET_REFRESH_ONE_MINUTE,
+		selectDependencies: [referenceDate],
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
index 1f512a11e592f..c4b270861423b 100644
--- a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
+++ b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -15,7 +15,7 @@ import type { Template, Workspace } from "api/typesGenerated";
 import { TopbarData, TopbarIcon } from "components/FullPageLayout/Topbar";
 import { displayError, displaySuccess } from "components/GlobalSnackbar/utils";
 import dayjs, { type Dayjs } from "dayjs";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import { getWorkspaceActivityStatus } from "modules/workspaces/activity";
 import { type FC, type ReactNode, forwardRef, useRef, useState } from "react";
 import { useMutation, useQueryClient } from "react-query";
@@ -162,9 +162,10 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 		}, 500);
 	};
 
-	const activityStatus = useTimeSync({
+	const activityStatus = useTimeSyncSelect({
 		targetRefreshInterval: 1_000,
-		select: () => getWorkspaceActivityStatus(workspace),
+		selectDependencies: [workspace],
+		select: (currentDate) => getWorkspaceActivityStatus(workspace, currentDate),
 	});
 	const { message, tooltip, danger } = autostopDisplay(
 		workspace,
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index 310b522664024..9704e8cfda58a 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -4,10 +4,10 @@
  * 2. Make sure the class respects the resyncOnNewSubscription option
  * 3. Add tests
  */
-export const IDEAL_REFRESH_ONE_SECOND = 1_000;
-export const IDEAL_REFRESH_ONE_MINUTE = 60 * 1_000;
-export const IDEAL_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
-export const IDEAL_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
+export const TARGET_REFRESH_ONE_SECOND = 1_000;
+export const TARGET_REFRESH_ONE_MINUTE = 60 * 1_000;
+export const TARGET_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
+export const TARGET_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
 
 export type SetInterval = (fn: () => void, intervalMs: number) => number;
 export type ClearInterval = (id: number | undefined) => void;
@@ -54,7 +54,7 @@ export const defaultOptions: TimeSyncInitOptions = {
 
 export type SubscriptionEntry = Readonly<{
 	id: string;
-	idealRefreshIntervalMs: number;
+	targetRefreshInterval: number;
 	onUpdate: (newDatetime: Date) => void;
 }>;
 
@@ -125,17 +125,15 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		const prevFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ??
-			Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.targetRefreshInterval ?? Number.POSITIVE_INFINITY;
 		if (this.#subscriptions.length > 1) {
 			this.#subscriptions.sort(
-				(e1, e2) => e1.idealRefreshIntervalMs - e2.idealRefreshIntervalMs,
+				(e1, e2) => e1.targetRefreshInterval - e2.targetRefreshInterval,
 			);
 		}
 
 		const newFastestInterval =
-			this.#subscriptions[0]?.idealRefreshIntervalMs ??
-			Number.POSITIVE_INFINITY;
+			this.#subscriptions[0]?.targetRefreshInterval ?? Number.POSITIVE_INFINITY;
 		if (prevFastestInterval === newFastestInterval) {
 			return;
 		}
@@ -177,9 +175,9 @@ export class TimeSync implements TimeSyncApi {
 	}
 
 	subscribe(entry: SubscriptionEntry): void {
-		if (entry.idealRefreshIntervalMs <= 0) {
+		if (entry.targetRefreshInterval <= 0) {
 			throw new Error(
-				`Refresh interval ${entry.idealRefreshIntervalMs} must be a positive integer (or Infinity)`,
+				`Refresh interval ${entry.targetRefreshInterval} must be a positive integer (or Infinity)`,
 			);
 		}
 
@@ -196,7 +194,7 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		this.#subscriptions[subIndex] = entry;
-		if (prev.idealRefreshIntervalMs !== entry.idealRefreshIntervalMs) {
+		if (prev.targetRefreshInterval !== entry.targetRefreshInterval) {
 			this.#reconcileRefreshIntervals();
 		}
 	}

From 08fda7b302d738cc0eb79a1b0b4a7f221ebfe6de Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 18:48:22 +0000
Subject: [PATCH 21/29] fix: add back type-checking

---
 site/.storybook/preview.jsx | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/site/.storybook/preview.jsx b/site/.storybook/preview.jsx
index 9dc51089668a4..fa153b0627665 100644
--- a/site/.storybook/preview.jsx
+++ b/site/.storybook/preview.jsx
@@ -1,3 +1,21 @@
+// @ts-check
+/**
+ * @file Defines the main configuration file for all of our Storybook tests.
+ * This file must be a JSX/JS file, but we can at least add some type safety via
+ * the ts-check directive.
+ * @see {@link https://storybook.js.org/docs/configure#configure-story-rendering}
+ *
+ * @typedef {import("react").ReactElement} ReactElement
+ * @typedef {import("react").PropsWithChildren} PropsWithChildren
+ * @typedef {import("react").FC<PropsWithChildren>} FC
+ *
+ * @typedef {import("@storybook/react").StoryContext} StoryContext
+ * @typedef {import("@storybook/react").Preview} Preview
+ *
+ * @typedef {(Story: FC, Context: StoryContext) => React.JSX.Element} Decorator A
+ * Storybook decorator function used to inject baseline data dependencies into
+ * our React components during testing.
+ */
 import "../src/index.css";
 import { ThemeProvider as EmotionThemeProvider } from "@emotion/react";
 import CssBaseline from "@mui/material/CssBaseline";

From 5233fb8f8ed4f9303f0703839837c2aaa1284a21 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Wed, 7 May 2025 23:30:21 +0000
Subject: [PATCH 22/29] chore: finish initial implementation of
 onSubscriptionAdd

---
 site/src/hooks/useTimeSync.tsx |  4 +-
 site/src/utils/TimeSync.ts     | 92 ++++++++++++++++++++++++----------
 2 files changed, 66 insertions(+), 30 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index d58d384d2445f..0b6d49e08aeb1 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -3,8 +3,6 @@
  *
  * 1. Fill out all incomplete methods
  * 2. Add tests
- * 3. See if there's a way to make sure that if you provide a type parameter to
- *    the hook, you must also provide a select function
  */
 import {
 	type FC,
@@ -308,7 +306,7 @@ export function useTimeSyncSelect<T = Date>(
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
-				targetRefreshInterval: targetRefreshInterval,
+				targetRefreshInterval,
 				id: hookId,
 				onUpdate: notifyReact,
 				select: selectForOutsideReact,
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index 9704e8cfda58a..11e894a2d4e10 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -98,6 +98,7 @@ export class TimeSync implements TimeSyncApi {
 	#latestDateSnapshot: Date;
 	#subscriptions: SubscriptionEntry[];
 	#latestIntervalId: number | undefined;
+	#currentRefreshInterval: number;
 
 	constructor(options: Partial<TimeSyncInitOptions>) {
 		const {
@@ -116,45 +117,82 @@ export class TimeSync implements TimeSyncApi {
 		this.#latestDateSnapshot = initialDatetime;
 		this.#subscriptions = [];
 		this.#latestIntervalId = undefined;
+		this.#currentRefreshInterval = Number.POSITIVE_INFINITY;
 	}
 
-	#reconcileRefreshIntervals(): void {
-		if (this.#subscriptions.length === 0) {
-			this.#clearInterval(this.#latestIntervalId);
-			return;
+	#onSubscriptionAdd(): void {
+		if (this.#resyncOnNewSubscription) {
+			this.#updateSnapshot();
 		}
 
-		const prevFastestInterval =
-			this.#subscriptions[0]?.targetRefreshInterval ?? Number.POSITIVE_INFINITY;
-		if (this.#subscriptions.length > 1) {
-			this.#subscriptions.sort(
-				(e1, e2) => e1.targetRefreshInterval - e2.targetRefreshInterval,
-			);
-		}
+		// Sort by refresh speed, descending
+		this.#subscriptions.sort(
+			(e1, e2) => e1.targetRefreshInterval - e2.targetRefreshInterval,
+		);
 
+		const oldFastestInterval = this.#currentRefreshInterval;
 		const newFastestInterval =
 			this.#subscriptions[0]?.targetRefreshInterval ?? Number.POSITIVE_INFINITY;
-		if (prevFastestInterval === newFastestInterval) {
+		if (oldFastestInterval === newFastestInterval) {
 			return;
 		}
-		if (newFastestInterval === Number.POSITIVE_INFINITY) {
-			this.#clearInterval(this.#latestIntervalId);
+
+		this.#currentRefreshInterval = newFastestInterval;
+		this.#clearInterval(this.#latestIntervalId);
+		this.#latestIntervalId = undefined;
+		if (this.#currentRefreshInterval === Number.POSITIVE_INFINITY) {
 			return;
 		}
 
-		/**
-		 * @todo Figure out the conditions when the interval should be set up,
-		 * and when/how it should be updated
-		 */
-		this.#latestIntervalId = this.#setInterval(() => {
-			this.#latestDateSnapshot = this.#createNewDatetime(
-				this.#latestDateSnapshot,
+		const newTime = this.#createNewDatetime(this.#latestDateSnapshot);
+		const elapsed =
+			newTime.getMilliseconds() - this.#latestDateSnapshot.getMilliseconds();
+
+		const startNewIntervalFromScratch = () => {
+			this.#latestIntervalId = this.#setInterval(
+				() => this.#updateSnapshot(),
+				this.#currentRefreshInterval,
 			);
-			this.#flushUpdateToSubscriptions();
-		}, newFastestInterval);
+		};
+
+		const unfulfilled = Math.max(0, this.#currentRefreshInterval - elapsed);
+		if (unfulfilled === 0) {
+			startNewIntervalFromScratch();
+			return;
+		}
+
+		// Feels a bit hokey to be setting a timeout via setInterval, but
+		// didn't want to add even more data dependencies to the constructor
+		// when setInterval can be used just fine in a pinch
+		this.#latestIntervalId = this.#setInterval(() => {
+			this.#clearInterval(this.#latestIntervalId);
+			this.#latestIntervalId = undefined;
+			startNewIntervalFromScratch();
+		}, unfulfilled);
+	}
+
+	/**
+	 * @todo This isn't done yet
+	 */
+	#onSubscriptionRemoval(): void {
+		if (this.#subscriptions.length === 0) {
+			this.#clearInterval(this.#latestIntervalId);
+			this.#latestIntervalId = undefined;
+			this.#currentRefreshInterval = Number.POSITIVE_INFINITY;
+			return;
+		}
+
+		const newFastestInterval =
+			this.#subscriptions[0]?.targetRefreshInterval ?? Number.POSITIVE_INFINITY;
+		if (newFastestInterval === this.#currentRefreshInterval) {
+			return;
+		}
 	}
 
-	#flushUpdateToSubscriptions(): void {
+	#updateSnapshot(): void {
+		this.#latestDateSnapshot = this.#createNewDatetime(
+			this.#latestDateSnapshot,
+		);
 		for (const subEntry of this.#subscriptions) {
 			subEntry.onUpdate(this.#latestDateSnapshot);
 		}
@@ -171,7 +209,7 @@ export class TimeSync implements TimeSyncApi {
 		}
 
 		this.#subscriptions = updated;
-		this.#reconcileRefreshIntervals();
+		this.#onSubscriptionRemoval();
 	}
 
 	subscribe(entry: SubscriptionEntry): void {
@@ -184,7 +222,7 @@ export class TimeSync implements TimeSyncApi {
 		const subIndex = this.#subscriptions.findIndex((s) => s.id === entry.id);
 		if (subIndex === -1) {
 			this.#subscriptions.push(entry);
-			this.#reconcileRefreshIntervals();
+			this.#onSubscriptionAdd();
 			return;
 		}
 
@@ -195,7 +233,7 @@ export class TimeSync implements TimeSyncApi {
 
 		this.#subscriptions[subIndex] = entry;
 		if (prev.targetRefreshInterval !== entry.targetRefreshInterval) {
-			this.#reconcileRefreshIntervals();
+			this.#onSubscriptionAdd();
 		}
 	}
 }

From 93cf58a2170b3a603dce8502ea3f81b8fbbdb5bc Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 15:40:22 +0000
Subject: [PATCH 23/29] fix: make error case more clear

---
 site/src/hooks/useTimeSync.tsx | 10 +++-------
 site/src/utils/TimeSync.ts     | 12 ++++++++----
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 0b6d49e08aeb1..e0205298a4665 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,8 +1,6 @@
 /**
  * @todo Things that still need to be done before this can be called done:
- *
- * 1. Fill out all incomplete methods
- * 2. Add tests
+ * 1. Add tests and address any bugs
  */
 import {
 	type FC,
@@ -233,7 +231,7 @@ function areDepsInvalidated(
 	return false;
 }
 
-type UseTimeSyncSelectOptions<T = Date> = Readonly<
+type UseTimeSyncSelectOptions<T> = Readonly<
 	UseTimeSyncOptions & {
 		/**
 		 * selectDependencies acts like the dependency array for a useMemo
@@ -271,9 +269,7 @@ type UseTimeSyncSelectOptions<T = Date> = Readonly<
  * frequent update interval, both component instances will update on that
  * interval.
  */
-export function useTimeSyncSelect<T = Date>(
-	options: UseTimeSyncSelectOptions<T>,
-): T {
+export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 	const { select, selectDependencies, targetRefreshInterval } = options;
 	const hookId = useId();
 	const timeSync = useTimeSyncContext();
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index 11e894a2d4e10..a03e27e4a7914 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -1,8 +1,8 @@
 /**
  * @todo What's left to do here:
  * 1. Fill out all incomplete methods
- * 2. Make sure the class respects the resyncOnNewSubscription option
- * 3. Add tests
+ * 2. Refactor as necessary
+ * 3. Add tests and address any bugs
  */
 export const TARGET_REFRESH_ONE_SECOND = 1_000;
 export const TARGET_REFRESH_ONE_MINUTE = 60 * 1_000;
@@ -213,9 +213,13 @@ export class TimeSync implements TimeSyncApi {
 	}
 
 	subscribe(entry: SubscriptionEntry): void {
-		if (entry.targetRefreshInterval <= 0) {
+		const intervalIsValid =
+			entry.targetRefreshInterval > 0 &&
+			(Number.isInteger(entry.targetRefreshInterval) ||
+				entry.targetRefreshInterval === Number.POSITIVE_INFINITY);
+		if (!intervalIsValid) {
 			throw new Error(
-				`Refresh interval ${entry.targetRefreshInterval} must be a positive integer (or Infinity)`,
+				`Refresh interval ${entry.targetRefreshInterval} must be a positive integer or Positive Infinity)`,
 			);
 		}
 

From 5ba068a9a61a3736b0a0dd742d0dc8171fd2bba8 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 15:58:47 +0000
Subject: [PATCH 24/29] docs: add notes about potential other approach for hook

---
 site/src/hooks/useTimeSync.tsx | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index e0205298a4665..c7ca89535dfb4 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,6 +1,15 @@
 /**
  * @todo Things that still need to be done before this can be called done:
- * 1. Add tests and address any bugs
+ * 1. Explore an idea for handling selectors without forcing someone to specify
+ *    data dependencies for what values are accessed via closure:
+ *    - A selector is ALWAYS run synchronously in a render. There is no way to
+ *      opt out of this behavior, not even memoization
+ *    - The selector is still used to determine whether a component should
+ *      re-render via a time update. It will be assumed that whatever function
+ *      is currently available will always be the most up-to-date
+ *    - This approach might make it more viable to combine useTimeSync and
+ *      useTimeSyncSelector again
+ * 2. Add tests and address any bugs
  */
 import {
 	type FC,

From f352e3b1acccb0566c7699cf9d70d439302ab3d4 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 18:00:23 +0000
Subject: [PATCH 25/29] fix: remove dependencies from hook API

---
 .../components/SignInLayout/SignInLayout.tsx  |   1 -
 site/src/hooks/useTimeSync.tsx                | 121 +++++++++---------
 .../CliInstallPage/CliInstallPageView.tsx     |   1 -
 site/src/pages/LoginPage/LoginPageView.tsx    |   1 -
 .../TemplateInsightsPage.tsx                  |   3 +-
 site/src/pages/WorkspacePage/AppStatuses.tsx  |   1 -
 .../WorkspaceScheduleControls.tsx             |   1 -
 7 files changed, 64 insertions(+), 65 deletions(-)

diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
index 550fc9f7c7464..f9eb20066d065 100644
--- a/site/src/components/SignInLayout/SignInLayout.tsx
+++ b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -5,7 +5,6 @@ import type { FC, PropsWithChildren } from "react";
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
 	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
-		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index c7ca89535dfb4..dba4e444db0a1 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -68,8 +68,56 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		this.#selectionCache = new Map();
 	}
 
+	#areValuesDeepEqual(value1: unknown, value2: unknown): boolean {
+		// JavaScript is fun and doesn't have a 100% foolproof comparison
+		// operation. Object.is covers the most cases, but you still need to
+		// compare 0 values, because even though JS programmers almost never
+		// care about +0 vs -0, Object.is does treat them as not being equal
+		if (Object.is(value1, value2)) {
+			return true;
+		}
+		if (value1 === 0 && value2 === 0) {
+			return true;
+		}
+
+		if (value1 instanceof Date && value2 instanceof Date) {
+			return value1.getMilliseconds() === value2.getMilliseconds();
+		}
+
+		// Can't reliably compare functions; just have to treat them as always
+		// different. Hopefully no one is storing functions in state for this
+		// hook, though
+		if (typeof value1 === "function" || typeof value2 === "function") {
+			return false;
+		}
+
+		if (Array.isArray(value1)) {
+			if (!Array.isArray(value2)) {
+				return false;
+			}
+			if (value1.length !== value2.length) {
+				return false;
+			}
+			return value1.every((el, i) => this.#areValuesDeepEqual(el, value2[i]));
+		}
+
+		const obj1 = value1 as Record<string, unknown>;
+		const obj2 = value1 as Record<string, unknown>;
+		if (Object.keys(obj1).length !== Object.keys(obj2).length) {
+			return false;
+		}
+		for (const key in obj1) {
+			if (!this.#areValuesDeepEqual(obj1[key], obj2[key])) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
 	// All functions that are part of the public interface must be defined as
-	// arrow functions, so that they work properly with React
+	// arrow functions, so they can be passed around React without losing their
+	// `this` context
 
 	getTimeSnapshot = () => {
 		return this.#timeSync.getTimeSnapshot();
@@ -123,14 +171,16 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	};
 
 	invalidateSelection = (id: string, select?: SelectCallback): void => {
-		const cacheEntry = this.#selectionCache.get(id);
-		if (cacheEntry === undefined) {
+		const prevSelection = this.#selectionCache.get(id);
+		if (prevSelection === undefined) {
 			return;
 		}
 
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
-		this.#selectionCache.set(id, { value: newSelection });
+		if (!this.#areValuesDeepEqual(newSelection, prevSelection.value)) {
+			this.#selectionCache.set(id, { value: newSelection });
+		}
 	};
 }
 
@@ -214,42 +264,8 @@ export function useTimeSync(options: UseTimeSyncOptions): Date {
 	return snapshot;
 }
 
-function areDepsInvalidated(
-	oldDeps: readonly unknown[] | undefined,
-	newDeps: readonly unknown[] | undefined,
-): boolean {
-	if (oldDeps === undefined) {
-		if (newDeps === undefined) {
-			return false;
-		}
-		return true;
-	}
-
-	const oldRecast = oldDeps as readonly unknown[];
-	const newRecast = oldDeps as readonly unknown[];
-	if (oldRecast.length !== newRecast.length) {
-		return true;
-	}
-
-	for (const [index, el] of oldRecast.entries()) {
-		if (el !== newRecast[index]) {
-			return true;
-		}
-	}
-
-	return false;
-}
-
 type UseTimeSyncSelectOptions<T> = Readonly<
 	UseTimeSyncOptions & {
-		/**
-		 * selectDependencies acts like the dependency array for a useMemo
-		 * callback. Whenever any of the elements in the array change by value,
-		 * that will cause the select callback to re-run synchronously and
-		 * produce a new, up-to-date value for the current render.
-		 */
-		selectDependencies: readonly unknown[];
-
 		/**
 		 * Allows you to transform any date values received from the TimeSync
 		 * class. Select functions work similarly to the selects from React
@@ -279,7 +295,7 @@ type UseTimeSyncSelectOptions<T> = Readonly<
  * interval.
  */
 export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
-	const { select, selectDependencies, targetRefreshInterval } = options;
+	const { select, targetRefreshInterval } = options;
 	const hookId = useId();
 	const timeSync = useTimeSyncContext();
 
@@ -296,7 +312,7 @@ export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 	// be initialized with whatever callback you give it on mount. So for the
 	// mounting render alone, it's safe to call a useEffectEvent callback from
 	// inside a render.
-	const selectForOutsideReact = useEffectEvent((date: Date): T => {
+	const externalSelect = useEffectEvent((date: Date): T => {
 		const recast = date as Date & T;
 		return select?.(recast) ?? recast;
 	});
@@ -314,31 +330,20 @@ export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 				targetRefreshInterval,
 				id: hookId,
 				onUpdate: notifyReact,
-				select: selectForOutsideReact,
+				select: externalSelect,
 			});
 		},
-		[timeSync, hookId, selectForOutsideReact, targetRefreshInterval],
+		[timeSync, hookId, externalSelect, targetRefreshInterval],
 	);
 
-	const [prevDeps, setPrevDeps] = useState(selectDependencies);
-	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDependencies);
-
 	const selection = useSyncExternalStore<T>(subscribe, () => {
-		if (depsAreInvalidated) {
-			// Need to make sure that we use the un-memoized version of select
-			// here because we need to call select callback mid-render to
-			// guarantee no stale data. The memoized version only syncs AFTER
-			// the current render has finished in full.
-			timeSync.invalidateSelection(hookId, select);
-		}
+		// Need to make sure that we use the un-memoized version of select
+		// here because we need to call select callback mid-render to
+		// guarantee no stale data. The memoized version only syncs AFTER
+		// the current render has finished in full.
+		timeSync.invalidateSelection(hookId, select);
 		return timeSync.getSelectionSnapshot(hookId);
 	});
 
-	// Setting state mid-render like this is valid, but we just need to make
-	// sure that we wait until after the useSyncExternalStore state getter runs
-	if (depsAreInvalidated) {
-		setPrevDeps(selectDependencies);
-	}
-
 	return selection;
 }
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
index 1ab756a379b33..ba37df59a3b0d 100644
--- a/site/src/pages/CliInstallPage/CliInstallPageView.tsx
+++ b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -12,7 +12,6 @@ type CliInstallPageViewProps = {
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
 	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
-		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
index f59100c451570..7a88bef9107fb 100644
--- a/site/src/pages/LoginPage/LoginPageView.tsx
+++ b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -30,7 +30,6 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 }) => {
 	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
-		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
index 4b25d0284d58a..eed80541e52dc 100644
--- a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
+++ b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -69,15 +69,14 @@ export default function TemplateInsightsPage() {
 	const { template } = useTemplateLayoutContext();
 	const [searchParams, setSearchParams] = useSearchParams();
 
-	const paramsInterval = searchParams.get("interval");
 	const insightsInterval = useTimeSyncSelect<InsightsInterval>({
 		targetRefreshInterval: TARGET_REFRESH_ONE_DAY,
-		selectDependencies: [paramsInterval],
 		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
 			const hasFiveWeeksOrMore = addWeeks(templateCreateDate, 5) < newDate;
 			const defaultInterval = hasFiveWeeksOrMore ? "week" : "day";
 
+			const paramsInterval = searchParams.get("interval");
 			if (paramsInterval === "week" || paramsInterval === "day") {
 				return paramsInterval;
 			}
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
index 516c9d30d354c..3a5d310016a66 100644
--- a/site/src/pages/WorkspacePage/AppStatuses.tsx
+++ b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -158,7 +158,6 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 }) => {
 	const comparisonDate = useTimeSyncSelect({
 		targetRefreshInterval: TARGET_REFRESH_ONE_MINUTE,
-		selectDependencies: [referenceDate],
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
index c4b270861423b..6493a4ffbd9d0 100644
--- a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
+++ b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
@@ -164,7 +164,6 @@ const AutostopDisplay: FC<AutostopDisplayProps> = ({
 
 	const activityStatus = useTimeSyncSelect({
 		targetRefreshInterval: 1_000,
-		selectDependencies: [workspace],
 		select: (currentDate) => getWorkspaceActivityStatus(workspace, currentDate),
 	});
 	const { message, tooltip, danger } = autostopDisplay(

From b5a68702ef42756a7310e6d90ff515a089b45480 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 18:46:53 +0000
Subject: [PATCH 26/29] refactor: clean up code

---
 site/src/hooks/useTimeSync.tsx | 122 +++++++++++++++++----------------
 1 file changed, 63 insertions(+), 59 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index dba4e444db0a1..567214d25c75d 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -68,53 +68,6 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		this.#selectionCache = new Map();
 	}
 
-	#areValuesDeepEqual(value1: unknown, value2: unknown): boolean {
-		// JavaScript is fun and doesn't have a 100% foolproof comparison
-		// operation. Object.is covers the most cases, but you still need to
-		// compare 0 values, because even though JS programmers almost never
-		// care about +0 vs -0, Object.is does treat them as not being equal
-		if (Object.is(value1, value2)) {
-			return true;
-		}
-		if (value1 === 0 && value2 === 0) {
-			return true;
-		}
-
-		if (value1 instanceof Date && value2 instanceof Date) {
-			return value1.getMilliseconds() === value2.getMilliseconds();
-		}
-
-		// Can't reliably compare functions; just have to treat them as always
-		// different. Hopefully no one is storing functions in state for this
-		// hook, though
-		if (typeof value1 === "function" || typeof value2 === "function") {
-			return false;
-		}
-
-		if (Array.isArray(value1)) {
-			if (!Array.isArray(value2)) {
-				return false;
-			}
-			if (value1.length !== value2.length) {
-				return false;
-			}
-			return value1.every((el, i) => this.#areValuesDeepEqual(el, value2[i]));
-		}
-
-		const obj1 = value1 as Record<string, unknown>;
-		const obj2 = value1 as Record<string, unknown>;
-		if (Object.keys(obj1).length !== Object.keys(obj2).length) {
-			return false;
-		}
-		for (const key in obj1) {
-			if (!this.#areValuesDeepEqual(obj1[key], obj2[key])) {
-				return false;
-			}
-		}
-
-		return true;
-	}
-
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so they can be passed around React without losing their
 	// `this` context
@@ -145,6 +98,9 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		};
 		this.#timeSync.subscribe(patchedEntry);
 
+		// Have to seed the selection cache with an initial value so that it's
+		// safe to get the value from React immediately after the subscription
+		// gets registered
 		const date = this.#timeSync.getTimeSnapshot();
 		const cacheValue = select?.(date) ?? date;
 		this.#selectionCache.set(id, { value: cacheValue });
@@ -178,12 +134,59 @@ class ReactTimeSync implements ReactTimeSyncApi {
 
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
-		if (!this.#areValuesDeepEqual(newSelection, prevSelection.value)) {
+		if (!areValuesDeepEqual(newSelection, prevSelection.value)) {
 			this.#selectionCache.set(id, { value: newSelection });
 		}
 	};
 }
 
+function areValuesDeepEqual(value1: unknown, value2: unknown): boolean {
+	// JavaScript is fun and doesn't have a 100% foolproof comparison
+	// operation. Object.is covers the most cases, but you still need to
+	// compare 0 values, because even though JS programmers almost never
+	// care about +0 vs -0, Object.is does treat them as not being equal
+	if (Object.is(value1, value2)) {
+		return true;
+	}
+	if (value1 === 0 && value2 === 0) {
+		return true;
+	}
+
+	if (value1 instanceof Date && value2 instanceof Date) {
+		return value1.getMilliseconds() === value2.getMilliseconds();
+	}
+
+	// Can't reliably compare functions; just have to treat them as always
+	// different. Hopefully no one is storing functions in state for this
+	// hook, though
+	if (typeof value1 === "function" || typeof value2 === "function") {
+		return false;
+	}
+
+	if (Array.isArray(value1)) {
+		if (!Array.isArray(value2)) {
+			return false;
+		}
+		if (value1.length !== value2.length) {
+			return false;
+		}
+		return value1.every((el, i) => areValuesDeepEqual(el, value2[i]));
+	}
+
+	const obj1 = value1 as Record<string, unknown>;
+	const obj2 = value1 as Record<string, unknown>;
+	if (Object.keys(obj1).length !== Object.keys(obj2).length) {
+		return false;
+	}
+	for (const key in obj1) {
+		if (!areValuesDeepEqual(obj1[key], obj2[key])) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
 const timeSyncContext = createContext<ReactTimeSync | null>(null);
 
 type TimeSyncProviderProps = Readonly<
@@ -317,13 +320,14 @@ export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 		return select?.(recast) ?? recast;
 	});
 
-	// We need to define this callback using useCallback instead of
-	// useEffectEvent because we want the memoization to be invalidated when the
-	// refresh interval changes. (When the subscription callback changes by
-	// reference, that causes useSyncExternalStore to redo the subscription with
-	// the new callback). All other values need to be included in the dependency
-	// array for correctness, but they should always maintain stable memory
-	// addresses
+	// We're leaning into the React hook API behavior to simplify needing to
+	// resync the refresh intervals when they change during re-renders. Whenever
+	// useSyncExternalStore receives a new callback by reference, it will
+	// automatically unsubscribe with the previous callback and re-subscribe
+	// with the new one. useCallback stabilizes the reference, with the ability
+	// to invalidate it whenever the interval changes. Have to include all other
+	// elements in the dependency array for correctness, but they should remain
+	// 100% stable for the entire lifetime of the component
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
@@ -337,10 +341,10 @@ export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 	);
 
 	const selection = useSyncExternalStore<T>(subscribe, () => {
-		// Need to make sure that we use the un-memoized version of select
-		// here because we need to call select callback mid-render to
-		// guarantee no stale data. The memoized version only syncs AFTER
-		// the current render has finished in full.
+		// Need to make sure that we use the un-memoized version of select here
+		// because we need to call select callback mid-render to guarantee no
+		// stale data. The memoized version only syncs AFTER the current render
+		// has finished in full.
 		timeSync.invalidateSelection(hookId, select);
 		return timeSync.getSelectionSnapshot(hookId);
 	});

From 10fbdfcd5b149348f8e079b1510c8088ce6d6747 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 19:34:17 +0000
Subject: [PATCH 27/29] refactor: make hook less confusing

---
 site/src/hooks/useTimeSync.tsx | 32 ++++++++++++++++++++------------
 site/src/utils/TimeSync.ts     |  5 -----
 2 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index 567214d25c75d..ebe4017d5a9ba 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -29,12 +29,10 @@ import {
 } from "utils/TimeSync";
 import { useEffectEvent } from "./hookPolyfills";
 
-export {
-	TARGET_REFRESH_ONE_DAY,
-	TARGET_REFRESH_ONE_HOUR,
-	TARGET_REFRESH_ONE_MINUTE,
-	TARGET_REFRESH_ONE_SECOND,
-} from "utils/TimeSync";
+export const TARGET_REFRESH_ONE_SECOND = 1_000;
+export const TARGET_REFRESH_ONE_MINUTE = 60 * 1_000;
+export const TARGET_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
+export const TARGET_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
 
 type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 
@@ -88,7 +86,7 @@ class ReactTimeSync implements ReactTimeSyncApi {
 			onUpdate: (newDate) => {
 				const prevSelection = this.getSelectionSnapshot(id);
 				const newSelection = select?.(newDate) ?? newDate;
-				if (newSelection === prevSelection) {
+				if (areValuesDeepEqual(prevSelection, newSelection)) {
 					return;
 				}
 
@@ -99,7 +97,7 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		this.#timeSync.subscribe(patchedEntry);
 
 		// Have to seed the selection cache with an initial value so that it's
-		// safe to get the value from React immediately after the subscription
+		// safe for React to get the value immediately after the subscription
 		// gets registered
 		const date = this.#timeSync.getTimeSnapshot();
 		const cacheValue = select?.(date) ?? date;
@@ -132,6 +130,11 @@ class ReactTimeSync implements ReactTimeSyncApi {
 			return;
 		}
 
+		// It is very, VERY important that we only change the value in the
+		// selection cache when it changes by value. If the state getter
+		// function for useSyncExternalStore always receives a new value by
+		// reference on every call, that will create an infinite render loop in
+		// dev mode
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
 		if (!areValuesDeepEqual(newSelection, prevSelection.value)) {
@@ -270,10 +273,15 @@ export function useTimeSync(options: UseTimeSyncOptions): Date {
 type UseTimeSyncSelectOptions<T> = Readonly<
 	UseTimeSyncOptions & {
 		/**
-		 * Allows you to transform any date values received from the TimeSync
-		 * class. Select functions work similarly to the selects from React
-		 * Query and Redux Toolkit – you don't need to memoize them, and they
-		 * will only run when the underlying TimeSync state has changed.
+		 * Allows you to transform any Date values received from the TimeSync
+		 * class, while providing render optimizations. Select functions are
+		 * ALWAYS run during a render to guarantee no wrong data from stale
+		 * closures.
+		 *
+		 * However, when a new time update is dispatched from TimeSync, the hook
+		 * will use the latest select callback received to transform the value.
+		 * If the select result has not changed compared to last time
+		 * (comparing via deep equality), the hook will skip re-rendering.
 		 *
 		 * Select functions must not be async. The hook will error out at the
 		 * type level if you provide one by mistake.
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index a03e27e4a7914..dfdf0e8519ba3 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -4,11 +4,6 @@
  * 2. Refactor as necessary
  * 3. Add tests and address any bugs
  */
-export const TARGET_REFRESH_ONE_SECOND = 1_000;
-export const TARGET_REFRESH_ONE_MINUTE = 60 * 1_000;
-export const TARGET_REFRESH_ONE_HOUR = 60 * 60 * 1_000;
-export const TARGET_REFRESH_ONE_DAY = 24 * 60 * 60 * 1_000;
-
 export type SetInterval = (fn: () => void, intervalMs: number) => number;
 export type ClearInterval = (id: number | undefined) => void;
 

From d7c70e26544cf2c518a1f0c5654f964adc2e065e Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 20:09:52 +0000
Subject: [PATCH 28/29] fix: resolve bug when syncing new interval

---
 site/src/hooks/useTimeSync.tsx | 67 ++++++++++------------------------
 site/src/utils/TimeSync.ts     | 21 ++++++-----
 2 files changed, 31 insertions(+), 57 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index ebe4017d5a9ba..b7fc4c98e1d5e 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -1,15 +1,6 @@
 /**
  * @todo Things that still need to be done before this can be called done:
- * 1. Explore an idea for handling selectors without forcing someone to specify
- *    data dependencies for what values are accessed via closure:
- *    - A selector is ALWAYS run synchronously in a render. There is no way to
- *      opt out of this behavior, not even memoization
- *    - The selector is still used to determine whether a component should
- *      re-render via a time update. It will be assumed that whatever function
- *      is currently available will always be the most up-to-date
- *    - This approach might make it more viable to combine useTimeSync and
- *      useTimeSyncSelector again
- * 2. Add tests and address any bugs
+ * 1. Add tests and address any bugs
  */
 import {
 	type FC,
@@ -77,9 +68,6 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
 		const { select, id, targetRefreshInterval, onUpdate } = entry;
 
-		// Make sure that we subscribe first, in case TimeSync is configured to
-		// invalidate the snapshot on a new subscription. Want to remove risk of
-		// stale data
 		const patchedEntry: SubscriptionEntry = {
 			id,
 			targetRefreshInterval,
@@ -94,15 +82,8 @@ class ReactTimeSync implements ReactTimeSyncApi {
 				onUpdate(newDate);
 			},
 		};
-		this.#timeSync.subscribe(patchedEntry);
-
-		// Have to seed the selection cache with an initial value so that it's
-		// safe for React to get the value immediately after the subscription
-		// gets registered
-		const date = this.#timeSync.getTimeSnapshot();
-		const cacheValue = select?.(date) ?? date;
-		this.#selectionCache.set(id, { value: cacheValue });
 
+		this.#timeSync.subscribe(patchedEntry);
 		return () => this.#timeSync.unsubscribe(id);
 	};
 
@@ -125,11 +106,6 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	};
 
 	invalidateSelection = (id: string, select?: SelectCallback): void => {
-		const prevSelection = this.#selectionCache.get(id);
-		if (prevSelection === undefined) {
-			return;
-		}
-
 		// It is very, VERY important that we only change the value in the
 		// selection cache when it changes by value. If the state getter
 		// function for useSyncExternalStore always receives a new value by
@@ -137,6 +113,13 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		// dev mode
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
+
+		const prevSelection = this.#selectionCache.get(id);
+		if (prevSelection === undefined) {
+			this.#selectionCache.set(id, { value: newSelection });
+			return;
+		}
+
 		if (!areValuesDeepEqual(newSelection, prevSelection.value)) {
 			this.#selectionCache.set(id, { value: newSelection });
 		}
@@ -310,42 +293,32 @@ export function useTimeSyncSelect<T>(options: UseTimeSyncSelectOptions<T>): T {
 	const hookId = useId();
 	const timeSync = useTimeSyncContext();
 
-	// This is the one place where we're borderline breaking the React rules.
-	// useEffectEvent is meant to be used only in useEffect calls, and normally
-	// shouldn't be called inside a render. But its behavior lines up with
-	// useSyncExternalStore, letting us cheat a little. useSyncExternalStore's
-	// state getter callback is called in two scenarios:
-	// (1) Mid-render on mount
-	// (2) Whenever React is notified of a state change (outside of React).
-	//
-	// Case 2 is basically an effect with extra steps (and single-threaded JS
-	// gives us assurance about correctness). And for (1), useEffectEvent will
-	// be initialized with whatever callback you give it on mount. So for the
-	// mounting render alone, it's safe to call a useEffectEvent callback from
-	// inside a render.
-	const externalSelect = useEffectEvent((date: Date): T => {
+	// externalSelect is passed to the ReactTimeSync class for use when the
+	// class dispatches a new Date update. It should not be called inside the
+	// render logic whatsoever.
+	const externalStableSelect = useEffectEvent((date: Date): T => {
 		const recast = date as Date & T;
 		return select?.(recast) ?? recast;
 	});
 
-	// We're leaning into the React hook API behavior to simplify needing to
-	// resync the refresh intervals when they change during re-renders. Whenever
+	// We're leaning into the React hook API behavior to simplify syncing the
+	// refresh intervals when they change during re-renders. Whenever
 	// useSyncExternalStore receives a new callback by reference, it will
 	// automatically unsubscribe with the previous callback and re-subscribe
 	// with the new one. useCallback stabilizes the reference, with the ability
-	// to invalidate it whenever the interval changes. Have to include all other
-	// elements in the dependency array for correctness, but they should remain
-	// 100% stable for the entire lifetime of the component
+	// to invalidate it whenever the interval changes. We have to include all
+	// other data dependencies in the dependency array for correctness, but they
+	// should remain 100% stable by reference for the lifetime of the component
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
 				targetRefreshInterval,
 				id: hookId,
 				onUpdate: notifyReact,
-				select: externalSelect,
+				select: externalStableSelect,
 			});
 		},
-		[timeSync, hookId, externalSelect, targetRefreshInterval],
+		[timeSync, hookId, externalStableSelect, targetRefreshInterval],
 	);
 
 	const selection = useSyncExternalStore<T>(subscribe, () => {
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
index dfdf0e8519ba3..449d17f561822 100644
--- a/site/src/utils/TimeSync.ts
+++ b/site/src/utils/TimeSync.ts
@@ -91,9 +91,9 @@ export class TimeSync implements TimeSyncApi {
 	readonly #clearInterval: ClearInterval;
 
 	#latestDateSnapshot: Date;
-	#subscriptions: SubscriptionEntry[];
-	#latestIntervalId: number | undefined;
-	#currentRefreshInterval: number;
+	#subscriptions: SubscriptionEntry[] = [];
+	#latestIntervalId: number | undefined = undefined;
+	#currentRefreshInterval: number = Number.POSITIVE_INFINITY;
 
 	constructor(options: Partial<TimeSyncInitOptions>) {
 		const {
@@ -108,11 +108,7 @@ export class TimeSync implements TimeSyncApi {
 		this.#clearInterval = clearInterval;
 		this.#createNewDatetime = createNewDatetime;
 		this.#resyncOnNewSubscription = resyncOnNewSubscription;
-
 		this.#latestDateSnapshot = initialDatetime;
-		this.#subscriptions = [];
-		this.#latestIntervalId = undefined;
-		this.#currentRefreshInterval = Number.POSITIVE_INFINITY;
 	}
 
 	#onSubscriptionAdd(): void {
@@ -185,9 +181,14 @@ export class TimeSync implements TimeSyncApi {
 	}
 
 	#updateSnapshot(): void {
-		this.#latestDateSnapshot = this.#createNewDatetime(
-			this.#latestDateSnapshot,
-		);
+		// It's assumed that TimeSync will be used with subscribers that will
+		// treat whatever Date they receive as an immutable value. But because
+		// the entire class breaks if someone does mutate it, we need to freeze
+		// the value
+		const newRawDate = this.#createNewDatetime(this.#latestDateSnapshot);
+		Object.freeze(newRawDate);
+		this.#latestDateSnapshot = newRawDate;
+
 		for (const subEntry of this.#subscriptions) {
 			subEntry.onUpdate(this.#latestDateSnapshot);
 		}

From 0ffe2afc09985410e6055735d595fcae7e3c94e7 Mon Sep 17 00:00:00 2001
From: Michael Smith <throwawayclover@gmail.com>
Date: Fri, 9 May 2025 20:25:03 +0000
Subject: [PATCH 29/29] fix: remove race condition in caching logic

---
 site/src/hooks/useTimeSync.tsx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
index b7fc4c98e1d5e..6ee1d66659a85 100644
--- a/site/src/hooks/useTimeSync.tsx
+++ b/site/src/hooks/useTimeSync.tsx
@@ -68,11 +68,11 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
 		const { select, id, targetRefreshInterval, onUpdate } = entry;
 
-		const patchedEntry: SubscriptionEntry = {
+		const fullEntry: SubscriptionEntry = {
 			id,
 			targetRefreshInterval,
 			onUpdate: (newDate) => {
-				const prevSelection = this.getSelectionSnapshot(id);
+				const prevSelection = this.#selectionCache.get(id)?.value;
 				const newSelection = select?.(newDate) ?? newDate;
 				if (areValuesDeepEqual(prevSelection, newSelection)) {
 					return;
@@ -83,7 +83,7 @@ class ReactTimeSync implements ReactTimeSyncApi {
 			},
 		};
 
-		this.#timeSync.subscribe(patchedEntry);
+		this.#timeSync.subscribe(fullEntry);
 		return () => this.#timeSync.unsubscribe(id);
 	};
 
@@ -114,13 +114,13 @@ class ReactTimeSync implements ReactTimeSyncApi {
 		const dateSnapshot = this.#timeSync.getTimeSnapshot();
 		const newSelection = select?.(dateSnapshot) ?? dateSnapshot;
 
-		const prevSelection = this.#selectionCache.get(id);
-		if (prevSelection === undefined) {
+		const cacheEntry = this.#selectionCache.get(id);
+		if (cacheEntry === undefined) {
 			this.#selectionCache.set(id, { value: newSelection });
 			return;
 		}
 
-		if (!areValuesDeepEqual(newSelection, prevSelection.value)) {
+		if (!areValuesDeepEqual(newSelection, cacheEntry.value)) {
 			this.#selectionCache.set(id, { value: newSelection });
 		}
 	};