@zenfg/inspector 0.1.0-beta.3 → 0.1.0

package/src/panelWorkbenchView.ts

@@ -12,8 +12,10 @@ import { MemoryView } from './panelMemoryView.ts';
 import { PassesView } from './panelPassesView.ts';
 import { ResourcesView } from './panelResourcesView.ts';
 import { renderGraphView, resizeGraph } from './panelGraphView.ts';
+import { DetailLayout } from './panelDetailLayout.ts';
+import { GraphSearch } from './panelGraphSearch.ts';
 import type { GraphViewState, Selection, WorkbenchTab } from './panelTypes.ts';
-import { formatEstimatedBytes, type WorkbenchCallbacks } from './panelWorkbenchHelpers.ts';
+import { enableTabKeyboard, formatEstimatedBytes, formatEstimateCoverage, formatTimingCoverage, type WorkbenchCallbacks } from './panelWorkbenchHelpers.ts';
 
 export type FrameGraphDebugWorkbenchActions = {
 	onCapture(): void;
@@ -47,6 +49,8 @@ export class FrameGraphDebugWorkbench {
 	private readonly tabList = document.createElement('div');
 	private readonly commandActions = document.createElement('div');
 	private readonly commandStatus = document.createElement('span');
+	private readonly feedback = document.createElement('details');
+	private readonly feedbackTitle = document.createElement('summary');
 	private readonly workspace = document.createElement('div');
 	private readonly main = document.createElement('main');
 	private readonly emptyHost = document.createElement('div');
@@ -57,6 +61,10 @@ export class FrameGraphDebugWorkbench {
 	private readonly memory: MemoryView;
 	private readonly diagnostics: DiagnosticsView;
 	private readonly inspector: InspectorView;
+	private readonly detailLayout: DetailLayout;
+	private readonly graphSearch: GraphSearch;
+	private readonly dirtyViews = new Set<WorkbenchTab>();
+	private readonly captureDetails = document.createElement('details');
 	private readonly inspectorOpenButton = document.createElement('button');
 	private readonly captureButton = document.createElement('button');
 	private readonly importButton = document.createElement('button');
@@ -72,6 +80,7 @@ export class FrameGraphDebugWorkbench {
 	private snapshot: FrameGraphDebugViewModel | undefined;
 	private selected: Selection | undefined;
 	private hovered: Selection | undefined;
+	private destroyed = false;
 
 	constructor(
 		private readonly graphView: GraphViewState,
@@ -94,7 +103,7 @@ export class FrameGraphDebugWorkbench {
 		this.commandStatus.className = 'zenfg-inspector-command-status';
 		this.commandStatus.setAttribute('role', 'status');
 		this.commandStatus.setAttribute('aria-live', 'polite');
-		this.workspace.className = 'zenfg-inspector-workspace inspector-open';
+		this.workspace.className = 'zenfg-inspector-workspace';
 		this.main.className = 'zenfg-inspector-main';
 		this.emptyHost.className = 'zenfg-inspector-workbench-empty';
 		this.emptyHost.setAttribute('role', 'status');
@@ -107,12 +116,25 @@ export class FrameGraphDebugWorkbench {
 		this.graphRoot.className = 'zenfg-inspector-view zenfg-inspector-graph-view';
 		this.graphRoot.id = `${options.idPrefix}-view-graph`;
 		this.graphRoot.setAttribute('role', 'tabpanel');
-		this.graphRoot.append(this.graphView.toolbar, this.graphView.host);
+		const graphViewport = document.createElement('div');
+		graphViewport.className = 'zenfg-inspector-graph-viewport';
+		graphViewport.append(this.graphView.host, this.graphView.toolbar);
+		if (this.graphView.legend) {
+			const legend = document.createElement('details');
+			legend.className = 'zenfg-inspector-legend-details';
+			const title = document.createElement('summary');
+			title.textContent = 'Legend';
+			legend.append(title, this.graphView.legend);
+			graphViewport.append(legend);
+		}
+		this.graphRoot.append(graphViewport);
 		this.passes = new PassesView(callbacks, options.idPrefix);
 		this.resources = new ResourcesView(callbacks, options.idPrefix);
 		this.memory = new MemoryView(callbacks, options.idPrefix);
 		this.diagnostics = new DiagnosticsView(callbacks, options.idPrefix);
 		this.inspector = new InspectorView(callbacks, (open) => this.handleInspectorOpenChange(open), options.idPrefix);
+		this.graphSearch = new GraphSearch((selection) => callbacks.onReveal?.(selection, 'graph'), `${options.idPrefix}-graph-search`);
+		this.graphView.toolbar.prepend(this.graphSearch.root);
 
 		this.views.set('overview', this.overviewRoot);
 		this.views.set('graph', this.graphRoot);
@@ -138,6 +160,7 @@ export class FrameGraphDebugWorkbench {
 			this.tabButtons.set(tab, button);
 			this.tabList.appendChild(button);
 		}
+		enableTabKeyboard(this.tabList);
 
 		this.inspectorOpenButton.type = 'button';
 		this.inspectorOpenButton.hidden = true;
@@ -191,7 +214,6 @@ export class FrameGraphDebugWorkbench {
 		this.exportMenu.append(this.downloadButton, this.copyButton);
 
 		this.commandActions.append(
-			this.commandStatus,
 			this.inspectorOpenButton,
 			this.captureButton,
 			this.importButton,
@@ -206,14 +228,15 @@ export class FrameGraphDebugWorkbench {
 			const targetNode = target as Node;
 			if (!this.exportButton.contains(targetNode) && !this.exportMenu.contains(targetNode)) this.setExportMenuOpen(false);
 		});
-		this.root.addEventListener('keydown', (event) => {
-			if (event.key !== 'Escape' || this.exportMenu.hidden) return;
-			this.setExportMenuOpen(false);
-			this.exportButton.focus();
-		});
+		this.root.addEventListener('keydown', (event) => this.handleMenuKey(event));
 		this.main.append(this.emptyHost, ...this.views.values());
 		this.workspace.append(this.main, this.inspector.root);
-		this.root.append(this.commandBar, this.workspace);
+		this.feedback.className = 'zenfg-inspector-feedback';
+		this.feedback.hidden = true;
+		this.feedback.append(this.feedbackTitle, this.commandStatus);
+		this.root.append(this.commandBar, this.feedback, this.workspace);
+		this.detailLayout = new DetailLayout(this.workspace, this.main, this.inspector.root, this.commandBar, () => this.inspector.setOpen(false));
+		this.workspace.addEventListener('detail-layout-change', () => this.resizeGraph());
 		this.showEmptyState('empty', 'Drop a ZenFG Snapshot here or choose Import.', 'Files are processed locally in your browser.');
 		this.setSnapshotActionState({
 			providerAvailable: false,
@@ -230,18 +253,13 @@ export class FrameGraphDebugWorkbench {
 		this.snapshot = snapshot;
 		this.selected = selected;
 		this.hovered = undefined;
-		this.renderSummary(snapshot);
-		this.passes.setSnapshot(snapshot);
-		this.resources.setSnapshot(snapshot);
-		this.memory.setSnapshot(snapshot);
-		this.diagnostics.setSnapshot(snapshot);
+		for (const tab of this.views.keys()) this.dirtyViews.add(tab);
+		this.renderDiagnosticBadge(snapshot);
+		this.graphSearch.setSnapshot(snapshot);
 		this.inspector.setSnapshot(snapshot);
-		this.passes.setSelection(selected);
-		this.resources.setSelection(selected);
-		this.memory.setSelection(selected);
-		this.diagnostics.setSelection(selected);
 		this.inspector.setSelection(selected, false);
 		this.emptyHost.hidden = true;
+		this.ensureActiveView();
 		this.updateActiveTab();
 		this.updateWorkspaceState();
 		if (this.activeTab === 'graph') this.renderGraph();
@@ -303,14 +321,14 @@ export class FrameGraphDebugWorkbench {
 		this.commandStatus.dataset.tone = state.message ? state.messageTone ?? 'error' : 'neutral';
 		if (state.message) this.commandStatus.title = state.message;
 		else this.commandStatus.removeAttribute('title');
-	}
+		this.feedback.hidden = !state.message;
+		this.feedback.dataset.tone = state.messageTone ?? 'neutral';
+		this.feedbackTitle.textContent = state.message ? state.messageTone === 'error' ? 'Operation failed · show details' : 'Operation feedback · show details' : '';
+	}
 
 	setSelection(selected: Selection | undefined): void {
 		this.selected = selected;
-		this.passes.setSelection(selected);
-		this.resources.setSelection(selected);
-		this.memory.setSelection(selected);
-		this.diagnostics.setSelection(selected);
+		this.updateActiveSelection();
 		this.inspector.setSelection(selected);
 		if (this.activeTab === 'graph') this.renderGraph();
 	}
@@ -321,11 +339,19 @@ export class FrameGraphDebugWorkbench {
 	}
 
 	setActiveTab(tab: WorkbenchTab): void {
+		if (this.destroyed) return;
 		if (this.activeTab === tab) return;
+		if (this.activeTab === 'graph') {
+			this.graphView.revealOnNextRender = undefined;
+			this.graphView.renderer?.cancelReveal?.();
+		}
 		this.activeTab = tab;
 		this.updateActiveTab();
+		this.ensureActiveView();
+		this.updateWorkspaceState();
 		if (tab === 'graph') {
 			window.requestAnimationFrame(() => {
+				if (this.destroyed || this.activeTab !== 'graph') return;
 				resizeGraph(this.graphView);
 				this.renderGraph();
 			});
@@ -334,13 +360,13 @@ export class FrameGraphDebugWorkbench {
 
 	refreshGraphStructure(): void {
 		if (!this.snapshot) return;
-		this.passes.setSnapshot(this.snapshot);
 		if (this.activeTab === 'graph') this.renderGraph();
 	}
 
 	resizeGraph(fit = false): void {
 		if (fit) this.graphView.fitOnNextRender = true;
 		window.requestAnimationFrame(() => {
+			if (this.destroyed) return;
 			resizeGraph(this.graphView);
 			if (this.activeTab === 'graph') this.renderGraph();
 		});
@@ -352,6 +378,7 @@ export class FrameGraphDebugWorkbench {
 			button.disabled = !this.hasSnapshot;
 			button.classList.toggle('active', active);
 			button.setAttribute('aria-selected', active ? 'true' : 'false');
+			button.tabIndex = active ? 0 : -1;
 			const view = this.views.get(tab)!;
 			view.hidden = !this.hasSnapshot || !active;
 			view.setAttribute('aria-labelledby', button.id);
@@ -375,9 +402,7 @@ export class FrameGraphDebugWorkbench {
 		const frameGraphSegments = snapshot.executionSegments.filter((segment) => segment.kind === 'frame-graph').length;
 		const opaqueIntervals = snapshot.executionSegments.length - frameGraphSegments;
 		const metrics = snapshot.metrics;
-		const coverage = metrics.timingEligibleNodeCount === 0
-			? 'No eligible passes'
-			: `${metrics.timedNodeCount}/${metrics.timingEligibleNodeCount} timed`;
+		const coverage = formatTimingCoverage(metrics.timedNodeCount, metrics.timingEligibleNodeCount);
 		const slowest = metrics.slowestNode
 			? `${labelNode(metrics.slowestNode)} · ${(metrics.slowestNode.gpuDurationMicros! / 1000).toFixed(3)} ms`
 			: 'Unknown';
@@ -394,41 +419,55 @@ export class FrameGraphDebugWorkbench {
 		const poolRetained = snapshot.resourcePool.status === 'available'
 			? `${snapshot.resourcePool.estimatedRetainedBytes === undefined ? 'Unknown' : formatBytes(snapshot.resourcePool.estimatedRetainedBytes)} · ${snapshot.resourcePool.retainedCount} allocations`
 			: 'Unavailable';
+		const counts = this.diagnosticCounts(snapshot);
 		this.summary.replaceChildren(
-			this.createSummaryGroup('Capture', [
-				['Source', snapshot.source.label],
-				['Schema', `${protocol.format} v${protocol.version.major}.${protocol.version.minor}`],
-				['Producer', producer],
-				['Runtime', runtimeLabel],
-				['Frame', String(snapshot.frameIndex)],
-				...(snapshot.source.migratedFromLegacy ? [['Migration', 'Legacy V0 → V1'] as const] : []),
-				['Timing', snapshot.profiling.status === 'available' ? 'Available' : snapshot.profiling.reason],
-			]),
-			this.createSummaryGroup('GPU', [
-				['GPU Span', snapshot.profiling.status === 'available' ? `${formatGpuFrameDuration(snapshot)} ms` : 'Unknown'],
-				['Coverage', coverage],
-				['Slowest', slowest],
-			]),
+			this.createSummaryGroup('Diagnostics', [
+				['Errors', String(counts.error)], ['Warnings', String(counts.warning)], ['Information', String(counts.info)],
+			], () => this.setActiveTab('diagnostics')),
+			this.createSummaryGroup('Execution timing', [
+				['CPU execute', snapshot.cpuProfiling.status === 'available' ? (snapshot.cpuProfiling.executionDurationMicros / 1000).toFixed(3) + ' ms' : 'Not collected'],
+				['CPU pass sum', snapshot.metrics.cpuTimedNodeCount ? (snapshot.metrics.cpuWorkDurationMicros / 1000).toFixed(3) + ' ms' : 'Not collected'],
+				['CPU coverage', formatTimingCoverage(snapshot.metrics.cpuTimedNodeCount, snapshot.nodes.length)],
+				['GPU span', snapshot.profiling.status === 'available' ? `${formatGpuFrameDuration(snapshot)} ms` : 'Not collected'],
+				['GPU coverage', coverage],
+				['Slowest GPU pass', slowest],
+			], () => metrics.slowestNode ? this.callbacks.onReveal?.({ kind: 'node', id: metrics.slowestNode.id }, 'passes') : this.setActiveTab('passes')),
 			this.createSummaryGroup('Work', [
 				['Nodes', `${snapshot.nodes.length} retained · ${snapshot.culledNodes.length} culled`],
 				['Segments', `${frameGraphSegments} FG · ${opaqueIntervals} opaque`],
 				['Groups', snapshot.availability.groups ? String(snapshot.debugGroups.length) : 'Unknown'],
 				['Recording order', snapshot.availability.recordingOrder ? 'Available' : 'Unknown'],
-			]),
+			], () => this.setActiveTab('passes')),
 			this.createSummaryGroup('Resources', [
-				['Logical / physical', `${snapshot.resources.length} / ${snapshot.physicalAllocations.length}`],
+				['Logical / physical', `${snapshot.resources.length} / ${protocol.memory.allocationReport.status === 'available' ? snapshot.physicalAllocations.length : 'Unavailable'}`],
 				['Texture views', snapshot.availability.textureViews ? String(snapshot.textureViewById.size) : 'Unknown'],
 				['Access regions', snapshot.availability.accessRegions ? 'Available' : 'Unknown'],
-				['Transient estimate', formatEstimatedBytes(metrics.transientEstimatedByteSize)],
-			]),
+				['Transient estimate', formatEstimateCoverage(metrics.transientEstimatedByteSize, metrics.estimatedCoverage.transient)],
+			], () => this.setActiveTab('resources')),
+			this.createSummaryGroup('Memory estimates', [
+				['Physical allocations', protocol.memory.allocationReport.status === 'available' ? formatEstimateCoverage(metrics.physicalEstimatedBytes, metrics.estimatedCoverage.physical) : 'Unavailable'],
+				['Alias reuse', protocol.memory.allocationReport.status === 'available' ? formatEstimatedBytes(metrics.aliasReuseBytes) : 'Unavailable'],
+			], () => this.setActiveTab('memory')),
 			this.createSummaryGroup('Pool', [
 				['Retained', poolRetained],
 				['Reuse', formatPoolHitRate(snapshot)],
-			]),
+			], () => this.setActiveTab('memory')),
 		);
+		const title = document.createElement('summary');
+		title.textContent = 'Capture information';
+		this.captureDetails.className = 'zenfg-inspector-capture-details';
+		this.captureDetails.replaceChildren(title, this.createSummaryGroup('Capture', [
+			['Source', snapshot.source.label], ['Frame', String(snapshot.frameIndex)],
+			['Captured at', protocol.capture.capturedAt ?? 'Unknown'],
+			['Schema', `${protocol.format} v${protocol.version.major}.${protocol.version.minor}`],
+			['Producer', producer], ['Runtime', runtimeLabel],
+			...(protocol.capture.migration ? [['Migration', `${protocol.capture.migration.sourceFormat} → canonical v${protocol.version.major}.${protocol.version.minor}`] as const] : []),
+			['Timing', snapshot.profiling.status === 'available' ? coverage : snapshot.profiling.reason],
+		]));
+		this.summary.append(this.captureDetails);
 	}
 
-	private createSummaryGroup(title: string, rows: readonly (readonly [string, string])[]): HTMLElement {
+	private createSummaryGroup(title: string, rows: readonly (readonly [string, string])[], onNavigate?: () => void): HTMLElement {
 		const group = document.createElement('section');
 		const heading = document.createElement('h2');
 		heading.textContent = title;
@@ -443,12 +482,21 @@ export class FrameGraphDebugWorkbench {
 			row.append(term, description);
 			group.appendChild(row);
 		}
+		if (onNavigate) {
+			const action = document.createElement('button');
+			action.type = 'button';
+			action.className = 'zenfg-inspector-relation-button';
+			action.textContent = `Explore ${title.toLowerCase()}`;
+			action.addEventListener('click', onNavigate);
+			group.append(action);
+		}
 		return group;
 	}
 
 	private setExportMenuOpen(open: boolean): void {
 		this.exportMenu.hidden = !open;
 		this.exportButton.setAttribute('aria-expanded', open ? 'true' : 'false');
+		if (open) this.downloadButton.focus();
 	}
 
 	private handleInspectorOpenChange(_open: boolean): void {
@@ -457,10 +505,111 @@ export class FrameGraphDebugWorkbench {
 	}
 
 	private updateWorkspaceState(): void {
-		const inspectorOpen = this.hasSnapshot && this.inspector.isOpen;
+		const inspectorOpen = this.hasSnapshot && this.inspector.isOpen && this.activeTab !== 'overview';
 		this.workspace.classList.toggle('has-capture', this.hasSnapshot);
-		this.workspace.classList.toggle('inspector-open', inspectorOpen);
-		this.inspector.root.classList.toggle('unavailable', !this.hasSnapshot);
-		this.inspectorOpenButton.hidden = !this.hasSnapshot || inspectorOpen;
+		this.inspector.root.classList.toggle('unavailable', !inspectorOpen);
+		this.inspectorOpenButton.hidden = !this.hasSnapshot || !this.selected || inspectorOpen || this.activeTab === 'overview';
+		this.detailLayout.update(inspectorOpen);
+	}
+
+	reveal(selection: Selection, tab: WorkbenchTab): void {
+		if (this.feedbackTitle.textContent === 'Graph location unavailable') {
+			this.feedback.hidden = true;
+			this.commandStatus.replaceChildren();
+			this.commandStatus.hidden = true;
+		}
+		this.setActiveTab(tab);
+		if (tab === 'passes') this.passes.reveal(selection);
+		else if (tab === 'resources') this.resources.reveal(selection);
+		else if (tab === 'memory') this.memory.reveal(selection);
+		else if (tab === 'diagnostics') this.diagnostics.reveal(selection);
+		if (this.detailLayout.isDrawer) this.inspector.setOpen(false);
+		if (tab === 'graph') this.renderGraph();
+	}
+
+	navigate(tab: WorkbenchTab, filter?: 'culled'): void {
+		this.setActiveTab(tab);
+		if (tab === 'passes' && filter === 'culled') this.passes.showCulled();
+		if (this.detailLayout.isDrawer) this.inspector.setOpen(false);
+	}
+
+	showNavigationIssue(message: string, selection: Selection): void {
+		if (this.detailLayout.isDrawer) this.inspector.setOpen(false);
+		this.feedback.hidden = false;
+		this.feedback.open = true;
+		this.feedback.dataset.tone = 'neutral';
+		this.feedbackTitle.textContent = 'Graph location unavailable';
+		const action = document.createElement('button');
+		action.type = 'button';
+		action.className = 'zenfg-inspector-relation-button';
+		const tab = selection.kind === 'resource' ? 'resources' : selection.kind === 'allocation' ? 'memory'
+			: selection.kind === 'root' || selection.kind === 'segment' ? 'diagnostics' : 'passes';
+		action.textContent = `Show in ${tab}`;
+		action.addEventListener('click', () => this.callbacks.onReveal?.(selection, tab));
+		this.commandStatus.hidden = false;
+		this.commandStatus.replaceChildren(document.createTextNode(`${message} `), action);
+		action.focus();
+	}
+
+	destroy(): void { this.destroyed = true; this.detailLayout.destroy(); }
+
+	private ensureActiveView(): void {
+		const snapshot = this.snapshot;
+		if (!snapshot) return;
+		if (this.dirtyViews.has(this.activeTab)) {
+			switch (this.activeTab) {
+				case 'overview': this.renderSummary(snapshot); break;
+				case 'passes': this.passes.setSnapshot(snapshot); break;
+				case 'resources': this.resources.setSnapshot(snapshot); break;
+				case 'memory': this.memory.setSnapshot(snapshot); break;
+				case 'diagnostics': this.diagnostics.setSnapshot(snapshot); break;
+			}
+			this.dirtyViews.delete(this.activeTab);
+		}
+		this.updateActiveSelection();
+	}
+
+	private updateActiveSelection(): void {
+		switch (this.activeTab) {
+			case 'passes': this.passes.setSelection(this.selected); break;
+			case 'resources': this.resources.setSelection(this.selected); break;
+			case 'memory': this.memory.setSelection(this.selected); break;
+			case 'diagnostics': this.diagnostics.setSelection(this.selected); break;
+		}
+	}
+
+	private diagnosticCounts(snapshot: FrameGraphDebugViewModel): Record<'error' | 'warning' | 'info', number> {
+		const counts = { error: 0, warning: 0, info: 0 };
+		for (const entry of snapshot.protocol.diagnostics) counts[entry.severity]++;
+		return counts;
+	}
+
+	private renderDiagnosticBadge(snapshot: FrameGraphDebugViewModel): void {
+		const counts = this.diagnosticCounts(snapshot);
+		const tab = this.tabButtons.get('diagnostics')!;
+		const label = document.createElement('span');
+		label.textContent = 'Diagnostics';
+		const badge = document.createElement('span');
+		badge.className = 'zenfg-inspector-diagnostic-badge';
+		badge.textContent = `${counts.error} / ${counts.warning}`;
+		badge.title = `${counts.error} errors, ${counts.warning} warnings`;
+		badge.setAttribute('aria-hidden', 'true');
+		tab.replaceChildren(label, ...(counts.error + counts.warning ? [badge] : []));
+		tab.title = badge.title;
+	}
+
+	private handleMenuKey(event: KeyboardEvent): void {
+		if (this.exportMenu.hidden || event.defaultPrevented) return;
+		if (event.key === 'Escape') {
+			event.preventDefault(); event.stopPropagation();
+			this.setExportMenuOpen(false); this.exportButton.focus();
+		} else if (['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) {
+			event.preventDefault(); event.stopPropagation();
+			const items = [this.downloadButton, this.copyButton].filter((button) => !button.disabled);
+			const index = items.indexOf(document.activeElement as HTMLButtonElement);
+			const next = event.key === 'Home' ? 0 : event.key === 'End' ? items.length - 1
+				: (index + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length;
+			items[next]?.focus();
+		}
 	}
 }

package/src/query.ts

@@ -9,14 +9,14 @@ export const ZENFG_INSPECTOR_QUERY_PARAM = 'fg';
  * @returns `false` when no URL is available or the supplied URL is invalid.
  */
 export function isZenFGInspectorRequested(href = globalThis.location?.href): boolean {
-    if (!href) {
-        return false;
-    }
-
-    try {
-        return new URL(href).searchParams.has(ZENFG_INSPECTOR_QUERY_PARAM);
-    }
-    catch {
-        return false;
-    }
-}
+    if (!href) {
+        return false;
+    }
+
+    try {
+        return new URL(href).searchParams.has(ZENFG_INSPECTOR_QUERY_PARAM);
+    }
+    catch {
+        return false;
+    }
+}