@zenfg/inspector 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZenFG contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @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)
+
+`@zenfg/inspector` is an embeddable, renderer-independent DOM workbench for
+ZenFG Snapshot data. It depends on `@zenfg/snapshot`, Cytoscape, and ELK; it has
+no WebGPU, wgpu, engine, or host-UI dependency.
+
+This is a public beta package. Public APIs may change before 1.0; integration
+projects should pin the exact beta version.
+
+For package selection, the capture data flow, version boundaries, and links to
+complete producer recipes, see the
+[ZenFG quick reference](https://github.com/uinosoft/zenfg/blob/main/docs/quick-reference.md).
+
+## Installation
+
+```sh
+npm install @zenfg/inspector@0.1.0-beta.1
+```
+
+## Usage
+
+```ts
+import { mountFrameGraphInspector } from '@zenfg/inspector';
+
+const inspector = mountFrameGraphInspector(document.querySelector('#tools')!, {
+  captureSnapshot: () => renderer.requestFrameGraphSnapshot(),
+  branding: 'ZenFG Inspector', // Pass false to hide visible branding.
+});
+
+inspector.setSnapshot(existingSnapshot);
+await inspector.importSnapshot(file);
+inspector.downloadSnapshot();
+await inspector.copySnapshotJson();
+inspector.destroy();
+```
+
+`FrameGraphInspector` fills any `HTMLElement` with a non-zero width and height,
+so the same workbench can be a full page or an embedded tool. Product branding,
+file selection, and file drag-and-drop are built in; an optional dock or overlay
+adapter remains the host application's responsibility. File import defaults to
+64 MiB and may be adjusted with
+`maxImportBytes`. `maxGraphElements` defaults to 5,000; captures above that
+layout budget retain Passes, Resources, Memory, Diagnostics, Inspector, and raw
+views while automatic Cytoscape/ELK layout is disabled with an explanation.
+
+## Workbench
+
+The persistent workbench provides Overview, Graph, Passes, Resources, Memory,
+and Diagnostics views plus a selection Inspector with Summary, Relations, and
+Raw panes. It supports live capture providers, direct Snapshot set/get, file
+import, Legacy V0 and Legacy Candidate V1 migration, canonical download,
+clipboard copy, and cleanup through `destroy()`.
+
+Capture, import, and direct replacement share a revision counter: stale async
+results and results arriving after destruction are ignored. A failed or
+oversized import leaves the current capture and UI state intact. The latest
+valid capture preserves tab, filter, sorting, group-expansion, graph mode,
+selection, Inspector, scrolling, and viewport state where possible.
+
+Graph layout is lazy and read-only. ELK computes layered compound geometry and
+Cytoscape renders it with pan, zoom, selection, hover, tooltips, group
+expansion, relayout, and fit controls. Input labels and raw fields are assigned
+with text DOM APIs; Snapshot extensions, URLs, labels, and messages are never
+executed as markup or code.
+
+The backend-free application in `apps/inspector` mounts the same workbench into
+a full-viewport host without adding duplicate controls. It is built as static
+files and includes third-party notices; hosting and deployment are deliberately
+separate.

package/dist/FrameGraphInspector.d.ts

@@ -0,0 +1,153 @@
+import { type FrameGraphSnapshot } from '@zenfg/snapshot';
+/** Construction and safety limits for an embedded {@link FrameGraphInspector}. */
+export type FrameGraphInspectorOptions = {
+    /**
+     * Product label shown in the workbench command bar. Pass `false` to hide
+     * visible branding while retaining the inspector's accessible name.
+     *
+     * @defaultValue `"ZenFG Inspector"`
+     */
+    branding?: string | false;
+    /**
+     * 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>;
+    /**
+     * Maximum accepted import size in bytes.
+     *
+     * @defaultValue `67108864` (64 MiB)
+     */
+    maxImportBytes?: number;
+    /**
+     * Maximum graph nodes plus edges accepted by automatic layout.
+     *
+     * @defaultValue `5000`
+     */
+    maxGraphElements?: number;
+};
+/**
+ * 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 declare class FrameGraphInspector {
+    /** Root element owned by this inspector instance. */
+    readonly dom: HTMLElement;
+    private readonly body;
+    private readonly content;
+    private readonly dropOverlay;
+    private readonly passesGraphModeButton;
+    private readonly resourcesGraphModeButton;
+    private readonly groupsButton;
+    private readonly collapseGroupsButton;
+    private readonly graphView;
+    private readonly workbench;
+    private captureSnapshotCallback;
+    private protocolSnapshot;
+    private operationRevision;
+    private viewModel;
+    private selected;
+    private hovered;
+    private capturing;
+    private importing;
+    private copying;
+    private copied;
+    private initialAutoCaptureAttempted;
+    private statusMessage;
+    private statusTone;
+    private destroyed;
+    private copyFeedbackTimeout;
+    private readonly maxImportBytes;
+    private dragDepth;
+    private readonly handleDragEnter;
+    private readonly handleDragOver;
+    private readonly handleDragLeave;
+    private readonly handleDragEnd;
+    private readonly handleDrop;
+    /**
+     * 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?: FrameGraphInspectorOptions);
+    /**
+     * Replaces or removes the live-capture provider.
+     *
+     * @remarks Installing a provider may immediately begin an asynchronous
+     * capture when no snapshot is displayed.
+     */
+    setCaptureSnapshotProvider(provider: FrameGraphInspectorOptions['captureSnapshot']): void;
+    /**
+     * 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.
+     */
+    captureSnapshot(): Promise<void>;
+    /**
+     * Validates and synchronously displays a programmatic Snapshot 1.0 value.
+     *
+     * @throws {@link FrameGraphSnapshotValidationError} if `snapshot` is invalid.
+     */
+    setSnapshot(snapshot: FrameGraphSnapshot): void;
+    /** Returns the currently displayed canonical snapshot, if any. */
+    getSnapshot(): FrameGraphSnapshot | undefined;
+    /**
+     * 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.
+     */
+    importSnapshot(file: File): Promise<void>;
+    /** Downloads the displayed snapshot as pretty-printed canonical JSON. */
+    downloadSnapshot(): void;
+    /**
+     * 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.
+     */
+    copySnapshotJson(): Promise<void>;
+    private applySnapshot;
+    /**
+     * Idempotently cancels pending UI results, releases graph resources, and
+     * removes the inspector workbench. Do not reuse the controller afterward.
+     */
+    destroy(): void;
+    private updateCaptureActions;
+    private maybeAutoCapture;
+    private handleSelect;
+    private handleHover;
+    private setGraphMode;
+    private updateGraphModeButtonState;
+    private toggleGroups;
+    private toggleGroup;
+    private collapseAllGroups;
+    private showEmptyState;
+    private setDropActive;
+    private clearDropState;
+    private reportCaptureIssue;
+}
+/**
+ * Creates an inspector, appends its root element to `host`, and returns its
+ * lifecycle controller.
+ *
+ * @throws If inspector construction fails; see {@link FrameGraphInspector}.
+ */
+export declare function mountFrameGraphInspector(host: HTMLElement, options?: FrameGraphInspectorOptions): FrameGraphInspector;
+//# sourceMappingURL=FrameGraphInspector.d.ts.map

package/dist/FrameGraphInspector.d.ts.map

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