Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

feat(explorer): add temporal diff comparison to the Temporal panel

Sameer630547531d8365cb
diff --git a/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.ts b/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.ts
new file mode 100644
index 00000000..9e7010ac
--- /dev/null
+++ b/explorer/src/workspaces/GraphWorkspace/plugins/temporalDiffState.ts
@@ -0,0 +1,23 @@
+// Fetch wrapper for GET /api/temporal/diff (see semantica/explorer/routes/temporal.py).
+// added_nodes are node IDs active at to_time but not at from_time; removed_nodes are the
+// inverse. Both are plain node-ID lists (no edge-level diffing), matching the snapshot
+// route's active_node_ids shape used elsewhere in this workspace.
+export interface TemporalDiffResult {
+ from_time: string;
+ to_time: string;
+ added_nodes: string[];
+ removed_nodes: string[];
+}
+
+export async function fetchTemporalDiff(
+ fromTime: string,
+ toTime: string,
+ signal?: AbortSignal,
+): Promise<TemporalDiffResult> {
+ const params = new URLSearchParams({ from_time: fromTime, to_time: toTime });
+ const response = await fetch(`/api/temporal/diff?${params}`, { signal });
+ if (!response.ok) {
+ throw new Error(`Temporal diff request failed with status ${response.status}`);
+ }
+ return response.json();
+}
diff --git a/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx b/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx
index bf656fc6..1b38921e 100644
--- a/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx
+++ b/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx
@@ -1,6 +1,10 @@
-import type { CSSProperties } from "react";
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+import { Loader2 } from "lucide-react";
-import type { GraphPlugin } from "./types";
+import { graph } from "../../../store/graphStore";
+import { GRAPH_THEME } from "../graphTheme";
+import { fetchTemporalDiff, type TemporalDiffResult } from "./temporalDiffState";
+import type { GraphPlugin, GraphPluginContext } from "./types";
const TEMPORAL_PANEL_ID = "temporal-panel";
@@ -11,6 +15,182 @@ function formatTemporalLabel(value: Date | null) {
return `${value.getFullYear()}/${String(value.getMonth() + 1).padStart(2, "0")}`;
}
+function isValidDateInput(value: string): boolean {
+ return value.trim().length > 0 && !Number.isNaN(new Date(value).getTime());
+}
+
+type DiffRequestState =
+ | { status: "idle" }
+ | { status: "loading" }
+ | { status: "error"; message: string }
+ | { status: "empty"; result: TemporalDiffResult }
+ | { status: "success"; result: TemporalDiffResult };
+
+// Diff highlight colors reuse existing theme tokens rather than introducing new
+// hex values: semantic[2] is the codebase's green, dangerText is the one named
+// danger/red token already used elsewhere in this workspace (GraphWorkspace.tsx).
+const DIFF_ADDED_COLOR = GRAPH_THEME.palette.semantic[2];
+const DIFF_REMOVED_COLOR = GRAPH_THEME.ui.control.dangerText;
+
+// Highlighting uses baseColor (the node's fill color), not ringColor/haloColor: those two
+// are only read by resolveNodeElementStyle/GraphCanvas's decoration pass for nodes in
+// hovered/selected/path visual state (see resolveNodeRingSize, showHalo in graphSceneState.ts
+// and the nodesToDecorate set in GraphCanvas.tsx) and are silently discarded by the sigma
+// nodeReducer for a node sitting in its default (untouched) state — which is exactly the
+// state every diffed node is in here. baseColor is read unconditionally by resolveNodeColor's
+// default branch regardless of interaction state or zoom tier, so it is the one attribute
+// confirmed to actually render the diff highlight.
+function clearDiffHighlight(context: GraphPluginContext, previousColors: Map<string, string | undefined>) {
+ previousColors.forEach((color, nodeId) => {
+ if (graph.hasNode(nodeId)) {
+ graph.setNodeAttribute(nodeId, "baseColor", color);
+ }
+ });
+ context.scene?.requestRender();
+}
+
+function applyDiffHighlight(context: GraphPluginContext, result: TemporalDiffResult): Map<string, string | undefined> {
+ const previousColors = new Map<string, string | undefined>();
+ const paint = (nodeId: string, color: string) => {
+ if (graph.hasNode(nodeId)) {
+ previousColors.set(nodeId, graph.getNodeAttribute(nodeId, "baseColor"));
+ graph.setNodeAttribute(nodeId, "baseColor", color);
+ }
+ };
+ result.added_nodes.forEach((nodeId) => paint(nodeId, DIFF_ADDED_COLOR));
+ result.removed_nodes.forEach((nodeId) => paint(nodeId, DIFF_REMOVED_COLOR));
+ context.scene?.requestRender();
+ return previousColors;
+}
+
+function DiffSection({ context }: { context: GraphPluginContext }) {
+ const [fromTime, setFromTime] = useState("");
+ const [toTime, setToTime] = useState("");
+ const [validationMessage, setValidationMessage] = useState<string | null>(null);
+ const [requestState, setRequestState] = useState<DiffRequestState>({ status: "idle" });
+ const abortRef = useRef<AbortController | null>(null);
+ // Maps currently-highlighted node ID -> its baseColor before highlighting, so clearing
+ // restores the exact prior value instead of an approximation.
+ const previousColorsRef = useRef<Map<string, string | undefined>>(new Map());
+
+ // Cancel any in-flight request and clear stale highlights when the panel unmounts
+ // (panel closed) — matches the cancellation pattern used by the snapshot fetch in
+ // GraphRuntimeStage.tsx (cancel-on-cleanup) plus AbortController per DecisionWorkspace.tsx.
+ useEffect(() => {
+ return () => {
+ abortRef.current?.abort();
+ clearDiffHighlight(context, previousColorsRef.current);
+ previousColorsRef.current = new Map();
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ const handleCompare = () => {
+ if (!fromTime.trim() || !toTime.trim()) {
+ setValidationMessage("Both a from and to time are required.");
+ return;
+ }
+ if (!isValidDateInput(fromTime) || !isValidDateInput(toTime)) {
+ setValidationMessage("Enter valid ISO datetimes, e.g. 2024-01-01T00:00:00.");
+ return;
+ }
+ if (new Date(fromTime).getTime() >= new Date(toTime).getTime()) {
+ setValidationMessage("From time must be before to time.");
+ return;
+ }
+ setValidationMessage(null);
+
+ // Cancel any request already in flight before starting a new one.
+ abortRef.current?.abort();
+ const controller = new AbortController();
+ abortRef.current = controller;
+
+ clearDiffHighlight(context, previousColorsRef.current);
+ previousColorsRef.current = new Map();
+ setRequestState({ status: "loading" });
+
+ fetchTemporalDiff(fromTime, toTime, controller.signal)
+ .then((result) => {
+ if (controller.signal.aborted) {
+ return;
+ }
+ if (!result.added_nodes.length && !result.removed_nodes.length) {
+ setRequestState({ status: "empty", result });
+ return;
+ }
+ previousColorsRef.current = applyDiffHighlight(context, result);
+ setRequestState({ status: "success", result });
+ })
+ .catch((error: unknown) => {
+ if (error instanceof Error && error.name === "AbortError") {
+ return;
+ }
+ setRequestState({
+ status: "error",
+ message: error instanceof Error ? error.message : "Temporal diff request failed.",
+ });
+ });
+ };
+
+ const isLoading = requestState.status === "loading";
+
+ return (
+ <div style={diffSectionStyle}>
+ <div style={panelEyebrowStyle}>Compare two points in time</div>
+ <div style={diffInputRowStyle}>
+ <input
+ value={fromTime}
+ onChange={(event) => setFromTime(event.target.value)}
+ placeholder="From, e.g. 2024-01-01T00:00:00"
+ style={diffInputStyle}
+ />
+ <input
+ value={toTime}
+ onChange={(event) => setToTime(event.target.value)}
+ placeholder="To, e.g. 2025-06-15T00:00:00"
+ style={diffInputStyle}
+ />
+ </div>
+ <button
+ type="button"
+ onClick={handleCompare}
+ disabled={isLoading}
+ style={{ ...diffActionButtonStyle, opacity: isLoading ? 0.7 : 1 }}
+ >
+ {isLoading ? <Loader2 size={13} className="animate-spin" style={{ marginRight: 6 }} /> : null}
+ {isLoading ? "Comparing…" : "Compare"}
+ </button>
+
+ {validationMessage ? <div style={diffValidationStyle}>{validationMessage}</div> : null}
+
+ {requestState.status === "error" ? (
+ <div style={diffErrorStyle}>{requestState.message}</div>
+ ) : null}
+
+ {requestState.status === "empty" ? (
+ <div style={emptyTextStyle}>No changes between these two points.</div>
+ ) : null}
+
+ {requestState.status === "success" ? (
+ <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+ <div style={detailRowStyle}>
+ <span style={detailLabelStyle}>Added</span>
+ <span style={{ ...detailValueStyle, color: DIFF_ADDED_COLOR }}>
+ {requestState.result.added_nodes.length.toLocaleString()}
+ </span>
+ </div>
+ <div style={detailRowStyle}>
+ <span style={detailLabelStyle}>Removed</span>
+ <span style={{ ...detailValueStyle, color: DIFF_REMOVED_COLOR }}>
+ {requestState.result.removed_nodes.length.toLocaleString()}
+ </span>
+ </div>
+ </div>
+ ) : null}
+ </div>
+ );
+}
+
export const temporalOverlayPlugin: GraphPlugin = {
id: "temporal-overlay",
mount: () => {},
@@ -80,7 +260,7 @@ export const temporalOverlayPlugin: GraphPlugin = {
order: 30,
defaultOpen: false,
preferredWidth: 320,
- preferredHeight: 220,
+ preferredHeight: 380,
content: (
<div style={panelBodyStyle}>
<div style={panelEyebrowStyle}>Current scrubber state</div>
@@ -100,6 +280,7 @@ export const temporalOverlayPlugin: GraphPlugin = {
{typeof temporal?.activeNodeCount === "number" ? temporal.activeNodeCount.toLocaleString() : "All"}
</span>
</div>
+ <DiffSection context={context} />
</div>
),
};
@@ -140,3 +321,62 @@ const detailValueStyle: CSSProperties = {
fontSize: 12,
fontWeight: 600,
};
+
+const diffSectionStyle: CSSProperties = {
+ display: "flex",
+ flexDirection: "column",
+ gap: 8,
+ marginTop: 4,
+ paddingTop: 10,
+ borderTop: "1px solid rgba(255,255,255,0.06)",
+};
+
+const diffInputRowStyle: CSSProperties = {
+ display: "flex",
+ gap: 8,
+};
+
+const diffInputStyle: CSSProperties = {
+ flex: 1,
+ minWidth: 0,
+ background: "rgba(5, 7, 10, 0.52)",
+ border: "1px solid rgba(211, 205, 190, 0.13)",
+ color: "#f3f7fd",
+ borderRadius: 12,
+ padding: "9px 11px",
+ fontSize: 12,
+ boxShadow: "inset 0 1px 0 rgba(255,255,255,0.035)",
+};
+
+const diffActionButtonStyle: CSSProperties = {
+ background: GRAPH_THEME.ui.control.primaryBg,
+ color: GRAPH_THEME.ui.control.primaryText,
+ border: `1px solid ${GRAPH_THEME.ui.control.primaryBorder}`,
+ borderRadius: 12,
+ padding: "9px 12px",
+ cursor: "pointer",
+ fontWeight: 700,
+ fontSize: 12,
+ display: "inline-flex",
+ alignItems: "center",
+ justifyContent: "center",
+ boxShadow: "inset 0 1px 0 rgba(255,255,255,0.07), 0 10px 24px rgba(0,0,0,0.18)",
+};
+
+const diffValidationStyle: CSSProperties = {
+ color: GRAPH_THEME.ui.control.dangerText,
+ fontSize: 12,
+ lineHeight: 1.5,
+};
+
+const diffErrorStyle: CSSProperties = {
+ color: GRAPH_THEME.ui.control.dangerText,
+ fontSize: 12,
+ lineHeight: 1.5,
+};
+
+const emptyTextStyle: CSSProperties = {
+ color: "#8ea4be",
+ fontSize: 12,
+ lineHeight: 1.5,
+};