@celestia-island/hikari 0.55.145 → 0.55.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.145",
+  "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/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 };
 }