@zenfg/inspector

@zenfg/inspector is an embeddable, renderer-independent DOM workbench for ZenFG Snapshot data. It depends on @zenfg/snapshot, Cytoscape, and ELK, but has no WebGPU, wgpu, engine, or host-UI dependency.

Use captured graphs, resource facts, and optional timings to understand a frame, then export Snapshot JSON alongside code for human or AI-assisted analysis. See the analyze-and-verify workflow.

The package owns Snapshot validation, migration, visualization, and workbench state. The host owns layout around the workbench, live-capture policy, file retention, and the renderer that produces Snapshot data.

Resource and access statistics describe the declarations captured in the graph. They do not automatically scan all shader bindings or measure total GPU memory; workload-private buffers can be absent. More explicit declarations can be useful for diagnosis. See Choosing resource declaration granularity.

Installation

npm install @zenfg/inspector@0.1.0

Quick start

Run in a modern browser from your existing TypeScript app. Give the host element an explicit size (for example, height: 600px) and supply a valid Snapshot capture. Call mountInspector(host, capture) below; the returned function removes the workbench.

Mount one Inspector into a host element and provide an optional live-capture callback:

import { mountFrameGraphInspector, type FrameGraphCaptureRequest } from '@zenfg/inspector';
import type { FrameGraphSnapshot } from '@zenfg/snapshot';

export function mountInspector(
	host: HTMLElement,
	capture: (request: FrameGraphCaptureRequest) => FrameGraphSnapshot | Promise<FrameGraphSnapshot>,
): () => void {
	const inspector = mountFrameGraphInspector(host, {
		captureSnapshot: capture,
		branding: 'ZenFG Inspector',
	});

	return () => inspector.destroy();
}

The host must have non-zero width and height. FrameGraphInspector fills that host, so the same workbench can be embedded in a tool panel or mounted as a full-page application.

Themes and style customization

Inspector uses Tokyo Night Storm by default and includes a complete Light preset. Use public --zfgi-* variables on an owned host, or pass a theme object and call setTheme() to update one instance without losing graph interaction state. After changing external CSS dynamically, call refreshTheme() to synchronize the Canvas graph. Static CSS is read automatically at mount.

See Theming for JS presets, the optional CSS preset stylesheet, variable reference, compatibility aliases, and multi-instance behavior.

Common tasks

Task	Public API
Mount into an existing element	mountFrameGraphInspector()
Construct without appending	new FrameGraphInspector() and its dom property
Request live data from the host	captureSnapshot option
Replace the current capture	setSnapshot()
Read the current canonical capture	getSnapshot()
Import and migrate a file	importSnapshot()
Download canonical Snapshot JSON	downloadSnapshot()
Copy canonical Snapshot JSON	copySnapshotJson()
Apply a preset or custom theme	theme option and setTheme()
Synchronize graph after external CSS changes	refreshTheme()
Set visible product branding	branding option
Limit imported file size	maxImportBytes option
Limit automatic graph layout	maxGraphElements option
Release DOM, workers, and listeners	destroy()

Exact options, defaults, return types, and lifecycle behavior are documented by the TSDoc preserved in the packaged source and declarations.

Workbench guide

See the workbench guide for views, graph interaction, timing, and memory interpretation.

Common mistakes

Symptom	Fix
The Inspector is mounted but invisible	Give the host element a non-zero width and height.
Live capture never becomes available	Provide captureSnapshot, or call setSnapshot() with canonical data.
A large capture has no graph layout	Raise maxGraphElements deliberately or use the tabular/raw views.
A failed import appears to do nothing	Inspect the visible validation feedback; the previous valid capture is intentionally preserved.
Old capture results replace new ones in host code	Let the Inspector own capture sequencing instead of applying asynchronous results separately.
DOM or worker resources remain after unmount	Call destroy() when the host tool is released.

Further reading

• Hosted Inspector
• @zenfg/snapshot
• ZenFG Core concepts
• ZenFG documentation index

Documentation and versions

This README describes @zenfg/inspector 0.1.0. Registry badges show the current published channel, not your installed version.

• Exact installed APIs: follow package.json → exports → dist/*.d.ts; declaration maps point to the included src/. Only declared export paths are public.
• Online guide (development branch). The site may describe changes newer than this package.
• TypeScript API (development branch).
• Source and documentation for this release.
• Shared concepts for this release and compatibility.
• Plain Markdown documentation index (development branch).
• Local guides: workbench and themes.

CPU and GPU capture

The Capture action always requests CPU and GPU together. Providers receive a FrameGraphCaptureRequest and must forward its timing mode to the runtime. Timing is collected only for capture frames; imported data and normal frames are unchanged. CPU columns, sorting, group sums and coverage include all retained node kinds. CPU execute total and GPU span remain separate. Missing, culled and real zero readings are distinct; zero does not guarantee zero CPU cost.