@zenfg/inspector 0.1.0-beta.2 → 0.1.0-beta.4

package/src/panelGraphVisuals.ts

@@ -1,7 +1,8 @@
 import type cytoscape from 'cytoscape';
 
 import type { GraphScene, GraphSceneEdge, GraphSceneNode } from './panelGraphScene.ts';
-import { GRAPH_VISUAL_THEME } from './panelVisualTheme.ts';
+import { GRAPH_VISUAL_THEME, type GraphVisualTheme } from './panelVisualTheme.ts';
+import { declarationEntrances, type FrameGraphDebugViewModel } from './debugCaptureModel.ts';
 
 export { GRAPH_VISUAL_THEME } from './panelVisualTheme.ts';
 
@@ -16,76 +17,75 @@ export const GRAPH_GEOMETRY = {
     groupPadding: 32,
     elkGroupPadding: { top: 46, right: 24, bottom: 24, left: 24 },
     edgeCornerRadius: 6,
+    outputWidth: 208,
+    outputTipWidth: 24,
+    outputLabelWidth: 160,
 } as const;
 
 const ENDPOINT_EDGE_DISTANCES = 'endpoints' as unknown as cytoscape.Css.Edge['edge-distances'];
 const EDGE_SEGMENT_RADII = `${GRAPH_GEOMETRY.edgeCornerRadius}px` as unknown as cytoscape.Css.Edge['segment-radii'];
 
 export type GraphLegendEntry = {
+    readonly group: 'Execution' | 'Resources' | 'Relationships';
     readonly key: string;
     readonly label: string;
     readonly color: string;
-    readonly shape: 'box' | 'ellipse' | 'group' | 'line';
+    readonly shape: 'box' | 'cut-rectangle' | 'tag' | 'ellipse' | 'group' | 'line';
     readonly lineStyle?: 'solid' | 'dotted' | 'dashed';
     readonly hollowArrow?: boolean;
 };
 
