@genome-spy/inspector 0.79.0

package/README.md

@@ -0,0 +1,114 @@
+# @genome-spy/inspector
+
+The inspector is a DevTools-like side panel for looking at GenomeSpy runtime
+state while developing or debugging visualizations. It shows the view hierarchy,
+encodings, scale/axis/legend resolutions, dataflow, params, and unit mark state.
+The goal is to make the live runtime easier to understand without adding debug
+UI or heavy inspection code to the default Core or App bundles.
+
+The initial implementation was largely vibe-coded with Codex. The tool is
+usable for development work, but the package API may still change as the
+integration points are refined.
+
+## Package Integrations
+
+### App
+
+GenomeSpy App uses the inspector through the App plugin surface:
+
+```js
+import { genomeSpyInspector } from "@genome-spy/inspector";
+
+await embed(element, spec, {
+  plugins: [genomeSpyInspector()],
+});
+```
+
+In the App development single-page entry, the inspector is installed
+automatically so it is available from the three-dot menu in the App toolbar
+during local development.
+
+The plugin uses App UI hooks to register a menu item and a side panel. It also
+registers an inspector launcher so App-side development commands can open this
+panel directly to a specific inspector view.
+
+### Playground
+
+GenomeSpy Playground depends on this package directly. The Playground toolbar
+has an Inspector button that replaces the editor/file pane with the inspector,
+so the plot and inspector are visible side by side.
+
+Playground uses the embeddable panel API:
+
+```js
+import { createInspectorPanel } from "@genome-spy/inspector";
+
+const inspector = await createInspectorPanel({
+  getRootView: () => embedResult.getDebugViewRoot(),
+});
+
+inspectorContainer.append(inspector.panel);
+await inspector.session.refresh();
+```
+
+The inspector is refreshed after Playground rebuilds the Core embed from the
+current editor contents.
+
+### Core Embeds
+
+Core does not load the inspector by itself. Applications that embed Core can
+install this package and attach the inspector only in development builds or
+behind their own debug UI.
+
+The Core embed result exposes a small debug hook:
+
+```js
+const api = await embed(element, spec);
+
+api.getDebugViewRoot();
+```
+
+That hook gives the inspector access to the live root view without adding a
+plugin system or loading debug UI into Core.
+
+For quick integration, use the floating overlay helper:
+
+```js
+import { embed } from "@genome-spy/core";
+import { attachInspectorOverlay } from "@genome-spy/inspector";
+
+const api = await embed(element, spec);
+
+await attachInspectorOverlay({
+  getRootView: () => api.getDebugViewRoot(),
+});
+```
+
+For applications with their own panels or split layouts, use
+`createInspectorPanel(...)` instead and place the returned `panel` element in
+the application UI.
+
+See the embed example:
+[Inspector overlay](../embed-examples/src/inspectorOverlay.html)
+([source](../embed-examples/src/inspectorOverlay.js)).
+
+## Architecture
+
+The inspector is centered around `InspectorSession`, which reads the live
+runtime through a small host object:
+
+```ts
+interface InspectorHost {
+  getRootView(): object | undefined;
+  highlightView?(view: object | null): void;
+}
+```
+
+The session dynamically imports Core debug snapshot helpers from
+`@genome-spy/core/debug/...` when it refreshes. This keeps debug-only collection
+code out of normal startup paths.
+
+`GsInspectorPanel` is a LitElement component that renders a session snapshot.
+`createInspectorPanel(...)` wires a session to the panel. App, Playground, and
+Core embed examples all use the same session and panel components, with only
+small host adapters around them.

package/dist/index.es.js

