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

package/src/debugCaptureModel.ts

@@ -6,7 +6,7 @@ import type {
 	FrameGraphSnapshotNodeKind,
 	FrameGraphSnapshotResourceKind,
 	FrameGraphSnapshotResourceOrigin,
-	FrameGraphSnapshotRootReason,
+	FrameGraphSnapshotRoot,
 	FrameGraphSnapshotSegment,
 	FrameGraphSnapshotTextureRegion,
 	FrameGraphSnapshotWriteContents,
@@ -59,12 +59,14 @@ export type FrameGraphDebugNode = {
 	readonly sideEffect: boolean;
 	readonly debugGroupId?: string;
     readonly gpuDurationMicros?: number;
+    readonly cpuDurationMicros?: number;
     readonly reads: readonly FrameGraphDebugAccess[];
     readonly writes: readonly FrameGraphDebugAccess[];
 };
 
 export type FrameGraphDebugResource = FrameGraphDebugResourceRef & {
 	readonly origin: FrameGraphSnapshotResourceOrigin;
+	readonly initialContents?: 'defined' | 'undefined';
 	readonly debugGroupId?: string;
 	readonly usageFlags: readonly string[];
     readonly lifetime?: { readonly firstUse: number; readonly lastUse: number };
@@ -80,12 +82,19 @@ export type FrameGraphDebugEdge = {
     readonly kind: 'value' | 'ordering';
 };
 
-export type FrameGraphDebugRoot = {
-	readonly reason: FrameGraphSnapshotRootReason;
-	readonly nodeId?: string;
+export type FrameGraphDebugRoot = FrameGraphSnapshotRoot & {
+	readonly key: string;
     readonly resource?: FrameGraphDebugResourceRef;
 };
 
+/** Semantic identity within one recording, independent of root array order. */
+export function rootKey(root: FrameGraphSnapshotRoot): string {
+	return root.reason === 'side-effect' ? JSON.stringify([root.reason, root.nodeId])
+		: JSON.stringify([root.reason, root.resourceId, root.range?.kind === 'buffer'
+			? ['buffer', root.range.offset, root.range.size]
+			: root.range?.regions.map((r) => [r.baseMipLevel, r.mipLevelCount, r.aspect, r.baseArrayLayer, r.arrayLayerCount, r.baseDepthSlice, r.depthSliceCount]) ?? null]);
+}
+
 export type FrameGraphDebugCulledNode = {
     readonly node: Omit<FrameGraphDebugNode, 'order'>;
     readonly reason: string;
@@ -105,6 +114,7 @@ export type FrameGraphDebugGroupSummary = {
 	readonly nodeKindCounts: Readonly<Partial<Record<FrameGraphSnapshotNodeKind, number>>>;
 	readonly inputResources: readonly FrameGraphDebugResourceRef[];
 	readonly outputResources: readonly FrameGraphDebugResourceRef[];
+	readonly outputRoots: readonly FrameGraphDebugRoot[];
 	readonly registeredTransientResourceCount: number;
 	readonly accessedTransientResourceCount: number;
 	readonly physicalAllocationCount: number;
@@ -112,6 +122,8 @@ export type FrameGraphDebugGroupSummary = {
 	readonly externalSubmissionCount: number;
 	readonly gpuWorkDurationMicros: number;
 	readonly timedNodeCount: number;
+	readonly cpuTimedNodeCount: number;
+	readonly cpuWorkDurationMicros: number;
 	readonly timingEligibleNodeCount: number;
 };
 
@@ -131,14 +143,23 @@ export type FrameGraphDebugGroup = {
 export type FrameGraphDebugMetrics = {
 	readonly timingEligibleNodeCount: number;
 	readonly timedNodeCount: number;
+	readonly cpuTimedNodeCount: number;
+	readonly cpuWorkDurationMicros: number;
 	readonly slowestNode?: FrameGraphDebugNode;
 	readonly transientEstimatedByteSize?: number;
 	readonly logicalCapacityBytes?: number;
 	readonly physicalEstimatedBytes?: number;
 	readonly aliasReuseBytes?: number;
 	readonly aliasedAllocationCount: number;
+	readonly estimatedCoverage: {
+		readonly transient: EstimateCoverage;
+		readonly logical: EstimateCoverage;
+		readonly physical: EstimateCoverage;
+	};
 };
 
+export type EstimateCoverage = { readonly known: number; readonly total: number };
+
 export type FrameGraphDebugSnapshotSource = {
 	readonly kind: 'live' | 'file' | 'programmatic';
 	readonly label: string;
@@ -160,6 +181,10 @@ export type FrameGraphDebugViewModel = {
 	readonly executionSegments: readonly FrameGraphDebugExecutionSegment[];
 	readonly textureViewById: ReadonlyMap<string, FrameGraphSnapshot['graph']['textureViews'][number]>;
 	readonly nodeById: ReadonlyMap<string, FrameGraphDebugNode>;
+	readonly canonicalNodeById: ReadonlyMap<string, FrameGraphSnapshot['graph']['nodes'][number]>;
+	readonly culledById: ReadonlyMap<string, FrameGraphDebugCulledNode>;
+	readonly diagnosticsByNodeId: ReadonlyMap<string, readonly FrameGraphSnapshot['diagnostics'][number][]>;
+	readonly diagnosticsByResourceId: ReadonlyMap<string, readonly FrameGraphSnapshot['diagnostics'][number][]>;
 	readonly resourceById: ReadonlyMap<string, FrameGraphDebugResource>;
 	readonly groupById: ReadonlyMap<string, FrameGraphDebugGroup>;
 	readonly groupByPathKey: ReadonlyMap<string, FrameGraphDebugGroup>;
@@ -169,6 +194,7 @@ export type FrameGraphDebugViewModel = {
 	readonly segmentByNodeId: ReadonlyMap<string, FrameGraphDebugExecutionSegment>;
 	readonly segmentByIndex: ReadonlyMap<number, FrameGraphDebugExecutionSegment>;
 	readonly metrics: FrameGraphDebugMetrics;
+    readonly cpuProfiling: FrameGraphSnapshot['timings']['cpu'];
     readonly profiling:
         | {
             readonly status: 'available';
@@ -207,6 +233,7 @@ export function createDebugViewModel(
 		? { ...source, migratedFromLegacy: true }
 		: source;
 	const gpuTiming = snapshot.timings.gpu;
+	const cpuTimings = new Map(snapshot.timings.cpu.status === 'available' ? snapshot.timings.cpu.nodes.map(node => [node.nodeId, node.durationMicros]) : []);
 	const resourcePool = snapshot.memory.poolReport;
 	const normalizedGroups = normalizeDebugGroups(compilation);
 	const knownGroupIds = new Set(normalizedGroups.map((group) => group.id));
@@ -269,6 +296,7 @@ export function createDebugViewModel(
 		sideEffect: node.sideEffect,
 		debugGroupId: node.groupId,
 		gpuDurationMicros: timings.get(node.id),
+		cpuDurationMicros: cpuTimings.get(node.id),
 		reads: nodeAccesses(node.id, 'read'),
 		writes: nodeAccesses(node.id, 'write'),
 	}));
@@ -277,6 +305,7 @@ export function createDebugViewModel(
 		kind: resource.kind,
 		label: resource.label,
 		origin: resource.origin,
+		initialContents: resource.initialContents,
 		debugGroupId: resource.groupId,
 		usageFlags: resource.usageFlags,
 		lifetime: resource.lifetime,
@@ -289,8 +318,8 @@ export function createDebugViewModel(
 		resource: resourceRef(dependency.resourceId),
 	}));
 	const roots: FrameGraphDebugRoot[] = compilation.roots.map((root) => ({
-		reason: root.reason,
-		nodeId: root.nodeId,
+		...root,
+		key: rootKey(root),
 		resource: root.resourceId === undefined ? undefined : resourceRef(root.resourceId),
 	}));
 	const culledNodes: FrameGraphDebugCulledNode[] = compilation.nodes
@@ -335,6 +364,18 @@ export function createDebugViewModel(
 		executionSegments,
 	});
 	const nodeById = new Map(nodes.map((node) => [node.id, node]));
+	const canonicalNodeById = new Map(compilation.nodes.map((node) => [node.id, node]));
+	const culledById = new Map(culledNodes.map((entry) => [entry.node.id, entry]));
+	const diagnosticsByNodeId = new Map<string, FrameGraphSnapshot['diagnostics'][number][]>();
+	const diagnosticsByResourceId = new Map<string, FrameGraphSnapshot['diagnostics'][number][]>();
+	for (const diagnostic of snapshot.diagnostics) {
+		for (const [id, index] of [[diagnostic.nodeId, diagnosticsByNodeId], [diagnostic.resourceId, diagnosticsByResourceId]] as const) {
+			if (id === undefined) continue;
+			const entries = index.get(id) ?? [];
+			entries.push(diagnostic);
+			index.set(id, entries);
+		}
+	}
 	const resourceById = new Map(resources.map((resource) => [resource.id, resource]));
 	const groupById = new Map(debugGroups.map((group) => [group.id, group]));
 	const groupByPathKey = new Map(debugGroups.map((group) => [group.pathKey, group]));
@@ -352,14 +393,18 @@ export function createDebugViewModel(
 	), undefined);
 	const transientResources = resources.filter((resource) => resource.origin === 'transient');
 	const transientEstimatedByteSize = sumKnown(transientResources.map((resource) => resource.estimatedByteSize));
-	const physicalEstimatedBytes = sumKnown(physicalAllocations.map((allocation) => allocation.estimatedByteSize));
+	const allocationAvailable = snapshot.memory.allocationReport.status === 'available';
+	const physicalSizes = physicalAllocations.map((allocation) => allocation.estimatedByteSize);
+	const physicalEstimatedBytes = allocationAvailable ? sumKnown(physicalSizes) : undefined;
 	const logicalAllocationSizes = transientResources
 		.filter((resource) => resource.physicalResourceId !== undefined)
 		.map((resource) => allocationById.get(resource.physicalResourceId!)?.estimatedByteSize);
-	const logicalCapacityBytes = sumKnown(logicalAllocationSizes);
+	const logicalCapacityBytes = allocationAvailable ? sumKnown(logicalAllocationSizes) : undefined;
 	const metrics: FrameGraphDebugMetrics = {
 		timingEligibleNodeCount: timingEligibleNodes.length,
 		timedNodeCount: timedNodes.length,
+		cpuTimedNodeCount: nodes.filter(node => node.cpuDurationMicros !== undefined).length,
+		cpuWorkDurationMicros: nodes.reduce((sum, node) => sum + (node.cpuDurationMicros ?? 0), 0),
 		slowestNode,
 		transientEstimatedByteSize,
 		logicalCapacityBytes,
@@ -368,6 +413,11 @@ export function createDebugViewModel(
 			? undefined
 			: Math.max(0, logicalCapacityBytes - physicalEstimatedBytes),
 		aliasedAllocationCount: physicalAllocations.filter((allocation) => allocation.resourceIds.length > 1).length,
+		estimatedCoverage: {
+			transient: estimateCoverage(transientResources.map((resource) => resource.estimatedByteSize)),
+			logical: estimateCoverage(logicalAllocationSizes),
+			physical: estimateCoverage(physicalSizes),
+		},
 	};
 
 	return {
@@ -385,6 +435,10 @@ export function createDebugViewModel(
 		executionSegments,
 		textureViewById,
 		nodeById,
+		canonicalNodeById,
+		culledById,
+		diagnosticsByNodeId,
+		diagnosticsByResourceId,
 		resourceById,
 		groupById,
 		groupByPathKey,
@@ -394,6 +448,7 @@ export function createDebugViewModel(
 		segmentByNodeId,
 		segmentByIndex,
 		metrics,
+        cpuProfiling: snapshot.timings.cpu,
         profiling: gpuTiming.status === 'available'
             ? {
                 status: 'available',
@@ -415,6 +470,10 @@ export function createDebugViewModel(
 	};
 }
 
+function estimateCoverage(values: readonly (number | undefined)[]): EstimateCoverage {
+	return { known: values.filter((value) => value !== undefined).length, total: values.length };
+}
+
 function sumKnown(values: readonly (number | undefined)[]): number | undefined {
 	let total = 0;
 	for (const value of values) {
@@ -492,6 +551,23 @@ function validateDebugGroupReferences(
 	}
 }
 
+/** Declaration boundaries are topological, not per-range initial-value provenance. */
+export function declarationEntrances(
+	nodes: readonly FrameGraphDebugNode[],
+	accesses: readonly FrameGraphDebugAccessEdge[],
+	edges: readonly FrameGraphDebugEdge[],
+): readonly FrameGraphDebugAccessEdge[] {
+	const retained = new Set(nodes.map((node) => node.id));
+	const incoming = new Set(edges.map((edge) => JSON.stringify([edge.resource.id, edge.toNodeId])));
+	const seen = new Set<string>();
+	return accesses.filter((access) => {
+		const key = JSON.stringify([access.resource.id, access.nodeId]);
+		if (!retained.has(access.nodeId) || incoming.has(key) || seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+
 function buildDebugGroupSummaries(input: {
 	readonly groups: readonly NormalizedDebugGroup[];
 	readonly nodes: readonly FrameGraphDebugNode[];
@@ -504,6 +580,7 @@ function buildDebugGroupSummaries(input: {
 }): FrameGraphDebugGroup[] {
 	const groupsById = new Map(input.groups.map((group) => [group.id, group]));
 	const resourcesById = new Map(input.resources.map((resource) => [resource.id, resource]));
+	const entrances = declarationEntrances(input.nodes, input.accessEdges, input.edges);
 	const isInGroup = (candidateId: string | undefined, groupId: string) => (
 		candidateId !== undefined && groupsById.get(candidateId)?.ancestorIds.includes(groupId) === true
 	);
@@ -526,23 +603,19 @@ function buildDebugGroupSummaries(input: {
 			if (!fromInside && toInside) inputIds.add(edge.resource.id);
 			if (fromInside && !toInside) outputIds.add(edge.resource.id);
 		}
-		for (const access of input.accessEdges) {
-			if (!retainedIds.has(access.nodeId)) continue;
-			const resource = resourcesById.get(access.resource.id);
-			const hasRetainedValueProducer = input.edges.some((edge) => (
-				edge.toNodeId === access.nodeId
-				&& edge.resource.id === access.resource.id
-				&& edge.kind === 'value'
-			));
-			if (access.mode === 'read' && resource && resource.origin !== 'transient' && !hasRetainedValueProducer) {
-				inputIds.add(resource.id);
-			}
+		for (const access of entrances) {
+			const fromInside = isInGroup(resourcesById.get(access.resource.id)?.debugGroupId, group.id);
+			const toInside = retainedIds.has(access.nodeId);
+			if (!fromInside && toInside) inputIds.add(access.resource.id);
+			if (fromInside && !toInside) outputIds.add(access.resource.id);
 		}
+		const outputRoots: FrameGraphDebugRoot[] = [];
 		for (const root of input.roots) {
 			if (!root.resource) continue;
-			if (input.accessEdges.some((access) => retainedIds.has(access.nodeId)
-				&& access.resource.id === root.resource!.id && access.mode === 'write')) {
+			if (root.resolution?.producerNodeIds.some((id) => retainedIds.has(id))
+				|| root.resolution?.usesInitialContents && isInGroup(resourcesById.get(root.resource.id)?.debugGroupId, group.id)) {
 				outputIds.add(root.resource.id);
+				outputRoots.push(root);
 			}
 		}
 
@@ -569,6 +642,7 @@ function buildDebugGroupSummaries(input: {
 				nodeKindCounts,
 				inputResources: [...inputIds].map((id) => resourcesById.get(id)!).filter(Boolean),
 				outputResources: [...outputIds].map((id) => resourcesById.get(id)!).filter(Boolean),
+				outputRoots,
 				registeredTransientResourceCount: registeredTransient.length,
 				accessedTransientResourceCount: accessedTransientIds.size,
 				physicalAllocationCount: allocationIds.size,
@@ -576,6 +650,8 @@ function buildDebugGroupSummaries(input: {
 				externalSubmissionCount: retained.filter((node) => node.kind === 'external-submission').length,
 				gpuWorkDurationMicros: timed.reduce((sum, node) => sum + node.gpuDurationMicros!, 0),
 				timedNodeCount: timed.length,
+				cpuTimedNodeCount: retained.filter(node => node.cpuDurationMicros !== undefined).length,
+				cpuWorkDurationMicros: retained.reduce((sum, node) => sum + (node.cpuDurationMicros ?? 0), 0),
 				timingEligibleNodeCount: timingEligible.length,
 			},
 		};

package/src/index.ts

@@ -17,5 +17,9 @@ export type {
 } from '@zenfg/snapshot';
 export { FrameGraphInspector, mountFrameGraphInspector } from './FrameGraphInspector.ts';
 export type { FrameGraphInspectorOptions } from './FrameGraphInspector.ts';
-export { ZENFG_INSPECTOR_QUERY_PARAM, isZenFGInspectorRequested } from './query.ts';
-export { ensureFrameGraphInspectorStyles } from './styles.ts';
+export { ZENFG_INSPECTOR_QUERY_PARAM, isZenFGInspectorRequested } from './query.ts';
+export { ensureFrameGraphInspectorStyles } from './styles.ts';
+
+export type { InspectorTheme, InspectorThemeVariables } from './theme.ts';
+
+export type { FrameGraphCaptureRequest } from './capture.ts';

package/src/panelAliasAnalysis.ts

@@ -22,9 +22,16 @@ export type AliasAnalysis = {
     readonly resources: ReadonlyMap<string, AliasAnalysisResource>;
     readonly minUse: number;
     readonly maxUse: number;
+    readonly hasLifetimes: boolean;
 };
 
+// View models are immutable for the lifetime of a capture. Search and selection
+// changes should not rebuild allocation membership or the execution domain.
+const analysisBySnapshot = new WeakMap<FrameGraphDebugViewModel, AliasAnalysis>();
+
 export function analyzeSnapshotAliases(snapshot: FrameGraphDebugViewModel): AliasAnalysis {
+    const cached = analysisBySnapshot.get(snapshot);
+    if (cached) return cached;
     const allocationById = snapshot.allocationById;
     const resourcesById = snapshot.resourceById;
     const allocationGroups = snapshot.physicalAllocations.map((allocation): AliasAnalysisAllocation => {
@@ -43,13 +50,14 @@ export function analyzeSnapshotAliases(snapshot: FrameGraphDebugViewModel): Alia
     let minUse = Number.POSITIVE_INFINITY;
     let maxUse = Number.NEGATIVE_INFINITY;
     for (const resource of snapshot.resources) {
-        if (!resource.lifetime) {
+        if (resource.origin !== 'transient' || !resource.lifetime) {
             continue;
         }
         minUse = Math.min(minUse, resource.lifetime.firstUse);
         maxUse = Math.max(maxUse, resource.lifetime.lastUse);
     }
-    if (!Number.isFinite(minUse) || !Number.isFinite(maxUse)) {
+    const hasLifetimes = Number.isFinite(minUse) && Number.isFinite(maxUse);
+    if (!hasLifetimes) {
         minUse = 0;
         maxUse = 0;
     }
@@ -65,16 +73,19 @@ export function analyzeSnapshotAliases(snapshot: FrameGraphDebugViewModel): Alia
             resource,
             allocation,
             aliasStatus,
-            nonAliasReasons: resolveNonAliasReasons(resource, allocation, allocationGroups),
+            nonAliasReasons: describeAliasStatus(aliasStatus),
         });
     }
 
-    return {
+    const analysis = {
         allocations: allocationGroups,
         resources: resourceAnalysis,
         minUse,
         maxUse,
+        hasLifetimes,
     };
+    analysisBySnapshot.set(snapshot, analysis);
+    return analysis;
 }
 
 function resolveAliasStatus(
@@ -94,71 +105,14 @@ function resolveAliasStatus(
     return allocationResources.length > 1 ? 'aliased' : 'single';
 }
 
-function resolveNonAliasReasons(
-    resource: FrameGraphDebugResource,
-    allocation: FrameGraphDebugPhysicalAllocation | undefined,
-    allocations: readonly AliasAnalysisAllocation[],
-): readonly string[] {
-    if (resource.origin !== 'transient') {
-        return ['Imported or swapchain resources do not participate in transient aliasing.'];
-    }
-    if (!resource.lifetime) {
-        return ['No lifetime is available for this resource in the retained graph.'];
-    }
-    if (!allocation) {
-        return ['No physical allocation is associated with this transient resource.'];
-    }
-
-    const reasons = new Set<string>();
-    for (const group of allocations) {
-        if (group.allocation.id === allocation.id) {
-            continue;
-        }
-        for (const other of group.resources) {
-            if (other.id === resource.id || other.origin !== 'transient') {
-                continue;
-            }
-            if (other.kind !== resource.kind) {
-                reasons.add(`Different kind from ${labelDebugResource(other)}.`);
-                continue;
-            }
-            if (group.allocation.compatibilityClassId !== allocation.compatibilityClassId) {
-                reasons.add(`Different compatibility class from ${labelDebugResource(other)}.`);
-                continue;
-            }
-            if (!other.lifetime) {
-                reasons.add(`Missing lifetime for ${labelDebugResource(other)}.`);
-                continue;
-            }
-            if (lifetimesOverlap(resource.lifetime, other.lifetime)) {
-                reasons.add(`Lifetime overlaps ${labelDebugResource(other)} (${other.lifetime.firstUse}-${other.lifetime.lastUse}).`);
-            }
-        }
-    }
-
-    if (reasons.size === 0) {
-        return allocationResourcesFor(allocations, allocation.id).length > 1
-            ? ['Aliases with resources in the same physical allocation.']
-            : ['No compatible non-overlapping transient resource was found in this snapshot.'];
+function describeAliasStatus(status: AliasAnalysisResource['aliasStatus']): readonly string[] {
+    switch (status) {
+        case 'not-transient': return ['Imported and surface resources do not participate in transient aliasing.'];
+        case 'no-lifetime': return ['No lifetime is available for this resource in the retained graph.'];
+        case 'not-allocated': return ['No physical allocation is associated with this transient resource.'];
+        case 'aliased': return ['Shares a physical allocation with other logical resources.'];
+        // The snapshot states allocation membership; it cannot explain allocator
+        // decisions by comparing every pair of logical resources.
+        case 'single': return ['This physical allocation contains one logical resource.'];
     }
-
-    return Array.from(reasons).slice(0, 6);
-}
-
-function allocationResourcesFor(
-    allocations: readonly AliasAnalysisAllocation[],
-    allocationId: string,
-): readonly FrameGraphDebugResource[] {
-    return allocations.find((group) => group.allocation.id === allocationId)?.resources ?? [];
-}
-
-function lifetimesOverlap(
-    a: NonNullable<FrameGraphDebugResource['lifetime']>,
-    b: NonNullable<FrameGraphDebugResource['lifetime']>,
-): boolean {
-    return a.firstUse <= b.lastUse && b.firstUse <= a.lastUse;
-}
-
-function labelDebugResource(resource: FrameGraphDebugResource): string {
-    return resource.label ?? `${resource.kind}-${resource.id}`;
 }