@celestia-island/hikari 0.55.144 → 0.55.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.144",
+  "version": "0.55.146",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkDatePicker.test.ts

@@ -194,7 +194,7 @@ describe("HkDatePicker", () => {
   });
 
   it("disables days outside the inclusive min/max bounds", async () => {
-    const p = mountPicker({ modelValue: "2026-08-16", min: "2026-08-10", max: "2026-08-20" });
+    const p = mountPicker({ modelValue: "2026-08-16", min: "2026-08-10", max: "2026-08-20", nativeOnMobile: true });
     openViaEnter(p);
     await nextTick();
     const byDay = new Map(
@@ -453,22 +453,12 @@ describe("HkDatePicker", () => {
     expect(stage?.querySelectorAll<HTMLButtonElement>(".hk-dp-cell:not([data-variant])").length).toBe(42);
   });
 
-  // ── Mobile pass-through to the native OS control ────────────────
+  // ── Mobile: the CALENDAR is the default; the native input is the
+  // ── explicit opt-out (2026-10-11 direction: no native controls) ──
 
-  it("renders a native date input instead of the calendar on mobile", () => {
+  it("keeps the calendar on mobile by default (no native input)", async () => {
     useMobileViewport();
     const p = mountPicker({ modelValue: "2026-08-16" });
-    const input = nativeInput(p.container);
-    expect(input).not.toBeNull();
-    expect(input?.type).toBe("date");
-    expect(input?.value).toBe("2026-08-16");
-    expect(p.container.querySelector(".hk-dp-trigger")).toBeNull();
-    expect(p.container.querySelector(".hk-dp-panel")).toBeNull();
-  });
-
-  it("keeps the custom calendar on mobile when nativeOnMobile is false", async () => {
-    useMobileViewport();
-    const p = mountPicker({ modelValue: "2026-08-16", nativeOnMobile: false });
     expect(p.container.querySelector(".hk-dp-trigger")).not.toBeNull();
     expect(nativeInput(p.container)).toBeNull();
     openViaEnter(p);
@@ -479,17 +469,28 @@ describe("HkDatePicker", () => {
     expect(panel()?.classList.contains("is-touch")).toBe(true);
   });
 
-  it("passes min/max through to the native input", () => {
+  it("renders a native date input on mobile only when nativeOnMobile opts in", () => {
+    useMobileViewport();
+    const p = mountPicker({ modelValue: "2026-08-16", nativeOnMobile: true });
+    const input = nativeInput(p.container);
+    expect(input).not.toBeNull();
+    expect(input?.type).toBe("date");
+    expect(input?.value).toBe("2026-08-16");
+    expect(p.container.querySelector(".hk-dp-trigger")).toBeNull();
+    expect(p.container.querySelector(".hk-dp-panel")).toBeNull();
+  });
+
+  it("passes min/max through to the native input (explicit opt-in)", () => {
     useMobileViewport();
-    const p = mountPicker({ modelValue: "2026-08-16", min: "2026-08-10", max: "2026-08-20" });
+    const p = mountPicker({ modelValue: "2026-08-16", min: "2026-08-10", max: "2026-08-20", nativeOnMobile: true });
     const input = nativeInput(p.container);
     expect(input?.min).toBe("2026-08-10");
     expect(input?.max).toBe("2026-08-20");
   });
 
-  it("native input edits emit the ISO date and clearing emits null", async () => {
+  it("native input edits emit the ISO date and clearing emits null (explicit opt-in)", async () => {
     useMobileViewport();
-    const p = mountPicker({ modelValue: "2026-08-16" });
+    const p = mountPicker({ modelValue: "2026-08-16", nativeOnMobile: true });
     const input = nativeInput(p.container);
     input!.value = "2026-08-20";
     input!.dispatchEvent(new Event("input", { bubbles: true }));
@@ -503,9 +504,9 @@ describe("HkDatePicker", () => {
     expect(p.emitted).toEqual(["2026-08-20", null]);
   });
 
-  it("native input edits outside the bounds are rejected and re-synced", async () => {
+  it("native input edits outside the bounds are rejected and re-synced (explicit opt-in)", async () => {
     useMobileViewport();
-    const p = mountPicker({ modelValue: "2026-08-16", max: "2026-08-20" });
+    const p = mountPicker({ modelValue: "2026-08-16", max: "2026-08-20", nativeOnMobile: true });
     const input = nativeInput(p.container);
     input!.value = "2026-09-01";
     input!.dispatchEvent(new Event("input", { bubbles: true }));

package/src/components/HkDatePicker.tsx

@@ -73,8 +73,12 @@ export default defineComponent({
     min: { type: String as PropType<string | undefined>, default: undefined },
     /** Inclusive upper bound as an ISO date; later days render disabled. */
     max: { type: String as PropType<string | undefined>, default: undefined },
-    /** Render the OS native `<input type="date">` on touch-sized viewports. */
-    nativeOnMobile: { type: Boolean, default: true },
+    /** Render the OS native `<input type="date">` on touch-sized viewports.
+     *  DEFAULTS FALSE since 2026-10-11 (user direction: no native controls
+     *  anywhere) — the calendar serves phones as a bottom sheet with the
+     *  enlarged touch chrome. The prop stays for one-off hosts that truly
+     *  want the OS picker; new callers should not set it. */
+    nativeOnMobile: { type: Boolean, default: false },
   },
   emits: {
     "update:modelValue": (_value: string | null) => true,

package/src/components/HkDateTimePicker.test.ts

@@ -324,11 +324,12 @@ describe("HkDateTimePicker", () => {
     expect(document.querySelectorAll(".hk-dtp-popup .hk-dtp-cell").length).toBe(42);
   });
 
-  // ── Mobile pass-through to the native OS control ────────────────
+  // ── Mobile: the calendar is the default; native is the explicit ──
+  // ── opt-out (2026-10-11 direction: no native controls) ───────────
 
-  it("renders a native datetime-local input instead of the calendar on mobile", () => {
+  it("renders a native datetime-local input on mobile only when nativeOnMobile opts in", () => {
     useMobileViewport();
-    const p = mountPicker();
+    const p = mountPicker({ nativeOnMobile: true });
     const input = nativeInput(p.container);
     expect(input).not.toBeNull();
     expect(input?.type).toBe("datetime-local");
@@ -337,9 +338,9 @@ describe("HkDateTimePicker", () => {
     expect(p.container.querySelector(".hk-dtp-grid")).toBeNull();
   });
 
-  it("uses a native date input when showTime is false", () => {
+  it("uses a native date input when showTime is false (explicit opt-in)", () => {
     useMobileViewport();
-    const p = mountPicker({ showTime: false });
+    const p = mountPicker({ showTime: false, nativeOnMobile: true });
     const input = nativeInput(p.container);
     expect(input?.type).toBe("date");
     expect(input?.value).toBe(isoDay(BASE));
@@ -347,15 +348,15 @@ describe("HkDateTimePicker", () => {
 
   it("passes min/max through to the native input in its wire format", () => {
     useMobileViewport();
-    const p = mountPicker({ min: dayOf(10, 8, 0), max: dayOf(20, 18, 30) });
+    const p = mountPicker({ min: dayOf(10, 8, 0), max: dayOf(20, 18, 30), nativeOnMobile: true });
     const input = nativeInput(p.container);
     expect(input?.min).toBe(isoMinute(dayOf(10, 8, 0)));
     expect(input?.max).toBe(isoMinute(dayOf(20, 18, 30)));
   });
 
-  it("keeps the custom calendar on mobile when nativeOnMobile is false", () => {
+  it("keeps the custom calendar on mobile by default", () => {
     useMobileViewport();
-    const p = mountPicker({ nativeOnMobile: false });
+    const p = mountPicker();
     expect(p.container.querySelector(".hk-dtp")).not.toBeNull();
     expect(dayCells().length).toBe(42);
     expect(nativeInput(p.container)).toBeNull();
@@ -365,7 +366,7 @@ describe("HkDateTimePicker", () => {
 
   it("native input edits update the model as a local-time Date", async () => {
     useMobileViewport();
-    const p = mountPicker();
+    const p = mountPicker({ nativeOnMobile: true });
     const input = nativeInput(p.container);
     input!.value = isoMinute(dayOf(20, 14, 5));
     input!.dispatchEvent(new Event("input", { bubbles: true }));
@@ -377,7 +378,7 @@ describe("HkDateTimePicker", () => {
 
   it("native date edits preserve the clock time when showTime is false", async () => {
     useMobileViewport();
-    const p = mountPicker({ showTime: false });
+    const p = mountPicker({ showTime: false, nativeOnMobile: true });
     const input = nativeInput(p.container);
     input!.value = isoDay(dayOf(20));
     input!.dispatchEvent(new Event("input", { bubbles: true }));
@@ -387,7 +388,7 @@ describe("HkDateTimePicker", () => {
 
   it("native input edits outside the bounds are rejected and re-synced", async () => {
     useMobileViewport();
-    const p = mountPicker({ max: dayOf(20, 23, 59) });
+    const p = mountPicker({ max: dayOf(20, 23, 59), nativeOnMobile: true });
     const input = nativeInput(p.container);
     // Next month, past the max bound.
     input!.value = isoMinute(new Date(BASE.getFullYear(), BASE.getMonth() + 1, 1, 10, 0));
@@ -399,7 +400,7 @@ describe("HkDateTimePicker", () => {
 
   it("clearing the native input falls back to the model value", async () => {
     useMobileViewport();
-    const p = mountPicker();
+    const p = mountPicker({ nativeOnMobile: true });
     const input = nativeInput(p.container);
     input!.value = "";
     input!.dispatchEvent(new Event("input", { bubbles: true }));
@@ -408,9 +409,9 @@ describe("HkDateTimePicker", () => {
     expect(input?.value).toBe(isoMinute(BASE));
   });
 
-  it("native input replaces even the popup chrome on mobile", () => {
+  it("native input replaces even the popup chrome on mobile (explicit opt-in)", () => {
     useMobileViewport();
-    const p = mountPicker({ mode: "popup", confirmLabel: "Confirm" });
+    const p = mountPicker({ mode: "popup", confirmLabel: "Confirm", nativeOnMobile: true });
     expect(nativeInput(p.container)).not.toBeNull();
     expect(p.container.querySelector(".hk-dtp-trigger")).toBeNull();
   });

package/src/components/HkDateTimePicker.tsx

@@ -95,7 +95,7 @@ export default defineComponent({
     confirmLabel: { type: String, default: undefined },
     showTime: { type: Boolean, default: true },
     /** Render the OS native `<input type="datetime-local">` on touch-sized viewports. */
-    nativeOnMobile: { type: Boolean, default: true },
+    nativeOnMobile: { type: Boolean, default: false }, // 2026-10-11: no native controls — the picker sheet serves phones
   },
   emits: {
     "update:modelValue": (_d: Date) => true,

package/src/components/HkFilterBar.tsx

@@ -99,6 +99,7 @@ export default defineComponent({
               anchorRef={anchorRef.value}
               placement={props.placement}
               offset={6}
+              sheetOnMobile
               title={label}
             >
               <div class="hk-filter-bar-panel" data-testid="hk-filter-bar-panel">

package/src/components/HkFilterPanel.tsx

@@ -1,5 +1,6 @@
 import { computed, defineComponent, type PropType } from "vue";
 
+import HkDatePicker from "./HkDatePicker";
 import HkInput from "./HkInput";
 import HkPopupSelect, { type HkPopupSelectOption } from "./HkPopupSelect";
 import { useI18n } from "../i18n/context";
@@ -168,9 +169,20 @@ export default defineComponent({
                       disabled={props.disabled}
                       options={selectOptions(field)}
                     />
+                  ) : field.kind === "date" ? (
+                    // The calendar picker — never the OS native input
+                    // (2026-10-11 direction); the wire format is the same
+                    // ISO YYYY-MM-DD the native input spoke.
+                    <HkDatePicker
+                      modelValue={condition.value || null}
+                      onUpdate:modelValue={(v: string | null) =>
+                        emitCondition(field, { value: v ?? "" })
+                      }
+                      disabled={props.disabled}
+                    />
                   ) : (
                     <HkInput
-                      type={field.kind === "date" ? "date" : "text"}
+                      type="text"
                       variant={field.kind === "number" ? "number" : "text"}
                       modelValue={condition.value}
                       onUpdate:modelValue={(v: string) =>

package/src/composables/useConnectionProbe.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, type Ref } from "vue";
+
+import { useConnectionProbe, type ProbeResult } from "./useConnectionProbe";
+
+/** The probe is a mount-scoped composable (onMounted drives the first
+ *  fetch); each test rides a minimal component harness. Fake timers own
+ *  both the clock (latency, countdown ladder) and the interval bus. */
+
+interface Deferred {
+  promise: Promise<Response>;
+  resolve: (r: Response) => void;
+  reject: (e: unknown) => void;
+}
+
+function deferredResponse(): Deferred {
+  let resolve!: (r: Response) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<Response>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function okResponse(): Response {
+  return { ok: true } as Response;
+}
+
+function mountProbe() {
+  let out!: { result: Ref<ProbeResult>; retryNow: () => void };
+  const app = createApp(
+    defineComponent({
+      setup() {
+        out = useConnectionProbe();
+        return () => h("div");
+      },
+    }),
+  );
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  app.mount(container);
+  return {
+    probe: () => out,
+    unmount: () => {
+      app.unmount();
+      container.remove();
+    },
+  };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+describe("useConnectionProbe continuous observation", () => {
+  it("keeps polling after a successful probe — parked-forever was the bug", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn(() => Promise.resolve(okResponse()));
+    vi.stubGlobal("fetch", fetchMock);
+    const { probe, unmount } = mountProbe();
+    try {
+      await vi.advanceTimersByTimeAsync(0);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(probe().result.value.state).toBe("connected");
+
+      // The scheduled re-check fires 15s later — the light KEEPS
+      // observing instead of recording the initial verdict forever.
+      await vi.advanceTimersByTimeAsync(15_000);
+      expect(fetchMock, "healthy backend keeps being polled").toHaveBeenCalledTimes(2);
+      expect(probe().result.value.state).toBe("connected");
+      expect(probe().result.value.connected).toBe(true);
+    } finally {
+      unmount();
+    }
+  });
+
+  it("a healthy re-check stays GREEN in flight — no reconnecting blink, no flash", async () => {
+    vi.useFakeTimers();
+    const first = deferredResponse();
+    const second = deferredResponse();
+    // Route by call order: first mount fetch, then the scheduled re-check.
+    let calls = 0;
+    const fetchMock = vi.fn(() => {
+      calls += 1;
+      return calls === 1 ? first.promise : second.promise;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { probe, unmount } = mountProbe();
+    try {
+      first.resolve(okResponse());
+      await vi.advanceTimersByTimeAsync(0);
+      expect(probe().result.value.state).toBe("connected");
+
+      // Fire the scheduled re-check and let it hang mid-fetch: the OLD
+      // behavior flipped the state to "reconnecting" here (yellow blink
+      // + recovery flash every interval). Quiet re-checks must not.
+      await vi.advanceTimersByTimeAsync(15_000);
+      await Promise.resolve(); // enter the awaiting fetch
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(probe().result.value.state, "in-flight re-check is quiet").toBe("connected");
+      expect(probe().result.value.connected).toBe(true);
+
+      second.resolve(okResponse());
+      await vi.advanceTimersByTimeAsync(0);
+      expect(probe().result.value.state).toBe("connected");
+    } finally {
+      unmount();
+    }
+  });
+
+  it("a re-check that fails drops into the retry ladder and recovers", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn();
+    fetchMock.mockResolvedValueOnce(okResponse()); // mount: healthy
+    fetchMock.mockRejectedValueOnce(new Error("backend died")); // re-check: dead
+    fetchMock.mockResolvedValueOnce(okResponse()); // ladder retry: back
+    vi.stubGlobal("fetch", fetchMock);
+    const { probe, unmount } = mountProbe();
+    try {
+      await vi.advanceTimersByTimeAsync(0);
+      expect(probe().result.value.state).toBe("connected");
+
+      await vi.advanceTimersByTimeAsync(15_000);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      // The failure is REAL and must show: red, disconnected, ladder
+      // armed (attempt 1 of the retryTotal, countdown to the next try).
+      expect(probe().result.value.connected).toBe(false);
+      expect(probe().result.value.state).toBe("disconnected");
+      expect(probe().result.value.attemptNumber).toBe(1);
+      expect(probe().result.value.countdown).toBeGreaterThan(0);
+
+      // Ladder retry succeeds: green again, and the attempt counter
+      // RESET — a lifetime odometer would read "Retrying N/3" with N
+      // grown by every healthy poll.
+      await vi.advanceTimersByTimeAsync(15_000);
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+      expect(probe().result.value.connected).toBe(true);
+      expect(probe().result.value.state).toBe("connected");
+      expect(probe().result.value.attemptNumber).toBe(0);
+    } finally {
+      unmount();
+    }
+  });
+
+  it("stops observing once unmounted", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn(() => Promise.resolve(okResponse()));
+    vi.stubGlobal("fetch", fetchMock);
+    const { probe, unmount } = mountProbe();
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.advanceTimersByTimeAsync(15_000);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    unmount();
+    await vi.advanceTimersByTimeAsync(45_000);
+    expect(fetchMock, "no polls after unmount").toHaveBeenCalledTimes(2);
+    expect(probe().result.value.state).toBe("connected");
+  });
+
+  it("an in-flight probe settling AFTER unmount arms no zombie loop", async () => {
+    vi.useFakeTimers();
+    const hang = deferredResponse();
+    const fetchMock = vi.fn(() => hang.promise);
+    vi.stubGlobal("fetch", fetchMock);
+    const { probe, unmount } = mountProbe();
+    // The race (R2 catch, 2026-10-11): the mount fetch is still in
+    // flight when the component unmounts; its late SUCCESS used to arm
+    // a fresh 15s slot on a dead component — a poll loop that never
+    // stopped (4+ fetches per 45s, forever). The disposed guard must
+    // swallow the arming; the late state write itself is harmless.
+    unmount();
+    hang.resolve(okResponse());
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(fetchMock, "no post-unmount polls, ever").toHaveBeenCalledTimes(1);
+    expect(probe().result.value.connected, "late write is harmless").toBe(true);
+  });
+});

package/src/composables/useConnectionProbe.ts

@@ -78,23 +78,38 @@ export function useConnectionProbe(): {
   let tickHandle: IntervalHandle | null = null;
   let nextAttemptAt = 0;
   let consecutiveFailures = 0;
+  // Set at unmount, read by schedulePoll: an in-flight probe resolving
+  // AFTER unmount must not arm a fresh slot — that race resurrected a
+  // 15s zombie loop polling forever on a dead component (R2 catch,
+  // 2026-10-11). Late state writes into the dead ref are harmless;
+  // late ARMING is not.
+  let disposed = false;
 
   function applyCountdown(): void {
     const seconds = Math.max(0, Math.ceil((nextAttemptAt - Date.now()) / 1000));
     result.value = { ...result.value, countdown: seconds };
   }
 
-  async function probeOnce(): Promise<void> {
+  async function probeOnce(opts?: { quiet?: boolean }): Promise<void> {
     pollHandle?.disconnect();
     pollHandle = null;
+    const wasConnected = result.value.connected;
+    // Quiet re-checks (the scheduled poll while healthy) keep the light
+    // GREEN through the fetch: flipping every healthy re-check through
+    // "reconnecting" would blink the pill and re-fire the recovery flash
+    // once per interval. A quiet re-check that FAILS falls through to
+    // the ladder below — that transition is real and must show.
+    const quiet = opts?.quiet === true && wasConnected;
     const attempt = result.value.attemptNumber + 1;
-    result.value = {
-      ...result.value,
-      state: result.value.connected ? "reconnecting" : "connecting",
-      attemptNumber: attempt,
-      retryCount: attempt,
-      countdown: 0,
-    };
+    if (!quiet) {
+      result.value = {
+        ...result.value,
+        state: wasConnected ? "reconnecting" : "connecting",
+        attemptNumber: attempt,
+        retryCount: attempt,
+        countdown: 0,
+      };
+    }
     const started = Date.now();
     try {
       const resp = await fetch(endpointUrl(), {
@@ -104,12 +119,26 @@ export function useConnectionProbe(): {
       const latencyMs = Date.now() - started;
       if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
       consecutiveFailures = 0;
+      nextAttemptAt = 0;
       result.value = {
         ...result.value,
         connected: true,
         state: "connected",
         latencyMs,
+        // The attempt counter is LADDER state, not a lifetime odometer:
+        // a healthy probe zeroes it so the next outage's ladder reads
+        // "Retrying 1/3" instead of an ever-growing number. Continuous
+        // polling made this matter — the counter used to stop moving
+        // once connected, so the creep was invisible.
+        attemptNumber: 0,
+        retryCount: 0,
+        countdown: 0,
       };
+      // Continuous observation (2026-10-11 auth-surface report): the
+      // light must FOLLOW the backend, not just record the initial
+      // verdict. Parked-forever-on-success meant a backend dying later
+      // left a permanently green light on sessionless surfaces.
+      schedulePoll(true);
     } catch {
       consecutiveFailures += 1;
       const failed = consecutiveFailures >= result.value.retryTotal;
@@ -118,6 +147,8 @@ export function useConnectionProbe(): {
         connected: false,
         state: failed ? "failed" : "disconnected",
         latencyMs: null,
+        attemptNumber: attempt,
+        retryCount: attempt,
       };
       nextAttemptAt = Date.now() + DEFAULT_POLL_MS;
       applyCountdown();
@@ -125,15 +156,21 @@ export function useConnectionProbe(): {
     }
   }
 
-  function schedulePoll(): void {
-    // Visibility-aware one-shot: the 15s retry window holds while the
-    // page is hidden instead of burning down on a throttled background
-    // timer (intervalBus — this is its designed case: data polling, not
-    // animation).
+  function schedulePoll(quiet = false): void {
+    // The zombie guard: an in-flight probe settling after unmount lands
+    // here with nothing left to serve — arming would loop forever on a
+    // dead component. Both call sites (success re-check AND the failure
+    // ladder) route through this single gate.
+    if (disposed) return;
+    // Visibility-aware one-shot: the 15s window holds while the page is
+    // hidden instead of burning down on a throttled background timer
+    // (intervalBus — this is its designed case: data polling, not
+    // animation). Retry-ladder hops stay loud; the success-path
+    // re-check passes `quiet` so a healthy poll never blinks the light.
     pollHandle?.disconnect();
     pollHandle = scheduleIntervalAfter(() => {
       pollHandle = null;
-      void probeOnce();
+      void probeOnce({ quiet });
     }, DEFAULT_POLL_MS);
   }
 
@@ -151,6 +188,9 @@ export function useConnectionProbe(): {
   onUnmounted(() => {
     liveProbes = Math.max(0, liveProbes - 1);
     probeRuntime?.pulse({ liveProbes });
+    // Disarm FIRST: an in-flight probe's late success must find the
+    // guard already up when it reaches schedulePoll.
+    disposed = true;
     pollHandle?.disconnect();
     pollHandle = null;
     tickHandle?.disconnect();

package/src/composables/useEngineHealth.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, type Ref } from "vue";
+
+import { useEngineHealth, type EngineHealth } from "./useEngineHealth";
+
+/** useEngineHealth is mount-scoped (onMounted drives the first fetch);
+ *  each test rides a minimal component harness. Fake timers own the
+ *  30s refresh loop. */
+
+interface Deferred {
+  promise: Promise<Response>;
+  resolve: (r: Response) => void;
+}
+
+function deferredJsonResponse(): Deferred {
+  let resolve!: (r: Response) => void;
+  const promise = new Promise<Response>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function okBody(body: Record<string, unknown>): Response {
+  return { ok: true, json: () => Promise.resolve(body) } as unknown as Response;
+}
+
+function mountHealth() {
+  let out!: {
+    health: Ref<EngineHealth | null>;
+    loading: Ref<boolean>;
+    error: Ref<string | null>;
+    refresh: () => Promise<void>;
+  };
+  const app = createApp(
+    defineComponent({
+      setup() {
+        out = useEngineHealth();
+        return () => h("div");
+      },
+    }),
+  );
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  app.mount(container);
+  return {
+    api: () => out,
+    unmount: () => {
+      app.unmount();
+      container.remove();
+    },
+  };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+describe("useEngineHealth refresh loop", () => {
+  it("recovers the engine row after a transient mount-time failure", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn();
+    fetchMock.mockRejectedValueOnce(new Error("transient")); // mount: fails
+    fetchMock.mockResolvedValueOnce(okBody({ engine_version: "9.8.7", build_hash: "abc1234" }));
+    vi.stubGlobal("fetch", fetchMock);
+    const { api, unmount } = mountHealth();
+    try {
+      await vi.advanceTimersByTimeAsync(0);
+      expect(api().health.value, "mount-time failure blanks the row").toBeNull();
+      expect(api().error.value).toBeTruthy();
+
+      // The one-shot era left this row dead for the page's whole life;
+      // the 30s loop revives it (2026-10-11 auth-surface report).
+      await vi.advanceTimersByTimeAsync(30_000);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(api().health.value?.engineVersion).toBe("9.8.7");
+      expect(api().health.value?.engineBuildHash).toBe("abc1234");
+      expect(api().error.value).toBeNull();
+    } finally {
+      unmount();
+    }
+  });
+
+  it("keeps the row fresh on cadence and stops on unmount", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn(() => Promise.resolve(okBody({ engine_version: "1.0.0" })));
+    vi.stubGlobal("fetch", fetchMock);
+    const { unmount } = mountHealth();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(fetchMock, "cadence refresh fires").toHaveBeenCalledTimes(2);
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    unmount();
+    await vi.advanceTimersByTimeAsync(90_000);
+    expect(fetchMock, "no refreshes after unmount").toHaveBeenCalledTimes(3);
+  });
+
+  it("never stacks requests — a slow refresh skips the next beat", async () => {
+    vi.useFakeTimers();
+    const slow = deferredJsonResponse();
+    const fetchMock = vi.fn();
+    fetchMock.mockResolvedValueOnce(okBody({ engine_version: "1.0.0" })); // mount
+    fetchMock.mockImplementationOnce(() => slow.promise); // t+30s: hangs
+    vi.stubGlobal("fetch", fetchMock);
+    const { api, unmount } = mountHealth();
+    try {
+      await vi.advanceTimersByTimeAsync(0);
+      await vi.advanceTimersByTimeAsync(30_000);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(api().loading.value).toBe(true);
+
+      // The t+60s beat arrives while the t+30s refresh still hangs — it
+      // must be skipped, not stacked.
+      await vi.advanceTimersByTimeAsync(30_000);
+      expect(fetchMock, "in-flight refresh holds the beat").toHaveBeenCalledTimes(2);
+
+      slow.resolve(okBody({ engine_version: "2.0.0" }));
+      await vi.advanceTimersByTimeAsync(0);
+      expect(api().loading.value).toBe(false);
+      expect(api().health.value?.engineVersion).toBe("2.0.0");
+    } finally {
+      unmount();
+    }
+  });
+});

package/src/composables/useEngineHealth.ts

@@ -1,4 +1,6 @@
-import { onMounted, ref, type Ref } from "vue";
+import { onMounted, onUnmounted, ref, type Ref } from "vue";
+
+import { scheduleInterval, type IntervalHandle } from "../runtime/intervalBus";
 
 /** Inlined subset of the `/api/health` network payload — kept local so
  *  hikari stays dependency-free of protocol packages. */
@@ -24,9 +26,18 @@ export interface EngineHealth {
   network: NetworkInfo | null;
 }
 
+/** Mounted refresh cadence (visibility-aware via the interval bus — a
+ * hidden tab parks instead of burning radio). 30s: engine identity is
+ * not latency-critical, but a transient mount-time failure must not
+ * blank the engine row for the page's whole life (2026-10-11
+ * auth-surface report — the one-shot fetch left a dead row forever). */
+const REFRESH_MS = 30_000;
+
 /**
- * Fetch `/api/health` once on mount and expose the engine/network subset.
- * Replaces per-app hand-rolled health fetches. Call `refresh()` to re-poll.
+ * Fetch `/api/health` on mount and keep it fresh on a visibility-aware
+ * 30s loop; expose the engine/network subset. Replaces per-app
+ * hand-rolled health fetches. Call `refresh()` to force an immediate
+ * re-poll outside the cadence.
  *
  * @param baseUrl Optional API origin (defaults to same-origin "").
  */
@@ -39,6 +50,7 @@ export function useEngineHealth(baseUrl?: string): {
   const health = ref<EngineHealth | null>(null);
   const loading = ref(false);
   const error = ref<string | null>(null);
+  let tickHandle: IntervalHandle | null = null;
 
   async function refresh(): Promise<void> {
     loading.value = true;
@@ -63,7 +75,19 @@ export function useEngineHealth(baseUrl?: string): {
     }
   }
 
-  onMounted(() => { void refresh(); });
+  onMounted(() => {
+    void refresh();
+    tickHandle = scheduleInterval(() => {
+      // Never stack requests on a slow endpoint — skip the beat while a
+      // refresh is still in flight.
+      if (!loading.value) void refresh();
+    }, REFRESH_MS);
+  });
+
+  onUnmounted(() => {
+    tickHandle?.disconnect();
+    tickHandle = null;
+  });
 
   return { health, loading, error, refresh };
 }