fix(explorer): gate temporal requests on graph load (#1003)

Explorer was firing temporal requests before the graph even loaded.

When the backend is down, /api/graph/nodes fails but the temporal
bounds and snapshot effects didn't care , they fired anyway, off in
their own corner, ignoring whether the graph actually came up. Every
page load with no backend meant three failed requests instead of one,
and a scrubber that had nothing to scrub.

Added two small predicate functions and gated the temporal effects on
them. Basically: don't ask for time-based data until you know the
graph itself loaded. An empty graph still counts as loaded, so that
case isn't broken.

Confirmed with the backend down, before and after: three failing
requests down to one.

Fixes #982.

explorer/package.json

@@ -9,7 +9,7 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "test:graph-store": "node --test tests/graphStore.multi-edge.test.mjs",
-    "test:graph-workspace": "node --import tsx --test tests/graphSceneState.display.test.ts",
+    "test:graph-workspace": "node --import tsx --test tests/graphSceneState.display.test.ts tests/temporalLifecycle.test.ts",
     "test:plugin-registry": "node --import tsx --test tests/pluginRegistry.temporal.test.mjs"
   },
   "dependencies": {

explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx

@@ -40,6 +40,7 @@ import {
   type GraphPluginToolbarItem,
 } from "./plugins";
 import { explorationEffectsShouldLoad, neighborhoodPanelShouldLoad, temporalOverlayShouldLoad } from "./pluginRegistryPredicates";
+import { shouldFetchTemporalBounds, shouldFetchTemporalSnapshot } from "./temporalLifecyclePredicates";
 import type { LinkPrediction, PathResponse } from "./GraphInspectorPanel";
 import type { GraphSceneHandle, GraphSceneRuntime } from "./scene";
 import type {
@@ -1440,7 +1441,18 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
     applyGraphReadySummary(summary);
   }, [applyGraphReadySummary, graphReady, summary]);
 
