From 7045ec11b59dfa79f8d87b2012dfb8788d51be10 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 19 May 2026 14:29:21 +0100 Subject: [PATCH] Add realtime viewer performance controls --- README.md | 2 + web/epiphany-graph-viewer/README.md | 39 ++++- web/epiphany-graph-viewer/src/App.tsx | 1 + web/epiphany-graph-viewer/src/index.ts | 2 + .../src/lib/EpiphanyGraphViewer.tsx | 137 +++++++++++++++++- web/epiphany-graph-viewer/src/lib/types.ts | 10 ++ 6 files changed, 187 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3b5880b..3dfe70b 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ export function GraphScreen({ state }: { state: EpiphanyGraphsState }) { state={state} layoutMode="combined-force" motion={{ strength: 1.05, flow: 1.1, orbit: 0.85 }} + performance="fast" /> ); } @@ -38,6 +39,7 @@ The public viewer API is intentionally coarse: - `layoutMode`: `layered`, `stress`, `force`, or `combined-force` - `motion`: viewer-owned force tuning for combined-force layouts +- `performance`: `quality`, `balanced`, `fast`, or explicit realtime budget knobs - `selection`, `focusSelection`, `expandedNode`, and callbacks for app integration - typed state and event payloads diff --git a/web/epiphany-graph-viewer/README.md b/web/epiphany-graph-viewer/README.md index 1b3ba0d..5c005aa 100644 --- a/web/epiphany-graph-viewer/README.md +++ b/web/epiphany-graph-viewer/README.md @@ -59,6 +59,7 @@ export function Screen() { state={state} layoutMode="combined-force" motion={{ strength: 1.05, flow: 1.1, orbit: 0.85 }} + performance="fast" /> ); } @@ -69,7 +70,7 @@ export function Screen() { The package exports: - `EpiphanyGraphViewer` -- state, selection, node, edge, layout mode, motion, and event payload types +- state, selection, node, edge, layout mode, motion, performance, and event payload types The package does not export demo data, validation helpers, ELK probes, SVG renderers, or engine controls. Those are implementation furniture. Consumers get the couch, not @@ -114,3 +115,39 @@ tune the viewer-owned model: `emitNodeEnvelopes` dispatches `epiphanygraph-node-envelopes` from the viewport for backdrops that want node-aware effects without owning graph physics. + +## Performance + +The viewer is tuned as a realtime machine. Clients choose a speed budget, and the +viewer adjusts animation frequency, node motion budget, edge refresh rate, and time +step stability. + +```tsx + +``` + +Presets: + +- `quality`: 60 FPS target, all practical nodes animated, edges refreshed every frame +- `balanced`: 40 FPS target, capped node motion, edges refreshed every other step +- `fast`: 24 FPS target, smaller animated-node budget, edges refreshed every third step + +Use explicit knobs when the host app knows its budget: + +```tsx + +``` diff --git a/web/epiphany-graph-viewer/src/App.tsx b/web/epiphany-graph-viewer/src/App.tsx index bd27c66..8b7dec6 100644 --- a/web/epiphany-graph-viewer/src/App.tsx +++ b/web/epiphany-graph-viewer/src/App.tsx @@ -70,6 +70,7 @@ export function App() { state={mockEpiphanyGraphState} layoutMode="combined-force" motion={{ strength: 1.08, flow: 1.1, orbit: 0.82, lift: 0.9 }} + performance="fast" /> diff --git a/web/epiphany-graph-viewer/src/index.ts b/web/epiphany-graph-viewer/src/index.ts index a6d16a3..1d4a23b 100644 --- a/web/epiphany-graph-viewer/src/index.ts +++ b/web/epiphany-graph-viewer/src/index.ts @@ -7,6 +7,8 @@ export type { EpiphanyGraphLayoutMode, EpiphanyGraphLayoutModeConfig, EpiphanyGraphMotionOptions, + EpiphanyGraphPerformanceOptions, + EpiphanyGraphPerformancePreset, EpiphanyGraphNode, EpiphanyGraphsState, EpiphanyGraphViewerProps, diff --git a/web/epiphany-graph-viewer/src/lib/EpiphanyGraphViewer.tsx b/web/epiphany-graph-viewer/src/lib/EpiphanyGraphViewer.tsx index 3c0f9e9..d0bcfd0 100644 --- a/web/epiphany-graph-viewer/src/lib/EpiphanyGraphViewer.tsx +++ b/web/epiphany-graph-viewer/src/lib/EpiphanyGraphViewer.tsx @@ -15,6 +15,8 @@ import type { EpiphanyGraphLink, EpiphanyGraphLayoutModeConfig, EpiphanyGraphMotionOptions, + EpiphanyGraphPerformanceOptions, + EpiphanyGraphPerformancePreset, EpiphanyGraphViewerProps, EpiphanyValidationIssue, GraphKey, @@ -59,6 +61,7 @@ export function EpiphanyGraphViewer({ graphDescriptions, layoutMode = "layered", motion, + performance, sidebar, sidebarWidth = 330, showSidebar = true, @@ -87,6 +90,7 @@ export function EpiphanyGraphViewer({ const viewportRef = useRef(null); const dynamicStateRef = useRef | null>(null); + const dynamicLayoutRef = useRef | null>(null); const wheelStateRef = useRef({ activeGraphKey, transforms, @@ -114,6 +118,8 @@ export function EpiphanyGraphViewer({ const layoutModeKey = layoutModeCacheKey(layoutMode); const motionOptions = resolveMotionOptions(layoutMode, motion); const motionKey = motionOptions ? motionOptionsCacheKey(motionOptions) : "off"; + const performanceOptions = resolvePerformanceOptions(performance); + const performanceKey = performanceOptionsCacheKey(performanceOptions); const updateSelection = (nextSelection: ViewerSelection | null) => { if (controlledSelection === undefined) { setLocalSelection(nextSelection); @@ -145,6 +151,7 @@ export function EpiphanyGraphViewer({ } setLayouts(nextLayouts); setDynamicLayouts(nextLayouts); + dynamicLayoutRef.current = nextLayouts; dynamicStateRef.current = { architecture: dynamicNodesFromLayout(nextLayouts.architecture), dataflow: dynamicNodesFromLayout(nextLayouts.dataflow), @@ -170,9 +177,21 @@ export function EpiphanyGraphViewer({ } let frameId = 0; - let lastTime = performance.now(); + let lastTime = globalThis.performance.now(); + let lastStepTime = lastTime; + let stepIndex = 0; const tick = (time: number) => { - const dt = Math.min(0.034, Math.max(0.001, (time - lastTime) / 1000)); + const minFrameMs = 1000 / performanceOptions.targetFps; + if (time - lastStepTime < minFrameMs) { + frameId = requestAnimationFrame(tick); + return; + } + stepIndex += 1; + lastStepTime = time; + const dt = Math.min( + performanceOptions.maxTimeStepMs / 1000, + Math.max(0.001, (time - lastTime) / 1000), + ); lastTime = time; const next = stepDynamicLayouts({ baseLayouts: layouts, @@ -185,8 +204,12 @@ export function EpiphanyGraphViewer({ viewportHeight: viewportSize.height, dt, time: time / 1000, + maxAnimatedNodes: performanceOptions.maxAnimatedNodes, + refreshEdges: stepIndex % performanceOptions.edgeRefreshRate === 0, + previousLayout: dynamicLayoutRef.current?.[activeGraphKey] ?? null, }); if (next) { + dynamicLayoutRef.current = next.layouts; setDynamicLayouts(next.layouts); } frameId = requestAnimationFrame(tick); @@ -197,6 +220,7 @@ export function EpiphanyGraphViewer({ activeGraphKey, layouts, motionKey, + performanceKey, transforms, viewportSize.height, viewportSize.width, @@ -1464,6 +1488,73 @@ function motionOptionsCacheKey(options: EpiphanyGraphMotionOptions) { ].join("|"); } +function resolvePerformanceOptions( + performance: EpiphanyGraphPerformancePreset | EpiphanyGraphPerformanceOptions | undefined, +): Required { + const base = performancePresetDefaults( + typeof performance === "string" ? performance : performance?.preset ?? "balanced", + ); + const overrides = typeof performance === "string" ? {} : performance ?? {}; + + return { + preset: overrides.preset ?? base.preset, + targetFps: clampWholeNumber(overrides.targetFps ?? base.targetFps, 1, 60), + maxAnimatedNodes: clampWholeNumber(overrides.maxAnimatedNodes ?? base.maxAnimatedNodes, 1, 5000), + edgeRefreshRate: clampWholeNumber(overrides.edgeRefreshRate ?? base.edgeRefreshRate, 1, 12), + maxTimeStepMs: clampWholeNumber(overrides.maxTimeStepMs ?? base.maxTimeStepMs, 8, 100), + }; +} + +function performancePresetDefaults( + preset: EpiphanyGraphPerformancePreset, +): Required { + if (preset === "quality") { + return { + preset, + targetFps: 60, + maxAnimatedNodes: 5000, + edgeRefreshRate: 1, + maxTimeStepMs: 34, + }; + } + + if (preset === "fast") { + return { + preset, + targetFps: 24, + maxAnimatedNodes: 90, + edgeRefreshRate: 3, + maxTimeStepMs: 24, + }; + } + + return { + preset, + targetFps: 40, + maxAnimatedNodes: 240, + edgeRefreshRate: 2, + maxTimeStepMs: 28, + }; +} + +function performanceOptionsCacheKey(options: Required) { + return [ + options.preset, + options.targetFps, + options.maxAnimatedNodes, + options.edgeRefreshRate, + options.maxTimeStepMs, + ].join("|"); +} + +function clampWholeNumber(value: number, min: number, max: number) { + if (!Number.isFinite(value)) { + return min; + } + + return Math.round(clamp(value, min, max)); +} + function sampleCombinedForce( x: number, y: number, @@ -1538,6 +1629,9 @@ function stepDynamicLayouts({ viewportHeight, dt, time, + maxAnimatedNodes, + refreshEdges, + previousLayout, }: { baseLayouts: Record; states: React.MutableRefObject | null>; @@ -1549,6 +1643,9 @@ function stepDynamicLayouts({ viewportHeight: number; dt: number; time: number; + maxAnimatedNodes: number; + refreshEdges: boolean; + previousLayout: GraphLayout | null; }): { layouts: Record } | null { if (!states.current) { states.current = { @@ -1571,8 +1668,13 @@ function stepDynamicLayouts({ const bounds = nodeAabb(baseLayout.nodes); const centerX = baseLayout.width * 0.5; const centerY = baseLayout.height * 0.5; + const animatedNodeIds = animatedNodeIdSet(baseLayout.nodes, maxAnimatedNodes); for (const node of baseLayout.nodes) { + if (animatedNodeIds && !animatedNodeIds.has(node.id)) { + continue; + } + let dynamic = stateLookup.get(node.id); if (!dynamic) { dynamic = { id: node.id, x: node.x, y: node.y, vx: 0, vy: 0 }; @@ -1613,7 +1715,13 @@ function stepDynamicLayouts({ dynamic.y += dynamic.vy * dt; } - const nextActiveLayout = layoutWithDynamicNodes(baseLayout, graphState, nodeLookup); + const nextActiveLayout = layoutWithDynamicNodes( + baseLayout, + graphState, + nodeLookup, + refreshEdges, + previousLayout, + ); if (motionOptions.emitNodeEnvelopes && viewportElement) { viewportElement.dispatchEvent(new CustomEvent("epiphanygraph-node-envelopes", { bubbles: true, @@ -1635,16 +1743,39 @@ function stepDynamicLayouts({ }; } +function animatedNodeIdSet(nodes: PositionedNode[], maxAnimatedNodes: number) { + if (nodes.length <= maxAnimatedNodes) { + return null; + } + + return new Set( + [...nodes] + .sort((left, right) => nodeAnimationScore(right) - nodeAnimationScore(left)) + .slice(0, maxAnimatedNodes) + .map((node) => node.id), + ); +} + +function nodeAnimationScore(node: PositionedNode) { + return node.degree * 2 + node.linkCount * 3; +} + function layoutWithDynamicNodes( layout: GraphLayout, dynamicNodes: DynamicNodeState[], nodeLookup: Map, + refreshEdges: boolean, + previousLayout: GraphLayout | null, ): GraphLayout { const dynamicLookup = new Map(dynamicNodes.map((node) => [node.id, node])); const nodes = layout.nodes.map((node) => { const dynamic = dynamicLookup.get(node.id); return dynamic ? { ...node, x: dynamic.x, y: dynamic.y } : node; }); + if (!refreshEdges) { + return { ...layout, nodes, edges: previousLayout?.edges ?? layout.edges }; + } + const nextLookup = new Map(nodes.map((node) => [node.id, node])); const edges = layout.edges.map((edge) => { const source = nextLookup.get(edge.source_id) ?? nodeLookup.get(edge.source_id); diff --git a/web/epiphany-graph-viewer/src/lib/types.ts b/web/epiphany-graph-viewer/src/lib/types.ts index 038c89a..60c4679 100644 --- a/web/epiphany-graph-viewer/src/lib/types.ts +++ b/web/epiphany-graph-viewer/src/lib/types.ts @@ -54,6 +54,15 @@ export type EpiphanyGraphLayoutMode = "layered" | "stress" | "force" | "combined export type EpiphanyGraphLayoutModeConfig = | EpiphanyGraphLayoutMode | Partial>; +export type EpiphanyGraphPerformancePreset = "quality" | "balanced" | "fast"; + +export interface EpiphanyGraphPerformanceOptions { + preset?: EpiphanyGraphPerformancePreset; + targetFps?: number; + maxAnimatedNodes?: number; + edgeRefreshRate?: number; + maxTimeStepMs?: number; +} export interface EpiphanyGraphMotionOptions { enabled?: boolean; @@ -117,6 +126,7 @@ export interface EpiphanyGraphViewerProps { graphDescriptions?: EpiphanyGraphDescriptions; layoutMode?: EpiphanyGraphLayoutModeConfig; motion?: EpiphanyGraphMotionOptions | boolean; + performance?: EpiphanyGraphPerformancePreset | EpiphanyGraphPerformanceOptions; sidebar?: ReactNode; sidebarWidth?: CSSProperties["width"]; showSidebar?: boolean;