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

package/src/FrameGraphInspector.ts

@@ -1,3 +1,6 @@
+import type { FrameGraphCaptureRequest } from './capture.ts';
+import type { InspectorTheme } from './theme.ts';
+import { InspectorThemeController, resolveGraphTheme } from './panelTheme.ts';
 import {
 	FrameGraphSnapshotValidationError,
 	decodeFrameGraphSnapshot,
@@ -11,20 +14,23 @@ import {
 	type FrameGraphDebugViewModel,
 } from './debugCaptureModel.ts';
 import { createToolbarButton } from './panelDomHelpers.ts';
-import { createPanelIcon } from './panelIcons.ts';
 import {
 	destroyGraph,
 	fitGraph,
+	resolveGraphScene,
+	renderGraphLegend,
 } from './panelGraphView.ts';
-import { graphGroupElementId } from './panelGraphScene.ts';
-import { selectionExists } from './panelSelection.ts';
-import type { GraphViewState, Selection } from './panelTypes.ts';
+import { graphGroupElementId, selectionKey } from './panelGraphScene.ts';
+import { resolveNodeSelection, selectionExists } from './panelSelection.ts';
+import type { GraphViewState, Selection, WorkbenchTab } from './panelTypes.ts';
 import { ensureFrameGraphInspectorStyles } from './styles.ts';
 import { sameSelection, type WorkbenchCallbacks } from './panelWorkbenchHelpers.ts';
 import { FrameGraphDebugWorkbench } from './panelWorkbenchView.ts';
 
 /** Construction and safety limits for an embedded {@link FrameGraphInspector}. */
 export type FrameGraphInspectorOptions = {
+	/** Optional CSS theme. Without one, host variables inherit over the Storm defaults. */
+	theme?: InspectorTheme;
 	/**
 	 * Product label shown in the workbench command bar. Pass `false` to hide
 	 * visible branding while retaining the inspector's accessible name.
@@ -36,7 +42,7 @@ export type FrameGraphInspectorOptions = {
 	 * Produces a live snapshot when capture is requested. The inspector awaits
 	 * promises and displays thrown or rejected errors in its status area.
 	 */
-	captureSnapshot?: () => FrameGraphSnapshot | undefined | Promise<FrameGraphSnapshot | undefined>;
+	captureSnapshot?: (request: FrameGraphCaptureRequest) => FrameGraphSnapshot | undefined | Promise<FrameGraphSnapshot | undefined>;
 	/**
 	 * Maximum accepted import size in bytes.
 	 *
@@ -74,13 +80,13 @@ const DEFAULT_BRANDING = 'ZenFG Inspector';
 export class FrameGraphInspector {
 	/** Root element owned by this inspector instance. */
 	readonly dom = document.createElement('section');
+	private readonly themeController = new InspectorThemeController(this.dom);
 
 	private readonly body = document.createElement('div');
 	private readonly content = document.createElement('div');
 	private readonly dropOverlay = document.createElement('div');
-	private readonly passesGraphModeButton: HTMLButtonElement;
-	private readonly resourcesGraphModeButton: HTMLButtonElement;
 	private readonly groupsButton: HTMLButtonElement;
+	private readonly declarationsButton: HTMLButtonElement;
 	private readonly collapseGroupsButton: HTMLButtonElement;
 	private readonly graphView: GraphViewState;
 	private readonly workbench: FrameGraphDebugWorkbench;
@@ -101,6 +107,7 @@ export class FrameGraphInspector {
 	private copyFeedbackTimeout: number | undefined;
 	private readonly maxImportBytes: number;
 	private dragDepth = 0;
+	private revealRevision = 0;
 	private readonly handleDragEnter = (event: DragEvent): void => {
 		if (!isFileDrag(event)) return;
 		event.preventDefault();
@@ -160,9 +167,10 @@ export class FrameGraphInspector {
 			host: document.createElement('div'),
 			toolbar: document.createElement('div'),
 			legend: graphLegend,
+			refreshTheme: () => this.refreshTheme(),
 			layoutElementBudget: normalizeLimit(options.maxGraphElements, DEFAULT_MAX_GRAPH_ELEMENTS, 'maxGraphElements'),
-			graphMode: 'passes',
 			groupsEnabled: true,
+			showResourceDeclarations: true,
 			expandedGroupPaths: new Set(),
 			fitOnNextRender: true,
 		};
@@ -171,32 +179,27 @@ export class FrameGraphInspector {
 		this.graphView.toolbar.setAttribute('role', 'toolbar');
 		this.graphView.toolbar.setAttribute('aria-label', 'Frame graph view controls');
 
-		this.passesGraphModeButton = createToolbarButton('Pass dependency', 'Show pass dependency graph', () => this.setGraphMode('passes'));
-		this.resourcesGraphModeButton = createToolbarButton('Resource access', 'Show resource access graph', () => this.setGraphMode('resources'));
+		this.declarationsButton = createToolbarButton('Declarations', 'Show resource declaration nodes', () => this.toggleDeclarations());
 		this.groupsButton = createToolbarButton('Groups', 'Toggle diagnostic group projection', () => this.toggleGroups());
 		this.collapseGroupsButton = createToolbarButton('Collapse All', 'Collapse every diagnostic group', () => this.collapseAllGroups());
-		this.passesGraphModeButton.classList.add('zenfg-inspector-mode-button');
-		this.resourcesGraphModeButton.classList.add('zenfg-inspector-mode-button');
-
-		const modeControls = document.createElement('div');
-		modeControls.className = 'zenfg-inspector-graph-mode-controls';
-		modeControls.setAttribute('role', 'group');
-		modeControls.setAttribute('aria-label', 'Graph mode');
-		modeControls.append(this.passesGraphModeButton, this.resourcesGraphModeButton);
+
 		const actionControls = document.createElement('div');
 		actionControls.className = 'zenfg-inspector-graph-action-controls';
 		actionControls.append(
+			this.declarationsButton,
 			this.groupsButton,
 			this.collapseGroupsButton,
-			createGraphIconButton('fit', 'Fit graph to view', () => fitGraph(this.graphView)),
+			createToolbarButton('Fit', 'Fit graph to view', () => fitGraph(this.graphView)),
 		);
-		this.graphView.toolbar.append(modeControls, graphLegend, actionControls);
+		this.graphView.toolbar.append(actionControls);
 
 		const callbacks: WorkbenchCallbacks = {
 			onSelect: (selection) => this.handleSelect(selection),
 			onHover: (selection) => this.handleHover(selection),
 			onGroupToggle: (pathKey) => this.toggleGroup(pathKey),
 			isGroupExpanded: (pathKey) => this.graphView.expandedGroupPaths.has(pathKey),
+			onReveal: (selection, tab) => this.handleReveal(selection, tab),
+			onNavigate: (tab, filter) => this.workbench.navigate(tab, filter),
 		};
 		this.workbench = new FrameGraphDebugWorkbench(this.graphView, callbacks, {
 			onCapture: () => { void this.captureSnapshot(); },
@@ -216,22 +219,49 @@ export class FrameGraphInspector {
 		this.dom.addEventListener('dragend', this.handleDragEnd);
 		this.dom.addEventListener('drop', this.handleDrop);
 		this.updateCaptureActions();
-		this.updateGraphModeButtonState();
+		this.updateGraphControls();
 		this.showEmptyState();
-		queueMicrotask(() => this.maybeAutoCapture());
+		if (options.theme) this.setTheme(options.theme);
+		queueMicrotask(() => { if (!this.destroyed) { this.refreshTheme(); this.maybeAutoCapture(); } });
 	}
 
+    /** Replace API-applied variables on this instance, then synchronize graph styles.
+     * Pass null to restore host CSS and defaults. Does not change capture or interaction state.
+     */
+    setTheme(theme: InspectorTheme | null): void {
+        if (this.destroyed) return;
+        this.themeController.apply(theme);
+        this.refreshTheme();
+    }
+
+    /** Re-read final CSS values after external CSS changes and refresh graph and legend.
+     * Does not write theme variables, recapture, fit, or rebuild the component.
+     */
+    refreshTheme(): void {
+        if (this.destroyed) return;
+        const theme = resolveGraphTheme(this.dom);
+        this.graphView.theme = theme;
+        this.graphView.renderer?.setTheme?.(theme);
+        if (this.viewModel) renderGraphLegend(this.graphView.legend, this.viewModel, theme, this.graphView.showResourceDeclarations);
+    }
+
 	/**
 	 * Replaces or removes the live-capture provider.
 	 *
 	 * @remarks Installing a provider may immediately begin an asynchronous
-	 * capture when no snapshot is displayed.
+	 * capture when no snapshot is displayed. Replacing or removing a provider
+	 * invalidates its pending capture results without cancelling the provider
+	 * promise. An already displayed snapshot and any pending import are preserved.
 	 */
 	setCaptureSnapshotProvider(provider: FrameGraphInspectorOptions['captureSnapshot']): void {
-		const changed = this.captureSnapshotCallback !== provider;
+		if (this.destroyed || this.captureSnapshotCallback === provider) return;
+		if (this.capturing) {
+			this.operationRevision += 1;
+			this.capturing = false;
+		}
 		this.captureSnapshotCallback = provider;
-		if (changed && !this.viewModel) this.initialAutoCaptureAttempted = false;
-		if (!provider && !this.viewModel) this.showEmptyState();
+		if (!this.viewModel) this.initialAutoCaptureAttempted = false;
+		if (!provider && !this.viewModel && !this.importing) this.showEmptyState();
 		this.updateCaptureActions();
 		this.maybeAutoCapture();
 	}
@@ -257,7 +287,8 @@ export class FrameGraphInspector {
 		if (!this.viewModel) this.workbench.showEmptyState('capturing', 'Capturing the next rendered frame…');
 		this.updateCaptureActions();
 		try {
-			const snapshot = await this.captureSnapshotCallback();
+			const request: FrameGraphCaptureRequest = { timing: 'both' };
+			const snapshot = await this.captureSnapshotCallback(request);
 			if (this.destroyed || revision !== this.operationRevision) return;
 			if (!snapshot) {
 				this.reportCaptureIssue('No snapshot was produced. Capture again when rendering is active.');
@@ -282,9 +313,9 @@ export class FrameGraphInspector {
 	}
 
 	/**
-	 * Validates and synchronously displays a programmatic Snapshot 1.0 value.
+	 * Validates and synchronously displays a programmatic Snapshot 1.2 value.
 	 *
-	 * @throws {@link FrameGraphSnapshotValidationError} if `snapshot` is invalid.
+	 * @throws {@link @zenfg/snapshot!index.FrameGraphSnapshotValidationError | FrameGraphSnapshotValidationError} if `snapshot` is invalid.
 	 */
 	setSnapshot(snapshot: FrameGraphSnapshot): void {
 		if (this.destroyed) return;
@@ -334,10 +365,17 @@ export class FrameGraphInspector {
 			});
 			const sourceFormat = decoded.snapshot.capture.migration?.sourceFormat;
 			if (sourceFormat) {
-				const sourceLabel = sourceFormat === 'legacy-v0' ? 'Legacy V0' : 'Legacy Candidate V1';
+				// The current import format can differ from retained historical provenance.
+				const sourceLabel = {
+					'legacy-v0': 'Legacy V0',
+					'legacy-candidate-v1': 'Legacy Candidate V1',
+					'snapshot-v1.1': 'Snapshot 1.1',
+				}[decoded.migrated && decoded.source !== 'v1' ? decoded.source : sourceFormat];
+				const version = decoded.snapshot.version;
+				const targetLabel = `Snapshot ${version.major}.${version.minor}`;
 				this.statusMessage = decoded.migrated
-					? `Imported ${sourceLabel} and migrated it to ZenFG Snapshot V1.`
-					: `Imported Snapshot V1 with ${sourceLabel} migration provenance.`;
+					? `Imported ${sourceLabel} and migrated it to ZenFG ${targetLabel}.`
+					: `Imported ${targetLabel} with ${sourceLabel} migration provenance.`;
 				this.statusTone = 'neutral';
 			}
 		}
@@ -413,18 +451,18 @@ export class FrameGraphInspector {
 		this.protocolSnapshot = snapshot;
 		this.viewModel = viewModel;
 		this.graphView.fitOnNextRender = true;
+		this.graphView.captureRevision = (this.graphView.captureRevision ?? 0) + 1;
+		this.graphView.revealOnNextRender = undefined;
+		this.graphView.renderer?.cancelReveal?.();
 		this.hovered = undefined;
 		this.initialAutoCaptureAttempted = true;
 		this.statusMessage = undefined;
 		this.statusTone = 'neutral';
-		if (!this.selected || !selectionExists(viewModel, this.selected)) {
-			this.selected = viewModel.nodes[0]
-				? { kind: 'node', id: viewModel.nodes[0].id }
-				: undefined;
-		}
+		if (this.selected?.kind === 'node' || this.selected?.kind === 'culled') this.selected = resolveNodeSelection(viewModel, this.selected.id);
+		else if (this.selected && !selectionExists(viewModel, this.selected)) this.selected = undefined;
 		this.workbench.setSnapshot(viewModel, this.selected);
 		this.updateCaptureActions();
-		this.updateGraphModeButtonState();
+		this.updateGraphControls();
 	}
 
 	/**
@@ -442,7 +480,9 @@ export class FrameGraphInspector {
 		this.dom.removeEventListener('dragleave', this.handleDragLeave);
 		this.dom.removeEventListener('dragend', this.handleDragEnd);
 		this.dom.removeEventListener('drop', this.handleDrop);
+		this.themeController.destroy();
 		destroyGraph(this.graphView);
+		this.workbench.destroy();
 		this.dom.remove();
 	}
 
@@ -472,59 +512,102 @@ export class FrameGraphInspector {
 		void this.captureSnapshot();
 	}
 	private handleSelect(selection: Selection): void {
+		if (!this.viewModel || !selectionExists(this.viewModel, selection)) return;
 		this.selected = selection;
 		this.workbench.setSelection(selection);
 	}
 
+	private handleReveal(selection: Selection, tab: WorkbenchTab): void {
+		const snapshot = this.viewModel;
+		if (!snapshot || !selectionExists(snapshot, selection)) return;
+		if (tab === 'graph') {
+			const expanded = new Set(this.graphView.expandedGroupPaths);
+			const groupsEnabled = this.graphView.groupsEnabled;
+			const showResourceDeclarations = this.graphView.showResourceDeclarations;
+			if (selection.kind === 'resource') this.graphView.showResourceDeclarations = true;
+			if (selection.kind === 'group') this.graphView.groupsEnabled = true;
+			let groupId: string | undefined;
+			if (selection.kind === 'node') groupId = snapshot.nodeById.get(selection.id)?.debugGroupId;
+			else if (selection.kind === 'resource') groupId = snapshot.resourceById.get(selection.id)?.debugGroupId;
+			else if (selection.kind === 'group') groupId = snapshot.groupByPathKey.get(selection.pathKey)?.parentId;
+			if (this.graphView.groupsEnabled && groupId) {
+				for (const id of snapshot.groupById.get(groupId)?.ancestorIds ?? []) {
+					const group = snapshot.groupById.get(id);
+					if (group) this.graphView.expandedGroupPaths.add(group.pathKey);
+				}
+			}
+			const scene = resolveGraphScene(this.graphView, snapshot);
+			const availableIds = new Set([...scene.nodes, ...scene.edges].map((entry) => entry.id));
+			if (!(scene.interaction.primaryElementIdsBySelection.get(selectionKey(selection))?.some((id) => availableIds.has(id)))) {
+				this.graphView.groupsEnabled = groupsEnabled;
+				this.graphView.showResourceDeclarations = showResourceDeclarations;
+				this.graphView.expandedGroupPaths.clear();
+				for (const path of expanded) this.graphView.expandedGroupPaths.add(path);
+				this.workbench.showNavigationIssue(selection.kind === 'culled' ? 'Culled passes are not part of Frame Flow.' : 'This object has no representation in Frame Flow.', selection);
+				return;
+			}
+			this.graphView.revealOnNextRender = { selection, revision: ++this.revealRevision };
+			this.updateGraphControls();
+		}
+		this.handleSelect(selection);
+		this.workbench.reveal(selection, tab);
+	}
+
 	private handleHover(selection: Selection | undefined): void {
 		if (!this.viewModel || sameSelection(this.hovered, selection)) return;
 		this.hovered = selection;
 		this.workbench.setHovered(selection);
 	}
 
-	private setGraphMode(mode: GraphViewState['graphMode']): void {
-		if (this.graphView.graphMode === mode) return;
-		this.graphView.graphMode = mode;
-		this.graphView.fitOnNextRender = true;
-		this.updateGraphModeButtonState();
-		this.workbench.refreshGraphStructure();
-	}
-
-	private updateGraphModeButtonState(): void {
-		const passesActive = this.graphView.graphMode === 'passes';
+	private updateGraphControls(): void {
+		const showDeclarations = this.graphView.showResourceDeclarations ?? true;
+		this.declarationsButton.classList.toggle('active', showDeclarations);
+		this.declarationsButton.setAttribute('aria-pressed', String(showDeclarations));
 		const hasGroups = (this.viewModel?.debugGroups.length ?? 0) > 0;
-		this.passesGraphModeButton.classList.toggle('active', passesActive);
-		this.resourcesGraphModeButton.classList.toggle('active', !passesActive);
-		this.passesGraphModeButton.setAttribute('aria-pressed', passesActive ? 'true' : 'false');
-		this.resourcesGraphModeButton.setAttribute('aria-pressed', passesActive ? 'false' : 'true');
-		this.groupsButton.disabled = !passesActive || !hasGroups;
-		this.groupsButton.classList.toggle('active', passesActive && hasGroups && this.graphView.groupsEnabled);
-		this.groupsButton.setAttribute('aria-pressed', passesActive && hasGroups && this.graphView.groupsEnabled ? 'true' : 'false');
+		this.groupsButton.disabled = !hasGroups;
+		this.groupsButton.hidden = !hasGroups;
+		this.collapseGroupsButton.hidden = !hasGroups;
+		this.groupsButton.classList.toggle('active', hasGroups && this.graphView.groupsEnabled);
+		this.groupsButton.setAttribute('aria-pressed', hasGroups && this.graphView.groupsEnabled ? 'true' : 'false');
 		const hasExpanded = this.viewModel?.debugGroups.some((group) => this.graphView.expandedGroupPaths.has(group.pathKey)) ?? false;
-		this.collapseGroupsButton.disabled = !passesActive || !hasGroups || !this.graphView.groupsEnabled || !hasExpanded;
+		this.collapseGroupsButton.disabled = !hasGroups || !this.graphView.groupsEnabled || !hasExpanded;
+	}
+
+	private toggleDeclarations(): void {
+		this.handleHover(undefined);
+		this.graphView.showResourceDeclarations = !(this.graphView.showResourceDeclarations ?? true);
+		this.graphView.renderer?.cancelReveal?.();
+		this.graphView.revealOnNextRender = undefined;
+		this.graphView.anchorElementIdOnNextRender = undefined;
+		this.graphView.fitOnNextRender = true;
+		this.updateGraphControls();
+		this.workbench.refreshGraphStructure();
 	}
 
 	private toggleGroups(): void {
-		if (this.graphView.graphMode !== 'passes' || !this.viewModel?.debugGroups.length) return;
+		if (!this.viewModel?.debugGroups.length) return;
+		this.handleHover(undefined);
 		this.graphView.groupsEnabled = !this.graphView.groupsEnabled;
 		this.graphView.fitOnNextRender = true;
-		this.updateGraphModeButtonState();
+		this.updateGraphControls();
 		this.workbench.refreshGraphStructure();
 	}
 
 	private toggleGroup(pathKey: string): void {
+		this.handleHover(undefined);
 		if (this.graphView.expandedGroupPaths.has(pathKey)) this.graphView.expandedGroupPaths.delete(pathKey);
 		else this.graphView.expandedGroupPaths.add(pathKey);
 		this.graphView.anchorElementIdOnNextRender = graphGroupElementId(pathKey);
-		this.updateGraphModeButtonState();
+		this.updateGraphControls();
 		this.workbench.refreshGraphStructure();
 	}
 
 	private collapseAllGroups(): void {
 		if (this.graphView.expandedGroupPaths.size === 0) return;
+		this.handleHover(undefined);
 		this.graphView.expandedGroupPaths.clear();
 		this.graphView.fitOnNextRender = true;
-		this.updateGraphModeButtonState();
+		this.updateGraphControls();
 		this.workbench.refreshGraphStructure();
 	}
 
@@ -568,16 +651,10 @@ export class FrameGraphInspector {
 export function mountFrameGraphInspector(host: HTMLElement, options?: FrameGraphInspectorOptions): FrameGraphInspector {
 	const inspector = new FrameGraphInspector(options);
 	host.appendChild(inspector.dom);
+	inspector.refreshTheme();
 	return inspector;
 }
 
-function createGraphIconButton(icon: 'fit', title: string, onClick: () => void): HTMLButtonElement {
-	const button = createToolbarButton('', title, onClick);
-	button.classList.add('zenfg-inspector-icon-button');
-	button.appendChild(createPanelIcon(icon));
-	return button;
-}
-
 async function writeTextToClipboard(text: string): Promise<void> {
 	if (navigator.clipboard?.writeText) {
 		await navigator.clipboard.writeText(text);
@@ -618,7 +695,7 @@ function formatImportLimit(bytes: number): string {
 }
 
 function formatIssues(issues: readonly { readonly path: string; readonly message: string }[]): string {
-	return issues.slice(0, 3).map((issue) => `${issue.path || '/'}: ${issue.message}`).join('; ');
+	return issues.map((issue) => `${issue.path || '/'}: ${issue.message}`).join('\n');
 }
 
 function isFileDrag(event: DragEvent): boolean {

package/src/capture.ts

@@ -0,0 +1,4 @@
+/** Requested timing families for the next live capture; never changes imported data. */
+export type FrameGraphCaptureRequest = {
+	readonly timing: 'cpu' | 'gpu' | 'both';
+};