@dxos/app-framework 0.10.0 → 0.11.0

package/dist/lib/chunk-SurfaceManager.mjs

@@ -0,0 +1,960 @@
+import { ReactSurface } from "./common/capabilities.mjs";
+import { Position } from "@dxos/util";
+import { Atom } from "@effect-atom/atom";
+import { log } from "@dxos/log";
+import { Fragment, Profiler, Suspense, createContext, createElement, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { ErrorBoundary } from "@dxos/react-error-boundary";
+import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
+import { raise } from "@dxos/debug";
+import { useDefaultValue } from "@dxos/react-hooks";
+import { RegistryContext, useAtomValue } from "@effect-atom/atom-react";
+import { mx } from "@dxos/ui-theme";
+import { createPortal } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { addEventListener, combine } from "@dxos/async";
+import * as Data from "effect/Data";
+//#region src/helpers.ts
+/**
+* Topologically sorts a list of nodes based on their dependencies.
+*/
+var topologicalSort = (nodes) => {
+	const getDependencies = (nodeId, seen = /* @__PURE__ */ new Set(), path = /* @__PURE__ */ new Set()) => {
+		if (path.has(nodeId)) throw new Error(`Circular dependency detected involving ${nodeId}`);
+		if (seen.has(nodeId)) return [];
+		const node = nodes.find((n) => n.id === nodeId);
+		if (!node) throw new Error(`Node ${nodeId} not found but is listed as a dependency`);
+		const newPath = /* @__PURE__ */ new Set([...path, nodeId]);
+		const newSeen = /* @__PURE__ */ new Set([...seen, nodeId]);
+		return [...(node.dependsOn ?? []).flatMap((depId) => getDependencies(depId, newSeen, newPath)), nodeId];
+	};
+	return nodes.map((node) => node.id).flatMap((id) => getDependencies(id)).filter((id, index, self) => self.indexOf(id) === index).map((id) => nodes.find((node) => node.id === id)).filter((node) => node !== void 0);
+};
+//#endregion
+//#region src/ui/components/PluginManager/PluginManagerProvider.ts
+var PluginManagerContext = createContext(void 0);
+/**
+* Get the plugin manager.
+*/
+var usePluginManager = () => useContext(PluginManagerContext) ?? raise(/* @__PURE__ */ new Error("Missing PluginManagerContext"));
+/**
+* Get the plugin manager if present, or `undefined` when rendered outside a {@link PluginManagerProvider}
+* (e.g. a standalone component story). Lets components treat plugin capabilities as a progressive
+* enhancement rather than a hard requirement.
+*/
+var useOptionalPluginManager = () => useContext(PluginManagerContext);
+/**
+* Context provider for a plugin manager.
+*/
+var PluginManagerProvider = PluginManagerContext.Provider;
+//#endregion
+//#region src/ui/components/Surface/context.ts
+var SurfaceContext = createContext(void 0);
+//#endregion
+//#region src/ui/components/Surface/SurfaceMetrics.ts
+/** Consecutive unstable renders before `dataUnstable` is flagged. */
+var UNSTABLE_THRESHOLD = 3;
+var surfaceMetricKey = (surfaceId, role) => `surface/${surfaceId}/${role}`;
+/**
+* Shallow (top-level) value equality. Used to distinguish a genuinely new `data`
+* value from a new object/array carrying the same content (the unstable-prop case).
+*/
+var shallowEqual = (a, b) => {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.is(a[key], b[key]));
+};
+/**
+* Singleton store of surface dev metrics. A module singleton (rather than a React
+* context) so the debug overlay — which renders in its own root outside the app's
+* provider tree — can read the same data as the in-app devtools panel.
+*/
+var SurfaceMetricsStore = class {
+	#metrics = /* @__PURE__ */ new Map();
+	#snapshot = [];
+	#listeners = /* @__PURE__ */ new Set();
+	#pendingNotify = false;
+	#entry(surfaceId, role) {
+		const id = surfaceMetricKey(surfaceId, role);
+		let metric = this.#metrics.get(id);
+		if (!metric) {
+			metric = {
+				id,
+				surfaceId,
+				role,
+				dispatches: 0,
+				candidates: 0,
+				truncated: false,
+				dataUnstable: false,
+				dataChurn: 0,
+				errors: 0,
+				mounts: 0,
+				unmounts: 0
+			};
+			this.#metrics.set(id, metric);
+		}
+		return metric;
+	}
+	/**
+	* Records a dispatch. `previousData` is the consumer's prior `data` reference;
+	* the store derives churn/instability from the identity-vs-value comparison.
+	*/
+	recordDispatch(surfaceId, role, args) {
+		const metric = this.#entry(surfaceId, role);
+		metric.dispatches += 1;
+		metric.candidates = args.candidates;
+		metric.truncated = args.truncated;
+		metric.dataChurn = args.dataChurn;
+		metric.dataUnstable = args.dataChurn >= UNSTABLE_THRESHOLD;
+		this.#schedule();
+	}
+	recordError(surfaceId, role) {
+		this.#entry(surfaceId, role).errors += 1;
+		this.#schedule();
+	}
+	recordMount(surfaceId, role) {
+		this.#entry(surfaceId, role).mounts += 1;
+		this.#schedule();
+	}
+	recordUnmount(surfaceId, role) {
+		this.#entry(surfaceId, role).unmounts += 1;
+		this.#schedule();
+	}
+	clear() {
+		this.#metrics.clear();
+		this.#snapshot = [];
+		this.#notify();
+	}
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	};
+	getSnapshot = () => this.#snapshot;
+	/** Defers notification to the next frame to coalesce bursts of records. */
+	#schedule() {
+		if (this.#pendingNotify || typeof requestAnimationFrame === "undefined") {
+			if (typeof requestAnimationFrame === "undefined") this.#notify();
+			return;
+		}
+		this.#pendingNotify = true;
+		requestAnimationFrame(() => {
+			this.#pendingNotify = false;
+			this.#notify();
+		});
+	}
+	#notify() {
+		this.#snapshot = [...this.#metrics.values()];
+		for (const listener of this.#listeners) listener();
+	}
+};
+var surfaceMetrics = new SurfaceMetricsStore();
+/**
+* Updates the running churn count for a consumer's `data` prop.
+*
+* @returns the new churn count (0 when `data` changed value or is unchanged).
+*/
+var nextDataChurn = (previous, next, churn) => {
+	if (Object.is(previous, next)) return churn;
+	return shallowEqual(previous, next) ? churn + 1 : 0;
+};
+/**
+* Subscribes to surface dev metrics, sorted with the most concerning first
+* (unstable data, then errors, then dispatch count).
+*/
+var useSurfaceMetrics = () => {
+	return [...useSyncExternalStore(surfaceMetrics.subscribe, surfaceMetrics.getSnapshot, surfaceMetrics.getSnapshot)].sort((a, b) => Number(b.dataUnstable) - Number(a.dataUnstable) || b.errors - a.errors || b.dispatches - a.dispatches);
+};
+//#endregion
+//#region src/ui/components/Surface/SurfaceDebug.tsx
+var DEBUG_FLAG = "__DX_DEBUG__";
+/**
+* Custom element tag wrapping each React surface in debug builds.
+*/
+var DX_SURFACE_TAG = "dx-surface";
+/**
+* Installs the `window.__DX__` DevTools helper. `__DX__.surfaces(component?)` returns the mounted
+* `<dx-surface>` elements (optionally filtered by `data-component`) — a console shortcut for the
+* otherwise-verbose `document.querySelectorAll('dx-surface[data-component="…"]')`.
+*/
+var ensureDebugApi = () => {
+	if (typeof window === "undefined") return;
+	window.__DX__ = {
+		...window.__DX__,
+		surfaces: (component) => Array.from(document.querySelectorAll(component ? `${DX_SURFACE_TAG}[data-component="${component}"]` : DX_SURFACE_TAG))
+	};
+};
+/**
+* Whether surface debugging is enabled, via the `VITE_DEBUG` build flag or the
+* `__DX_DEBUG__` runtime global. The runtime flag is toggleable without a
+* rebuild and takes effect on the next render.
+*/
+var isSurfaceDebugEnabled = () => Boolean(void 0) || typeof window !== "undefined" && DEBUG_FLAG in window;
+/**
+* Whether the `<dx-surface>` wrapper is rendered. Enabled in any development build (or when
+* `VITE_DEBUG` is set) so the wrapper's `data-*` attributes and `window.__DX__` helpers are available
+* for DOM inspection independent of the runtime highlight flag. Production renders no wrapper.
+*/
+var isSurfaceWrapperEnabled = () => Boolean(false) || Boolean(void 0);
+var flagListeners = /* @__PURE__ */ new Set();
+var subscribeFlag = (listener) => {
+	flagListeners.add(listener);
+	return () => {
+		flagListeners.delete(listener);
+	};
+};
+/**
+* Toggles the `__DX_DEBUG__` runtime flag, which gates the visual highlight overlay (not the
+* `<dx-surface>` wrapper). The overlay redraws immediately; surfaces pick it up on their next render.
+*/
+var setSurfaceDebug = (enabled) => {
+	if (typeof window === "undefined") return;
+	if (enabled) window[DEBUG_FLAG] = true;
+	else delete window[DEBUG_FLAG];
+	for (const listener of flagListeners) listener();
+};
+var elementRegistered = false;
+var ensureSurfaceElement = () => {
+	if (elementRegistered || typeof customElements === "undefined") return;
+	elementRegistered = true;
+	if (!customElements.get("dx-surface")) {
+		class DxSurfaceElement extends HTMLElement {
+			connectedCallback() {
+				this.style.display = "contents";
+			}
+		}
+		customElements.define(DX_SURFACE_TAG, DxSurfaceElement);
+	}
+};
+/**
+* Singleton registry of mounted debug surfaces. Centralizes overlay rendering so
+* a single set of observers/listeners serves every surface, instead of each
+* surface mounting its own portal and observers.
+*/
+var SurfaceDebugManager = class {
+	#entries = /* @__PURE__ */ new Set();
+	#snapshot = [];
+	#listeners = /* @__PURE__ */ new Set();
+	#nextKey = 0;
+	register(element, infoRef) {
+		const entry = {
+			key: this.#nextKey++,
+			element,
+			infoRef
+		};
+		this.#entries.add(entry);
+		this.#update();
+		return () => {
+			this.#entries.delete(entry);
+			this.#update();
+		};
+	}
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	};
+	getSnapshot = () => this.#snapshot;
+	#update() {
+		this.#snapshot = [...this.#entries];
+		for (const listener of this.#listeners) listener();
+	}
+};
+var manager = new SurfaceDebugManager();
+var overlayMounted = false;
+var ensureOverlay = () => {
+	if (overlayMounted || typeof document === "undefined") return;
+	overlayMounted = true;
+	const root = document.createElement("div");
+	root.id = "dx-surface-overlay";
+	document.body.appendChild(root);
+	createRoot(root).render(/* @__PURE__ */ jsx(SurfaceDebugOverlay, {}));
+};
+/**
+* Measures a `display: contents` element (which has no box of its own) by unioning the border boxes
+* of its rendered children. Deliberately uses each child's own `getBoundingClientRect` rather than a
+* Range over all contents: a Range unions every descendant rect, so content overflowing an inner
+* `overflow: auto` scroll container inflates the width past the surface's visible bounds. A direct
+* child's box is clipped to its own border box, so the highlight stays tight to what is on screen.
+*/
+var measureContents = (element) => {
+	if (typeof document === "undefined" || typeof getComputedStyle !== "function") return null;
+	const boxes = [];
+	const collect = (node) => {
+		for (const child of node.children) if (getComputedStyle(child).display === "contents") collect(child);
+		else {
+			const rect = child.getBoundingClientRect();
+			if (rect.width > 0 || rect.height > 0) boxes.push(rect);
+		}
+	};
+	collect(element);
+	if (boxes.length === 0) return null;
+	let left = Infinity;
+	let top = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	for (const box of boxes) {
+		left = Math.min(left, box.left);
+		top = Math.min(top, box.top);
+		right = Math.max(right, box.right);
+		bottom = Math.max(bottom, box.bottom);
+	}
+	return new DOMRect(left, top, right - left, bottom - top);
+};
+var EMPTY_RECTS = /* @__PURE__ */ new Map();
+/**
+* Single overlay that draws boundary highlights for every registered surface.
+* One ResizeObserver plus one scroll/resize listener serve all surfaces.
+*/
+var SurfaceDebugOverlay = () => {
+	const entries = useSyncExternalStore(manager.subscribe, manager.getSnapshot, manager.getSnapshot);
+	const enabled = useSyncExternalStore(subscribeFlag, isSurfaceDebugEnabled, isSurfaceDebugEnabled);
+	const [rects, setRects] = useState(EMPTY_RECTS);
+	useLayoutEffect(() => {
+		if (!enabled || entries.length === 0) {
+			setRects(EMPTY_RECTS);
+			return;
+		}
+		const measure = () => {
+			const next = /* @__PURE__ */ new Map();
+			for (const entry of entries) {
+				const rect = measureContents(entry.element);
+				if (rect) next.set(entry.key, rect);
+			}
+			setRects(next);
+		};
+		const observer = typeof ResizeObserver !== "undefined" ? new ResizeObserver(measure) : void 0;
+		for (const entry of entries) if (observer && entry.element.parentElement) observer.observe(entry.element.parentElement);
+		measure();
+		return combine(addEventListener(window, "scroll", measure, true), addEventListener(window, "resize", measure), () => observer?.disconnect());
+	}, [entries, enabled]);
+	if (!enabled) return null;
+	return createPortal(/* @__PURE__ */ jsx(Fragment$1, { children: entries.map((entry) => {
+		const rect = rects.get(entry.key);
+		return rect ? /* @__PURE__ */ jsx(SurfaceHighlight, {
+			infoRef: entry.infoRef,
+			rect
+		}, entry.key) : null;
+	}) }), document.body);
+};
+/** Subscribes to the metric for a single surface. */
+var useSurfaceMetric = (surfaceId, role) => {
+	const all = useSyncExternalStore(surfaceMetrics.subscribe, surfaceMetrics.getSnapshot, surfaceMetrics.getSnapshot);
+	const key = surfaceMetricKey(surfaceId, role);
+	return all.find((metric) => metric.id === key);
+};
+var SurfaceHighlight = ({ infoRef, rect }) => {
+	const [expand, setExpand] = useState(false);
+	const info = infoRef.current;
+	const metric = useSurfaceMetric(info.id ?? "", info.role);
+	const concern = !!metric && (metric.dataUnstable || metric.errors > 0);
+	return /* @__PURE__ */ jsx("div", {
+		className: "z-[100] fixed flex flex-col-reverse scrollbar-none overflow-auto pointer-events-none",
+		style: {
+			top: rect.top,
+			left: rect.left,
+			width: rect.width,
+			height: rect.height
+		},
+		children: expand ? /* @__PURE__ */ jsx("div", {
+			className: "absolute inset-0 border-2 border-rose-500 border-dotted overflow-auto pointer-events-auto",
+			onPointerDown: (ev) => ev.stopPropagation(),
+			onClick: (ev) => {
+				ev.stopPropagation();
+				setExpand(false);
+			},
+			children: /* @__PURE__ */ jsx("div", {
+				className: "absolute left-1 right-1 bottom-1 max-h-[20rem] overflow-auto dx-card-surface ring-2 ring-separator rounded-sm opacity-90",
+				children: /* @__PURE__ */ jsx("pre", {
+					className: "inline-block p-2 text-xs text-description font-mono font-thin",
+					children: JSON.stringify({
+						info,
+						metric
+					}, null, 2)
+				})
+			})
+		}) : /* @__PURE__ */ jsx("span", {
+			className: mx(concern ? "text-rose-500" : "text-green-500", "absolute right-2 bottom-1 flex items-center p-1 opacity-80 hover:opacity-100 text-sm cursor-pointer pointer-events-auto"),
+			title: metricSummary(info.id ?? "", metric),
+			onPointerDown: (ev) => ev.stopPropagation(),
+			onClick: (ev) => {
+				ev.stopPropagation();
+				setExpand(true);
+			},
+			children: concern ? "⚠" : "ⓘ"
+		})
+	});
+};
+var metricSummary = (surfaceId, metric) => {
+	if (!metric) return surfaceId;
+	const parts = [
+		surfaceId,
+		`dispatches=${metric.dispatches}`,
+		`candidates=${metric.candidates}${metric.truncated ? "(+truncated)" : ""}`,
+		`mounts=${metric.mounts}/unmounts=${metric.unmounts}`
+	];
+	if (metric.dataUnstable) parts.push(`UNSTABLE data (churn=${metric.dataChurn})`);
+	if (metric.errors > 0) parts.push(`errors=${metric.errors}`);
+	return parts.join(" · ");
+};
+/**
+* Recovers the rendered surface component's name from the React fiber. Surfaces are registered as
+* anonymous `component: (props) => <Real .../>` wrappers, so the static component carries no useful
+* name; walking the fiber's child chain to the first component with a display name (as DevTools does)
+* finds the real one. The wrapper's own inferred name is the property key ('component'), so skip it.
+*/
+var renderedComponentName = (element) => {
+	const node = element;
+	const fiberKey = Object.keys(node).find((key) => key.startsWith("__reactFiber$"));
+	let fiber = fiberKey ? node[fiberKey]?.child : void 0;
+	while (fiber) {
+		const { type } = fiber;
+		if (typeof type === "function") {
+			const name = type.displayName ?? type.name;
+			if (name && name !== "component") return name;
+		}
+		fiber = fiber.child;
+	}
+};
+/**
+* Debug wrapper that mounts each React surface inside a `<dx-surface>` element
+* and registers it with the centralized overlay. The element is named and
+* inspectable in DevTools and queryable (`document.querySelectorAll('dx-surface')`).
+*/
+var DebugSurface = ({ info, children }) => {
+	const infoRef = useRef(info);
+	infoRef.current = info;
+	const elementRef = useRef(null);
+	useEffect(() => {
+		ensureSurfaceElement();
+		ensureOverlay();
+		ensureDebugApi();
+		const { id, role } = infoRef.current;
+		if (id) surfaceMetrics.recordMount(id, role);
+		const element = elementRef.current;
+		const unregister = element ? manager.register(element, infoRef) : void 0;
+		const component = element ? renderedComponentName(element) : void 0;
+		if (element && component) element.setAttribute("data-component", component);
+		return () => {
+			if (id) surfaceMetrics.recordUnmount(id, role);
+			unregister?.();
+		};
+	}, []);
+	return createElement(DX_SURFACE_TAG, {
+		"className": "contents",
+		"data-id": info.id,
+		"data-role": info.role,
+		"ref": elementRef
+	}, children);
+};
+//#endregion
+//#region src/ui/components/Surface/SurfaceManagerContext.ts
+var SurfaceManagerContext = createContext(void 0);
+/**
+* Get the surface manager. Throws when rendered outside a {@link SurfaceManagerProvider};
+* surfaces already hard-require the plugin-manager context, so there is no optional variant.
+*/
+var useSurfaceManager = () => useContext(SurfaceManagerContext) ?? raise(/* @__PURE__ */ new Error("Missing SurfaceManagerContext"));
+/**
+* Context provider for a surface manager.
+*/
+var SurfaceManagerProvider = SurfaceManagerContext.Provider;
+//#endregion
+//#region src/ui/components/Surface/SurfaceProfilerContext.tsx
+var MAX_ENTRIES = 500;
+/**
+* Store that collects profiler entries and notifies subscribers.
+*/
+var SurfaceProfilerStore = class {
+	_entries = [];
+	_listeners = /* @__PURE__ */ new Set();
+	_snapshot = [];
+	_pendingNotify = false;
+	/**
+	* Records an entry and schedules a deferred notification to avoid re-render loops.
+	* `_snapshot` is rebuilt only when the deferred notification actually fires
+	* ({@link _notifySync}) — not here — so `getSnapshot` stays referentially stable for any
+	* synchronous re-invocation React makes within the same commit (e.g. the tearing check a
+	* profiled subscriber's own `useSyncExternalStore` runs right after this Profiler's
+	* `onRender` callback). Rebuilding it synchronously here would change what `getSnapshot`
+	* returns before listeners are told, which React reads as a torn store and forces an
+	* immediate re-render — and if the re-rendering component is itself profiled, that
+	* re-render re-triggers `record`, looping forever.
+	*/
+	record(entry) {
+		this._entries.push(entry);
+		if (this._entries.length > MAX_ENTRIES) this._entries = this._entries.slice(-500);
+		this._scheduleNotify();
+	}
+	clear() {
+		this._entries = [];
+		this._snapshot = [];
+		this._notifySync();
+	}
+	subscribe = (listener) => {
+		this._listeners.add(listener);
+		return () => {
+			this._listeners.delete(listener);
+		};
+	};
+	getSnapshot = () => {
+		return this._snapshot;
+	};
+	/**
+	* Defers notification to the next animation frame to break the
+	* Profiler onRender → record → notify → re-render → onRender loop.
+	*/
+	_scheduleNotify() {
+		if (!this._pendingNotify) {
+			this._pendingNotify = true;
+			requestAnimationFrame(() => {
+				this._pendingNotify = false;
+				this._notifySync();
+			});
+		}
+	}
+	_notifySync() {
+		this._snapshot = [...this._entries];
+		for (const listener of this._listeners) listener();
+	}
+};
+var SurfaceProfilerContext = createContext(void 0);
+/**
+* Provider that collects React Profiler data from Surface components.
+*/
+var SurfaceProfilerProvider = ({ children }) => {
+	const storeRef = useRef(null);
+	if (!storeRef.current) storeRef.current = new SurfaceProfilerStore();
+	return /* @__PURE__ */ jsx(SurfaceProfilerContext.Provider, {
+		value: { store: storeRef.current },
+		children
+	});
+};
+/**
+* Returns a stable onRender callback for use with React Profiler.
+*/
+var useSurfaceProfilerCallback = () => {
+	const store = useContext(SurfaceProfilerContext)?.store;
+	return useMemo(() => {
+		if (!store) return;
+		return (id, phase, actualDuration, baseDuration, startTime, commitTime) => {
+			store.record({
+				id,
+				phase,
+				actualDuration,
+				baseDuration,
+				startTime,
+				commitTime,
+				timestamp: Date.now()
+			});
+		};
+	}, [store]);
+};
+/**
+* Returns all profiler entries reactively.
+*/
+var useSurfaceProfilerEntries = () => {
+	const context = useContext(SurfaceProfilerContext);
+	return useSyncExternalStore(context?.store.subscribe ?? noop, context?.store.getSnapshot ?? emptySnapshot);
+};
+/**
+* Returns aggregated stats grouped by surface id.
+*/
+var useSurfaceProfilerStats = () => {
+	const entries = useSurfaceProfilerEntries();
+	const statsMap = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		let stats = statsMap.get(entry.id);
+		if (!stats) {
+			stats = {
+				id: entry.id,
+				mountCount: 0,
+				updateCount: 0,
+				totalRenders: 0,
+				avgActualDuration: 0,
+				maxActualDuration: 0,
+				avgBaseDuration: 0,
+				lastActualDuration: 0,
+				lastCommitTime: 0
+			};
+			statsMap.set(entry.id, stats);
+		}
+		if (entry.phase === "mount") stats.mountCount++;
+		else stats.updateCount++;
+		stats.totalRenders++;
+		stats.avgActualDuration = (stats.avgActualDuration * (stats.totalRenders - 1) + entry.actualDuration) / stats.totalRenders;
+		stats.avgBaseDuration = (stats.avgBaseDuration * (stats.totalRenders - 1) + entry.baseDuration) / stats.totalRenders;
+		stats.maxActualDuration = Math.max(stats.maxActualDuration, entry.actualDuration);
+		stats.lastActualDuration = entry.actualDuration;
+		stats.lastCommitTime = entry.commitTime;
+	}
+	return [...statsMap.values()].sort((a, b) => b.maxActualDuration - a.maxActualDuration);
+};
+/**
+* Clears all collected profiler entries.
+*/
+var useSurfaceProfilerClear = () => {
+	const store = useContext(SurfaceProfilerContext)?.store;
+	return useMemo(() => store ? () => store.clear() : void 0, [store]);
+};
+var noop = () => () => {};
+var EMPTY_SNAPSHOT = [];
+var emptySnapshot = () => EMPTY_SNAPSHOT;
+//#endregion
+//#region src/ui/components/Surface/SurfaceComponent.tsx
+var DEFAULT_PLACEHOLDER = /* @__PURE__ */ jsx(Fragment, {});
+var WebComponentWrapper = memo(({ id, role, data, limit, definition, ...rest }) => {
+	const containerRef = useRef(null);
+	const elementRef = useRef(null);
+	const propsRef = useRef({
+		id,
+		role,
+		data,
+		limit,
+		...rest
+	});
+	propsRef.current = {
+		id,
+		role,
+		data,
+		limit,
+		...rest
+	};
+	useEffect(() => {
+		if (!containerRef.current || elementRef.current) return;
+		const element = document.createElement(definition.tagName);
+		elementRef.current = element;
+		Object.assign(element, propsRef.current);
+		containerRef.current.appendChild(element);
+		return () => {
+			if (elementRef.current && containerRef.current?.contains(elementRef.current)) containerRef.current.removeChild(elementRef.current);
+			elementRef.current = null;
+		};
+	}, [definition.tagName]);
+	const previousPropsRef = useRef({});
+	useEffect(() => {
+		const element = elementRef.current;
+		if (element) {
+			for (const key of Object.keys(previousPropsRef.current)) if (!(key in propsRef.current)) Reflect.deleteProperty(element, key);
+			Object.assign(element, propsRef.current);
+			previousPropsRef.current = propsRef.current;
+		}
+	});
+	return /* @__PURE__ */ jsx("div", { ref: containerRef });
+});
+WebComponentWrapper.displayName = "WebComponentWrapper";
+/**
+* Wrapper component that provides context for a surface.
+*/
+var SurfaceContextProvider = memo(({ id, role, data, limit, fallback = ErrorFallback$1, definition, ...rest }) => {
+	const contextValue = useMemo(() => ({
+		id,
+		role,
+		data
+	}), [
+		id,
+		role,
+		data
+	]);
+	const onProfilerRender = useSurfaceProfilerCallback();
+	const profilerId = `surface/${id}/${role}`;
+	const onError = isSurfaceDebugEnabled() ? () => surfaceMetrics.recordError(id, role) : void 0;
+	if (definition.kind === "web-component") return /* @__PURE__ */ jsx(ErrorBoundary, {
+		name: "surface",
+		resetKeys: [data],
+		FallbackComponent: fallback,
+		onError,
+		children: /* @__PURE__ */ jsx(SurfaceContext.Provider, {
+			value: contextValue,
+			children: /* @__PURE__ */ jsx(WebComponentWrapper, {
+				id,
+				role,
+				data,
+				limit,
+				definition,
+				...rest
+			})
+		})
+	});
+	const Component = definition.component;
+	const surfaceProps = {
+		id,
+		role,
+		data,
+		limit,
+		...rest
+	};
+	const component = /* @__PURE__ */ jsx(Component, { ...definition.props?.(surfaceProps) ?? surfaceProps });
+	const profiled = onProfilerRender && !profilerId.includes("org.dxos.plugin.debug") ? /* @__PURE__ */ jsx(Profiler, {
+		id: profilerId,
+		onRender: onProfilerRender,
+		children: component
+	}) : component;
+	if (isSurfaceWrapperEnabled()) return /* @__PURE__ */ jsx(ErrorBoundary, {
+		name: "surface",
+		resetKeys: [data],
+		FallbackComponent: fallback,
+		onError,
+		children: /* @__PURE__ */ jsx(SurfaceContext.Provider, {
+			value: contextValue,
+			children: /* @__PURE__ */ jsx(DebugSurface, {
+				info: contextValue,
+				children: profiled
+			})
+		})
+	});
+	return /* @__PURE__ */ jsx(ErrorBoundary, {
+		name: "surface",
+		resetKeys: [data],
+		FallbackComponent: fallback,
+		onError,
+		children: /* @__PURE__ */ jsx(SurfaceContext.Provider, {
+			value: contextValue,
+			children: profiled
+		})
+	});
+});
+SurfaceContextProvider.displayName = "SurfaceContextProvider";
+/**
+* A surface is a named region of the screen that can be populated by plugins.
+* The `type` prop is a {@link Role.Role} that defines which region and its
+* associated data contract.
+*
+* A surface is a boundary that may resolve to zero, one, or many components, so
+* it intentionally accepts no `ref`; consumers needing an element should own one
+* inside their contributed component.
+*/
+var SurfaceComponent = memo(({ id: _id, type, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }) => {
+	const data = useDefaultValue(dataProp, () => ({}));
+	const surfaceManager = useSurfaceManager();
+	const effectiveRole = type?.role ?? "";
+	const definitions = matchCandidates(useAtomValue(surfaceManager.candidatesAtom(effectiveRole)), effectiveRole, data);
+	const candidates = limit != null ? definitions.slice(0, limit) : definitions;
+	const truncated = limit != null && definitions.length > limit;
+	const churnRef = useRef({
+		data: void 0,
+		churn: 0
+	});
+	useEffect(() => {
+		if (!isSurfaceDebugEnabled() || effectiveRole === "") return;
+		const previous = churnRef.current;
+		const churn = previous.data === void 0 ? 0 : nextDataChurn(previous.data, data, previous.churn);
+		churnRef.current = {
+			data,
+			churn
+		};
+		for (const definition of candidates) surfaceMetrics.recordDispatch(definition.id, effectiveRole, {
+			candidates: candidates.length,
+			truncated,
+			dataChurn: churn
+		});
+	});
+	if (type?.role == null) return null;
+	return /* @__PURE__ */ jsx(Suspense, {
+		fallback: placeholder,
+		children: candidates.map((definition) => /* @__PURE__ */ jsx(SurfaceContextProvider, {
+			id: definition.id,
+			role: effectiveRole,
+			data,
+			limit,
+			definition,
+			...rest
+		}, definition.id))
+	});
+});
+SurfaceComponent.displayName = "Surface";
+var ErrorFallback$1 = ({ error }) => {
+	const { message } = error instanceof Error ? error : { message: String(error) };
+	return /* @__PURE__ */ jsx("div", {
+		role: "alert",
+		"data-testid": "error-boundary-fallback",
+		children: /* @__PURE__ */ jsx("h1", {
+			className: "flex p-2 text-sm text-info-text",
+			children: message
+		})
+	});
+};
+/**
+* Filters the pre-indexed candidates for a role through their data guards.
+*/
+var matchCandidates = (definitions, role, data) => {
+	if (!definitions) return [];
+	return definitions.filter(({ filter }) => filter ? filter(data ?? {}, role) : true);
+};
+/**
+* @returns a stable function that checks whether a contributed surface is available for a
+* role & data. The surface manager is captured via context, so the returned function carries
+* no dependency of its own and is safe to store and invoke later — e.g. from inside another
+* callback such as a render-prop or event handler — since it calls no hooks itself.
+*/
+var useIsSurfaceAvailable = () => {
+	const surfaceManager = useSurfaceManager();
+	const registry = useContext(RegistryContext);
+	return useCallback((args) => {
+		const effectiveRole = args.type?.role;
+		if (effectiveRole == null) return false;
+		return matchCandidates(registry.get(surfaceManager.candidatesAtom(effectiveRole)), effectiveRole, args.data).length > 0;
+	}, [surfaceManager, registry]);
+};
+//#endregion
+//#region src/ui/components/Surface/types.ts
+var __dxlog_file$1 = "/__w/dxos/dxos/packages/sdk/app-framework/src/ui/components/Surface/types.ts";
+/**
+* Runtime guard for {@link Filter}. Distinguishes new-style filter bindings from
+* legacy predicate filters.
+*/
+var isFilter = (value) => typeof value === "object" && value !== null && Array.isArray(value.bindings);
+/**
+* Creates a {@link Filter} from a role token and an optional guard.
+*
+* When `guard` is omitted the filter matches any data at the token's role
+* (role-only dispatch). Pass a guard to add runtime data-shape validation on
+* top of the role match.
+*
+* This is the framework-level primitive; `@dxos/app-toolkit` builds richer
+* domain-aware helpers (ECHO schema checks, literal matching, etc.) on top of it.
+*/
+var makeFilter = (token, guard) => {
+	const boundGuard = guard == null ? () => true : (data) => {
+		try {
+			return guard(data);
+		} catch (err) {
+			log.catch(err, void 0, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file$1,
+				L: 57,
+				S: void 0
+			});
+			return false;
+		}
+	};
+	return { bindings: [{
+		role: token.role,
+		guard: boundGuard
+	}] };
+};
+var expandBindings = (filter) => {
+	const bindings = filter.bindings;
+	const roles = Array.from(new Set(bindings.map((binding) => binding.role)));
+	const guard = (data, role) => {
+		if (role != null) return bindings.some((entry) => entry.role === role && entry.guard(data));
+		return bindings.some((entry) => entry.guard(data));
+	};
+	return {
+		role: roles.length === 1 ? roles[0] : roles,
+		guard
+	};
+};
+/**
+* Whether a surface or extension local ID follows NSID conventions: the final
+* dot-separated segment must be camelCase (letters and digits only, starting
+* with a letter — no hyphens or underscores). This mirrors the rule enforced
+* when the id is appended to a plugin's NSID to form a full DXN path.
+*
+* A definition with an invalid id is dropped at dispatch rather than rejected
+* here, so a single malformed contribution cannot crash plugin activation.
+*
+* @example Valid:   'about', 'integrationArticle', 'article.journal'
+* @example Invalid: 'integration-article', 'plugin-spec'
+*/
+var isValidLocalId = (id) => /^[a-zA-Z][a-zA-Z0-9]*$/.test(id.split(".").pop() ?? "");
+function create(definition) {
+	const { id, filter, component, props, position } = definition;
+	const { role, guard } = expandBindings(filter);
+	return {
+		kind: "react",
+		id,
+		role,
+		position,
+		component,
+		props,
+		filter: guard
+	};
+}
+function createWeb(definition) {
+	const { id, filter, tagName, position } = definition;
+	const { role, guard } = expandBindings(filter);
+	return {
+		kind: "web-component",
+		id,
+		role,
+		position,
+		tagName,
+		filter: guard
+	};
+}
+//#endregion
+//#region src/ui/components/Surface/SurfaceManager.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-framework/src/ui/components/Surface/SurfaceManager.ts";
+var EMPTY_CANDIDATES = Data.array([]);
+/**
+* Groups definitions by role with each bucket pre-sorted by {@link Position}, so
+* dispatch avoids a full scan and re-sort on every render. Pure helper — callers
+* are responsible for filtering out invalid definitions before calling this.
+*/
+var indexByRole = (definitions) => {
+	const index = /* @__PURE__ */ new Map();
+	for (const definition of definitions) {
+		const roles = Array.isArray(definition.role) ? definition.role : [definition.role];
+		for (const role of roles) {
+			let bucket = index.get(role);
+			if (!bucket) {
+				bucket = [];
+				index.set(role, bucket);
+			}
+			bucket.push(definition);
+		}
+	}
+	for (const bucket of index.values()) bucket.sort(Position.compare);
+	return index;
+};
+/**
+* Owns the per-manager surface memoization: one derived index atom plus a per-role
+* family of candidate atoms. A single instance is provided via
+* {@link SurfaceManagerProvider}, so instance identity does the per-manager keying
+* (replacing module-level WeakMaps) and `Atom.family` does the per-role keying.
+* Atom lifecycle is tied to the provider rather than module-global state.
+*/
+var SurfaceManager = class {
+	#capabilities;
+	#index = Atom.make((get) => {
+		const definitions = get(this.#capabilities.atom(ReactSurface)).flat();
+		return indexByRole(this.#dropInvalid(definitions));
+	}).pipe(Atom.keepAlive);
+	#candidates = Atom.family((role) => Atom.make((get) => {
+		const bucket = get(this.#index).get(role);
+		return bucket ? Data.array(bucket) : EMPTY_CANDIDATES;
+	}).pipe(Atom.keepAlive));
+	#warnedInvalidIds = /* @__PURE__ */ new Set();
+	constructor(capabilities) {
+		this.#capabilities = capabilities;
+	}
+	/** Derived atom yielding the (position-sorted) candidates for a single role. */
+	candidatesAtom(role) {
+		return this.#candidates(role);
+	}
+	/** Drops definitions with an invalid local id, warning once per id. */
+	#dropInvalid(definitions) {
+		return definitions.filter((definition) => {
+			if (isValidLocalId(definition.id)) return true;
+			if (!this.#warnedInvalidIds.has(definition.id)) {
+				this.#warnedInvalidIds.add(definition.id);
+				log.warn("dropping surface with invalid id; the final segment must be camelCase (no hyphens or underscores)", { id: definition.id }, {
+					"~LogMeta": "~LogMeta",
+					F: __dxlog_file,
+					L: 88,
+					S: this
+				});
+			}
+			return false;
+		});
+	}
+};
+//#endregion
+export { topologicalSort as C, usePluginManager as S, surfaceMetrics as _, makeFilter as a, PluginManagerProvider as b, SurfaceProfilerProvider as c, useSurfaceProfilerEntries as d, useSurfaceProfilerStats as f, setSurfaceDebug as g, isSurfaceDebugEnabled as h, isFilter as i, useSurfaceProfilerCallback as l, useSurfaceManager as m, create as n, SurfaceComponent as o, SurfaceManagerProvider as p, createWeb as r, useIsSurfaceAvailable as s, SurfaceManager as t, useSurfaceProfilerClear as u, useSurfaceMetrics as v, useOptionalPluginManager as x, SurfaceContext as y };
+
+//# sourceMappingURL=chunk-SurfaceManager.mjs.map