-const NODE_LEGEND_ENTRIES = {
-    render: nodeLegend('render', 'Render', GRAPH_VISUAL_THEME.render.stroke),
-    compute: nodeLegend('compute', 'Compute', GRAPH_VISUAL_THEME.compute.stroke),
-    copy: nodeLegend('copy', 'Copy', GRAPH_VISUAL_THEME.copy.stroke),
-    'clear-buffer': nodeLegend('clear', 'Clear', GRAPH_VISUAL_THEME.clear.stroke),
-    command: nodeLegend('command', 'Command', GRAPH_VISUAL_THEME.command.stroke),
-    'external-submission': nodeLegend('external', 'External', GRAPH_VISUAL_THEME.external.stroke),
-} as const;
+export function createGraphLegend(snapshot: FrameGraphDebugViewModel, theme: GraphVisualTheme = GRAPH_VISUAL_THEME, showResourceDeclarations = true): readonly GraphLegendEntry[] {
+    const nodeEntries = {
+        render: nodeLegend('render', 'Render', theme.render.stroke),
+        compute: nodeLegend('compute', 'Compute', theme.compute.stroke),
+        copy: nodeLegend('copy', 'Copy', theme.copy.stroke),
+        'clear-buffer': nodeLegend('clear', 'Clear', theme.clear.stroke),
+        command: nodeLegend('command', 'Command', theme.command.stroke),
+        'external-submission': { ...nodeLegend('external', 'External', theme.external.stroke), shape: 'cut-rectangle' as const },
+    } as const;
 
-export function createGraphLegend(scene: GraphScene): readonly GraphLegendEntry[] {
     const entries: GraphLegendEntry[] = [];
-    const passKinds = new Set(scene.nodes.flatMap((node) => node.kind === 'pass' || node.kind === 'culled-pass'
-        ? [node.passKind]
-        : []));
+    const passKinds = new Set(snapshot.nodes.map((node) => node.kind));
     for (const kind of ['render', 'compute', 'copy', 'clear-buffer', 'command', 'external-submission'] as const) {
-        if (passKinds.has(kind)) entries.push(NODE_LEGEND_ENTRIES[kind]);
-    }
-    if (scene.nodes.some((node) => node.kind === 'group')) {
-        entries.push({ key: 'group', label: 'Group', color: GRAPH_VISUAL_THEME.group.stroke, shape: 'group' });
+        if (passKinds.has(kind)) entries.push(nodeEntries[kind]);
     }
-    if (scene.nodes.some((node) => node.kind === 'resource' && node.resourceKind === 'texture')) {
-        entries.push({ key: 'texture', label: 'Texture', color: GRAPH_VISUAL_THEME.texture.stroke, shape: 'ellipse' });
+    const retained = new Set(snapshot.nodes.map((node) => node.id));
+    const used = new Set([
+        ...snapshot.accessEdges.filter((access) => retained.has(access.nodeId)).map((access) => access.resource.id),
+        ...snapshot.roots.flatMap((root) => root.resource ? [root.resource.id] : []),
+    ]);
+    const resources = showResourceDeclarations ? snapshot.resources.filter((resource) => used.has(resource.id)) : [];
+    if (resources.length) entries.push({ group: 'Resources', key: 'declaration', label: 'Declaration', color: theme.declaration.stroke, shape: 'ellipse' });
+    if (snapshot.roots.some((root) => root.resource)) entries.push({ group: 'Resources', key: 'output', label: 'Output', color: theme.output.stroke, shape: 'tag' });
+    if ([...snapshot.nodes, ...resources].some((item) => item.debugGroupId !== undefined)) {
+        entries.push({ group: 'Relationships', key: 'group', label: 'Group', color: theme.group.stroke, shape: 'group' });
     }
-    if (scene.nodes.some((node) => node.kind === 'resource' && node.resourceKind === 'buffer')) {
-        entries.push({ key: 'buffer', label: 'Buffer', color: GRAPH_VISUAL_THEME.buffer.stroke, shape: 'ellipse' });
+    if (snapshot.edges.some((edge) => edge.kind === 'value')
+        || (showResourceDeclarations && declarationEntrances(snapshot.nodes, snapshot.accessEdges, snapshot.edges).length)
+        || snapshot.roots.some((root) => root.resource && root.resolution && ((showResourceDeclarations && root.resolution.usesInitialContents) || root.resolution.producerNodeIds.length))) {
+        entries.push(edgeLegend('flow', 'Resource Flow', theme.dependency.value, 'solid'));
     }
-    if (scene.nodes.some((node) => node.kind === 'culled-pass')) {
+    if (snapshot.edges.some((edge) => edge.kind === 'ordering')) {
         entries.push({
-            key: 'culled',
-            label: 'Culled',
-            color: GRAPH_VISUAL_THEME.culled.stroke,
-            shape: 'box',
-            lineStyle: 'dashed',
-        });
-    }
-    if (scene.edges.some((edge) => edge.kind === 'dependency' && edge.dependencyKind === 'value')) {
-        entries.push(edgeLegend('value', 'Value', GRAPH_VISUAL_THEME.dependency.value, 'solid'));
-    }
-    if (scene.edges.some((edge) => edge.kind === 'dependency' && edge.dependencyKind === 'ordering')) {
-        entries.push({
-            ...edgeLegend('ordering', 'Order', GRAPH_VISUAL_THEME.dependency.ordering, 'dotted'),
+            ...edgeLegend('ordering', 'Order', theme.dependency.ordering, 'dotted'),
             hollowArrow: true,
         });
     }
-    if (scene.edges.some((edge) => edge.kind === 'access' && edge.accessMode === 'read')) {
-        entries.push(edgeLegend('read', 'Read', GRAPH_VISUAL_THEME.access.read, 'solid'));
-    }
-    if (scene.edges.some((edge) => edge.kind === 'access' && edge.accessMode === 'write')) {
-        entries.push(edgeLegend('write', 'Write', GRAPH_VISUAL_THEME.access.write, 'solid'));
-    }
     return entries;
 }
 
-export function createGraphStyles(): cytoscape.StylesheetJson {
-    const theme = GRAPH_VISUAL_THEME;
+export function createGraphStyles(theme: GraphVisualTheme = GRAPH_VISUAL_THEME): cytoscape.StylesheetJson {
     return [
+        {
+            selector: 'core',
+            style: {
+                'active-bg-color': theme.activeBackground.color,
+                'active-bg-opacity': theme.activeBackground.opacity,
+                'active-bg-size': theme.activeBackground.size,
+            // Cytoscape accepts partial core styles; its Core type marks every property required.
+            } satisfies Partial<cytoscape.Css.Core> as cytoscape.Css.Core,
+        },
         {
             selector: 'node',
             style: {
@@ -94,14 +94,16 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
                 'height': 'data(height)',
                 'label': 'data(displayLabel)',
                 'text-wrap': 'wrap',
-                'text-max-width': '160px',
-                'font-family': 'ui-monospace, SFMono-Regular, Consolas, Liberation Mono, monospace',
-                'font-size': GRAPH_GEOMETRY.baseFontSize,
+                'text-max-width': 'data(labelMaxWidth)',
+                'font-family': theme.fontFamily,
+                'font-size': (element: cytoscape.SingularElementArgument) => (element.data('labelFontSize') as number | undefined) ?? theme.fontSize,
+                'line-height': 1.2,
                 'min-zoomed-font-size': GRAPH_GEOMETRY.minimumZoomedFontSize,
                 'color': theme.text,
                 'background-color': theme.surfaceRaised,
                 'border-color': theme.group.stroke,
-                'border-width': 1.25,
+                'border-width': theme.nodeBorderWidth,
+                'border-style': 'solid',
                 'text-valign': 'center',
                 'text-halign': 'center',
                 'overlay-opacity': 0,
@@ -118,34 +120,28 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
             style: {
                 'background-color': theme.external.fill,
                 'border-color': theme.external.stroke,
-                'border-style': 'double',
-                'border-width': 3,
+                'shape': 'cut-rectangle',
+                'corner-radius': '10px',
             },
         },
         {
-            selector: 'node[kind = "culled-pass"]',
-            style: {
-                'background-color': theme.culled.fill,
-                'border-color': theme.culled.stroke,
-                'color': theme.muted,
-                'border-style': 'dashed',
-                'opacity': 0.72,
-            },
-        },
-        {
-            selector: 'node[kind = "resource"][resourceKind = "texture"]',
+            selector: 'node[kind = "resource"]',
             style: {
                 'shape': 'ellipse',
-                'background-color': theme.texture.fill,
-                'border-color': theme.texture.stroke,
+                'background-color': theme.declaration.fill,
+                'border-color': theme.declaration.stroke,
             },
         },
         {
-            selector: 'node[kind = "resource"][resourceKind = "buffer"]',
+            selector: 'node[kind = "root"]',
             style: {
-                'shape': 'ellipse',
-                'background-color': theme.buffer.fill,
-                'border-color': theme.buffer.stroke,
+                'shape': 'polygon',
+                'shape-polygon-points': `-1 -1 ${1 - 2 * GRAPH_GEOMETRY.outputTipWidth / GRAPH_GEOMETRY.outputWidth} -1 1 0 ${1 - 2 * GRAPH_GEOMETRY.outputTipWidth / GRAPH_GEOMETRY.outputWidth} 1 -1 1`,
+                'background-color': theme.output.fill,
+                'border-color': theme.output.stroke,
+                'text-max-width': 'data(labelMaxWidth)',
+                // Keep a short tip and center the label in the rectangular body.
+                'text-margin-x': -GRAPH_GEOMETRY.outputTipWidth / 2 * theme.fontSize / GRAPH_GEOMETRY.baseFontSize,
             },
         },
         {
@@ -159,13 +155,13 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
             style: {
                 'background-color': theme.group.fill,
                 'border-color': theme.group.stroke,
-                'border-width': 2,
+                'border-width': theme.groupBorderWidth,
                 'color': theme.text,
             },
         },
         {
             selector: 'node[kind = "group"][collapsed = 0]',
-            style: expandedGroupStyle(theme.group.fill),
+            style: expandedGroupStyle(theme.group.fill, theme),
         },
         {
             selector: 'node[kind = "group"][collapsed = 0][depthBand = 1]',
@@ -174,16 +170,16 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
         {
             selector: 'edge',
             style: {
-                'width': 1.5,
+                'width': theme.edgeWidth,
                 'line-color': theme.dependency.value,
-                'line-opacity': 0.82,
+                'line-opacity': theme.edgeOpacity,
                 'target-arrow-color': theme.dependency.value,
                 'target-arrow-shape': 'triangle',
                 'target-arrow-fill': 'filled',
-                'arrow-scale': 0.8,
+                'arrow-scale': theme.arrowScale,
                 'curve-style': 'straight',
                 'label': 'data(displayLabel)',
-                'font-family': 'ui-monospace, SFMono-Regular, Consolas, Liberation Mono, monospace',
+                'font-family': theme.fontFamily,
                 'font-size': 10,
                 'min-zoomed-font-size': GRAPH_GEOMETRY.minimumZoomedFontSize,
                 'color': theme.text,
@@ -196,33 +192,15 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
             },
         },
         {
-            selector: 'edge[dependencyKind = "ordering"]',
+            selector: 'edge[kind = "ordering"]',
             style: {
                 'line-color': theme.dependency.ordering,
                 'target-arrow-color': theme.dependency.ordering,
                 'line-style': 'dotted',
                 'target-arrow-fill': 'hollow',
-                'line-opacity': 0.72,
-            },
-        },
-        {
-            selector: 'edge[accessMode = "read"]',
-            style: {
-                'line-color': theme.access.read,
-                'target-arrow-color': theme.access.read,
+                'line-opacity': theme.orderingOpacity,
             },
         },
-        {
-            selector: 'edge[accessMode = "write"]',
-            style: {
-                'line-color': theme.access.write,
-                'target-arrow-color': theme.access.write,
-            },
-        },
-        {
-            selector: 'edge[dashed = 1]',
-            style: { 'line-style': 'dashed', 'line-opacity': 0.46, 'opacity': 0.58 },
-        },
         {
             selector: 'edge.elk-route',
             style: {
@@ -244,7 +222,7 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
             selector: 'node.semantic-hover',
             style: {
                 'border-color': theme.hover,
-                'border-width': 2,
+                'border-width': theme.hoverWidth,
                 'z-index': 15,
             },
         },
@@ -254,7 +232,7 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
                 'line-color': theme.hover,
                 'target-arrow-color': theme.hover,
                 'line-opacity': 1,
-                'width': 2.5,
+                'width': theme.hoverWidth,
                 'z-index': 15,
             },
         },
@@ -262,10 +240,7 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
             selector: 'node.semantic-selected',
             style: {
                 'border-color': theme.selected,
-                'border-width': 3,
-                'underlay-color': theme.selected,
-                'underlay-padding': 5,
-                'underlay-opacity': 0.18,
+                'border-width': theme.selectedWidth,
                 'opacity': 1,
                 'z-index': 20,
             },
@@ -276,50 +251,108 @@ export function createGraphStyles(): cytoscape.StylesheetJson {
                 'line-color': theme.selected,
                 'target-arrow-color': theme.selected,
                 'line-opacity': 1,
-                'width': 3,
+                'width': theme.selectedWidth,
                 'z-index': 20,
             },
         },
     ];
 }
 
-export function nodeDimensions(node: GraphSceneNode): { readonly width: number; readonly height: number } {
+function baseNodeDimensions(node: GraphSceneNode): { readonly width: number; readonly height: number } {
     switch (node.kind) {
         case 'pass':
             return { width: 184, height: node.label.includes('\n') ? 62 : 48 };
-        case 'culled-pass':
-            return { width: 184, height: 64 };
+        case 'root':
+            return { width: GRAPH_GEOMETRY.outputWidth, height: Math.max(58, node.label.split('\n').length * 17 + 24) };
         case 'resource':
-            return { width: 166, height: node.label.includes('\n') ? 58 : 46 };
+            return { width: 184, height: Math.max(58, node.label.split('\n').length * 17 + 24) };
         case 'group':
-            return node.collapsed ? { width: 224, height: 68 } : { width: 120, height: 80 };
+            return node.collapsed ? { width: 240, height: 80 } : { width: 120, height: 80 };
     }
 }
 
+export function nodeDimensions(node: GraphSceneNode, theme: GraphVisualTheme = GRAPH_VISUAL_THEME): { readonly width: number; readonly height: number } {
+    const base = baseNodeDimensions(node);
+    const scale = theme.fontSize / GRAPH_GEOMETRY.baseFontSize;
+    return { width: base.width * scale, height: base.height * scale };
+}
+
+/** Enlarge short labels within the existing box; retain the theme size for dense text. */
+export function graphLabelFontSize(label: string, width: number, height: number, theme: GraphVisualTheme): number {
+    const context = graphTextContext();
+    if (context) context.font = theme.fontSize + 'px ' + theme.fontFamily;
+    const lines = label.split('\n');
+    const widest = Math.max(1, ...lines.map(line => context?.measureText(line).width ?? [...line].length * theme.fontSize * .62));
+    const widthScale = width / widest;
+    const heightScale = height / (lines.length * theme.fontSize * 1.2);
+    return Math.max(theme.fontSize, Math.floor(theme.fontSize * Math.min(1.25, widthScale, heightScale) * 4) / 4);
+}
+
+/** Wrap only the group name (up to two lines); keep the node-count row distinct. */
+export function fitCollapsedGroupLabel(label: string, width: number, theme: GraphVisualTheme): string {
+    const [name = '', ...summary] = label.split('\n');
+    const context = graphTextContext();
+    if (context) context.font = theme.fontSize + 'px ' + theme.fontFamily;
+    const measure = (text: string) => context?.measureText(text).width ?? [...text].length * theme.fontSize * .62;
+    const chars = [...name];
+    let split = 0;
+    while (split < chars.length && measure(chars.slice(0, split + 1).join('')) <= width) split++;
+    if (split === chars.length) return fitGraphLabel(label, width, theme);
+    // Prefer a word/path boundary without losing characters, including Unicode.
+    const prefix = chars.slice(0, split).join('');
+    const boundary = Math.max(prefix.lastIndexOf(' '), prefix.lastIndexOf('.'), prefix.lastIndexOf('/'));
+    if (boundary > prefix.length / 2) split = [...prefix.slice(0, boundary + 1)].length;
+    return fitGraphLabel([
+        chars.slice(0, split).join('').trimEnd(),
+        chars.slice(split).join('').trimStart(),
+        ...summary,
+    ].join('\n'), width, theme);
+}
+
+/** Fit the already semantic label to its available width after font changes. */
+export function fitGraphLabel(label: string, width: number, theme: GraphVisualTheme): string {
+    const context = graphTextContext();
+    if (context) context.font = theme.fontSize + 'px ' + theme.fontFamily;
+    const measure = (text: string) => context?.measureText(text).width ?? [...text].length * theme.fontSize * .62;
+    return label.split('\n').map(line => {
+        if (measure(line) <= width) return line;
+        const chars = [...line];
+        while (chars.length && measure(chars.join('') + '…') > width) chars.pop();
+        return chars.join('') + '…';
+    }).join('\n');
+}
+
+let textContext: CanvasRenderingContext2D | null | undefined;
+function graphTextContext(): CanvasRenderingContext2D | null {
+    if (typeof document === 'undefined') return null;
+    if (textContext === undefined) textContext = document.createElement('canvas').getContext('2d');
+    return textContext;
+}
+
 export function graphLayoutGeometryKey(scene: GraphScene): string {
     return JSON.stringify({
         topology: scene.topologyKey,
         dimensions: scene.nodes.map((node) => {
             const dimensions = nodeDimensions(node);
-            return [node.id, dimensions.width, dimensions.height];
+            return [node.id, dimensions.width, dimensions.height, node.kind === 'pass' && node.passKind === 'external-submission'];
         }),
     });
 }
 
-export function graphEdgeDisplayLabel(edge: GraphSceneEdge): string {
-    return edge.kind === 'access' ? '' : edge.label ?? '';
+export function graphEdgeDisplayLabel(_edge: GraphSceneEdge): string {
+    return '';
 }
 
 export function expandedGroupLabelMaxWidth(outerWidth: number): number {
     return Math.max(80, Math.floor(outerWidth - GRAPH_GEOMETRY.groupTitleInset * 2));
 }
 
-export function isOverviewGraphScale(zoom: number): boolean {
-    return GRAPH_GEOMETRY.baseFontSize * zoom < GRAPH_GEOMETRY.overviewFontThreshold;
+export function isOverviewGraphScale(zoom: number, theme: GraphVisualTheme = GRAPH_VISUAL_THEME): boolean {
+    return theme.fontSize * zoom < GRAPH_GEOMETRY.overviewFontThreshold;
 }
 
 function nodeLegend(key: string, label: string, color: string): GraphLegendEntry {
-    return { key, label, color, shape: 'box' };
+    return { group: 'Execution', key, label, color, shape: 'box' };
 }
 
 function edgeLegend(
@@ -328,7 +361,7 @@ function edgeLegend(
     color: string,
     lineStyle: NonNullable<GraphLegendEntry['lineStyle']>,
 ): GraphLegendEntry {
-    return { key, label, color, shape: 'line', lineStyle };
+    return { group: 'Relationships', key, label, color, shape: 'line', lineStyle };
 }
 
 function passStyle(
@@ -341,15 +374,16 @@ function passStyle(
     };
 }
 
-function expandedGroupStyle(backgroundColor: string): cytoscape.Css.Node {
+function expandedGroupStyle(backgroundColor: string, theme: GraphVisualTheme): cytoscape.Css.Node {
     const geometry = GRAPH_GEOMETRY;
     return {
         'background-color': backgroundColor,
-        'background-opacity': 0.34,
-        'border-color': GRAPH_VISUAL_THEME.group.stroke,
-        'border-width': 1.5,
+        'background-opacity': theme.groupOpacity,
+        'border-color': theme.group.stroke,
+        'border-width': theme.groupBorderWidth,
         'padding': `${geometry.groupPadding}px`,
-        'compound-sizing-wrt-labels': 'include',
+        'compound-sizing-wrt-labels': 'exclude',
+        'text-wrap': 'ellipsis',
         'min-width': '120px',
         'min-height': '80px',
         'text-valign': 'top-inside',
@@ -358,7 +392,7 @@ function expandedGroupStyle(backgroundColor: string): cytoscape.Css.Node {
         'text-margin-x': geometry.groupTitleInset - geometry.groupPadding * 2,
         'text-margin-y': geometry.groupTitleInset - geometry.groupPadding * 2,
         'line-height': geometry.groupTitleLineHeight,
-        'color': GRAPH_VISUAL_THEME.text,
+        'color': theme.text,
         'font-weight': 600,
     };
 }