@zenfg/inspector 0.1.0-beta.3 → 0.1.0

package/GUIDE.md

@@ -0,0 +1,182 @@
+# Inspector workbench guide
+
+## Workbench behavior
+
+The workbench provides Overview, Graph, Passes, Resources, Memory, and
+Diagnostics views plus a selection Inspector. It supports live capture, direct
+Snapshot replacement, file import, supported legacy migration, canonical
+download, clipboard copy, filtering, sorting, group expansion, and graph
+navigation.
+
+The first capture opens Graph with no selection and the detail pane closed.
+Subsequent captures preserve the current view, filters, and selection when the
+same object still exists. Pass selection follows the node ID across retained and
+culled states; removing the selected object clears selection and closes details.
+These preferences, group expansion, and detail width belong to the current
+Inspector instance and are not saved across sessions.
+
+| View | Purpose |
+| --- | --- |
+| Overview | Full-width diagnostic counts, timing coverage, slowest pass, work counts, and memory estimates, with links to the relevant views. Capture metadata is expandable. |
+| Graph | Frame Flow structure, searchable by pass, resource, group, or output, with explicit target location and a collapsible legend. |
+| Passes | All, Retained, or Culled passes, filtered by kind and name/ID/group, with order and GPU sorting. The separate Group Hierarchy has its own expansion and path search. |
+| Resources | Name/ID/group, type, and Transient/Imported/Surface filters, plus name, estimated size, and first-use sorting. Full descriptors and allocations remain in details. |
+| Memory | Physical allocations and their logical resources, inclusive execution-slot lifetimes, search, allocation/size sorting, and All/Aliased/Single/Unallocated filters. |
+| Diagnostics | Every captured error, warning, and informational message, including repeated codes. Severity and code/message filters precede expandable retention roots, culling reasons, and execution segments. |
+
+Lists show the matching and total counts, retain continuous scrolling, and offer
+**Clear filters**. Passes order retained work by execution order, then culled work
+by recording order when available, falling back to capture order. Retained means
+the compiler kept a pass; it does not itself prove GPU execution. Culled work has
+no execution order, segment, or GPU timing. The Group Hierarchy arrows only change
+that tree; **Show in Graph** is a separate action.
+
+Diagnostics preserve capture order within each severity and offer separate
+node and resource links when a message references both. Culled-node links work
+the same way as retained-node links. The Diagnostics tab shows error/warning
+counts. Source, frame, and capture time are available under **Capture information**
+in Overview; an absent capture timestamp is shown as unknown. The collapsible
+graph legend floats inside the canvas without changing its size or viewport.
+Graph controls also float over the canvas. **Search** opens the search field;
+**Escape** dismisses it. **Fit** frames the graph in the available viewport.
+
+The selection pane has **Summary**, **Relations**, and **Raw** tabs. Summary
+explains compilation status, timing coverage, accesses, allocation relationships,
+and attached diagnostics. Relations distinguish access facts, dependencies,
+output sources, and allocation membership. Raw shows the selected original
+object and its JSON path in the canonical Snapshot, with field/value search,
+folding, and copy of the complete object regardless of the current search. Legacy
+imports explicitly identify their migrated canonical data. IDs can be copied
+without their presentation labels.
+
+Selecting an object opens its details on object views. Overview uses the full
+width while retaining selection. The pane defaults to 300px and can be resized
+from 300px to 480px while leaving at least 520px for the main view. Workspaces narrower than
+828px use a modal drawer capped at 340px, with at least a 24px outside strip,
+a backdrop, keyboard focus containment, and focus restoration when closed. The main content width determines table and information
+layout; auxiliary table columns move into details when space is limited.
+Arrow keys and Home/End switch tabs. Escape first dismisses the innermost active
+menu or detail pane; the Examples host respects handled key events.
+
+### Timing and memory interpretation
+
+Timing labels distinguish not collected, partial coverage, complete coverage,
+not applicable, and a measured zero. **Measured pass sum** is the sum of available
+pass timings with its timed/eligible count; **GPU span** is displayed separately.
+Opaque external work has no inferred duration. Passes is the comparison table
+for individual timings; Diagnostics does not repeat it.
+
+Memory numbers are estimates with different scopes:
+
+| Metric | Meaning |
+| --- | --- |
+| Transient estimate | Declared estimated sizes of transient logical resources. |
+| Logical capacity | Allocation capacity counted for each assigned logical transient resource. |
+| Physical estimate | Estimated sizes of physical allocations in the allocation report. |
+| Alias reuse | Logical capacity minus physical estimate, where both are known. |
+| Pool retained | Producer-reported retained pool allocations, which may outlive this graph. |
+
+An unavailable report is not zero. Unknown resource/allocation sizes remain
+unknown, and partial summaries show the known-size coverage. A valid empty report
+can contain real zero totals. None of these metrics is total GPU memory or a
+measured peak. Memory summaries always cover the entire Snapshot; filters change
+the visible rows and matching count only. A lifetime includes both first and last
+execution slots. Tick positions, grid lines, and resource bars share one stable
+Snapshot coordinate range; missing lifetimes have no bar.
+
+### Frame Flow interaction
+
+Graph is a single **Frame Flow** view: resource declarations → retained pass
+dependencies → explicit resource outputs. Resource entrances belong to their
+declaration groups; output roots remain top-level and use compiler-supplied final
+producers and initial-content contributions. Culled passes remain in lists and
+details, not in the graph. Collapsed groups aggregate relationships without
+discarding their underlying semantics.
+The **Declarations** toolbar toggle shows resource declaration entrances by default.
+Turn it off to focus on pass dependencies and outputs: declaration entrances,
+their relationships (including initial-content output edges), and resource-only
+groups leave the layout. Pass dependencies and producer-to-output edges remain.
+Outputs with known initial-content contributions show **With initial contents**
+or **Initial contents only**; unavailable Legacy sources are not inferred.
+The toggle persists across views and captures within this Inspector instance.
+Changing it fits the updated graph while preserving selection and group expansion.
+Resources, details, memory, and Snapshot data remain complete.
+
+All nodes use single-line borders. Ordinary passes are rounded rectangles,
+external submissions are cut-corner rectangles, resource entrances are ellipses,
+and output roots are right-pointing tags. Declarations and outputs each have a
+role colour independent of Buffer/Texture; pass categories have distinct colours.
+Resources and Memory retain their resource-type colours. Hover and selection
+change border emphasis, not shape, text colour, or fill.
+
+Entrances show source/type first and the resource name second; outputs show their
+purpose first and name second. Names are truncated to one line, with full names
+available on hover and in details. Output ranges appear only to distinguish
+different ranges of the same resource and purpose. Exact ranges and final sources
+remain in hover/details. Semantic zoom hides auxiliary types and range summaries.
+The grouped legend describes the whole snapshot's Frame Flow, including collapsed
+objects, respects the Declarations toggle, and remains stable while groups expand/collapse. Culled-only categories
+and unused resources do not add legend entries.
+
+Category fills are opaque sRGB tints over the canvas: 18% in Storm and 8% in
+Light. Theme-specific node text targets at least 7:1 contrast. Supporting text targets 4.5:1, and identifying
+borders/symbols target 3:1 against their adjacent backgrounds. Automated checks
+cover both official themes and interaction states; custom CSS colour overrides must
+preserve these contrast relationships.
+
+Solid edges represent declarations, values, and output sources; dashed edges
+represent ordering-only relationships. Edges never carry labels. Hover provides
+temporary hints: resource entrances and edges link only to visible entrances and
+edges with the same logical resource ID, regardless of range. Passes, groups, and
+output nodes only highlight themselves. These associations do not imply matching
+ranges or a continuous dataflow path, and never substitute a collapsed group for
+a hidden resource entrance.
+Direct and linked hover use the same strong visual style. Selection uses a blue
+outline without a glow. Hovering a Summary or Relations link previews its target
+in the graph using the same rules, without changing selection or moving the view;
+leaving the link or changing/closing the detail pane clears the preview.
+
+Resource **Pass accesses** entries link only the pass name; access mode, write
+contents, producesValue, and available ranges remain descriptive text. Pass details
+use the same access facts. An access is not a graph
+relationship and is not mapped to an arbitrary dependency edge.
+Resource Relations also link to individual output roots by reason and range.
+
+Clicking an entrance, edge, or Resources row selects the same logical resource,
+including all its visible entrances and edges, but no passes, groups, or outputs.
+An output still selects its Root. Its **View resource** action and other resource
+links use the same resource selection. Changing to a different resource opens
+Summary; selecting the current resource again preserves the active detail tab.
+Selection does not switch workbench views, change filters, expand groups, or move
+the viewport. A hidden entrance becomes selected when manually expanded; its
+visible cross-group edges remain selected while it is hidden. Hover previews are
+independent, with selection styling taking precedence, and never pin a tooltip.
+Edge hints show only the resource and distinct relationship types, including
+mixed types in aggregates. There is no independent edge detail or relationship list.
+Double-clicking a group expands or collapses it without replacing selection;
+single-click group selection waits briefly to distinguish that gesture.
+Legacy outputs with unavailable
+resolution remain visible but have no inferred source edges.
+
+Explicit **Show in …** actions perform navigation: they switch views, clear
+blocking filters, expand necessary ancestors, and scroll or center the target.
+They close a narrow-host drawer so the target is visible. Graph search uses the
+same explicit location behavior. Explicit resource location also turns Declarations
+on; ordinary selection and hover never change the toggle. Failed location restores
+the previous declaration and group settings. Objects absent from Frame Flow show an
+explanation and a list-view action; locating an object does not bypass the graph
+element budget. Ordinary selection and hover retain the behavior above.
+
+Capture, import, and direct replacement share a revision counter so stale async
+results cannot replace newer data. Failed or oversized imports leave the
+current valid capture and UI state intact, and operation feedback can be expanded
+to inspect the full failure reason. Views render their new capture on first
+activation, and selection updates refresh only the active view and details.
+Memory grouping and lifetime coordinates are cached per Snapshot; Raw is created
+only when opened. Graph layout is lazy and is disabled
+with an explanation when a capture exceeds `maxGraphElements`; the tabular and
+raw views remain available.
+
+Snapshot labels, URLs, extensions, and diagnostics are assigned through text
+DOM APIs and are never executed as markup or code. The standalone Site page in
+`apps/site/inspector` mounts this same package without adding duplicate controls.