@@ -0,0 +1,229 @@
+import { getViewIdentityRegistry as e } from "@genome-spy/core/view/viewIdentityRegistry.js";
+//#region \0rolldown/runtime.js
+var t = Object.defineProperty, n = (e, n) => {
+	let r = {};
+	for (var i in e) t(r, i, {
+		get: e[i],
+		enumerable: !0
+	});
+	return n || t(r, Symbol.toStringTag, { value: "Module" }), r;
+}, r = {
+	prefix: "fas",
+	iconName: "bug",
+	icon: [
+		512,
+		512,
+		[],
+		"f188",
+		"M256 0c53 0 96 43 96 96l0 3.6c0 15.7-12.7 28.4-28.4 28.4l-135.1 0c-15.7 0-28.4-12.7-28.4-28.4l0-3.6c0-53 43-96 96-96zM41.4 105.4c12.5-12.5 32.8-12.5 45.3 0l64 64c.7 .7 1.3 1.4 1.9 2.1c14.2-7.3 30.4-11.4 47.5-11.4l112 0c17.1 0 33.2 4.1 47.5 11.4c.6-.7 1.2-1.4 1.9-2.1l64-64c12.5-12.5 32.8-12.5 45.3 0s12.5 32.8 0 45.3l-64 64c-.7 .7-1.4 1.3-2.1 1.9c6.2 12 10.1 25.3 11.1 39.5l64.3 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-64 0c0 24.6-5.5 47.8-15.4 68.6c2.2 1.3 4.2 2.9 6 4.8l64 64c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0l-63.1-63.1c-24.5 21.8-55.8 36.2-90.3 39.6L272 240c0-8.8-7.2-16-16-16s-16 7.2-16 16l0 239.2c-34.5-3.4-65.8-17.8-90.3-39.6L86.6 502.6c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3l64-64c1.9-1.9 3.9-3.4 6-4.8C101.5 367.8 96 344.6 96 320l-64 0c-17.7 0-32-14.3-32-32s14.3-32 32-32l64.3 0c1.1-14.1 5-27.5 11.1-39.5c-.7-.6-1.4-1.2-2.1-1.9l-64-64c-12.5-12.5-12.5-32.8 0-45.3z"
+	]
+}, i = /* @__PURE__ */ n({ default: () => a }), a = class extends EventTarget {
+	#e;
+	#t = !1;
+	#n = /* @__PURE__ */ new WeakMap();
+	#r = /* @__PURE__ */ new Map();
+	#i = {};
+	#a = /* @__PURE__ */ new WeakSet();
+	#o;
+	#s;
+	#c;
+	#l;
+	#u;
+	#d = [];
+	#f = !1;
+	snapshot = {
+		rootId: void 0,
+		nodes: [],
+		resolutions: {
+			scales: [],
+			axes: [],
+			legends: []
+		},
+		dataflow: {
+			sourceIds: [],
+			nodes: [],
+			collectorCount: 0
+		},
+		params: { scopes: [] },
+		marks: { marks: [] }
+	};
+	constructor(e) {
+		super(), this.#e = e;
+	}
+	get includeChrome() {
+		return this.#t;
+	}
+	async setIncludeChrome(e) {
+		this.#t !== e && (this.#t = e, await this.refresh());
+	}
+	async refresh() {
+		if (this.#f) return;
+		let e = this.#y(), [t, n, r, i, a] = await Promise.all([
+			this.#p(),
+			this.#m(),
+			this.#h(),
+			this.#g(),
+			this.#_()
+		]);
+		this.#r = /* @__PURE__ */ new Map(), this.#a = o(e);
+		let s = t.createViewDebugSnapshot(e, {
+			includeChrome: this.#t,
+			getDebugId: (e) => this.#b(e)
+		});
+		this.snapshot = {
+			...s,
+			resolutions: n.createResolutionDebugSnapshot(e, { getDebugId: (e) => this.#b(e) }),
+			dataflow: r.createDataflowDebugSnapshot(e?.context.dataFlow, {
+				getDebugId: (e) => this.#b(e),
+				rootView: e
+			}),
+			params: i.createParamDebugSnapshot(e, { getDebugId: (e) => this.#b(e) }),
+			marks: a.createMarkDebugSnapshot(e, { getDebugId: (e) => this.#b(e) })
+		}, this.#v(), this.dispatchEvent(new Event("snapshot"));
+	}
+	highlightView(e) {
+		let t = e ? this.#r.get(e) : null;
+		if (this.#e.highlightView) {
+			this.#e.highlightView(t ?? null);
+			return;
+		}
+		let n = this.#y();
+		n && n.context.highlightView(t ?? null);
+	}
+	dispose() {
+		this.#f = !0;
+		for (let e of this.#d.splice(0)) e();
+		this.highlightView(void 0);
+	}
+	#p() {
+		return this.#o ??= import("@genome-spy/core/debug/viewDebugSnapshot.js"), this.#o;
+	}
+	#m() {
+		return this.#s ??= import("@genome-spy/core/debug/resolutionDebugSnapshot.js"), this.#s;
+	}
+	#h() {
+		return this.#c ??= import("@genome-spy/core/debug/dataflowDebugSnapshot.js"), this.#c;
+	}
+	#g() {
+		return this.#l ??= import("@genome-spy/core/debug/paramDebugSnapshot.js"), this.#l;
+	}
+	#_() {
+		return this.#u ??= import("@genome-spy/core/debug/markDebugSnapshot.js"), this.#u;
+	}
+	#v() {
+		if (this.#d.length > 0) return;
+		let e = this.#y();
+		if (!e) return;
+		let t = () => {
+			this.refresh();
+		};
+		for (let n of [
+			"layoutComputed",
+			"subtreeDataReady",
+			"dataFlowBuilt"
+		]) e.context.addBroadcastListener(n, t), this.#d.push(() => e.context.removeBroadcastListener(n, t));
+	}
+	#y() {
+		return this.#e.getRootView();
+	}
+	#b(t) {
+		if (this.#a.has(t)) {
+			let n = e(this.#y()).getId(t);
+			return this.#r.set(n, t), n;
+		}
+		let n = this.#n.get(t);
+		if (n) return this.#r.set(n, t), n;
+		let r = s(t), i = (this.#i[r] ?? 0) + 1;
+		this.#i[r] = i;
+		let a = r + String(i);
+		return this.#n.set(t, a), this.#r.set(a, t), a;
+	}
+};
+function o(e) {
+	let t = /* @__PURE__ */ new WeakSet();
+	return e?.visit?.((e) => {
+		t.add(e);
+	}), t;
+}
+function s(e) {
+	return "channel" in e ? "r" : "o";
+}
+//#endregion
+//#region src/inspectorPlugin.js
+function c(e = {}) {
+	return {
+		name: "@genome-spy/inspector",
+		async install(t) {
+			if (!t.ui?.registerToolbarMenuItem) throw Error("genomeSpyInspector requires an App UI host.");
+			let n, i, o, s = async () => {
+				if (i) return i;
+				if (!t.ui.registerSidePanel) throw Error("genomeSpyInspector requires side panel support.");
+				let [{ GsInspectorPanel: r }] = await Promise.all([import("./inspectorPanel-Dc1i_a0B.js")]);
+				return n = new a({ getRootView: () => t.genomeSpy ? t.genomeSpy.viewRoot : void 0 }), o = new r(), o.session = n, o.addEventListener("close", () => {
+					i?.hide();
+				}), i = t.ui.registerSidePanel({
+					id: "genome-spy-inspector",
+					element: o,
+					preferredWidth: e.preferredWidth ?? "min(46vw, 760px)"
+				}), i;
+			}, c = async (e = {}) => {
+				let t = await s();
+				e.panel && o && (o.activePanel = e.panel), t.show(), await n.refresh();
+			}, l = t.ui.registerToolbarMenuItem({
+				label: "Inspector",
+				icon: r,
+				callback: () => {
+					c().catch(() => {});
+				}
+			});
+			return () => {
+				l(), n?.dispose(), n = void 0, i?.dispose(), i = void 0, o?.remove(), o = void 0;
+			};
+		}
+	};
+}
+//#endregion
+//#region src/index.js
+async function l(e, t = {}) {
+	let [{ default: n }, { GsInspectorPanel: r }] = await Promise.all([Promise.resolve().then(() => i), import("./inspectorPanel-Dc1i_a0B.js")]), a = new n(e), o = new r();
+	return o.session = a, t.activePanel && (o.activePanel = t.activePanel), {
+		panel: o,
+		session: a,
+		dispose: () => {
+			a.dispose(), o.remove();
+		}
+	};
+}
+async function u(e, t = {}) {
+	let n = t.container ?? document.body, r = document.createElement("section");
+	r.className = "gs-inspector-overlay", Object.assign(r.style, {
+		position: "fixed",
+		top: "0",
+		right: "0",
+		bottom: "0",
+		zIndex: "2147483647",
+		width: t.width ?? "min(46vw, 760px)",
+		minWidth: "320px",
+		maxWidth: "100vw",
+		boxShadow: "0 0 18px rgba(0, 0, 0, 0.35)",
+		resize: "horizontal",
+		overflow: "hidden"
+	});
+	let i = await l(e, { activePanel: t.activePanel });
+	Object.assign(i.panel.style, {
+		display: "block",
+		height: "100%",
+		minHeight: "0"
+	}), r.append(i.panel), n.append(r);
+	let a = () => {
+		i.dispose(), r.remove();
+	};
+	return i.panel.addEventListener("close", a, { once: !0 }), await i.session.refresh(), {
+		element: r,
+		panel: i.panel,
+		session: i.session,
+		dispose: a
+	};
+}
+//#endregion
+export { a as InspectorSession, u as attachInspectorOverlay, l as createInspectorPanel, c as genomeSpyInspector };