Add realtime viewer performance controls
This commit is contained in:
parent
8f0e0f2273
commit
7045ec11b5
6 changed files with 187 additions and 4 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<EpiphanyGraphViewer
|
||||
state={state}
|
||||
layoutMode="combined-force"
|
||||
performance="fast"
|
||||
/>
|
||||
```
|
||||
|
||||
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
|
||||
<EpiphanyGraphViewer
|
||||
state={state}
|
||||
layoutMode="combined-force"
|
||||
performance={{
|
||||
preset: "fast",
|
||||
targetFps: 30,
|
||||
maxAnimatedNodes: 120,
|
||||
edgeRefreshRate: 3,
|
||||
maxTimeStepMs: 24,
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
/>
|
||||
</section>
|
||||
</main>
|
||||
|
|
|
|||
|
|
@ -7,6 +7,8 @@ export type {
|
|||
EpiphanyGraphLayoutMode,
|
||||
EpiphanyGraphLayoutModeConfig,
|
||||
EpiphanyGraphMotionOptions,
|
||||
EpiphanyGraphPerformanceOptions,
|
||||
EpiphanyGraphPerformancePreset,
|
||||
EpiphanyGraphNode,
|
||||
EpiphanyGraphsState,
|
||||
EpiphanyGraphViewerProps,
|
||||
|
|
|
|||
|
|
@ -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<HTMLDivElement | null>(null);
|
||||
const dynamicStateRef = useRef<Record<GraphKey, DynamicNodeState[]> | null>(null);
|
||||
const dynamicLayoutRef = useRef<Record<GraphKey, GraphLayout> | 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<EpiphanyGraphPerformanceOptions> {
|
||||
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<EpiphanyGraphPerformanceOptions> {
|
||||
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<EpiphanyGraphPerformanceOptions>) {
|
||||
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<GraphKey, GraphLayout>;
|
||||
states: React.MutableRefObject<Record<GraphKey, DynamicNodeState[]> | null>;
|
||||
|
|
@ -1549,6 +1643,9 @@ function stepDynamicLayouts({
|
|||
viewportHeight: number;
|
||||
dt: number;
|
||||
time: number;
|
||||
maxAnimatedNodes: number;
|
||||
refreshEdges: boolean;
|
||||
previousLayout: GraphLayout | null;
|
||||
}): { layouts: Record<GraphKey, GraphLayout> } | 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<NodeEnvelope[]>("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<string, PositionedNode>,
|
||||
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);
|
||||
|
|
|
|||
|
|
@ -54,6 +54,15 @@ export type EpiphanyGraphLayoutMode = "layered" | "stress" | "force" | "combined
|
|||
export type EpiphanyGraphLayoutModeConfig =
|
||||
| EpiphanyGraphLayoutMode
|
||||
| Partial<Record<GraphKey, EpiphanyGraphLayoutMode>>;
|
||||
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;
|
||||
|
|
|
|||
Loading…
Reference in a new issue