@celestia-island/hikari 0.55.145 → 0.55.147

package/package.json

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

package/src/components/HkBoard.nodeActions.test.tsx

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkBoard, { type BoardNodeInput } from "./HkBoard";
+
+/** Pointer event the suite can dispatch (happy-dom has PointerEvent). */
+function pointerEvent(type: string, x: number, y: number): Event {
+  const Ctor = (globalThis as { PointerEvent?: typeof MouseEvent }).PointerEvent ?? MouseEvent;
+  const ev = new Ctor(type, { bubbles: true, cancelable: true, clientX: x, clientY: y });
+  (ev as { pointerId?: number }).pointerId = 1;
+  return ev;
+}
+
+const nodes: BoardNodeInput[] = [
+  { id: "a", x: 0, y: 0, w: 100, h: 60, draggable: true, label: "A" },
+  { id: "b", x: 160, y: 0, w: 100, h: 60, draggable: true, label: "B" },
+];
+
+/** Mounts the board with the given slots, the repo's own way (no
+ * @vue/test-utils in this package): a throwaway app on document.body. */
+function mountBoard(slots: Record<string, () => unknown> = {}, onNodeMove?: () => void): unknown {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  // (defineComponent(fn) treats fn as a FUNCTIONAL component — the wrapper
+  // needs the explicit setup form to hand HkBoard its slots.)
+  const wrapper = defineComponent({
+    setup: () => () => h(HkBoard, { nodes, onNodeMove }, slots),
+  });
+  const app = createApp(wrapper);
+  app.mount(host);
+  return app;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("HkBoard nodeActions slot", () => {
+  it("renders the slot per node, docked inside the node shell", () => {
+    mountBoard({
+      nodeActions: () => [
+        h("button", { "data-test": "act" }, "act"),
+      ],
+    });
+    const docks = [...document.body.querySelectorAll<HTMLElement>(".hk-board-node-actions")];
+    expect(docks).toHaveLength(2);
+    expect(docks[0].querySelector("[data-test=act]")).toBeTruthy();
+    expect(docks[1].querySelector("[data-test=act]")).toBeTruthy();
+    // The dock lives INSIDE the node shell (the SCSS anchors it to the
+    // node's bottom-end corner — pinned by the source contract below).
+    expect(docks[0].closest(".hk-board-node")).toBeTruthy();
+    expect(docks[0].parentElement!.classList.contains("hk-board-node")).toBe(true);
+  });
+
+  it("renders nothing when the slot is absent", () => {
+    mountBoard();
+    expect(document.body.querySelector(".hk-board-node-actions")).toBeNull();
+  });
+
+  it("keeps a press that starts on a dock action from becoming a node drag", () => {
+    // The board captures the pointer on its own root for draggable nodes;
+    // a dock press must not enter that gesture (upstream HkMinimap guards
+    // its zoom chrome the same way). happy-dom cannot emulate capture, so
+    // the observable contract here is the DRAG: a pointer that travels
+    // after starting on the dock leaves the node where it was.
+    const onNodeMove = vi.fn();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const app = mountBoard(
+      { nodeActions: () => [h("button", { "data-test": "act" }, "act")] },
+      onNodeMove,
+    ) as { unmount: () => void };
+
+    const dock = document.body.querySelector<HTMLElement>(".hk-board-node-actions")!;
+    const shell = dock.closest(".hk-board-node") as HTMLElement;
+    const before = shell.style.left;
+    dock.dispatchEvent(pointerEvent("pointerdown", 90, 50));
+    shell.dispatchEvent(pointerEvent("pointermove", 400, 50));
+    shell.dispatchEvent(pointerEvent("pointerup", 400, 50));
+    expect(shell.style.left).toBe(before);
+    expect(onNodeMove).not.toHaveBeenCalled();
+    app.unmount();
+  });
+});
+
+/** Source contract for the dock's load-bearing rules (vitest cannot see
+ * stylesheets — a deleted rule leaves every DOM guard green). */
+const boardScss = (await import("node:fs")).readFileSync(
+  (await import("node:path")).resolve(__dirname, "./HkBoard.scss"),
+  "utf8",
+);
+
+describe("HkBoard nodeActions dock styles", () => {
+  it("docks the actions to the node's bottom-end corner above the body", () => {
+    const block = boardScss.slice(boardScss.indexOf("&-actions {"));
+    expect(block.slice(0, 400)).toMatch(/position:\s*absolute/);
+    expect(block.slice(0, 400)).toMatch(/inset-inline-end/);
+    expect(block.slice(0, 400)).toMatch(/bottom:/);
+    expect(block.slice(0, 400)).toMatch(/z-index/);
+  });
+});

package/src/components/HkBoard.scss

@@ -44,6 +44,21 @@
   position: absolute;
   box-sizing: border-box;
 
+  // Per-node action dock (the `nodeActions` slot): consumer-injected
+  // controls ride the node's bottom-end corner above the body, so hosts
+  // stop hand-drawing their own buttons into the node slot. The dock owns
+  // its own capture-safety (see HkBoard.tsx) — a press that starts here
+  // never becomes a node drag.
+  &-actions {
+    position: absolute;
+    inset-inline-end: var(--hk-board-node-action-inset, 4px);
+    bottom: var(--hk-board-node-action-inset, 4px);
+    z-index: 6;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+  }
+
   &--draggable {
     cursor: grab;
 

package/src/components/HkBoard.tsx

@@ -453,6 +453,26 @@ export default defineComponent({
               {slots.node
                 ? slots.node({ node: n })
                 : <div class="hk-board-node-shell">{n.label ?? ""}</div>}
+              {slots.nodeActions
+                ? (
+                  <div
+                    class="hk-board-node-actions"
+                    // A press that starts on an action belongs to that
+                    // action: this component captures the pointer on its own
+                    // root for every draggable node, and a captured press
+                    // retargets the following events to the ancestor — an
+                    // action button's own click would never fire. Stopping
+                    // the bubble here is the same guard HkMinimap puts on
+                    // its zoom chrome. The keydown twin keeps a focused
+                    // action's Enter/Space from reaching the node's own key
+                    // handling.
+                    onPointerdown={(e: PointerEvent) => e.stopPropagation()}
+                    onKeydown={(e: KeyboardEvent) => e.stopPropagation()}
+                  >
+                    {slots.nodeActions({ node: n })}
+                  </div>
+                )
+                : null}
             </div>
           ))}
         </div>

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 };
 }