swarm-ui: shared refresh-interval polling control

Closes #3446.

New ui/refresh-interval/RefreshInterval — a RefreshIntervalPicker
(off/10s/30s/1m preset select) plus a useRefreshInterval hook that
polls on that cadence, pausing while the document is hidden and
resyncing immediately on becoming visible again (same pattern
RelativeTime already uses). The hook keeps the caller's onTick fresh
via a ref rather than an effect dependency, so a new closure each
render doesn't re-arm the timer.

HivesPage wires it in: defaults to 30s (no inputs on this page to
interrupt, and the point of the feature is not needing a manual
reload), replacing the old fetch-once-at-mount effect. A successful
refresh also clears any previous fetch error instead of leaving a
stale failure on screen after the data's recovered.

Verified: tsc clean, build succeeds, screenshotted the hives page
(auto-loads on mount, picker defaults to 30s) and the components page
demo.

frontend/packages/swarm-ui/src/pages/ComponentsPage.tsx

@@ -9,6 +9,7 @@ import { useState } from 'preact/hooks';
 import type { ComponentChildren } from 'preact';
 import { Panel } from '../ui/panel/Panel.js';
 import { RelativeTime } from '../ui/relative-time/RelativeTime.js';
+import { RefreshIntervalPicker, type RefreshIntervalMs } from '../ui/refresh-interval/RefreshInterval.js';
 import { StatusChip, type ChipTone } from '../ui/status-chip/StatusChip.js';
 import { Table, type TableColumn } from '../ui/table/Table.js';
 import { TextField } from '../ui/text-field/TextField.js';
@@ -80,6 +81,11 @@ function SelectFieldSample() {
   );
 }
 
+function RefreshIntervalPickerSample() {
+  const [value, setValue] = useState<RefreshIntervalMs>(30_000);
+  return <RefreshIntervalPicker id="sample-refresh-interval" value={value} onChange={setValue} />;
+}
+
 export function ComponentsPage() {
   return (
     <Panel title="components">
@@ -127,6 +133,12 @@ export function ComponentsPage() {
         </div>
       </Section>
 
+      <Section title="RefreshIntervalPicker">
+        <Sample label="editable">
+          <RefreshIntervalPickerSample />
+        </Sample>
+      </Section>
+
       <Section title="TextField">
         <Sample label="editable">
           <TextFieldSample />

frontend/packages/swarm-ui/src/pages/HivesPage.tsx

@@ -7,11 +7,21 @@
 // that placeholder's comment laid out. Its own component/file rather
 // than living in `App.tsx`, matching `JobsPage`'s shape: `App.tsx` is
 // routing, a page owns its own fetch + render.
-import { useEffect, useState } from 'preact/hooks';
+//
+// Polls on a `RefreshIntervalPicker` cadence rather than fetching once
+// at mount — no inputs on this page, so a re-fetch clobbering an
+// in-progress edit (the hook's stated caller obligation) isn't a live
+// concern here.
+import { useState } from 'preact/hooks';
 import { ApiErrorPanel } from '@hive/shared/api-error-panel.js';
 import { readApiError, type ProblemDetails } from '@hive/shared/api-error.js';
 import { Panel } from '../ui/panel/Panel.js';
 import { RelativeTime } from '../ui/relative-time/RelativeTime.js';
+import {
+  RefreshIntervalPicker,
+  useRefreshInterval,
+  type RefreshIntervalMs,
+} from '../ui/refresh-interval/RefreshInterval.js';
 import { StatusChip, type ChipTone } from '../ui/status-chip/StatusChip.js';
 import { Table, type TableColumn } from '../ui/table/Table.js';
 
@@ -75,11 +85,19 @@ const COLUMNS: TableColumn<HiveStatus>[] = [
   },
 ];
 
+// 30s default: this page has no inputs to interrupt, and the whole
+// point of a refresh-interval control is "no manual reload needed" — an
+// operator who wants it off still can, but the out-of-the-box behaviour
+// should actually solve the staleness problem rather than require an
+// opt-in every visit.
+const DEFAULT_INTERVAL_MS: RefreshIntervalMs = 30_000;
+
 export function HivesPage() {
   const [hives, setHives] = useState<HiveStatus[] | null>(null);
   const [error, setError] = useState<ProblemDetails | null>(null);
+  const [intervalMs, setIntervalMs] = useState<RefreshIntervalMs>(DEFAULT_INTERVAL_MS);
 
-  useEffect(() => {
+  useRefreshInterval(intervalMs, () => {
     (async () => {
       const r = await fetch('/api/hives/status');
       if (!r.ok) {
@@ -87,11 +105,16 @@ export function HivesPage() {
         return;
       }
       setHives((await r.json()) as HiveStatus[]);
+      // A refresh that succeeds clears a previous failure — otherwise a
+      // transient error would sit on screen forever after the data
+      // itself has recovered.
+      setError(null);
     })().catch((e: unknown) => setError({ detail: String(e) }));
-  }, []);
+  });
 
   return (
     <Panel title="hives">
+      <RefreshIntervalPicker id="hives-refresh" value={intervalMs} onChange={setIntervalMs} />
       {error ? <ApiErrorPanel context="failed to load the hive roster" problem={error} /> : null}
       {!error && hives === null ? <p>loading…</p> : null}
       {hives ? <Table columns={COLUMNS} rows={hives} rowKey={(h) => h.name} /> : null}