package/README.md

@@ -1,9 +1,10 @@
 # @zenfg/inspector
 
-[![npm](https://img.shields.io/npm/v/%40zenfg%2Finspector?include_prereleases&label=npm)](https://www.npmjs.com/package/@zenfg/inspector)
-[![status: beta](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/uinosoft/zenfg/blob/main/CHANGELOG.md)
-[![CI](https://github.com/uinosoft/zenfg/actions/workflows/ci.yml/badge.svg)](https://github.com/uinosoft/zenfg/actions/workflows/ci.yml)
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/uinosoft/zenfg/blob/main/LICENSE)
+<!-- generated:badges:start -->
+[![@zenfg/inspector published latest version](https://img.shields.io/npm/v/%40zenfg%2Finspector/latest?label=npm)](https://www.npmjs.com/package/@zenfg/inspector)
+[![API Docs (development)](https://img.shields.io/badge/API_docs-development-blue)](https://uinosoft.github.io/zenfg/docs/api/inspector/)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/LICENSE)
+<!-- generated:badges:end -->
 
 `@zenfg/inspector` is an embeddable, renderer-independent DOM workbench for
 ZenFG Snapshot data. It depends on `@zenfg/snapshot`, Cytoscape, and ELK, but has
@@ -13,24 +14,35 @@ 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](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/docs/core-concepts.md#choosing-resource-declaration-granularity).
+
 ## Installation
 
+<!-- generated:installation:start -->
 ```sh
-npm install @zenfg/inspector@0.1.0-beta.3
+npm install @zenfg/inspector@0.1.0
 ```
+<!-- generated:installation:end -->
 
 ## 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:
 
 ```ts
-import { mountFrameGraphInspector } from '@zenfg/inspector';
+import { mountFrameGraphInspector, type FrameGraphCaptureRequest } from '@zenfg/inspector';
 import type { FrameGraphSnapshot } from '@zenfg/snapshot';
 
 export function mountInspector(
 	host: HTMLElement,
-	capture: () => FrameGraphSnapshot | Promise<FrameGraphSnapshot>,
+	capture: (request: FrameGraphCaptureRequest) => FrameGraphSnapshot | Promise<FrameGraphSnapshot>,
 ): () => void {
 	const inspector = mountFrameGraphInspector(host, {
 		captureSnapshot: capture,
@@ -45,6 +57,17 @@ 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](./THEMING.md) for JS presets, the optional CSS preset stylesheet,
+variable reference, compatibility aliases, and multi-instance behavior.
+
 ## Common tasks
 
 | Task | Public API |
@@ -57,6 +80,8 @@ full-page application.
 | 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 |
@@ -65,85 +90,9 @@ full-page application.
 Exact options, defaults, return types, and lifecycle behavior are documented by
 the TSDoc preserved in the packaged source and declarations.
 
-## Workbench behavior
-
-The workbench provides Overview, Graph, Passes, Resources, Memory, and
-Diagnostics views plus a selection Inspector. It supports live capture, direct
-Snapshot replacement, file import, supported legacy migration, canonical
-download, clipboard copy, filtering, sorting, group expansion, and graph
-navigation.
-
-Graph is a single **Frame Flow** view: resource declarations → retained pass
-dependencies → explicit resource outputs. Resource entrances belong to their
-declaration groups; output roots remain top-level and use compiler-supplied final
-producers and initial-content contributions. Culled passes remain in lists and
-details, not in the graph. Collapsed groups aggregate relationships without
-discarding their underlying semantics.
-All nodes use single-line borders. Ordinary passes are rounded rectangles,
-external submissions are cut-corner rectangles, resource entrances are ellipses,
-and output roots are right-pointing tags. Declarations and outputs each have a
-role colour independent of Buffer/Texture; pass categories have distinct colours.
-Resources and Memory retain their resource-type colours. Hover and selection
-change border emphasis, not shape, text colour, or fill.
-
-Entrances show source/type first and the resource name second; outputs show their
-purpose first and name second. Names are truncated to one line, with full names
-available on hover and in details. Output ranges appear only to distinguish
-different ranges of the same resource and purpose. Exact ranges and final sources
-remain in hover/details. Semantic zoom hides auxiliary types and range summaries.
-The grouped legend describes the whole snapshot's Frame Flow, including collapsed
-objects, and remains stable while groups expand/collapse. Culled-only categories
-and unused resources do not add legend entries.
-
-Category fills are opaque 18% sRGB tints over the canvas; node text stays light
-and targets at least 7:1 contrast. Supporting text targets 4.5:1, and identifying
-borders/symbols target 3:1 against their adjacent backgrounds. Automated checks
-cover the default theme and interaction states; custom CSS colour overrides must
-preserve these contrast relationships.
-
-Solid edges represent declarations, values, and output sources; dashed edges
-represent ordering-only relationships. Edges never carry labels. Hover provides
-temporary hints: resource entrances and edges link only to visible entrances and
-edges with the same logical resource ID, regardless of range. Passes, groups, and
-output nodes only highlight themselves. These associations do not imply matching
-ranges or a continuous dataflow path, and never substitute a collapsed group for
-a hidden resource entrance.
-Direct and linked hover use the same strong visual style. Selection uses a blue
-outline without a glow. Hovering a Summary or Relations link previews its target
-in the graph using the same rules, without changing selection or moving the view;
-leaving the link or changing/closing the detail pane clears the preview.
-
-Resource **Pass accesses** entries link only the pass name; access mode, write
-contents, producesValue, and available ranges remain descriptive text. Pass details
-use the same access facts. An access is not a graph
-relationship and is not mapped to an arbitrary dependency edge.
-Resource Relations also link to individual output roots by reason and range.
-
-Clicking an entrance, edge, or Resources row selects the same logical resource,
-including all its visible entrances and edges, but no passes, groups, or outputs.
-An output still selects its Root. Its **View resource** action and other resource
-links use the same resource selection. Changing to a different resource opens
-Summary; selecting the current resource again preserves the active detail tab.
-Selection does not switch workbench views, change filters, expand groups, or move
-the viewport. A hidden entrance becomes selected when manually expanded; its
-visible cross-group edges remain selected while it is hidden. Hover previews are
-independent, with selection styling taking precedence, and never pin a tooltip.
-Edge hints show only the resource and distinct relationship types, including
-mixed types in aggregates. There is no independent edge detail or relationship list.
-Double-clicking a group expands or collapses it without replacing selection;
-single-click group selection waits briefly to distinguish that gesture.
-Legacy outputs with unavailable
-resolution remain visible but have no inferred source edges.
-
-Capture, import, and direct replacement share a revision counter so stale async
-results cannot replace newer data. Failed or oversized imports leave the
-current valid capture and UI state intact. Graph layout is lazy and is disabled
-with an explanation when a capture exceeds `maxGraphElements`; the tabular and
-raw views remain available.
-
-Snapshot labels, URLs, extensions, and diagnostics are assigned through text
-DOM APIs and are never executed as markup or code. The standalone application
-in `apps/inspector` mounts this same package without adding duplicate controls.
+## Workbench guide
+
+See the [workbench guide](./GUIDE.md) for views, graph interaction, timing, and memory interpretation.
 
 ## Common mistakes
 
@@ -159,6 +108,29 @@ in `apps/inspector` mounts this same package without adding duplicate controls.
 ## Further reading
 
 - [Hosted Inspector](https://uinosoft.github.io/zenfg/inspector/)
-- [`@zenfg/snapshot`](https://github.com/uinosoft/zenfg/blob/main/packages/snapshot/README.md)
-- [ZenFG Core concepts](https://github.com/uinosoft/zenfg/blob/main/docs/core-concepts.md)
-- [ZenFG documentation index](https://github.com/uinosoft/zenfg/blob/main/docs/README.md)
+- [`@zenfg/snapshot`](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/packages/snapshot/README.md)
+- [ZenFG Core concepts](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/docs/core-concepts.md)
+- [ZenFG documentation index](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/docs/README.md)
+
+## Documentation and versions
+
+<!-- generated:documentation:start -->
+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)](https://uinosoft.github.io/zenfg/docs/packages/inspector.html). The site may describe changes newer than this package.
+- [TypeScript API (development branch)](https://uinosoft.github.io/zenfg/docs/api/inspector/).
+- [Source and documentation for this release](https://github.com/uinosoft/zenfg/tree/npm/inspector/v0.1.0/packages/inspector).
+- [Shared concepts for this release](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/docs/core-concepts.md) and [compatibility](https://github.com/uinosoft/zenfg/blob/npm/inspector/v0.1.0/docs/compatibility.md).
+- [Plain Markdown documentation index (development branch)](https://uinosoft.github.io/zenfg/docs/llms.txt).
+- Local guides: [workbench](./GUIDE.md) and [themes](./THEMING.md).
+<!-- generated:documentation:end -->
+
+## 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.

package/THEMING.md

@@ -0,0 +1,124 @@
+# Inspector themes
+
+The public styling contract is the `--zfgi-*` CSS custom properties. Inspector
+ships complete Tokyo Night Storm defaults, supports partial host overrides, and
+does not require a base theme, theme name, registration, or browser storage.
+Theme changes are scoped to one Inspector. Snapshot data never contains themes.
+
+## Official presets and custom themes
+
+```ts
+import { mountFrameGraphInspector } from '@zenfg/inspector';
+import { tokyoNightStorm, tokyoNightLight, type InspectorTheme } from '@zenfg/inspector/theme';
+
+const inspector = mountFrameGraphInspector(host, { theme: tokyoNightLight });
+inspector.setTheme(tokyoNightStorm);
+
+const brandTheme: InspectorTheme = {
+  ...tokyoNightLight,
+  variables: { ...tokyoNightLight.variables, '--zfgi-accent': '#2959aa' },
+};
+inspector.setTheme(brandTheme);
+inspector.setTheme(null); // Restore host CSS and component defaults.
+```
+
+Both presets are ordinary immutable `InspectorTheme` objects. The pure `/theme`
+entry can be imported without a DOM and does not load Cytoscape or ELK. Hosts
+can also use its shared `visualThemes` and `visualMetrics` foundations.
+
+`setTheme()` replaces the API's current variable set on `inspector.dom.style`
+and automatically synchronizes the graph. Omitted entries do not retain the
+previous preset's colors. Reset restores pre-existing inline declarations and
+leaves unrelated styles and subsequently edited declarations alone. Root inline
+variables take precedence over inherited host variables, following normal CSS.
+
+`colorScheme: 'dark' | 'light'` maps to `--zfgi-color-scheme`; do not repeat it
+inside `variables`. It controls native browser appearance, not palette choice.
+The component does not infer light colors from a light background or this hint.
+
+## CSS-only use
+
+Static variables on the host are picked up at mount and graph initialization:
+
+```css
+.inspector-host {
+  --zfgi-accent: var(--app-accent, #7aa2f7);
+  --zfgi-font-ui: system-ui, sans-serif;
+  --zfgi-graph-render-stroke: #9ece6a;
+}
+```
+
+No JS theme call is required. Unspecified variables use CSS fallbacks. The
+component does not write a full inline theme during default mounting, so parent
+variables inherit normally. Configure dependent overrides on the same container:
+CSS custom-property references are resolved where they are declared.
+
+For complete CSS presets, explicitly import the optional stylesheet:
+
+```css
+@import '@zenfg/inspector/themes.css';
+```
+
+```html
+<div class="inspector-host" data-zfgi-theme="tokyo-night-light"></div>
+```
+
+The other preset selector is `data-zfgi-theme="tokyo-night-storm"`. The stylesheet
+does not select a global theme; declarations only apply to matching containers.
+Its values are generated from the same definitions as the JavaScript presets.
+
+## Dynamic CSS and graph synchronization
+
+```ts
+host.dataset.zfgiTheme = 'tokyo-night-light';
+inspector.refreshTheme();
+```
+
+DOM styling updates through CSS. Cytoscape consumes resolved values rather than
+browser CSS, so call `refreshTheme()` after changing host variables, classes,
+theme attributes, or media-query-dependent values. JS `setTheme()` already does
+this. Refresh reads CSS without rewriting variables. No global observers or
+polling are installed; hidden graphs also refresh when shown again.
+
+Palette changes keep the graph instance, positions, pan/zoom, selection, group
+expansion, current views, filters, detail state, and scroll positions. Graph font
+changes update label measurement and layout while preserving zoom and an anchor.
+
+## Supported variables
+
+All names below have the `--zfgi-` prefix. `InspectorThemeVariables` provides
+the exhaustive TypeScript key list. Values use CSS syntax: lengths such as
+`13px`, font-family stacks, colors including `var()` and `color-mix()`, and
+unitless opacity or scale values. Use positive font sizes and widths, opacity
+in the range 0–1, and non-negative arrow scale.
+
+| Group | Names after the prefix |
+| --- | --- |
+| Surfaces | `canvas`, `background`, `surface`, `surface-raised`, `surface-hover` |
+| Text and emphasis | `text`, `text-secondary`, `muted`, `accent`, `accent-soft`, `accent-hover` |
+| Boundaries and feedback | `border`, `border-subtle`, `border-strong`, `success`, `warning`, `danger`, `shadow`, `backdrop` |
+| Typography | `font-ui`, `font-mono`, `font-size`, `font-size-small` |
+| Dimensions | `control-height`, `row-height`, `radius-sm`, `radius-md`, `space-1`, `space-2`, `space-3`, `space-4` |
+| Native appearance | `color-scheme` (JS uses the separate `colorScheme` field) |
+| Graph labels | `graph-text`, `graph-muted`, `graph-font-family`, `graph-font-size` |
+| Graph categories | `graph-{category}-stroke`, `graph-{category}-fill` |
+| Graph groups | `graph-group-stroke`, `graph-group-fill`, `graph-group-alternate-fill`, `graph-group-opacity`, `graph-group-border-width` |
+| Graph relationships | `graph-value`, `graph-ordering`, `graph-read`, `graph-write`, `graph-edge-width`, `graph-edge-opacity`, `graph-ordering-opacity`, `graph-arrow-scale` |
+| Graph states | `graph-hover`, `graph-selected`, `graph-hover-width`, `graph-selected-width`, `graph-node-border-width`, `graph-culled-stroke`, `graph-culled-fill` |
+| Graph press indicator | `graph-active-bg`, `graph-active-bg-opacity`, `graph-active-bg-size` (radius in CSS pixels, default `12px`; opacity defaults to `0.08`) |
+| Derived category fills | `graph-tint` (18% in Storm, 8% in Light) |
+
+Categories are `render`, `compute`, `copy`, `clear`, `command`, `external`,
+`declaration`, `output`, `texture`, and `buffer`. Category colors also drive
+legends, type labels, and resource bars. Semantic shapes and layout algorithms
+are not theme parameters. Hover/selection emphasize outlines without replacing
+node shapes or category fills.
+
+The existing `--zenfg-inspector-*` names for background, surfaces, borders,
+text, accent, status colors, font families, and radii remain fallback aliases.
+When both are supplied, the corresponding new `--zfgi-*` value wins. Internal
+`--fgd-*` properties and presentation classes are not the public theme contract.
+
+Official presets target at least 7:1 node-text contrast, 4.5:1 UI text contrast,
+and 3:1 identifying borders and edges. Custom colors should preserve these
+relationships; theme application does not automatically correct a custom palette.

package/dist/FrameGraphInspector.d.ts

@@ -1,6 +1,10 @@
+import type { FrameGraphCaptureRequest } from './capture.ts';
+import type { InspectorTheme } from './theme.ts';
 import { type FrameGraphSnapshot } from '@zenfg/snapshot';
 /** 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.
@@ -12,7 +16,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.
      *
@@ -45,10 +49,12 @@ export type FrameGraphInspectorOptions = {
 export declare class FrameGraphInspector {
     /** Root element owned by this inspector instance. */
     readonly dom: HTMLElement;
+    private readonly themeController;
     private readonly body;
     private readonly content;
     private readonly dropOverlay;
     private readonly groupsButton;
+    private readonly declarationsButton;
     private readonly collapseGroupsButton;
     private readonly graphView;
     private readonly workbench;
@@ -69,6 +75,7 @@ export declare class FrameGraphInspector {
     private copyFeedbackTimeout;
     private readonly maxImportBytes;
     private dragDepth;
+    private revealRevision;
     private readonly handleDragEnter;
     private readonly handleDragOver;
     private readonly handleDragLeave;
@@ -81,11 +88,21 @@ export declare class FrameGraphInspector {
      * or if browser DOM globals are unavailable.
      */
     constructor(options?: FrameGraphInspectorOptions);
+    /** 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;
+    /** 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;
     /**
      * 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;
     /**
@@ -97,9 +114,9 @@ export declare class FrameGraphInspector {
      */
     captureSnapshot(): Promise<void>;
     /**
-     * Validates and synchronously displays a programmatic Snapshot 1.1 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;
     /** Returns the currently displayed canonical snapshot, if any. */
@@ -130,8 +147,10 @@ export declare class FrameGraphInspector {
     private updateCaptureActions;
     private maybeAutoCapture;
     private handleSelect;
+    private handleReveal;
     private handleHover;
     private updateGraphControls;
+    private toggleDeclarations;
     private toggleGroups;
     private toggleGroup;
     private collapseAllGroups;

package/dist/FrameGraphInspector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameGraphInspector.d.ts","sourceRoot":"","sources":["../src/FrameGraphInspector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FrameGraphInspector.d.ts","sourceRoot":"","sources":["../src/FrameGraphInspector.ts"],"names":[],"mappings":"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"}