+  const canFetchTemporalBounds = shouldFetchTemporalBounds(summary);
+  const canFetchTemporalSnapshot = shouldFetchTemporalSnapshot({
+    debouncedTime,
+    isLoading,
+    summary,
+  });
+
   useEffect(() => {
+    if (!canFetchTemporalBounds) {
+      return;
+    }
+
     let cancelled = false;
     const loadBounds = async () => {
       try {
@@ -1460,10 +1472,21 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
     return () => {
       cancelled = true;
     };
-  }, [summary?.nodeCount, summary?.edgeCount]);
+  }, [
+    canFetchTemporalBounds,
+    summary?.nodeCount,
+    summary?.edgeCount,
+  ]);
 
   useEffect(() => {
-    if (!debouncedTime || isLoading) return;
+    if (!canFetchTemporalSnapshot) {
+      return;
+    }
+
+    if (!debouncedTime) {
+      return;
+    }
+
     let cancelled = false;
 
     const applySnapshot = async () => {
@@ -1505,7 +1528,10 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
     return () => {
       cancelled = true;
     };
-  }, [debouncedTime, isLoading]);
+  }, [
+    canFetchTemporalSnapshot,
+    debouncedTime,
+  ]);
 
   const resolveNodeIdForFocusedMode = useCallback((
     nodeId: string,

explorer/src/workspaces/GraphWorkspace/temporalLifecyclePredicates.ts

@@ -0,0 +1,31 @@
+import type { GraphLoadSummary } from "./types";
+
+/**
+ * Predicates for gating GraphWorkspace temporal API requests.
+ *
+ * Temporal bounds and snapshot requests must strictly not execute until the
+ * initial graph load has succeeded (summary !== undefined). An empty graph
+ * (nodeCount: 0) is still a successful load and must not be rejected.
+ */
+
+export function shouldFetchTemporalBounds(
+  summary: GraphLoadSummary | undefined,
+): boolean {
+  return summary !== undefined;
+}
+
+export function shouldFetchTemporalSnapshot({
+  debouncedTime,
+  isLoading,
+  summary,
+}: {
+  debouncedTime: Date | null;
+  isLoading: boolean;
+  summary: GraphLoadSummary | undefined;
+}): boolean {
+  return (
+    summary !== undefined &&
+    debouncedTime !== null &&
+    !isLoading
+  );
+}

explorer/tests/temporalLifecycle.test.ts

@@ -0,0 +1,114 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  shouldFetchTemporalBounds,
+  shouldFetchTemporalSnapshot,
+} from "../src/workspaces/GraphWorkspace/temporalLifecyclePredicates.ts";
+import type { GraphLoadSummary } from "../src/workspaces/GraphWorkspace/types.ts";
+
+const sampleSummary: GraphLoadSummary = {
+  nodeCount: 42,
+  edgeCount: 78,
+  loadTimeMs: 120,
+  hasCoordinates: true,
+  layoutSource: "provided",
+  layoutReady: true,
+};
+
+const emptyGraphSummary: GraphLoadSummary = {
+  nodeCount: 0,
+  edgeCount: 0,
+  loadTimeMs: 15,
+  hasCoordinates: false,
+  layoutSource: "runtime",
+  layoutReady: false,
+};
+
+// ── shouldFetchTemporalBounds ────────────────────────────────────────────────
+
+test("temporal bounds: false when summary is undefined (initial mount or failed load)", () => {
+  assert.equal(
+    shouldFetchTemporalBounds(undefined),
+    false,
+    "bounds request must not run before graph load succeeds",
+  );
+});
+
+test("temporal bounds: true when non-empty summary is present", () => {
+  assert.equal(
+    shouldFetchTemporalBounds(sampleSummary),
+    true,
+    "bounds request should run when successful graph summary exists",
+  );
+});
+
+test("temporal bounds: true when successful summary has nodeCount of 0", () => {
+  assert.equal(
+    shouldFetchTemporalBounds(emptyGraphSummary),
+    true,
+    "an empty graph is still a successful load and must allow bounds fetching",
+  );
+});
+
+// ── shouldFetchTemporalSnapshot ──────────────────────────────────────────────
+
+test("temporal snapshot: false when summary is undefined even if scrubber time is set and isLoading is false", () => {
+  assert.equal(
+    shouldFetchTemporalSnapshot({
+      debouncedTime: new Date("2024-01-01T00:00:00Z"),
+      isLoading: false,
+      summary: undefined,
+    }),
+    false,
+    "snapshot request must not run when graph load failed",
+  );
+});
+
+test("temporal snapshot: false when graph is currently loading", () => {
+  assert.equal(
+    shouldFetchTemporalSnapshot({
+      debouncedTime: new Date("2024-01-01T00:00:00Z"),
+      isLoading: true,
+      summary: sampleSummary,
+    }),
+    false,
+    "snapshot request must not run while graph is loading",
+  );
+});
+
+test("temporal snapshot: false when debouncedTime is null", () => {
+  assert.equal(
+    shouldFetchTemporalSnapshot({
+      debouncedTime: null,
+      isLoading: false,
+      summary: sampleSummary,
+    }),
+    false,
+    "snapshot request must not run without a scrubber timestamp",
+  );
+});
+
+test("temporal snapshot: true when summary exists, isLoading is false, and time is set", () => {
+  assert.equal(
+    shouldFetchTemporalSnapshot({
+      debouncedTime: new Date("2024-01-01T00:00:00Z"),
+      isLoading: false,
+      summary: sampleSummary,
+    }),
+    true,
+    "snapshot request should run after graph load succeeds and time is set",
+  );
+});
+
+test("temporal snapshot: true when successful summary has 0 nodes, isLoading is false, and time is set", () => {
+  assert.equal(
+    shouldFetchTemporalSnapshot({
+      debouncedTime: new Date("2024-01-01T00:00:00Z"),
+      isLoading: false,
+      summary: emptyGraphSummary,
+    }),
+    true,
+    "empty successful graph must allow snapshot requests once ready",
+  );
+});