@celestia-island/hikari 0.55.158 → 0.55.159

package/package.json

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

package/src/components/HkInfiniteTail.tsx

@@ -25,11 +25,14 @@ import "./HkInfiniteTail.scss";
  * - `"idle"` — more exists, nothing in flight. With `auto` (default)
  *   the invisible sentinel watches the viewport and emits `loadMore`
  *   as it approaches; with `auto={false}` the explicit load-more
- *   button (HkLoadMore) renders instead. NOTE: with `auto`, a tail
- *   page failure retries in place every time the sentinel re-enters
- *   view (the machine's error guard paces it to one attempt per
- *   emission, no backoff) — hosts that want backoff map the error
- *   state away from `"idle"` themselves.
+ *   button (HkLoadMore) renders instead. NOTE: a failed page
+ *   terminalizes the machine's walk — the tail keeps emitting
+ *   `loadMore` as the sentinel re-enters view, but each emission is a
+ *   no-op until the host calls `reload()` (the retry verb; the
+ *   delivered rows stay on screen under the host's stale banner).
+ *   Auto-retrying from the tail is deliberately not supported: the
+ *   sentinel would re-fire on a fixed geometry with no backoff, one
+ *   RPC per round trip, which locks a shared rate budget.
  *
  * The sentinel observes the BROWSER viewport (IntersectionObserver,
  * `rootMargin` lookahead), so it works inside any nested scroll

package/src/composables/useInfinitePages.test.ts

@@ -114,7 +114,7 @@ describe("useInfinitePages", () => {
     expect(handle.exhausted.value).toBe(true);
   });
 
-  it("a failed later page keeps the delivered rows and retries in place", async () => {
+  it("a failed later page keeps the delivered rows and terminalizes the walk", async () => {
     const fetcher = vi
       .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
       .mockImplementationOnce(async () => page([{ id: "a" }], 3, true))
@@ -127,10 +127,36 @@ describe("useInfinitePages", () => {
     await handle.loadMore();
     expect(handle.error.value).toBe("boom");
     expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
-    // The tail failure is retriable without a full reload.
+    // A tail failure does NOT auto-retry: the sentinel's idle re-check
+    // would re-fire loadMore on a fixed geometry with no backoff — one
+    // RPC per round trip forever, locking any shared rate budget. The
+    // failure is terminal until `reload`.
     await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
+    // `reload` is the retry verb: it clears the failure and refetches
+    // from page one.
+    await handle.reload();
     expect(handle.error.value).toBeNull();
-    expect(handle.items.value.map((r) => r.id)).toEqual(["a", "b", "c"]);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["b", "c"]);
+  });
+
+  it("a tail failure cannot storm: repeated loadMore stays a no-op", async () => {
+    const fetcher = vi
+      .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
+      .mockImplementationOnce(async () => page([{ id: "a" }], 5, true))
+      .mockImplementation(async () => {
+        throw new Error("tail down");
+      });
+    const { handle } = withHandle(() => useInfinitePages<Row>({ fetcher, pageSize: 1 }));
+    await vi.waitFor(() => expect(handle.loading.value).toBe(false));
+    await handle.loadMore();
+    expect(handle.error.value).toBe("tail down");
+    // Ten idle-entry re-checks (the tail sentinel's emission pattern)
+    // spend ZERO further RPCs.
+    for (let i = 0; i < 10; i++) await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
   });
 
   it("a param change triggers a debounced reload from page one", async () => {

package/src/composables/useInfinitePages.ts

@@ -83,9 +83,9 @@ export interface InfinitePagesHandle<T> {
   error: Ref<string | null>;
   /** One-based index of the next page to fetch. */
   nextPage: Ref<number>;
-  /** Fetch the next page (guarded: no-op while busy or exhausted).
-   * A TAIL-page failure stays retriable in place — the next `loadMore`
-   * refetches the same page; only a page-one failure needs `reload`. */
+  /** Fetch the next page (guarded: no-op while busy, exhausted, or
+   * after ANY failure — `reload` is the retry verb for both the
+   * first-page and the tail-page error dialects). */
   loadMore: () => Promise<void>;
   /** Reset to page one and fetch (also the error-clearing retry). */
   reload: () => Promise<void>;
@@ -101,7 +101,11 @@ export interface InfinitePagesHandle<T> {
  *
  * Error dialect: a failed page keeps everything already delivered (the
  * consumer renders it as a stale banner — one failed fetch must never
- * hide rows the user was reading); `reload` is the retry verb.
+ * hide rows the user was reading) and terminalizes the walk; `reload`
+ * is the retry verb for every failure. Auto-retrying a tail failure is
+ * deliberately NOT done: the tail's sentinel would re-fire on a fixed
+ * geometry with no backoff, turning one flaky page into an RPC storm
+ * that locks a shared rate budget.
  */
 export function useInfinitePages<T, P extends Record<string, unknown> = Record<string, unknown>>(
   options: InfinitePagesOptions<T, P>,
@@ -123,9 +127,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   let seq = 0;
   let reloadTimer: ReturnType<typeof setTimeout> | null = null;
   let disposed = false;
-  /** Which phase the current `error` came from — a tail-page failure
-   * retried by `loadMore` in place, a first-page failure by `reload`. */
-  let errorPhase: "load" | "more" = "load";
 
   function normalize(result: HkPageResultLike<T>): HkPageResult<T> {
     const loose = result as {
@@ -196,14 +197,20 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   }
 
   async function loadMore(): Promise<void> {
-    // A failure from a LATER page is retriable in place (the delivered
-    // rows stay, the cursor stays); a failure from page one needs a
-    // full reload (the retry verb for the hard-error state).
+    // ANY failure terminalizes the walk until `reload()` — including a
+    // tail-page failure. The in-place retry this used to allow read
+    // fine in isolation but stormed in the field: a failed tail leaves
+    // the state machine "idle", the tail's sentinel stays in view, and
+    // its idle-entry re-check fires loadMore again with no geometry
+    // change — one RPC per round trip, no backoff, forever. On a shared
+    // per-user rate budget that loop locks the bucket and denies every
+    // OTHER paged page, so the retry verb is `reload()` (the delivered
+    // rows stay on screen under the stale banner; the header refresh is
+    // the user's affordance).
     if (loading.value || loadingMore.value || exhausted.value) return;
-    if (error.value && errorPhase !== "more") return;
+    if (error.value) return;
     if (nextPage.value > 1 && items.value.length === 0) return;
     loadingMore.value = true;
-    errorPhase = "more";
     const mine = ++seq;
     try {
       await fetchPage(nextPage.value, mine);
@@ -225,7 +232,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
       reloadTimer = null;
     }
     loading.value = true;
-    errorPhase = "load";
     error.value = null;
     if (!options.keepDuringReload) {
       // Invalidate the cursor BEFORE the fetch so a straggler from the