@zenfg/inspector 0.1.0-beta.1

package/dist/FrameGraphInspector.js

@@ -0,0 +1,580 @@
+import { FrameGraphSnapshotValidationError, decodeFrameGraphSnapshot, parseFrameGraphSnapshot, stringifyFrameGraphSnapshot, } from '@zenfg/snapshot';
+import { createDebugViewModel, } from "./debugCaptureModel.js";
+import { createToolbarButton } from "./panelDomHelpers.js";
+import { createPanelIcon } from "./panelIcons.js";
+import { destroyGraph, fitGraph, } from "./panelGraphView.js";
+import { graphGroupElementId } from "./panelGraphScene.js";
+import { selectionExists } from "./panelSelection.js";
+import { ensureFrameGraphInspectorStyles } from "./styles.js";
+import { sameSelection } from "./panelWorkbenchHelpers.js";
+import { FrameGraphDebugWorkbench } from "./panelWorkbenchView.js";
+const DEFAULT_MAX_IMPORT_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_GRAPH_ELEMENTS = 5_000;
+const DEFAULT_BRANDING = 'ZenFG Inspector';
+/**
+ * Browser lifecycle controller for one embeddable FrameGraph inspector.
+ *
+ * @remarks The constructor creates, but does not append, {@link dom}. Use
+ * {@link mountFrameGraphInspector} for the common append-and-return workflow.
+ * Async capture, import, and clipboard failures are reported in the UI. Call
+ * {@link destroy} when the controller is no longer needed.
+ *
+ * @example
+ * ```ts
+ * const inspector = new FrameGraphInspector({ captureSnapshot: capture });
+ * document.body.append(inspector.dom);
+ * // Later:
+ * inspector.destroy();
+ * ```
+ */
+export class FrameGraphInspector {
+    /** Root element owned by this inspector instance. */
+    dom = document.createElement('section');
+    body = document.createElement('div');
+    content = document.createElement('div');
+    dropOverlay = document.createElement('div');
+    passesGraphModeButton;
+    resourcesGraphModeButton;
+    groupsButton;
+    collapseGroupsButton;
+    graphView;
+    workbench;
+    captureSnapshotCallback;
+    protocolSnapshot;
+    operationRevision = 0;
+    viewModel;
+    selected;
+    hovered;
+    capturing = false;
+    importing = false;
+    copying = false;
+    copied = false;
+    initialAutoCaptureAttempted = false;
+    statusMessage;
+    statusTone = 'neutral';
+    destroyed = false;
+    copyFeedbackTimeout;
+    maxImportBytes;
+    dragDepth = 0;
+    handleDragEnter = (event) => {
+        if (!isFileDrag(event))
+            return;
+        event.preventDefault();
+        this.dragDepth += 1;
+        this.setDropActive(true);
+    };
+    handleDragOver = (event) => {
+        if (!isFileDrag(event))
+            return;
+        event.preventDefault();
+        if (event.dataTransfer)
+            event.dataTransfer.dropEffect = 'copy';
+        this.setDropActive(true);
+    };
+    handleDragLeave = (event) => {
+        if (!isFileDrag(event) && this.dragDepth === 0)
+            return;
+        this.dragDepth = Math.max(0, this.dragDepth - 1);
+        if (this.dragDepth === 0)
+            this.setDropActive(false);
+    };
+    handleDragEnd = () => this.clearDropState();
+    handleDrop = (event) => {
+        const file = event.dataTransfer?.files?.[0];
+        if (!file)
+            return;
+        event.preventDefault();
+        this.clearDropState();
+        void this.importSnapshot(file);
+    };
+    /**
+     * Creates a detached inspector UI.
+     *
+     * @throws If a configured numeric limit is not a non-negative safe integer,
+     * or if browser DOM globals are unavailable.
+     */
+    constructor(options = {}) {
+        ensureFrameGraphInspectorStyles();
+        this.captureSnapshotCallback = options.captureSnapshot;
+        this.maxImportBytes = normalizeMaxImportBytes(options.maxImportBytes);
+        const branding = options.branding ?? DEFAULT_BRANDING;
+        this.dom.className = 'zenfg-inspector';
+        this.dom.id = createInspectorId();
+        this.dom.setAttribute('role', 'region');
+        this.dom.setAttribute('aria-label', branding === false ? DEFAULT_BRANDING : branding);
+        this.body.className = 'zenfg-inspector-body';
+        this.content.className = 'zenfg-inspector-content';
+        this.dropOverlay.className = 'zenfg-inspector-drop-overlay';
+        this.dropOverlay.hidden = true;
+        this.dropOverlay.setAttribute('aria-hidden', 'true');
+        const dropTitle = document.createElement('strong');
+        dropTitle.textContent = 'Drop snapshot to open';
+        const dropDetail = document.createElement('span');
+        dropDetail.textContent = 'The first file will be imported locally.';
+        this.dropOverlay.append(dropTitle, dropDetail);
+        const graphLegend = document.createElement('div');
+        graphLegend.className = 'zenfg-inspector-graph-legend';
+        graphLegend.setAttribute('aria-label', 'Graph legend');
+        this.graphView = {
+            host: document.createElement('div'),
+            toolbar: document.createElement('div'),
+            legend: graphLegend,
+            layoutElementBudget: normalizeLimit(options.maxGraphElements, DEFAULT_MAX_GRAPH_ELEMENTS, 'maxGraphElements'),
+            graphMode: 'passes',
+            groupsEnabled: true,
+            expandedGroupPaths: new Set(),
+            fitOnNextRender: true,
+        };
+        this.graphView.host.className = 'zenfg-inspector-graph';
+        this.graphView.toolbar.className = 'zenfg-inspector-graph-toolbar';
+        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.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.groupsButton, this.collapseGroupsButton, createGraphIconButton('fit', 'Fit graph to view', () => fitGraph(this.graphView)));
+        this.graphView.toolbar.append(modeControls, graphLegend, actionControls);
+        const callbacks = {
+            onSelect: (selection) => this.handleSelect(selection),
+            onHover: (selection) => this.handleHover(selection),
+            onGroupToggle: (pathKey) => this.toggleGroup(pathKey),
+            isGroupExpanded: (pathKey) => this.graphView.expandedGroupPaths.has(pathKey),
+        };
+        this.workbench = new FrameGraphDebugWorkbench(this.graphView, callbacks, {
+            onCapture: () => { void this.captureSnapshot(); },
+            onImport: (file) => { void this.importSnapshot(file); },
+            onDownload: () => this.downloadSnapshot(),
+            onCopyJson: () => { void this.copySnapshotJson(); },
+        }, {
+            branding,
+            idPrefix: this.dom.id,
+        });
+        this.content.append(this.workbench.root);
+        this.body.appendChild(this.content);
+        this.dom.append(this.body, this.dropOverlay);
+        this.dom.addEventListener('dragenter', this.handleDragEnter);
+        this.dom.addEventListener('dragover', this.handleDragOver);
+        this.dom.addEventListener('dragleave', this.handleDragLeave);
+        this.dom.addEventListener('dragend', this.handleDragEnd);
+        this.dom.addEventListener('drop', this.handleDrop);
+        this.updateCaptureActions();
+        this.updateGraphModeButtonState();
+        this.showEmptyState();
+        queueMicrotask(() => this.maybeAutoCapture());
+    }
+    /**
+     * Replaces or removes the live-capture provider.
+     *
+     * @remarks Installing a provider may immediately begin an asynchronous
+     * capture when no snapshot is displayed.
+     */
+    setCaptureSnapshotProvider(provider) {
+        const changed = this.captureSnapshotCallback !== provider;
+        this.captureSnapshotCallback = provider;
+        if (changed && !this.viewModel)
+            this.initialAutoCaptureAttempted = false;
+        if (!provider && !this.viewModel)
+            this.showEmptyState();
+        this.updateCaptureActions();
+        this.maybeAutoCapture();
+    }
+    /**
+     * Requests and displays a live snapshot from the configured provider.
+     *
+     * @remarks Concurrent requests are coalesced. Provider errors, invalid
+     * snapshots, and an unavailable provider are displayed in the inspector and
+     * do not reject the returned promise.
+     */
+    async captureSnapshot() {
+        if (this.destroyed || this.capturing)
+            return;
+        if (!this.captureSnapshotCallback) {
+            this.reportCaptureIssue('Waiting for a FrameGraph capture source.');
+            return;
+        }
+        const revision = ++this.operationRevision;
+        this.importing = false;
+        this.capturing = true;
+        this.statusMessage = undefined;
+        this.statusTone = 'neutral';
+        if (!this.viewModel)
+            this.workbench.showEmptyState('capturing', 'Capturing the next rendered frame…');
+        this.updateCaptureActions();
+        try {
+            const snapshot = await this.captureSnapshotCallback();
+            if (this.destroyed || revision !== this.operationRevision)
+                return;
+            if (!snapshot) {
+                this.reportCaptureIssue('No snapshot was produced. Capture again when rendering is active.');
+                return;
+            }
+            const decoded = decodeFrameGraphSnapshot(snapshot);
+            if (!decoded.ok) {
+                this.reportCaptureIssue(`Failed to capture FrameGraph: ${formatIssues(decoded.issues)}`);
+                return;
+            }
+            this.applySnapshot(decoded.snapshot, { kind: 'live', label: 'Live Capture' });
+        }
+        catch (error) {
+            if (!this.destroyed && revision === this.operationRevision) {
+                this.reportCaptureIssue(`Failed to capture FrameGraph: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        finally {
+            if (revision === this.operationRevision)
+                this.capturing = false;
+            if (!this.destroyed && revision === this.operationRevision)
+                this.updateCaptureActions();
+        }
+    }
+    /**
+     * Validates and synchronously displays a programmatic Snapshot 1.0 value.
+     *
+     * @throws {@link FrameGraphSnapshotValidationError} if `snapshot` is invalid.
+     */
+    setSnapshot(snapshot) {
+        if (this.destroyed)
+            return;
+        this.operationRevision += 1;
+        this.capturing = false;
+        this.importing = false;
+        const decoded = decodeFrameGraphSnapshot(snapshot);
+        if (!decoded.ok)
+            throw new FrameGraphSnapshotValidationError(decoded.issues);
+        this.applySnapshot(decoded.snapshot, { kind: 'programmatic', label: 'Programmatic' });
+    }
+    /** Returns the currently displayed canonical snapshot, if any. */
+    getSnapshot() {
+        return this.protocolSnapshot;
+    }
+    /**
+     * Reads, migrates, validates, and displays a snapshot JSON file.
+     *
+     * @remarks Files above `maxImportBytes`, read failures, invalid JSON, and
+     * validation failures are displayed in the UI and do not reject the promise.
+     */
+    async importSnapshot(file) {
+        if (this.destroyed)
+            return;
+        const revision = ++this.operationRevision;
+        this.capturing = false;
+        this.importing = false;
+        if (file.size > this.maxImportBytes) {
+            this.reportCaptureIssue(`Import exceeds the ${formatImportLimit(this.maxImportBytes)} limit.`);
+            return;
+        }
+        this.importing = true;
+        this.statusMessage = undefined;
+        this.statusTone = 'neutral';
+        this.updateCaptureActions();
+        try {
+            const text = await file.text();
+            if (this.destroyed || revision !== this.operationRevision)
+                return;
+            const decoded = parseFrameGraphSnapshot(text);
+            if (!decoded.ok) {
+                this.reportCaptureIssue(`Failed to import snapshot: ${formatIssues(decoded.issues)}`);
+                return;
+            }
+            this.applySnapshot(decoded.snapshot, {
+                kind: 'file',
+                label: file.name || 'Imported JSON',
+            });
+            const sourceFormat = decoded.snapshot.capture.migration?.sourceFormat;
+            if (sourceFormat) {
+                const sourceLabel = sourceFormat === 'legacy-v0' ? 'Legacy V0' : 'Legacy Candidate V1';
+                this.statusMessage = decoded.migrated
+                    ? `Imported ${sourceLabel} and migrated it to ZenFG Snapshot V1.`
+                    : `Imported Snapshot V1 with ${sourceLabel} migration provenance.`;
+                this.statusTone = 'neutral';
+            }
+        }
+        catch (error) {
+            if (!this.destroyed && revision === this.operationRevision) {
+                this.reportCaptureIssue(`Failed to import snapshot: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        finally {
+            if (revision === this.operationRevision)
+                this.importing = false;
+            if (!this.destroyed && revision === this.operationRevision)
+                this.updateCaptureActions();
+        }
+    }
+    /** Downloads the displayed snapshot as pretty-printed canonical JSON. */
+    downloadSnapshot() {
+        if (this.destroyed || !this.protocolSnapshot)
+            return;
+        const json = stringifyFrameGraphSnapshot(this.protocolSnapshot, { pretty: true });
+        const url = URL.createObjectURL(new Blob([json], { type: 'application/json;charset=utf-8' }));
+        const anchor = document.createElement('a');
+        anchor.href = url;
+        anchor.download = `frame-graph-${this.protocolSnapshot.capture.frameIndex}.fgsnapshot.json`;
+        anchor.click();
+        URL.revokeObjectURL(url);
+    }
+    /**
+     * Copies the displayed snapshot as pretty-printed canonical JSON.
+     *
+     * @remarks Clipboard failures are shown in the UI and do not reject the
+     * returned promise. A legacy `document.execCommand` fallback is used when the
+     * async Clipboard API is unavailable.
+     */
+    async copySnapshotJson() {
+        if (this.destroyed || this.copying || !this.protocolSnapshot)
+            return;
+        const snapshot = this.protocolSnapshot;
+        const revision = this.operationRevision;
+        this.copying = true;
+        this.copied = false;
+        this.statusMessage = undefined;
+        this.statusTone = 'neutral';
+        this.updateCaptureActions();
+        try {
+            await writeTextToClipboard(stringifyFrameGraphSnapshot(snapshot, { pretty: true }));
+            if (this.destroyed || revision !== this.operationRevision)
+                return;
+            this.copied = true;
+            if (this.copyFeedbackTimeout !== undefined)
+                window.clearTimeout(this.copyFeedbackTimeout);
+            this.copyFeedbackTimeout = window.setTimeout(() => {
+                this.copied = false;
+                this.copyFeedbackTimeout = undefined;
+                this.updateCaptureActions();
+            }, 1200);
+        }
+        catch (error) {
+            if (!this.destroyed && revision === this.operationRevision) {
+                this.statusMessage = `Failed to copy snapshot: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            console.warn('Failed to copy FrameGraph Snapshot.', error);
+        }
+        finally {
+            this.copying = false;
+            if (!this.destroyed)
+                this.updateCaptureActions();
+        }
+    }
+    applySnapshot(snapshot, source) {
+        const viewModel = createDebugViewModel(snapshot, source);
+        this.copied = false;
+        if (this.copyFeedbackTimeout !== undefined) {
+            window.clearTimeout(this.copyFeedbackTimeout);
+            this.copyFeedbackTimeout = undefined;
+        }
+        this.protocolSnapshot = snapshot;
+        this.viewModel = viewModel;
+        this.graphView.fitOnNextRender = true;
+        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;
+        }
+        this.workbench.setSnapshot(viewModel, this.selected);
+        this.updateCaptureActions();
+        this.updateGraphModeButtonState();
+    }
+    /**
+     * Idempotently cancels pending UI results, releases graph resources, and
+     * removes the inspector workbench. Do not reuse the controller afterward.
+     */
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.operationRevision += 1;
+        if (this.copyFeedbackTimeout !== undefined)
+            window.clearTimeout(this.copyFeedbackTimeout);
+        this.clearDropState();
+        this.dom.removeEventListener('dragenter', this.handleDragEnter);
+        this.dom.removeEventListener('dragover', this.handleDragOver);
+        this.dom.removeEventListener('dragleave', this.handleDragLeave);
+        this.dom.removeEventListener('dragend', this.handleDragEnd);
+        this.dom.removeEventListener('drop', this.handleDrop);
+        destroyGraph(this.graphView);
+        this.dom.remove();
+    }
+    updateCaptureActions() {
+        this.workbench.setSnapshotActionState({
+            providerAvailable: Boolean(this.captureSnapshotCallback),
+            hasCapture: Boolean(this.viewModel),
+            capturing: this.capturing,
+            importing: this.importing,
+            copying: this.copying,
+            copied: this.copied,
+            message: this.viewModel ? this.statusMessage : undefined,
+            messageTone: this.statusTone,
+        });
+    }
+    maybeAutoCapture() {
+        if (this.destroyed
+            || this.viewModel
+            || this.initialAutoCaptureAttempted
+            || this.capturing
+            || this.importing
+            || !this.captureSnapshotCallback)
+            return;
+        this.initialAutoCaptureAttempted = true;
+        void this.captureSnapshot();
+    }
+    handleSelect(selection) {
+        this.selected = selection;
+        this.workbench.setSelection(selection);
+    }
+    handleHover(selection) {
+        if (!this.viewModel || sameSelection(this.hovered, selection))
+            return;
+        this.hovered = selection;
+        this.workbench.setHovered(selection);
+    }
+    setGraphMode(mode) {
+        if (this.graphView.graphMode === mode)
+            return;
+        this.graphView.graphMode = mode;
+        this.graphView.fitOnNextRender = true;
+        this.updateGraphModeButtonState();
+        this.workbench.refreshGraphStructure();
+    }
+    updateGraphModeButtonState() {
+        const passesActive = this.graphView.graphMode === 'passes';
+        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');
+        const hasExpanded = this.viewModel?.debugGroups.some((group) => this.graphView.expandedGroupPaths.has(group.pathKey)) ?? false;
+        this.collapseGroupsButton.disabled = !passesActive || !hasGroups || !this.graphView.groupsEnabled || !hasExpanded;
+    }
+    toggleGroups() {
+        if (this.graphView.graphMode !== 'passes' || !this.viewModel?.debugGroups.length)
+            return;
+        this.graphView.groupsEnabled = !this.graphView.groupsEnabled;
+        this.graphView.fitOnNextRender = true;
+        this.updateGraphModeButtonState();
+        this.workbench.refreshGraphStructure();
+    }
+    toggleGroup(pathKey) {
+        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.workbench.refreshGraphStructure();
+    }
+    collapseAllGroups() {
+        if (this.graphView.expandedGroupPaths.size === 0)
+            return;
+        this.graphView.expandedGroupPaths.clear();
+        this.graphView.fitOnNextRender = true;
+        this.updateGraphModeButtonState();
+        this.workbench.refreshGraphStructure();
+    }
+    showEmptyState() {
+        const providerAvailable = Boolean(this.captureSnapshotCallback);
+        this.workbench.showEmptyState('empty', providerAvailable
+            ? 'No capture yet. Use Capture to request the next rendered frame.'
+            : 'Drop a ZenFG Snapshot here or choose Import.', providerAvailable ? undefined : 'Files are processed locally in your browser.');
+    }
+    setDropActive(active) {
+        if (this.destroyed)
+            return;
+        this.dropOverlay.hidden = !active;
+        this.dom.classList.toggle('drop-active', active);
+    }
+    clearDropState() {
+        this.dragDepth = 0;
+        this.dropOverlay.hidden = true;
+        this.dom.classList.remove('drop-active');
+    }
+    reportCaptureIssue(message) {
+        this.statusMessage = message;
+        this.statusTone = 'error';
+        if (!this.viewModel)
+            this.workbench.showEmptyState('error', message);
+        this.updateCaptureActions();
+    }
+}
+/**
+ * Creates an inspector, appends its root element to `host`, and returns its
+ * lifecycle controller.
+ *
+ * @throws If inspector construction fails; see {@link FrameGraphInspector}.
+ */
+export function mountFrameGraphInspector(host, options) {
+    const inspector = new FrameGraphInspector(options);
+    host.appendChild(inspector.dom);
+    return inspector;
+}
+function createGraphIconButton(icon, title, onClick) {
+    const button = createToolbarButton('', title, onClick);
+    button.classList.add('zenfg-inspector-icon-button');
+    button.appendChild(createPanelIcon(icon));
+    return button;
+}
+async function writeTextToClipboard(text) {
+    if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+        return;
+    }
+    const textArea = document.createElement('textarea');
+    textArea.value = text;
+    textArea.setAttribute('readonly', 'true');
+    textArea.style.position = 'fixed';
+    textArea.style.left = '-9999px';
+    textArea.style.top = '0';
+    document.body.appendChild(textArea);
+    textArea.select();
+    try {
+        if (!document.execCommand('copy'))
+            throw new Error('document.execCommand("copy") returned false.');
+    }
+    finally {
+        textArea.remove();
+    }
+}
+function normalizeMaxImportBytes(value) {
+    return normalizeLimit(value, DEFAULT_MAX_IMPORT_BYTES, 'maxImportBytes');
+}
+function normalizeLimit(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative safe integer.`);
+    }
+    return value;
+}
+function formatImportLimit(bytes) {
+    return bytes >= 1024 * 1024 && bytes % (1024 * 1024) === 0
+        ? `${bytes / (1024 * 1024)} MiB`
+        : `${bytes} bytes`;
+}
+function formatIssues(issues) {
+    return issues.slice(0, 3).map((issue) => `${issue.path || '/'}: ${issue.message}`).join('; ');
+}
+function isFileDrag(event) {
+    return Array.from(event.dataTransfer?.types ?? []).includes('Files');
+}
+let nextInspectorId = 0;
+function createInspectorId() {
+    nextInspectorId += 1;
+    return `zenfg-inspector-${nextInspectorId}`;
+}
+//# sourceMappingURL=FrameGraphInspector.js.map