gloomberb 0.14.0 → 0.15.0

package/src/plugins/builtin/risk-factors/pane.tsx

@@ -3,10 +3,13 @@ import type {
   CloudRiskNotePayload,
 } from "../../../api-client";
 import {
-  EmptyState, PaneStatusBody, Prose, SectionHeading, Spinner,
+  EmptyState, PaneStatusBody, Prose, QueryBar, SectionHeading, Spinner, StatGrid,
   Tabs,
   usePaneFooter,
-  type PaneFooterSegment
+  usePaneHeaderTabs,
+  type PaneFooterSegment,
+  type PaneHint,
+  type QueryBarFilter,
 } from "../../../components";
 import { useShortcut } from "../../../react/input";
 import { useAsyncResource } from "../../../react/async-resource";
@@ -20,6 +23,7 @@ import {
   type ScrollBoxRenderable,
 } from "../../../ui";
 import { isPlainKey } from "../../../utils/keyboard";
+import { usePluginPaneState } from "../../runtime";
 import { useBoundTicker } from "../shared/ticker-request";
 import { discardRiskData, loadRiskReport, loadRiskReports } from "./data";
 
@@ -71,26 +75,36 @@ function RiskLine({
   );
 }
 
+export function RiskFactorsResearchTab(props: { focused: boolean; width: number; height: number }) {
+  return <RiskFactorsPane {...props} nested />;
+}
+
 export function RiskFactorsPane({
   focused,
   width,
+  nested = false,
 }: {
   focused: boolean;
   width: number;
   height: number;
+  /** Inside Ticker Research, whose own tab strip keeps h/l and the arrows. */
+  nested?: boolean;
 }) {
   const { symbol } = useBoundTicker();
   const ticker = symbol ? symbol.toUpperCase() : null;
   const nativePaneChrome = useUiCapabilities().nativePaneChrome === true;
   const rendererHost = useRendererHost();
 
-  const [selection, setSelection] = useState<{ ticker: string | null; year: number | null }>({ ticker: null, year: null });
+  // The year is remembered with the pane; the ticker it was chosen on is the
+  // one the pane opened with, so a restored year applies to it.
+  const [selectedYear, setSelectedYear] = usePluginPaneState<number | null>("filingYear", null);
+  const [selectedTicker, setSelectedTicker] = useState<string | null>(ticker);
   const listLoader = useCallback((force: boolean) => loadRiskReports(ticker!, { force }), [ticker]);
   const list = useAsyncResource(ticker ? listLoader : null, { clearOnError: discardRiskData });
   const years = useMemo(() => [...(list.data?.reports ?? [])].sort((a, b) => b.reportYear - a.reportYear), [list.data]);
   // Null follows the newest discovered filing; an explicit choice stays on that year.
-  const year = selection.ticker === ticker && selection.year !== null
-    ? selection.year : years[0]?.reportYear ?? null;
+  const year = selectedTicker === ticker && selectedYear !== null
+    ? selectedYear : years[0]?.reportYear ?? null;
   const reportLoader = useCallback((force: boolean) => loadRiskReport(ticker!, year!, { force }), [ticker, year]);
   const detail = useAsyncResource(ticker && year !== null ? reportLoader : null, { clearOnError: discardRiskData });
   const report = detail.data;
@@ -110,6 +124,13 @@ export function RiskFactorsPane({
     if (report?.docUrl) void rendererHost.openExternal(report.docUrl);
   }, [rendererHost, report]);
 
+  const nextYear = useCallback(() => {
+    if (years.length < 2) return;
+    const index = years.findIndex((entry) => entry.reportYear === year);
+    setSelectedTicker(ticker);
+    setSelectedYear(years[(index + 1) % years.length]!.reportYear);
+  }, [setSelectedYear, ticker, year, years]);
+
   const scrollBy = useCallback((delta: number) => {
     const scrollBox = scrollRef.current;
     if (!scrollBox?.viewport) return;
@@ -123,9 +144,19 @@ export function RiskFactorsPane({
   useShortcut(
     (event) => {
       if (isPlainKey(event, "r")) refresh();
-      else if (isPlainKey(event, "o")) openFiling();
-      else if (isPlainKey(event, "j", "down")) scrollBy(1);
-      else if (isPlainKey(event, "k", "up")) scrollBy(-1);
+      else if (isPlainKey(event, "o")) {
+        event.preventDefault();
+        openFiling();
+      }
+      // One line per press; marked handled so the pane scroll keys, which
+      // page this report, do not scroll it again.
+      else if (isPlainKey(event, "j", "down")) {
+        event.preventDefault();
+        scrollBy(1);
+      } else if (isPlainKey(event, "k", "up")) {
+        event.preventDefault();
+        scrollBy(-1);
+      }
     },
     { enabled: focused, scope: "risk-factors" },
   );
@@ -142,14 +173,40 @@ export function RiskFactorsPane({
     if ((reportError || report?.stale) && report) {
       info.push({ id: "report-stale", parts: [{ text: `Report cached ${new Date(report.fetchedAt).toISOString()}`, tone: "muted" }] });
     }
-    const hints = report?.docUrl
+    const hints: PaneHint[] = report?.docUrl
       ? [{ id: "open", key: "o", label: "pen filing", onPress: openFiling }]
       : [];
+    // The year strip answers h/l only where it is the pane's own strip; `y`
+    // steps it everywhere, including under Ticker Research's strip.
+    if (ticker && years.length > 1) hints.push({ id: "year", key: "y", label: "ear", onPress: nextYear });
     return { info, hints };
-  }, [list.loading, detail.loading, listError, reportError, list.data, report, year, openFiling]);
+  }, [list.loading, detail.loading, listError, reportError, list.data, report, year, openFiling, ticker, years.length, nextYear]);
 
   const bodyWidth = Math.max(12, width - 2);
   const proseWidth = Math.min(bodyWidth, MAX_PROSE_WIDTH);
+  const yearTabs = useMemo(() => years.map((entry) => ({
+    label: `${entry.reportYear} 10-K`,
+    value: String(entry.reportYear),
+  })), [years]);
+  const selectYear = (value: string) => { setSelectedTicker(ticker); setSelectedYear(Number(value)); };
+  const tabsInHeader = usePaneHeaderTabs(years.length > 1 ? {
+    tabs: yearTabs,
+    activeValue: year === null ? "" : String(year),
+    onSelect: selectYear,
+    focused,
+  } : null);
+
+  // Nested in Ticker Research the years stay in the body: the terminal keeps
+  // its tab row, the desktop picks the year from the query bar.
+  const yearStrip = years.length > 1 && !tabsInHeader;
+  const yearFilters: QueryBarFilter[] = yearStrip && nativePaneChrome ? [{
+    id: "year",
+    label: "10-K",
+    inline: years.length <= 4,
+    value: year === null ? "" : String(year),
+    options: years.map((entry) => ({ label: String(entry.reportYear), value: String(entry.reportYear) })),
+    onChange: selectYear,
+  }] : [];
 
   if (!ticker) return <EmptyState title="Pick a ticker to see its risk factors." />;
   if (!list.data && list.loading) return <PaneStatusBody loading align="center" loadingLabel="Loading risk factors..." />;
@@ -157,16 +214,15 @@ export function RiskFactorsPane({
   if (year === null) return <EmptyState title={`No 10-K risk factors on file for ${ticker}.`} />;
 
   const diff = report?.diff ?? null;
-  const summaryLine = report
+  // A choice of years names the year in the tabs or the filter; a single
+  // report says which one it is here.
+  const meta = report
     ? [
-        `${report.reportYear} 10-K`,
+        years.length > 1 ? null : `${report.reportYear} 10-K`,
         `Filed ${report.filedAt?.slice(0, 10) || "unavailable"}`,
-        `Report updated ${report.updatedAt?.slice(0, 10) || "unavailable"}`,
-        `${report.riskCount} risks in ${report.groupCount} groups`,
-        diff
-          ? `${diff.added.length} new, ${diff.removed.length} dropped, ${diff.reworded.length} reworded vs prior year`
-          : "no prior year on file",
-      ].join("  ·  ")
+        `updated ${report.updatedAt?.slice(0, 10) || "unavailable"}`,
+        diff ? null : "no prior year on file",
+      ].filter(Boolean).join(" · ")
     : "";
 
   return (
@@ -178,27 +234,34 @@ export function RiskFactorsPane({
       minHeight={0}
       overflow="hidden"
     >
-      {years.length > 1 && (
+      {yearStrip && !nativePaneChrome && (
         <Box height={1} flexShrink={0} paddingX={1} overflow="hidden">
           <Tabs
-            tabs={years.map((entry) => ({
-              label: `${entry.reportYear} 10-K`,
-              value: String(entry.reportYear),
-            }))}
+            tabs={yearTabs}
             activeValue={year === null ? "" : String(year)}
-            onSelect={(value) => setSelection({ ticker, year: Number(value) })}
+            onSelect={selectYear}
             compact
             variant="bare"
             focused={focused}
+            keyboardNavigation={!nested}
           />
         </Box>
       )}
+      {(yearFilters.length > 0 || meta) && <QueryBar width={width} filters={yearFilters} meta={meta || undefined} />}
+      {report && diff ? (
+        <StatGrid width={width} items={[
+          { id: "new", label: "New", value: String(diff.added.length) },
+          { id: "dropped", label: "Dropped", value: String(diff.removed.length) },
+          { id: "reworded", label: "Reworded", value: String(diff.reworded.length) },
+        ]} />
+      ) : null}
       <ScrollBox
         ref={scrollRef}
         flexGrow={1}
         flexShrink={1}
         flexBasis={0}
         minHeight={0}
+        scrollY
         paddingX={1}
       >
         {report ? (
@@ -206,14 +269,9 @@ export function RiskFactorsPane({
             flexDirection="column"
             width={nativePaneChrome ? "100%" : bodyWidth}
           >
-            <Prose
-              text={summaryLine}
-              width={proseWidth}
-              color={colors.textDim}
-            />
             {report.overview ? (
               <Box flexDirection="column">
-                <SectionHeading marginTop={1}
+                <SectionHeading
                   title={diff ? "WHAT THE CHANGES SAY" : "WHAT DOMINATES"}
                 />
                 {report.overview.split("\n").map((point) => (
@@ -229,7 +287,7 @@ export function RiskFactorsPane({
             ) : null}
             {diff ? (
               <Box flexDirection="column">
-                <SectionHeading marginTop={1} title="WHAT CHANGED" />
+                <SectionHeading marginTop={report.overview ? 1 : 0} title="WHAT CHANGED" />
                 {diff.added.length === 0 &&
                 diff.removed.length === 0 &&
                 diff.reworded.length === 0 ? (
@@ -272,7 +330,7 @@ export function RiskFactorsPane({
               </Box>
             ) : report.notes.top.length > 0 ? (
               <Box flexDirection="column">
-                <SectionHeading marginTop={1} title="MOST SPECIFIC TO THE COMPANY" />
+                <SectionHeading marginTop={report.overview ? 1 : 0} title="MOST SPECIFIC TO THE COMPANY" />
                 {report.notes.top.map((note) => (
                   <RiskLine
                     key={`top-${note.index}`}
@@ -286,7 +344,7 @@ export function RiskFactorsPane({
               </Box>
             ) : null}
             <Box flexDirection="column">
-              <SectionHeading marginTop={1} title={`ALL ${report.riskCount} RISK FACTORS`} />
+              <SectionHeading marginTop={1} title="ALL RISK FACTORS" />
               {report.risks.map((risk, index) => (
                 <Prose
                   key={`${index}-${risk.heading}`}

package/src/plugins/builtin/scanner/denied.tsx

@@ -1,6 +1,5 @@
-import { Button, EmptyState } from "../../../components";
+import { Button, PaneStatusBody } from "../../../components";
 import { t } from "../../../i18n";
-import { Box } from "../../../ui";
 import { SignInWall } from "../cloud/auth-actions";
 import { useCloudPlanAction, useCloudUpgradeAction } from "../shared/cloud-upgrade";
 
@@ -16,16 +15,16 @@ export function ScannerDeniedState({ reason }: { reason: string | null }) {
     return <SignInWall action="stream the market scanners" />;
   }
 
+  // The status body carries the pane inset that a bare EmptyState lacks.
   return (
-    <Box flexDirection="column" paddingX={1} paddingY={1}>
-      <EmptyState
-        title="Options flow is part of Gloom Cloud Pro."
-        message="Live sweeps, blocks, and large premium prints from the full OPRA feed."
-        actions={<>
-          <Button label={t("Upgrade to Pro")} onPress={openUpgrade} />
-          <Button label={t("Manage account")} variant="secondary" onPress={openPlan} />
-        </>}
-      />
-    </Box>
+    <PaneStatusBody
+      empty
+      emptyTitle="Options flow is part of Gloom Cloud Pro."
+      emptyMessage="Real-time sweeps, blocks and large premium prints across US options exchanges."
+      actions={<>
+        <Button label={t("Upgrade to Pro")} onPress={openUpgrade} />
+        <Button label={t("Manage account")} variant="secondary" onPress={openPlan} />
+      </>}
+    />
   );
 }

package/src/plugins/builtin/scanner/feed.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { apiClient } from "../../../api-client";
 import type {
   ScannerFlowPayload,
@@ -10,6 +10,7 @@ import { tf } from "../../../i18n";
 import { useCloudAccessFooter } from "../shared/cloud-upgrade";
 import { usePaneStatusFooter } from "../shared/pane-footer";
 import { CLOUD_QUOTE_DELAY_MINUTES } from "../shared/plan-access";
+import { useAppVisible } from "../../../state/app/activity";
 
 export interface ScannerFeedState<T extends ScannerPayload> {
   payload: T | null;
@@ -22,15 +23,23 @@ const INITIAL_STATE = { payload: null, denied: false, deniedReason: null } as co
 
 function useScannerFeed<T extends ScannerPayload>(scanner: "hilo" | "flow"): ScannerFeedState<T> {
   const [state, setState] = useState<ScannerFeedState<T>>(INITIAL_STATE);
+  // A hidden app drops the subscription like every other stream; the last
+  // payload stays on screen until the server resends on return.
+  const appVisible = useAppVisible();
+  const subscribedScannerRef = useRef(scanner);
 
   useEffect(() => {
-    setState(INITIAL_STATE);
+    if (subscribedScannerRef.current !== scanner) {
+      subscribedScannerRef.current = scanner;
+      setState(INITIAL_STATE);
+    }
+    if (!appVisible) return;
     return apiClient.subscribeScanner(scanner, (event) => {
       setState(event.type === "denied"
         ? { payload: null, denied: true, deniedReason: event.reason }
         : { payload: event.payload as unknown as T, denied: false, deniedReason: null });
     });
-  }, [scanner]);
+  }, [appVisible, scanner]);
 
   return state;
 }
@@ -53,6 +62,7 @@ export function useScannerStatusFooter(
   registrationId: string,
   state: ScannerFeedState<ScannerPayload>,
   focused: boolean,
+  extra: PaneFooterSegment | null = null,
 ): void {
   const { hint: upgradeHint, segment } = useCloudAccessFooter({
     delayLabel: tf("{count}m", { count: state.payload?.delayMinutes || CLOUD_QUOTE_DELAY_MINUTES }),
@@ -73,9 +83,8 @@ export function useScannerStatusFooter(
       }];
     }
     const status = state.payload?.status;
-    if (!status || status === "starting") {
-      return [{ id: "scanner-status", parts: [{ text: "connecting", tone: "muted" as const }] }];
-    }
+    // The feed connects in the background; nothing to report until it answers.
+    if (!status || status === "starting") return [];
     if (status === "live") {
       return [{ id: "scanner-status", parts: [{ text: "live", tone: "positive" as const }] }];
     }
@@ -85,9 +94,16 @@ export function useScannerStatusFooter(
     return [{ id: "scanner-status", parts: [{ text: "degraded", tone: "warning" as const }] }];
   }, [state.denied, state.deniedReason, state.payload?.status]);
 
-  const info = useMemo(
-    () => (segment ? [segment, ...status] : status),
-    [segment, status],
+  // The upgrade segment carries the delay for free accounts; a delayed feed reaching Pro still says so.
+  const delayMinutes = state.payload?.access === "delayed" ? state.payload.delayMinutes || CLOUD_QUOTE_DELAY_MINUTES : null;
+  const info = useMemo<PaneFooterSegment[]>(
+    () => {
+      const base = segment ? [segment, ...status]
+        : delayMinutes != null ? [{ id: "scanner-delay", parts: [{ text: tf("{delay} delayed", { delay: tf("{count}m", { count: delayMinutes }) }), tone: "muted" as const }] }, ...status]
+          : status;
+      return extra ? [...base, extra] : base;
+    },
+    [delayMinutes, extra, segment, status],
   );
 
   usePaneStatusFooter({ registrationId, info, hints: upgradeHint ? [upgradeHint] : undefined });

package/src/plugins/builtin/scanner/flow-history.test.tsx

@@ -0,0 +1,138 @@
+import { afterEach, expect, test } from "bun:test";
+import { act, useState } from "react";
+import type { ScannerFlowEvent, ScannerFlowHistoryPage, ScannerFlowHistoryQuery } from "../../../api-client";
+import { testRender } from "../../../renderers/opentui/test-utils";
+import { nextFlowCursor, useFlowHistory, type FlowHistoryLoader } from "./flow-history";
+
+let setup: Awaited<ReturnType<typeof testRender>> | undefined;
+afterEach(() => {
+  setup?.renderer.destroy();
+  setup = undefined;
+});
+
+function print(id: string, at: number): ScannerFlowEvent {
+  return {
+    id, at, underlying: "NVDA", contract: "NVDA261218C00200000", right: "C", strike: 200,
+    expiry: "2026-12-18", side: "ask", kind: "sweep", size: 100, price: 10, premium: 100_000,
+    volume: 1_000, openInterest: 500, volOi: 2, iv: 0.5,
+  };
+}
+
+type Probe = ReturnType<typeof useFlowHistory>;
+
+async function mount(
+  props: { query: ScannerFlowHistoryQuery; oldestLive: { at: number; id: string } | null },
+  load: FlowHistoryLoader,
+) {
+  const ref: { current: Probe | null; setProps: ((next: typeof props) => void) | null } = {
+    current: null,
+    setProps: null,
+  };
+  function Harness() {
+    const [current, setProps] = useState(props);
+    ref.setProps = setProps;
+    ref.current = useFlowHistory(current.query, current.oldestLive, true, load);
+    return <text>{String(ref.current.events.length)}</text>;
+  }
+  setup = await testRender(<Harness />, { width: 20, height: 3 });
+  await act(async () => {
+    await setup!.renderOnce();
+  });
+  return {
+    ref,
+    rerender: async (next: typeof props) => {
+      await act(async () => {
+        ref.setProps!(next);
+        await setup!.renderOnce();
+      });
+    },
+    flush: async () => {
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        await setup!.renderOnce();
+      });
+    },
+  };
+}
+
+test("the first page starts under the oldest live print and later pages continue from the last", async () => {
+  const requests: ScannerFlowHistoryQuery[] = [];
+  const pages: ScannerFlowHistoryPage[] = [
+    { events: [print("b", 900), print("a", 800)], hasMore: true },
+    { events: [print("z", 700)], hasMore: false },
+  ];
+  const view = await mount(
+    { query: { limit: 2, minPremium: 250_000 }, oldestLive: { at: 1_000, id: "live" } },
+    async (query) => {
+      requests.push(query);
+      return pages.shift()!;
+    },
+  );
+
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  // Nothing further once the server says the log is exhausted.
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+
+  expect(requests).toEqual([
+    { limit: 2, minPremium: 250_000, before: { at: 1_000, id: "live" } },
+    { limit: 2, minPremium: 250_000, before: { at: 800, id: "a" } },
+  ]);
+  expect(view.ref.current!.events.map((event) => event.id)).toEqual(["b", "a", "z"]);
+  expect(view.ref.current!.hasMore).toBe(false);
+});
+
+test("a filter change drops the pages and ignores the answer to the old query", async () => {
+  let resolveOld: ((page: ScannerFlowHistoryPage) => void) | undefined;
+  const view = await mount(
+    { query: { limit: 2 }, oldestLive: null },
+    (query) => query.right === "P"
+      ? Promise.resolve({ events: [print("put", 500)], hasMore: false })
+      : new Promise((resolve) => { resolveOld = resolve; }),
+  );
+
+  await act(async () => view.ref.current!.loadMore());
+  await view.rerender({ query: { limit: 2, right: "P" }, oldestLive: null });
+  expect(view.ref.current!.loading).toBe(false);
+
+  await act(async () => resolveOld!({ events: [print("stale", 600)], hasMore: true }));
+  await view.flush();
+  expect(view.ref.current!.events).toEqual([]);
+
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  expect(view.ref.current!.events.map((event) => event.id)).toEqual(["put"]);
+});
+
+test("a failed page stops loading until retried", async () => {
+  let fail = true;
+  let calls = 0;
+  const view = await mount({ query: { limit: 1 }, oldestLive: null }, async () => {
+    calls += 1;
+    if (fail) throw new Error("Cloud unavailable");
+    return { events: [print("x", 1)], hasMore: false };
+  });
+
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  expect(view.ref.current!.error).toBe("Cloud unavailable");
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  expect(calls).toBe(1);
+
+  fail = false;
+  await act(async () => view.ref.current!.retry());
+  await view.flush();
+  await act(async () => view.ref.current!.loadMore());
+  await view.flush();
+  expect(calls).toBe(2);
+  expect(view.ref.current!.events.map((event) => event.id)).toEqual(["x"]);
+});
+
+test("with nothing live yet, the first page is the latest recorded prints", () => {
+  expect(nextFlowCursor([], null)).toBeUndefined();
+  expect(nextFlowCursor([print("p", 5)], { at: 9, id: "live" })).toEqual({ at: 5, id: "p" });
+});

package/src/plugins/builtin/scanner/flow-history.ts

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  apiClient,
+  type ScannerFlowEvent,
+  type ScannerFlowHistoryPage,
+  type ScannerFlowHistoryQuery,
+} from "../../../api-client";
+import { flowHistorySearch, mergeFlowRows } from "./flow-model";
+
+export interface FlowHistoryState {
+  /** The query the pages belong to; a filter change starts over. */
+  key: string;
+  events: ScannerFlowEvent[];
+  hasMore: boolean;
+  loading: boolean;
+  error: string | null;
+}
+
+export type FlowHistoryLoader = (
+  query: ScannerFlowHistoryQuery,
+  signal: AbortSignal,
+) => Promise<ScannerFlowHistoryPage>;
+
+/** Aborts on the caller's signal or after `ms`; AbortSignal.any is too new for older system WebViews. */
+function withTimeout(signal: AbortSignal, ms: number): AbortSignal {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal.aborted) abort();
+  else signal.addEventListener("abort", abort, { once: true });
+  const timeout = AbortSignal.timeout(ms);
+  if (timeout.aborted) abort();
+  else timeout.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+
+const loadRecordedPrints: FlowHistoryLoader = (query, signal) =>
+  apiClient.getScannerFlowHistory(flowHistorySearch(query), withTimeout(signal, 20_000));
+
+function emptyHistory(key: string): FlowHistoryState {
+  return { key, events: [], hasMore: true, loading: false, error: null };
+}
+
+/** Where the next page starts: below the last page, or below the oldest live print. */
+export function nextFlowCursor(
+  pages: readonly ScannerFlowEvent[],
+  oldestLive: { at: number; id: string } | null,
+): { at: number; id: string } | undefined {
+  const last = pages.at(-1);
+  if (last) return { at: last.at, id: last.id };
+  return oldestLive ?? undefined;
+}
+
+/**
+ * Recorded prints below everything the pane already holds, one page at a
+ * time. The first page starts under the oldest live print the pane has kept,
+ * so the two never overlap or leave a gap; later pages continue from the last.
+ */
+export function useFlowHistory(
+  query: ScannerFlowHistoryQuery,
+  oldestLive: { at: number; id: string } | null,
+  enabled: boolean,
+  load: FlowHistoryLoader = loadRecordedPrints,
+) {
+  const key = JSON.stringify(query);
+  const [state, setState] = useState<FlowHistoryState>(() => emptyHistory(key));
+  const current = state.key === key ? state : emptyHistory(key);
+  const inFlight = useRef<AbortController | null>(null);
+
+  // Pages for the previous filters are dropped along with their request.
+  useEffect(() => () => {
+    inFlight.current?.abort();
+    inFlight.current = null;
+  }, [key]);
+
+  const loadMore = useCallback(() => {
+    if (!enabled || current.loading || !current.hasMore || current.error) return;
+    const before = nextFlowCursor(current.events, oldestLive);
+    const controller = new AbortController();
+    inFlight.current?.abort();
+    inFlight.current = controller;
+    setState({ ...current, loading: true });
+    load({ ...query, ...(before ? { before } : {}) }, controller.signal).then(
+      (page) => {
+        if (controller.signal.aborted) return;
+        setState((previous) => previous.key !== key ? previous : {
+          key,
+          events: mergeFlowRows(previous.events, page.events),
+          hasMore: page.hasMore && page.events.length > 0,
+          loading: false,
+          error: null,
+        });
+      },
+      (error: unknown) => {
+        if (controller.signal.aborted) return;
+        setState((previous) => previous.key !== key ? previous : {
+          ...previous,
+          loading: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      },
+    );
+  }, [current, enabled, key, load, oldestLive, query]);
+
+  const retry = useCallback(() => {
+    setState((previous) => previous.key === key ? { ...previous, error: null } : previous);
+  }, [key]);
+
+  return { ...current, loadMore, retry };
+}