@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/dashboard/apps/frontend/src/use-dashboard-app-model.tsx

@@ -0,0 +1,782 @@
+import type { CostMonitorProjection } from "@zaip-ai/dashboard-cost-monitor/contracts";
+import type { CostCurrency, CostLocale } from "@zaip-ai/dashboard-cost-monitor/react";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import * as React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { LoadingArea } from "./AppLoadingPanels.js";
+import {
+  isAbortError,
+  isCurrentCostSummaryRequest,
+  isCurrentDashboardRequest,
+  isCurrentOperationsPeriodRequest,
+  isCurrentPeriodTransition,
+  shouldLoadCostSummary,
+} from "./AppRequestGuards.js";
+import {
+  type BoardStageState,
+  type OverviewClassificationPages,
+  type OverviewStatusPages,
+  overviewClassificationPageKey,
+  overviewStatusPageKey,
+} from "./AppWorkBoard.js";
+import { currencyKey, initialDashboardView, savedLocale } from "./app-preferences.js";
+import { readDashboardSessionToken } from "./app-session-token.js";
+import type { DashboardView } from "./DashboardCapabilityNav.js";
+import type {
+  FxRate,
+  OperationsBoardPage,
+  OperationsEntityPageKind,
+  OperationsLifecyclePageKind,
+  OperationsPageFilters,
+  PricingCatalog,
+  ReconciliationResult,
+  WorkBoardStage,
+} from "./dashboard-api.js";
+import { DashboardApiClient } from "./dashboard-api.js";
+import { reconciliationCommandOutcome } from "./dashboard-api-reconciliation.js";
+import {
+  navigateDashboard,
+  renderCapabilityNavigation,
+  useDashboardBrowserLease,
+} from "./dashboard-app-shell.js";
+import {
+  currentCostByRun as buildCurrentCostByRun,
+  factualCostFacts,
+} from "./dashboard-cost-facts.js";
+import {
+  type DashboardIdentityResponse,
+  defaultDashboardIdentity,
+  mergeDashboardIdentity,
+} from "./dashboard-identity.js";
+import { retryDashboardLoad } from "./dashboard-retry.js";
+import { createDashboardSetupRoute } from "./dashboard-setup-route.js";
+import { createDashboardViewSelector } from "./dashboard-view-actions.js";
+import { defaultOperationsPeriod, requestPeriodForOperations } from "./operations-period.js";
+import {
+  millisecondsUntilNextSaoPauloDay,
+  rolloverOperationsPeriod,
+} from "./sao-paulo-day-rollover.js";
+import { useAppCostLoaders } from "./use-app-cost-loaders.js";
+import { useAppEffects } from "./use-app-effects.js";
+import { useAppOperationsPages } from "./use-app-operations-pages.js";
+import { useAppTraceDocuments } from "./use-app-trace-documents.js";
+import { useAppTraceTaskPagination } from "./use-app-trace-task-pagination.js";
+import { useAppWorkBoard } from "./use-app-work-board.js";
+import { useAppWorkListPage } from "./use-app-work-list-page.js";
+import { useOperationsDetailExport } from "./use-operations-detail-export.js";
+import { useSnapshotNotice } from "./use-snapshot-notice.js";
+import "./loading-feedback.css";
+import "./period-transition-overlay.css";
+
+export function useDashboardAppModel() {
+  const sessionToken = readDashboardSessionToken();
+  useDashboardBrowserLease(sessionToken);
+  const [snapshotUpdating, setSnapshotUpdating] = useState(false);
+  const token = useMemo(readDashboardSessionToken, []);
+  const api = useMemo(() => new DashboardApiClient(token), [token]);
+  const { loadCostDetail, loadCostReadModelPage, loadCostRunPage, loadCostGroupPage } =
+    useAppCostLoaders(api);
+  const [dashboardView, setDashboardView] = useState<DashboardView | null>(() =>
+    initialDashboardView(window.location.pathname),
+  );
+  const dashboardViewRef = useRef(dashboardView);
+  dashboardViewRef.current = dashboardView;
+  const [operations, setOperations] = useState<OperationsProjection | null>(null);
+  const [entityPage, setEntityPage] = useState<{
+    offset: number;
+    total: number | null;
+    loading: boolean;
+    error: string | null;
+    aggregation?: "canonical_entity" | "page_partial" | undefined;
+  }>({ offset: 0, total: null, loading: false, error: null });
+  const [entityPageKind, setEntityPageKind] = useState<
+    OperationsEntityPageKind | OperationsLifecyclePageKind
+  >("runs");
+  const entityFiltersRef = useRef<OperationsPageFilters>({ query: "", status: "", risk: "" });
+  const [boardTotals, setBoardTotals] = useState<Partial<Record<WorkBoardStage, number>>>({});
+  const [boardKindTotals, setBoardKindTotals] = useState<
+    Partial<Record<WorkBoardStage, OperationsBoardPage["totals_by_kind"]>>
+  >({});
+  const [boardStates, setBoardStates] = useState<Partial<Record<WorkBoardStage, BoardStageState>>>(
+    {},
+  );
+  const [overviewStatusPages, setOverviewStatusPages] = useState<OverviewStatusPages>({});
+  const [overviewClassificationPages, setOverviewClassificationPages] =
+    useState<OverviewClassificationPages>({});
+  const [costs, setCosts] = useState<CostMonitorProjection | null>(null);
+  const [displayedCosts, setDisplayedCosts] = useState<CostMonitorProjection | null>(null);
+  const [costLocale, setCostLocale] = useState<CostLocale>(savedLocale);
+  const [currency, setCurrency] = useState<CostCurrency>(() =>
+    window.localStorage.getItem(currencyKey) === "USD" ? "USD" : "BRL",
+  );
+  const currencyRef = useRef(currency);
+  currencyRef.current = currency;
+  // Language is the global selector's source of truth for the paired display
+  // currency, so Operations and Cost Monitor cannot diverge.
+  const changeDashboardLocale = useCallback((next: CostLocale) => {
+    setCostLocale(next);
+    setCurrency(next === "en-US" ? "USD" : "BRL");
+  }, []);
+  const [operationsPeriod, setOperationsPeriod] = useState(() => defaultOperationsPeriod);
+  // All Time may update its displayed factual range without changing the
+  // unbounded request identity. Keep the refresh callback stable for that
+  // presentation-only synchronization.
+  const operationsRequestFrom =
+    operationsPeriod.preset === "all" ? null : operationsPeriod.range.start;
+  const operationsRequestTo = operationsPeriod.preset === "all" ? null : operationsPeriod.range.end;
+  const operationsRequestPeriod = useMemo(
+    () => ({ from: operationsRequestFrom, to: operationsRequestTo }),
+    [operationsRequestFrom, operationsRequestTo],
+  );
+  const operationsPeriodRef = useRef(operationsPeriod);
+  operationsPeriodRef.current = operationsPeriod;
+  const rolloverRefreshRequested = useRef<typeof operationsPeriod | null>(null);
+  const [helpOpen, setHelpOpen] = useState(false);
+  const [pricing, setPricing] = useState<PricingCatalog | null>(null);
+  const [fxRate, setFxRate] = useState<FxRate | null>(null);
+  const [pathname, setPathname] = useState(window.location.pathname);
+  const [operationsLoading, setOperationsLoading] = useState(true);
+  const [, setOperationsSurfaceLoading] = useState(false);
+  const [, setCostSurfaceLoading] = useState(false);
+  const [periodTransitionPending, setPeriodTransitionPending] = useState(false);
+  const [loadingArea, setLoadingArea] = useState<LoadingArea | null>("operations");
+  const [failedArea, setFailedArea] = useState<LoadingArea | null>(null);
+  const [refreshDialog, setRefreshDialog] = useState<
+    "choose" | "refreshing" | "reconciling" | null
+  >(null);
+  useEffect(() => {
+    void api
+      .ready()
+      .then((ready) => setSnapshotUpdating(ready.snapshot_state === "updating"))
+      .catch(() => {});
+  }, [api]);
+  const [error, setError] = useState<string | null>(null);
+  const [reconciliationResult, setReconciliationResult] = useState<ReconciliationResult | null>(
+    null,
+  );
+  const [lastUpdatedAt, setLastUpdatedAt] = useState<string | null>(null);
+  const [dashboardIdentity, setDashboardIdentity] = useState(defaultDashboardIdentity);
+  const applyDashboardIdentity = useCallback((identity: DashboardIdentityResponse) => {
+    setDashboardIdentity((current) => mergeDashboardIdentity(current, identity));
+  }, []);
+  useEffect(() => {
+    let cancelled = false;
+    // Identity is workspace metadata, rather than period data. Start it beside
+    // the compact projection and never make period/filter refreshes erase it.
+    void api
+      .dashboardIdentity()
+      .then((identity) => {
+        if (!cancelled) applyDashboardIdentity(identity);
+      })
+      // The compact Operations projection remains usable when an older local
+      // runtime has not yet supplied this optional endpoint.
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [api, applyDashboardIdentity]);
+  const {
+    closeDocument,
+    documentDetail,
+    openDocument,
+    openTrace,
+    openTraceChange,
+    openTraceMacro,
+    selectedTraceTaskId,
+    setSelectedTraceTaskId,
+    setTrace,
+    setTraceLink,
+    setTraceLoadingTaskId,
+    setTraceTasks,
+    trace,
+    traceLink,
+    traceLoadingTaskId,
+    traceTasks,
+  } = useAppTraceDocuments({ api, operations, setError, setFailedArea, setLoadingArea });
+  const { loadMoreTraceTasks, traceTasksHasMore, traceTasksLoading } = useAppTraceTaskPagination(
+    api,
+    traceTasks,
+    setTraceTasks,
+  );
+  const refreshVersion = useRef(0);
+
+  const periodTransitionVersionRef = useRef(0);
+  const detailLoadInFlight = useRef(false);
+  const costLoadingCount = useRef(0);
+  const costSummaryRequestVersion = useRef(0);
+  const costSummaryAbortRef = useRef<AbortController | null>(null);
+  const costsLoadedRef = useRef(false);
+  const operationsDetailLoadedRef = useRef(false);
+  const operationsDetailCancelRef = useRef<(() => void) | null>(null);
+  const operationsDetailAbortRef = useRef<AbortController | null>(null);
+  const operationsPageAbortRef = useRef<AbortController | null>(null);
+  const operationsPageRequestVersionRef = useRef(0);
+  const boardLoadedRef = useRef<Partial<Record<WorkBoardStage, number>>>({});
+  const boardInFlightRef = useRef(new Set<WorkBoardStage>());
+  const boardAbortControllersRef = useRef(new Map<WorkBoardStage, AbortController>());
+  const overviewStatusInFlightRef = useRef(new Set<string>());
+  const boardInitialPageRef = useRef(new Set<WorkBoardStage>());
+  const boardFiltersRef = useRef<OperationsPageFilters>({
+    query: "",
+    status: "",
+    risk: "",
+    origin: "",
+    kind: "",
+  });
+  const boardFilterKeyRef = useRef("||||");
+  const boardRequestVersionRef = useRef(0);
+  const quickOverviewMetricsRef =
+    useRef<OperationsProjection["summary"]["overview_metrics"]>(undefined);
+  const {
+    workListPage,
+    workListFiltersRef,
+    loadWorkListFilters,
+    loadWorkListPage,
+    resetWorkListPage,
+  } = useAppWorkListPage({ api, operationsPeriod, operationsPeriodRef });
+  // A new local SQLite generation is immutable and verified by the launcher.
+  // Its server begins warming the compact first fold as soon as readiness is
+  // observed, so the first paint must join that bounded cache instead of
+  // forcing a second full aggregate calculation.
+  const initialAggregateFreshRef = useRef(false);
+  const refresh = useCallback(
+    async (
+      visible = true,
+      reconcileOpenWork = false,
+      refreshProjection = false,
+      reloadCostSummary = false,
+    ) => {
+      operationsDetailCancelRef.current?.();
+      operationsDetailCancelRef.current = null;
+      operationsDetailAbortRef.current?.abort();
+      operationsDetailAbortRef.current = null;
+      boardRequestVersionRef.current += 1;
+      for (const controller of boardAbortControllersRef.current.values()) controller.abort();
+      boardAbortControllersRef.current.clear();
+      boardInFlightRef.current.clear();
+      boardInitialPageRef.current.clear();
+      boardLoadedRef.current = {};
+      setBoardTotals({});
+      setBoardKindTotals({});
+      setBoardStates({});
+      setOverviewStatusPages({});
+      setOverviewClassificationPages({});
+      const requestVersion = ++refreshVersion.current;
+      const transitionVersion = periodTransitionVersionRef.current;
+      const activeDashboardView = dashboardViewRef.current;
+      const period = operationsRequestPeriod;
+      const isCurrentRequest = () =>
+        isCurrentDashboardRequest(requestVersion, refreshVersion.current) &&
+        isCurrentOperationsPeriodRequest(
+          requestVersion,
+          refreshVersion.current,
+          period,
+          requestPeriodForOperations(operationsPeriodRef.current),
+        );
+      if (visible) {
+        setOperationsLoading(true);
+        setLoadingArea("operations");
+      }
+      setError(null);
+      setFailedArea(null);
+      try {
+        if (reconcileOpenWork) {
+          const reconciliationResponse = await api.reconcileOpenWork(currency, period);
+          const commandOutcome = reconciliationCommandOutcome(
+            reconciliationResponse,
+            isCurrentRequest(),
+          );
+          // The compact reconciliation outcome is useful on its own. Reveal
+          // it before the optional quick GET so a historical snapshot load
+          // cannot keep the operator in the progress dialog.
+          setReconciliationResult(commandOutcome.reconciliation);
+          if (commandOutcome.dismissProgressDialog) setRefreshDialog(null);
+          if (!commandOutcome.applySnapshotState) return false;
+          setSnapshotUpdating(reconciliationResponse.snapshot_state === "updating");
+          // Reconciliation returns promptly while a new SQLite generation may
+          // still be promoted. Only read a compact Operations projection when
+          // that promotion is already complete; the revision observer handles
+          // the deferred case without fetching Cost Monitor detail data.
+          if (commandOutcome.reloadQuickProjection) {
+            const projection = await api.operations(period, "quick", undefined, true);
+            if (!isCurrentRequest()) return false;
+            initialAggregateFreshRef.current = false;
+            setOperations(projection);
+            quickOverviewMetricsRef.current = projection.summary.overview_metrics;
+            operationsDetailLoadedRef.current = false;
+            setLastUpdatedAt(projection.summary.latest_token_collected_at ?? null);
+          }
+        } else if (refreshProjection) {
+          let snapshot: Awaited<ReturnType<typeof api.refreshProjection>>;
+          snapshot = await api.refreshProjection(currency, period);
+          if (!isCurrentRequest()) return false;
+          setOperations(snapshot.operations);
+          quickOverviewMetricsRef.current = snapshot.operations.summary.overview_metrics;
+          operationsDetailLoadedRef.current = true;
+          setCosts(snapshot.costs);
+          costsLoadedRef.current = true;
+          setDisplayedCosts(null);
+          const dashboard = snapshot.dashboard;
+          if (dashboard) {
+            setDashboardIdentity((current) => mergeDashboardIdentity(current, dashboard));
+          }
+          setLastUpdatedAt(snapshot.projection.latest_token_collected_at ?? null);
+        } else {
+          {
+            // First paint is aggregate-only; board and detail data are loaded
+            // on their own bounded routes rather than hydrating entity arrays.
+            const [projection, costSummary] = await Promise.all([
+              api.operations(period, "quick", undefined, initialAggregateFreshRef.current),
+              // An English first paint must have the factual USD summary
+              // before Operations formats currency. BRL retains the fast
+              // Operations-only path until the user opens Cost Monitor.
+              currency === "USD" || reloadCostSummary
+                ? api.costMonitor(currency, period, "summary")
+                : Promise.resolve(null),
+            ]);
+            if (!isCurrentRequest()) return false;
+            initialAggregateFreshRef.current = false;
+            setOperations(projection);
+            quickOverviewMetricsRef.current = projection.summary.overview_metrics;
+            operationsDetailLoadedRef.current = false;
+            if (costSummary !== null) {
+              setCosts(costSummary);
+              // This is only a first-fold placeholder.  It must not suppress
+              // the factual, narrow Cost summary when the user opens Cost.
+              costsLoadedRef.current = false;
+              setDisplayedCosts(null);
+            }
+            setLastUpdatedAt(projection.summary.latest_token_collected_at ?? null);
+          }
+        }
+        return true;
+      } catch (cause) {
+        if (!isCurrentRequest()) return false;
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setFailedArea(activeDashboardView === "cost-monitor" ? "costs" : "operations");
+        return false;
+      } finally {
+        if (
+          isCurrentRequest() &&
+          isCurrentPeriodTransition(transitionVersion, periodTransitionVersionRef.current)
+        )
+          setPeriodTransitionPending(false);
+        if (visible && isCurrentRequest()) {
+          setOperationsLoading(false);
+          setLoadingArea((current) => (current === "operations" ? null : current));
+        }
+      }
+    },
+    [api, currency, operationsRequestPeriod],
+  );
+  const loadOperationsDetails = useCallback(
+    async (signal?: AbortSignal): Promise<OperationsProjection | null> => {
+      if (operationsDetailLoadedRef.current) return null;
+      if (detailLoadInFlight.current) return null;
+      if (signal?.aborted) return null;
+      operationsDetailAbortRef.current?.abort();
+      const controller = signal === undefined ? new AbortController() : null;
+      const requestSignal = signal ?? controller?.signal;
+      if (requestSignal === undefined) return null;
+      if (controller !== null) operationsDetailAbortRef.current = controller;
+      detailLoadInFlight.current = true;
+      costLoadingCount.current += 1;
+      setLoadingArea("costs");
+      setFailedArea(null);
+      try {
+        const requestVersion = ++refreshVersion.current;
+        const period = requestPeriodForOperations(operationsPeriod);
+        const isCurrentRequest = () =>
+          isCurrentDashboardRequest(requestVersion, refreshVersion.current) &&
+          isCurrentOperationsPeriodRequest(
+            requestVersion,
+            refreshVersion.current,
+            period,
+            requestPeriodForOperations(operationsPeriodRef.current),
+          );
+        const projection = await api.operations(period, "detail", requestSignal);
+        if (!isCurrentRequest()) return null;
+        setOperations(projection);
+        operationsDetailLoadedRef.current = true;
+        return projection;
+      } catch (cause) {
+        if (requestSignal.aborted || isAbortError(cause)) return null;
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setFailedArea("operations");
+        return null;
+      } finally {
+        if (controller !== null && operationsDetailAbortRef.current === controller) {
+          operationsDetailAbortRef.current = null;
+        }
+        detailLoadInFlight.current = false;
+        costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
+        if (costLoadingCount.current === 0) {
+          setLoadingArea((current) => (current === "costs" ? null : current));
+        }
+      }
+    },
+    [api, operationsPeriod],
+  );
+  const { loadOperationsEntityPage, loadOperationsLifecyclePage } = useAppOperationsPages({
+    api,
+    entityFiltersRef,
+    operationsPageAbortRef,
+    operationsPageRequestVersionRef,
+    operationsPeriod,
+    operationsPeriodRef,
+    refreshVersion,
+    setEntityPage,
+    setEntityPageKind,
+    setOperations,
+  });
+  const loadFilteredOperationsPage = useCallback(
+    (
+      view: "runs" | "conversations" | "executions" | "changes" | "decisions",
+      filters: OperationsPageFilters,
+    ) => {
+      entityFiltersRef.current = filters;
+      if (view === "changes" || view === "decisions")
+        void loadOperationsLifecyclePage(view, 0, filters);
+      else void loadOperationsEntityPage(view, 0, filters);
+    },
+    [loadOperationsEntityPage, loadOperationsLifecyclePage],
+  );
+  const {
+    boardExportSource,
+    loadFilteredBoard,
+    loadMoreBoard,
+    loadOverviewClassificationPage,
+    loadOverviewStatusPage,
+    resetBoard,
+  } = useAppWorkBoard({
+    api,
+    boardAbortControllersRef,
+    boardFilterKeyRef,
+    boardFiltersRef,
+    boardInFlightRef,
+    boardInitialPageRef,
+    boardLoadedRef,
+    boardRequestVersionRef,
+    dashboardView,
+    operations,
+    operationsPeriod,
+    operationsPeriodRef,
+    overviewStatusInFlightRef,
+    quickOverviewMetricsRef,
+    setBoardKindTotals,
+    setBoardStates,
+    setBoardTotals,
+    setOperations,
+    setOverviewClassificationPages,
+    setOverviewStatusPages,
+  });
+  const detailExportSource = useOperationsDetailExport({ api, operationsPeriod });
+
+  const refreshFromDialog = async (reconcileOpenWork: boolean) => {
+    if (reconcileOpenWork) {
+      setReconciliationResult(null);
+    }
+    setRefreshDialog(reconcileOpenWork ? "reconciling" : "refreshing");
+    try {
+      await refresh(false, reconcileOpenWork, !reconcileOpenWork);
+    } finally {
+      // A transport/runtime failure must not trap the user in the progress
+      // overlay. `refresh` normally reports the error on the affected panel;
+      // this also covers an unexpected rejection before it reaches that path.
+      setRefreshDialog(null);
+    }
+  };
+  useEffect(() => {
+    let timeout: number | null = null;
+    const scheduleRollover = () => {
+      timeout = window.setTimeout(() => {
+        setOperationsPeriod((current) => {
+          const next = rolloverOperationsPeriod(current);
+          if (next !== current) rolloverRefreshRequested.current = next;
+          return next;
+        });
+        scheduleRollover();
+      }, millisecondsUntilNextSaoPauloDay());
+    };
+    scheduleRollover();
+    return () => {
+      if (timeout !== null) window.clearTimeout(timeout);
+    };
+  }, []);
+  useEffect(() => {
+    if (rolloverRefreshRequested.current !== operationsPeriod) return;
+    rolloverRefreshRequested.current = null;
+    // The date changed while this tab stayed open. Refresh only the immutable
+    // projection: lifecycle reconciliation always remains an explicit action.
+    void refresh(false, false, true, true);
+  }, [operationsPeriod, refresh]);
+  useAppEffects({
+    api,
+    costLocale,
+    currency,
+    dashboardView,
+    loadOperationsDetails,
+    operations,
+    operationsDetailAbortRef,
+    operationsDetailCancelRef,
+    operationsPageAbortRef,
+    pathname,
+    pricing,
+    refresh,
+    refreshVersion,
+    setSnapshotUpdating,
+    setError,
+    setFxRate,
+    setPathname,
+    setPricing,
+    snapshotUpdating,
+  });
+
+  const navigate = navigateDashboard(setPathname);
+
+  const loadCostSummary = useCallback(async () => {
+    costSummaryAbortRef.current?.abort();
+    const controller = new AbortController();
+    costSummaryAbortRef.current = controller;
+    const requestVersion = ++costSummaryRequestVersion.current;
+    const period = requestPeriodForOperations(operationsPeriod);
+    costLoadingCount.current += 1;
+    setLoadingArea("costs");
+    setError(null);
+    setFailedArea(null);
+    try {
+      const summary = await api.costMonitor(currency, period, "summary", controller.signal);
+      const currentPeriod = requestPeriodForOperations(operationsPeriodRef.current);
+      if (
+        !isCurrentCostSummaryRequest({
+          aborted: controller.signal.aborted,
+          currentCurrency: currencyRef.current,
+          currentPeriod,
+          currentRequestVersion: costSummaryRequestVersion.current,
+          requestVersion,
+          requestedCurrency: currency,
+          requestedPeriod: period,
+        })
+      )
+        return;
+      setCosts(summary);
+      costsLoadedRef.current = true;
+      setDisplayedCosts(null);
+    } catch (cause) {
+      if (controller.signal.aborted || requestVersion !== costSummaryRequestVersion.current) return;
+      setError(cause instanceof Error ? cause.message : String(cause));
+      setFailedArea("costs");
+    } finally {
+      costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
+      if (costLoadingCount.current === 0)
+        setLoadingArea((current) => (current === "costs" ? null : current));
+      if (costSummaryAbortRef.current === controller) costSummaryAbortRef.current = null;
+    }
+  }, [api, currency, operationsPeriod]);
+
+  // The global language selector can request USD while Operations is active.
+  // Acquire its coherent Cost Monitor snapshot here instead of requiring a
+  // navigation to the Cost Monitor tab first.
+  useEffect(() => {
+    if (currency !== "USD" || costs?.currency === currency) return;
+    void loadCostSummary();
+  }, [costs?.currency, currency, loadCostSummary]);
+
+  // A global period change invalidates the Cost snapshot before React commits
+  // the replacement view. All Time also needs its factual Cost range while
+  // Operations is active, so its disabled date inputs do not fall back to
+  // today's Operations range. The request itself remains deliberately
+  // unbounded. The in-flight guard prevents duplicate requests.
+  useEffect(() => {
+    if (
+      (dashboardView !== "cost-monitor" && operationsPeriod.preset !== "all") ||
+      costSummaryAbortRef.current !== null
+    )
+      return;
+    if (
+      shouldLoadCostSummary({
+        costsLoaded: costsLoadedRef.current,
+        currency,
+        snapshotCurrency: costs?.currency,
+      })
+    )
+      void loadCostSummary();
+  }, [costs?.currency, currency, dashboardView, loadCostSummary, operationsPeriod.preset]);
+
+  const selectDashboardView = createDashboardViewSelector({
+    setDashboardView,
+    costsLoadedRef,
+    currency,
+    costs,
+    loadCostSummary,
+    costSummaryAbortRef,
+    traceTasks,
+    boardRequestVersionRef,
+    loadMoreTraceTasks,
+    setTraceTasks,
+    setSelectedTraceTaskId,
+    openTrace,
+    setTrace,
+    setTraceLoadingTaskId,
+  });
+  const currentCostByRun = buildCurrentCostByRun(costs, displayedCosts, currency);
+  const { fact: factualCostFact, periods: factualCostPeriods } = factualCostFacts(
+    costs,
+    displayedCosts,
+    currency,
+  );
+  const retryLastLoad = () =>
+    retryDashboardLoad(
+      failedArea,
+      selectedTraceTaskId,
+      operations,
+      loadCostSummary,
+      openTrace,
+      loadOperationsDetails,
+      refresh,
+      setError,
+    );
+
+  const setupRoute = createDashboardSetupRoute(
+    api,
+    costLocale,
+    fxRate,
+    navigate,
+    pathname,
+    pricing,
+    refresh,
+    setFxRate,
+    setPricing,
+  );
+  // A request is not an empty dashboard state. One accessible global gate
+  // prevents every tab from briefly presenting zero/empty placeholders while
+  // its coherent replacement snapshot or page is still in flight.
+  // The stale snapshot is useful only while the initial screen still waits
+  // for data.  Once Operations has arrived, the normal dashboard is the
+  // clearest confirmation that it opened; do not leave a duplicate toast.
+  return {
+    loadMoreBoard,
+    overviewStatusPageKey,
+    overviewClassificationPageKey,
+    boardRequestVersionRef,
+    boardAbortControllersRef,
+    boardInFlightRef,
+    boardInitialPageRef,
+    boardLoadedRef,
+    setBoardTotals,
+    setBoardKindTotals,
+    setBoardStates,
+    setOverviewStatusPages,
+    setOverviewClassificationPages,
+    setOperationsLoading,
+    operations,
+    error,
+    globalLoadingPending:
+      periodTransitionPending || (currency === "USD" && costs?.currency !== currency),
+    costLocale,
+    refresh: async () => {
+      await refresh();
+    },
+    snapshotNotice: useSnapshotNotice(
+      snapshotUpdating,
+      operations === null && operationsLoading,
+      costLocale,
+    ),
+    setupRoute,
+    failedArea,
+    retryLastLoad,
+    costs,
+    currency,
+    dashboardView,
+    lastUpdatedAt,
+    loadCostDetail,
+    loadCostReadModelPage,
+    loadCostRunPage,
+    loadCostGroupPage,
+    loadingArea,
+    setDisplayedCosts,
+    setCurrency,
+    setCostSurfaceLoading,
+    changeDashboardLocale,
+    loadMoreTraceTasks,
+    openTrace,
+    setRefreshDialog,
+    setSelectedTraceTaskId,
+    openTraceChange,
+    openTraceMacro,
+    selectedTraceTaskId,
+    trace,
+    traceLoadingTaskId,
+    traceTasksHasMore,
+    traceTasksLoading,
+    traceTasks,
+    capabilityNavigation: renderCapabilityNavigation(
+      dashboardView,
+      costLocale,
+      (view) => void selectDashboardView(view),
+    ),
+    boardTotals,
+    boardKindTotals,
+    boardExportSource,
+    detailExportSource,
+    boardStates,
+    operationsPeriod,
+    entityPage,
+    dashboardIdentity,
+    operationsLoading,
+    factualCostFact,
+    factualCostPeriods,
+    setOperationsSurfaceLoading,
+    currentCostByRun,
+    loadOperationsEntityPage,
+    loadOperationsLifecyclePage,
+    loadOperationsDetails,
+    entityPageKind,
+    loadFilteredOperationsPage,
+    loadFilteredBoard,
+    loadWorkListPage,
+    loadWorkListFilters,
+    workListFiltersRef,
+    boardFiltersRef,
+    workListPage,
+    overviewStatusPages,
+    loadOverviewStatusPage,
+    overviewClassificationPages,
+    loadOverviewClassificationPage,
+    openDocument,
+    api,
+    setError,
+    operationsPeriodRef,
+    setOperationsPeriod,
+    operationsDetailLoadedRef,
+    operationsDetailCancelRef,
+    operationsDetailAbortRef,
+    operationsPageAbortRef,
+    resetWorkListPage,
+    operationsPageRequestVersionRef,
+    resetBoard,
+    refreshVersion,
+    costSummaryAbortRef,
+    costSummaryRequestVersion,
+    setEntityPage,
+    costsLoadedRef,
+    setCosts,
+    setPeriodTransitionPending,
+    periodTransitionVersionRef,
+    setLoadingArea,
+    navigate,
+    setHelpOpen,
+    closeDocument,
+    documentDetail,
+    helpOpen,
+    reconciliationResult,
+    setReconciliationResult,
+    refreshDialog,
+    setTrace,
+    traceLink,
+    setTraceLoadingTaskId,
+    setTraceLink,
+    refreshFromDialog,
+    renderedOperations: operations as OperationsProjection,
+  };
+}