@dxos/app-graph 0.10.0 → 0.11.1

package/dist/lib/chunk-graph-builder.mjs

@@ -0,0 +1,1901 @@
+import { Atom, Registry } from "@effect-atom/atom";
+import * as Function from "effect/Function";
+import * as Option from "effect/Option";
+import * as Pipeable from "effect/Pipeable";
+import { Event, Trigger } from "@dxos/async";
+import { todo } from "@dxos/debug";
+import { invariant } from "@dxos/invariant";
+import { log } from "@dxos/log";
+import { Position, getDebugName, isNonNullable } from "@dxos/util";
+import * as Array$1 from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Record from "effect/Record";
+import { scheduleTask, yieldOrContinue } from "#scheduler";
+import { Entity, Obj } from "@dxos/echo";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/node.ts
+var node_exports = /* @__PURE__ */ __exportAll({
+	ActionGroupType: () => ActionGroupType,
+	ActionType: () => ActionType,
+	RootId: () => RootId,
+	RootType: () => RootType,
+	actionGroupSymbol: () => actionGroupSymbol,
+	actionRelation: () => actionRelation,
+	childRelation: () => childRelation,
+	hasDisposition: () => hasDisposition,
+	isAction: () => isAction,
+	isActionGroup: () => isActionGroup,
+	isActionLike: () => isActionLike,
+	isGraphNode: () => isGraphNode,
+	make: () => make$2,
+	makeAction: () => makeAction,
+	makeActionGroup: () => makeActionGroup,
+	relation: () => relation
+});
+/**
+* Root node ID.
+*/
+var RootId = "root";
+/**
+* Root node type.
+*/
+var RootType = "org.dxos.type.graphRoot";
+/**
+* Action node type.
+*/
+var ActionType = "org.dxos.type.graphAction";
+/**
+* Action group node type.
+*/
+var ActionGroupType = "org.dxos.type.graphActionGroup";
+var relation = (kind, direction = "outbound") => ({
+	kind,
+	direction
+});
+var childRelation = (direction = "outbound") => relation("child", direction);
+var actionRelation = (direction = "outbound") => relation("action", direction);
+var isGraphNode = (data) => data && typeof data === "object" && "id" in data && "properties" in data && data.properties ? typeof data.properties === "object" && "data" in data : false;
+var isAction = (data) => isGraphNode(data) ? typeof data.data === "function" && data.type === "org.dxos.type.graphAction" : false;
+var actionGroupSymbol = Symbol("ActionGroup");
+var isActionGroup = (data) => isGraphNode(data) ? data.data === actionGroupSymbol && data.type === "org.dxos.type.graphActionGroup" : false;
+var isActionLike = (data) => isAction(data) || isActionGroup(data);
+/**
+* Tests whether a node's `disposition` property (a single string or an array, letting one node opt
+* into multiple surfaces at once) includes any of `key`. Every surface that routes nodes/actions by
+* disposition (toolbar, nav-tree list-item, sigil menu, …) should filter through this rather than
+* comparing `properties.disposition` directly, so a node can multi-target surfaces.
+*/
+var hasDisposition = (node, key) => {
+	const disposition = node.properties.disposition;
+	const dispositions = Array.isArray(disposition) ? disposition : disposition !== void 0 ? [disposition] : [];
+	const keys = Array.isArray(key) ? key : [key];
+	return dispositions.some((candidate) => keys.includes(candidate));
+};
+/** Typed factory for constructing a NodeArg. Provides auto-complete and type validation. */
+var make$2 = (arg) => arg;
+/** Create an action node. Automatically sets `type: ActionType`. */
+var makeAction = (arg) => ({
+	...arg,
+	type: ActionType
+});
+/** Create an action group node. Automatically sets `type` and `data`. */
+var makeActionGroup = (arg) => ({
+	...arg,
+	type: ActionGroupType,
+	data: actionGroupSymbol
+});
+//#endregion
+//#region src/util.ts
+var __dxlog_file$2 = "/__w/dxos/dxos/packages/sdk/app-graph/src/util.ts";
+var PRIMARY = "
";
+var SECONDARY = "";
+var PATH = "/";
+/** Join parts with the primary separator. */
+var primaryKey = (...parts) => parts.join(PRIMARY);
+/** Split a key on the primary separator. */
+var primaryParts = (key) => key.split(PRIMARY);
+/** Join parts with the secondary separator. */
+var secondaryKey = (...parts) => parts.join(SECONDARY);
+/** Split a key on the secondary separator. */
+var secondaryParts = (key) => key.split(SECONDARY);
+/**
+* Normalize a relation input to a full Relation object.
+*/
+var normalizeRelation = (relation$2) => relation$2 == null ? childRelation() : typeof relation$2 === "string" ? relation(relation$2) : relation$2;
+/**
+* Shallow-compare two values: same reference, or same own-keys with === values.
+*/
+var shallowEqual = (a, b) => {
+	if (a === b) return true;
+	if (a == null || b == null || typeof a !== "object" || typeof b !== "object") return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	return keysA.every((k) => a[k] === b[k]);
+};
+/**
+* Returns true if two NodeArg arrays are semantically identical (same id, type, data, properties per index).
+* Inline child nodes (the `nodes` field) are compared recursively.
+*/
+var nodeArgsUnchanged = (prev, next) => {
+	if (prev.length !== next.length) return false;
+	return prev.every((prevNode, idx) => {
+		const nextNode = next[idx];
+		return prevNode.id === nextNode.id && prevNode.type === nextNode.type && shallowEqual(prevNode.data, nextNode.data) && shallowEqual(prevNode.properties, nextNode.properties) && nodeArgsUnchanged(prevNode.nodes ?? [], nextNode.nodes ?? []) && nodeArgsUnchanged(prevNode.actions ?? [], nextNode.actions ?? []);
+	});
+};
+/**
+* Build a qualified node ID by joining path segments.
+*/
+var qualifyId = (parentId, ...segmentIds) => [parentId, ...segmentIds].join(PATH);
+/**
+* Validate that a segment ID does not contain the path separator.
+*/
+var validateSegmentId = (id) => {
+	invariant(!id.includes(PATH), `Node segment ID must not contain '${PATH}': ${id}`, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$2,
+		L: 85,
+		S: void 0,
+		A: ["!id.includes(PATH)", "`Node segment ID must not contain '${PATH}': ${id}`"]
+	});
+};
+/**
+* Extract the parent qualified ID (everything before the last path separator).
+* Returns undefined for IDs with no parent (single segment).
+*/
+var getParentId = (qualifiedId) => {
+	const lastSlash = qualifiedId.lastIndexOf(PATH);
+	return lastSlash > 0 ? qualifiedId.slice(0, lastSlash) : void 0;
+};
+/**
+* Extract the last segment of a qualified ID.
+*/
+var getSegmentId = (qualifiedId) => {
+	return qualifiedId.split(PATH).pop() ?? qualifiedId;
+};
+//#endregion
+//#region src/graph.ts
+var graph_exports = /* @__PURE__ */ __exportAll({
+	GraphKind: () => GraphKind,
+	GraphTypeId: () => GraphTypeId,
+	addEdge: () => addEdge,
+	addEdges: () => addEdges,
+	addNode: () => addNode,
+	addNodes: () => addNodes,
+	expand: () => expand,
+	getActions: () => getActions,
+	getConnections: () => getConnections,
+	getEdges: () => getEdges,
+	getGraph: () => getGraph,
+	getNode: () => getNode,
+	getNodeOrThrow: () => getNodeOrThrow,
+	getPath: () => getPath,
+	getRoot: () => getRoot,
+	initialize: () => initialize,
+	make: () => make$1,
+	relationFromKey: () => relationFromKey,
+	relationKey: () => relationKey,
+	removeEdge: () => removeEdge,
+	removeEdges: () => removeEdges,
+	removeNode: () => removeNode,
+	removeNodes: () => removeNodes,
+	sortEdges: () => sortEdges,
+	toJSON: () => toJSON,
+	traverse: () => traverse,
+	waitForPath: () => waitForPath
+});
+var __dxlog_file$1 = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph.ts";
+var graphSymbol = Symbol("graph");
+/**
+* Get the Graph a Node is currently associated with.
+*/
+var getGraph = (node) => {
+	const graph = node[graphSymbol];
+	invariant(graph, "Node is not associated with a graph.", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 32,
+		S: void 0,
+		A: ["graph", "'Node is not associated with a graph.'"]
+	});
+	return graph;
+};
+/**
+* Identifier denoting a Graph.
+*/
+var GraphTypeId = Symbol.for("@dxos/app-graph/Graph");
+/**
+* Identifier for the graph kind discriminator.
+*/
+var GraphKind = Symbol.for("@dxos/app-graph/GraphKind");
+/**
+* The Graph represents the user interface information architecture of the application constructed via plugins.
+* @internal
+*/
+var GraphImpl = class {
+	[GraphTypeId] = GraphTypeId;
+	[GraphKind] = "writable";
+	pipe() {
+		return Pipeable.pipeArguments(this, arguments);
+	}
+	onNodeChanged = new Event();
+	_onExpand;
+	_onInitialize;
+	_onRemoveNode;
+	_registry;
+	_expanded = /* @__PURE__ */ new Set();
+	_pendingExpands = /* @__PURE__ */ new Set();
+	_initialized = /* @__PURE__ */ new Set();
+	_initialEdges = /* @__PURE__ */ new Map();
+	_initialNodes = /* @__PURE__ */ new Map([[RootId, this._constructNode({
+		id: RootId,
+		type: RootType,
+		data: null,
+		properties: {}
+	})]]);
+	/** @internal */
+	_node = Atom.family((id) => {
+		const initial = this._initialNodes.get(id) ?? Option.none();
+		return Atom.make(initial).pipe(Atom.keepAlive, Atom.withLabel(`graph:node:${id}`));
+	});
+	_nodeOrThrow = Atom.family((id) => {
+		return Atom.make((get) => {
+			const node = get(this._node(id));
+			invariant(Option.isSome(node), `Node not available: ${id}`, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file$1,
+				L: 171,
+				S: this,
+				A: ["Option.isSome(node)", "`Node not available: ${id}`"]
+			});
+			return node.value;
+		});
+	});
+	_edges = Atom.family((id) => {
+		const initial = this._initialEdges.get(id) ?? {};
+		return Atom.make(initial).pipe(Atom.keepAlive, Atom.withLabel(`graph:edges:${id}`));
+	});
+	_connections = Atom.family((key) => {
+		return Atom.make((get) => {
+			const parts = key ? primaryParts(key) : [];
+			if (parts.length < 2 || !parts[0]) return [];
+			const { id, relation } = relationFromConnectionKey(key);
+			return (get(this._edges(id))[relationKey(relation)] ?? []).map((id) => get(this._node(id))).filter(Option.isSome).map((o) => o.value);
+		}).pipe(Atom.withLabel(`graph:connections:${key}`));
+	});
+	_actions = Atom.family((id) => {
+		return Atom.make((get) => {
+			if (!id) return [];
+			return get(this._connections(connectionKey(id, actionRelation())));
+		}).pipe(Atom.withLabel(`graph:actions:${id}`));
+	});
+	_json = Atom.family((id) => {
+		return Atom.make((get) => {
+			const toJSON = (node, seen = []) => {
+				const nodes = get(this._connections(connectionKey(node.id, "child")));
+				const obj = {
+					id: node.id,
+					type: node.type
+				};
+				if (node.properties.label) obj.label = node.properties.label;
+				if (nodes.length) obj.nodes = nodes.map((n) => {
+					const nextSeen = [...seen, node.id];
+					return nextSeen.includes(n.id) ? void 0 : toJSON(n, nextSeen);
+				}).filter(isNonNullable);
+				return obj;
+			};
+			return toJSON(get(this._nodeOrThrow(id)));
+		}).pipe(Atom.withLabel(`graph:json:${id}`));
+	});
+	constructor({ registry, nodes, edges, onInitialize, onExpand, onRemoveNode } = {}) {
+		this._registry = registry ?? Registry.make();
+		this._onInitialize = onInitialize;
+		this._onExpand = onExpand;
+		this._onRemoveNode = onRemoveNode;
+		if (nodes) nodes.forEach((node) => {
+			this._initialNodes.set(node.id, this._constructNode(node));
+		});
+		if (edges) Object.entries(edges).forEach(([source, edges]) => {
+			this._initialEdges.set(source, edges);
+		});
+	}
+	json(id = RootId) {
+		return jsonImpl(this, id);
+	}
+	node(id) {
+		return nodeImpl(this, id);
+	}
+	nodeOrThrow(id) {
+		return nodeOrThrowImpl(this, id);
+	}
+	connections(id, relation) {
+		return connectionsImpl(this, id, relation);
+	}
+	actions(id) {
+		return actionsImpl(this, id);
+	}
+	edges(id) {
+		return edgesImpl(this, id);
+	}
+	/** @internal */
+	_constructNode(node) {
+		return Option.some({
+			[graphSymbol]: this,
+			data: null,
+			properties: {},
+			...node
+		});
+	}
+};
+/**
+* Internal helper to access GraphImpl internals.
+* @internal
+*/
+var getInternal = (graph) => {
+	return graph;
+};
+/**
+* Convert the graph to a JSON object.
+*/
+var toJSON = (graph, id = RootId) => {
+	const internal = getInternal(graph);
+	return internal._registry.get(internal._json(id));
+};
+/**
+* Implementation helper for json.
+*/
+var jsonImpl = (graph, id = RootId) => {
+	return getInternal(graph)._json(id);
+};
+/**
+* Implementation helper for node.
+*/
+var nodeImpl = (graph, id) => {
+	return getInternal(graph)._node(id);
+};
+/**
+* Implementation helper for nodeOrThrow.
+*/
+var nodeOrThrowImpl = (graph, id) => {
+	return getInternal(graph)._nodeOrThrow(id);
+};
+/**
+* Implementation helper for connections.
+*/
+var connectionsImpl = (graph, id, relation) => {
+	return getInternal(graph)._connections(connectionKey(id, relation));
+};
+/**
+* Implementation helper for actions.
+*/
+var actionsImpl = (graph, id) => {
+	return getInternal(graph)._actions(id);
+};
+/**
+* Implementation helper for edges.
+*/
+var edgesImpl = (graph, id) => {
+	return getInternal(graph)._edges(id);
+};
+/**
+* Implementation helper for getNode.
+*/
+var getNodeImpl = (graph, id) => {
+	return getInternal(graph)._registry.get(nodeImpl(graph, id));
+};
+function getNode(graphOrId, id) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		return (graph) => getNodeImpl(graph, id);
+	} else return getNodeImpl(graphOrId, id);
+}
+/**
+* Implementation helper for getNodeOrThrow.
+*/
+var getNodeOrThrowImpl = (graph, id) => {
+	return getInternal(graph)._registry.get(nodeOrThrowImpl(graph, id));
+};
+function getNodeOrThrow(graphOrId, id) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		return (graph) => getNodeOrThrowImpl(graph, id);
+	} else return getNodeOrThrowImpl(graphOrId, id);
+}
+/**
+* Get the root node of the graph.
+* This is an alias for `getNodeOrThrow(graph, ROOT_ID)`.
+*/
+function getRoot(graph) {
+	return getNodeOrThrowImpl(graph, RootId);
+}
+/**
+* Implementation helper for getConnections.
+*/
+var getConnectionsImpl = (graph, id, relation) => {
+	return getInternal(graph)._registry.get(connectionsImpl(graph, id, relation));
+};
+function getConnections(graphOrId, idOrRelation, relation) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		const rel = idOrRelation;
+		return (graph) => getConnectionsImpl(graph, id, rel);
+	} else {
+		const graph = graphOrId;
+		const id = idOrRelation;
+		invariant(relation !== void 0, "Relation is required.", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 448,
+			S: this,
+			A: ["relation !== undefined", "'Relation is required.'"]
+		});
+		return getConnectionsImpl(graph, id, relation);
+	}
+}
+/**
+* Implementation helper for getActions.
+*/
+var getActionsImpl = (graph, id) => {
+	return getInternal(graph)._registry.get(actionsImpl(graph, id));
+};
+function getActions(graphOrId, id) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		return (graph) => getActionsImpl(graph, id);
+	} else return getActionsImpl(graphOrId, id);
+}
+/**
+* Implementation helper for getEdges.
+*/
+var getEdgesImpl = (graph, id) => {
+	return getInternal(graph)._registry.get(edgesImpl(graph, id));
+};
+function getEdges(graphOrId, id) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		return (graph) => getEdgesImpl(graph, id);
+	} else return getEdgesImpl(graphOrId, id);
+}
+/**
+* Recursive depth-first traversal of the graph.
+*/
+/**
+* Implementation helper for traverse.
+*/
+var traverseImpl = (graph, options, path = []) => {
+	const { visitor, source = RootId, relation } = options;
+	if (path.includes(source)) return;
+	if (visitor(getNodeOrThrow(graph, source), [...path, source]) === false) return;
+	const relations = Array.isArray(relation) ? relation : [relation];
+	const seen = /* @__PURE__ */ new Set();
+	for (const rel of relations) for (const connected of getConnections(graph, source, rel)) if (!seen.has(connected.id)) {
+		seen.add(connected.id);
+		traverseImpl(graph, {
+			source: connected.id,
+			relation,
+			visitor
+		}, [...path, source]);
+	}
+};
+function traverse(graphOrOptions, optionsOrPath, path) {
+	if (typeof graphOrOptions === "object" && "visitor" in graphOrOptions) {
+		const options = graphOrOptions;
+		const pathArg = Array.isArray(optionsOrPath) ? optionsOrPath : void 0;
+		return (graph) => traverseImpl(graph, options, pathArg);
+	} else return traverseImpl(graphOrOptions, optionsOrPath, path ?? (Array.isArray(optionsOrPath) ? optionsOrPath : void 0));
+}
+/**
+* Implementation helper for getPath.
+*/
+var getPathImpl = (graph, params) => {
+	return Function.pipe(getNode(graph, params.source ?? "root"), Option.flatMap((node) => {
+		let found = Option.none();
+		traverseImpl(graph, {
+			source: node.id,
+			relation: "child",
+			visitor: (node, path) => {
+				if (Option.isSome(found)) return false;
+				if (node.id === params.target) found = Option.some(path);
+			}
+		});
+		return found;
+	}));
+};
+function getPath(graphOrParams, params) {
+	if (params === void 0 && typeof graphOrParams === "object" && "target" in graphOrParams) {
+		const params = graphOrParams;
+		return (graph) => getPathImpl(graph, params);
+	} else return getPathImpl(graphOrParams, params);
+}
+/**
+* Implementation helper for waitForPath.
+*/
+var waitForPathImpl = (graph, params, options) => {
+	const { timeout = 5e3, interval = 500 } = options ?? {};
+	const path = getPathImpl(graph, params);
+	if (Option.isSome(path)) return Promise.resolve(path.value);
+	const trigger = new Trigger();
+	const i = setInterval(() => {
+		const path = getPathImpl(graph, params);
+		if (Option.isSome(path)) trigger.wake(path.value);
+	}, interval);
+	return trigger.wait({ timeout }).finally(() => clearInterval(i));
+};
+function waitForPath(graphOrParams, paramsOrOptions, options) {
+	if (typeof graphOrParams === "object" && "target" in graphOrParams) {
+		const params = graphOrParams;
+		const opts = typeof paramsOrOptions === "object" && !("target" in paramsOrOptions) ? paramsOrOptions : void 0;
+		return (graph) => waitForPathImpl(graph, params, opts);
+	} else return waitForPathImpl(graphOrParams, paramsOrOptions, options);
+}
+/**
+* Implementation helper for initialize.
+*/
+var initializeImpl = async (graph, id) => {
+	const internal = getInternal(graph);
+	const initialized = internal._initialized.has(id);
+	log("initialize", {
+		id,
+		initialized
+	}, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 670,
+		S: void 0
+	});
+	if (!initialized) {
+		internal._initialized.add(id);
+		await internal._onInitialize?.(id);
+	}
+	return graph;
+};
+function initialize(graphOrId, id) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		return (graph) => initializeImpl(graph, id);
+	} else return initializeImpl(graphOrId, id);
+}
+/**
+* Implementation helper for expand.
+* If the node does not exist yet, the expand is recorded as pending and applied when the node is added.
+*/
+var expandImpl = (graph, id, relation) => {
+	const internal = getInternal(graph);
+	const normalizedRelation = normalizeRelation(relation);
+	const key = primaryKey(id, relationKey(normalizedRelation));
+	const nodeOpt = internal._registry.get(internal._node(id));
+	if (Option.isNone(nodeOpt)) {
+		internal._pendingExpands.add(key);
+		log("expand", {
+			key,
+			deferred: true
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 719,
+			S: void 0
+		});
+		return graph;
+	}
+	const expanded = internal._expanded.has(key);
+	log("expand", {
+		key,
+		expanded
+	}, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 724,
+		S: void 0
+	});
+	if (!expanded) {
+		internal._expanded.add(key);
+		internal._onExpand?.(id, normalizedRelation);
+	}
+	return graph;
+};
+function expand(graphOrId, idOrRelation, relation) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		const rel = idOrRelation;
+		return (graph) => expandImpl(graph, id, rel);
+	} else {
+		const graph = graphOrId;
+		const id = idOrRelation;
+		invariant(relation !== void 0, "Relation is required.", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 760,
+			S: this,
+			A: ["relation !== undefined", "'Relation is required.'"]
+		});
+		return expandImpl(graph, id, relation);
+	}
+}
+/**
+* Implementation helper for sortEdges.
+*/
+var sortEdgesImpl = (graph, id, relation, order) => {
+	const internal = getInternal(graph);
+	const edgesAtom = internal._edges(id);
+	const edges = internal._registry.get(edgesAtom);
+	const relationId = relationKey(relation);
+	const current = edges[relationId] ?? [];
+	const unsorted = current.filter((id) => !order.includes(id));
+	const newOrder = [...order.filter((id) => current.includes(id)), ...unsorted];
+	if (newOrder.length === current.length && newOrder.every((id, i) => id === current[i])) return graph;
+	internal._registry.set(edgesAtom, {
+		...edges,
+		[relationId]: newOrder
+	});
+	return graph;
+};
+function sortEdges(graphOrId, idOrRelation, relationOrOrder, order) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		const relation = idOrRelation;
+		const order = relationOrOrder;
+		return (graph) => sortEdgesImpl(graph, id, relation, order);
+	} else return sortEdgesImpl(graphOrId, idOrRelation, relationOrOrder, order);
+}
+/**
+* Implementation helper for addNodes.
+*/
+var addNodesImpl = (graph, nodes) => {
+	Atom.batch(() => {
+		nodes.map((node) => addNodeImpl(graph, node));
+	});
+	return graph;
+};
+function addNodes(graphOrNodes, nodes) {
+	if (nodes === void 0) {
+		const nodes = graphOrNodes;
+		return (graph) => addNodesImpl(graph, nodes);
+	} else return addNodesImpl(graphOrNodes, nodes);
+}
+/**
+* Implementation helper for addNode.
+*/
+var addNodeImpl = (graph, nodeArg) => {
+	const internal = getInternal(graph);
+	const { nodes, actions, edges, id, type, data = null, properties = {}, ...rest } = nodeArg;
+	const nodeAtom = internal._node(id);
+	const existingNode = internal._registry.get(nodeAtom);
+	Option.match(existingNode, {
+		onSome: (existing) => {
+			const typeChanged = existing.type !== type;
+			const dataChanged = !shallowEqual(existing.data, data);
+			const propertiesChanged = Object.keys(properties).some((key) => existing.properties[key] !== properties[key]);
+			const changed = typeChanged || dataChanged || propertiesChanged;
+			log("existing node", {
+				id,
+				changed,
+				typeChanged,
+				dataChanged,
+				propertiesChanged
+			}, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file$1,
+				L: 886,
+				S: void 0
+			});
+			if (changed) {
+				log("updating node", {
+					id,
+					type,
+					data,
+					properties
+				}, {
+					"~LogMeta": "~LogMeta",
+					F: __dxlog_file$1,
+					L: 894,
+					S: void 0
+				});
+				const newNode = Option.some({
+					...existing,
+					...rest,
+					type,
+					data,
+					properties: {
+						...existing.properties,
+						...properties
+					}
+				});
+				internal._registry.set(nodeAtom, newNode);
+				graph.onNodeChanged.emit({
+					id,
+					node: newNode
+				});
+			}
+		},
+		onNone: () => {
+			log("new node", {
+				id,
+				type,
+				data,
+				properties
+			}, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file$1,
+				L: 907,
+				S: void 0
+			});
+			const newNode = internal._constructNode({
+				id,
+				type,
+				data,
+				properties,
+				...rest
+			});
+			internal._registry.set(nodeAtom, newNode);
+			graph.onNodeChanged.emit({
+				id,
+				node: newNode
+			});
+			const toApply = [...internal._pendingExpands].filter((k) => primaryParts(k)[0] === id);
+			for (const pendingKey of toApply) {
+				internal._pendingExpands.delete(pendingKey);
+				const relation = relationFromKey(primaryParts(pendingKey)[1]);
+				internal._expanded.add(pendingKey);
+				internal._onExpand?.(id, relation);
+			}
+		}
+	});
+	if (nodes) {
+		addNodesImpl(graph, nodes);
+		addEdgesImpl(graph, nodes.map((node) => ({
+			source: id,
+			target: node.id,
+			relation: "child"
+		})));
+		sortEdgesImpl(graph, id, "child", nodes.map((n) => n.id));
+	}
+	if (actions) {
+		addNodesImpl(graph, actions);
+		const actionRelation$1 = actionRelation();
+		addEdgesImpl(graph, actions.map((node) => ({
+			source: id,
+			target: node.id,
+			relation: actionRelation$1
+		})));
+		sortEdgesImpl(graph, id, actionRelation$1, actions.map((node) => node.id));
+	}
+	if (edges) todo();
+	return graph;
+};
+function addNode(graphOrNodeArg, nodeArg) {
+	if (nodeArg === void 0) {
+		const nodeArg = graphOrNodeArg;
+		return (graph) => addNodeImpl(graph, nodeArg);
+	} else return addNodeImpl(graphOrNodeArg, nodeArg);
+}
+/**
+* Implementation helper for removeNodes.
+*/
+var removeNodesImpl = (graph, ids, edges = false) => {
+	Atom.batch(() => {
+		ids.map((id) => removeNodeImpl(graph, id, edges));
+	});
+	return graph;
+};
+function removeNodes(graphOrIds, idsOrEdges, edges) {
+	if (Array.isArray(graphOrIds)) {
+		const ids = graphOrIds;
+		const edgesArg = typeof idsOrEdges === "boolean" ? idsOrEdges : false;
+		return (graph) => removeNodesImpl(graph, ids, edgesArg);
+	} else return removeNodesImpl(graphOrIds, idsOrEdges, edges ?? false);
+}
+/**
+* Implementation helper for removeNode.
+*/
+var removeNodeImpl = (graph, id, edges = false) => {
+	const internal = getInternal(graph);
+	const nodeAtom = internal._node(id);
+	internal._registry.set(nodeAtom, Option.none());
+	graph.onNodeChanged.emit({
+		id,
+		node: Option.none()
+	});
+	if (edges) {
+		const nodeEdges = internal._registry.get(internal._edges(id));
+		const edgesToRemove = [];
+		for (const [relationKeyValue, relatedIds] of Object.entries(nodeEdges)) {
+			const relation = relationFromKey(relationKeyValue);
+			const isInboundRelation = relation.direction === "inbound";
+			for (const relatedId of relatedIds) if (isInboundRelation) edgesToRemove.push({
+				source: relatedId,
+				target: id,
+				relation: inverseRelation(relation)
+			});
+			else edgesToRemove.push({
+				source: id,
+				target: relatedId,
+				relation
+			});
+		}
+		removeEdgesImpl(graph, edgesToRemove);
+	}
+	internal._onRemoveNode?.(id);
+	return graph;
+};
+function removeNode(graphOrId, idOrEdges, edges) {
+	if (typeof graphOrId === "string") {
+		const id = graphOrId;
+		const edgesArg = typeof idOrEdges === "boolean" ? idOrEdges : false;
+		return (graph) => removeNodeImpl(graph, id, edgesArg);
+	} else return removeNodeImpl(graphOrId, idOrEdges, edges ?? false);
+}
+/**
+* Implementation helper for addEdges.
+*/
+var addEdgesImpl = (graph, edges) => {
+	Atom.batch(() => {
+		edges.map((edge) => addEdgeImpl(graph, edge));
+	});
+	return graph;
+};
+function addEdges(graphOrEdges, edges) {
+	if (edges === void 0) {
+		const edges = graphOrEdges;
+		return (graph) => addEdgesImpl(graph, edges);
+	} else return addEdgesImpl(graphOrEdges, edges);
+}
+/**
+* Implementation helper for addEdge.
+*/
+var addEdgeImpl = (graph, edgeArg) => {
+	const relation = normalizeRelation(edgeArg.relation);
+	const relationId = relationKey(relation);
+	const inverseId = relationKey(inverseRelation(relation));
+	const internal = getInternal(graph);
+	const sourceAtom = internal._edges(edgeArg.source);
+	const source = internal._registry.get(sourceAtom);
+	const sourceList = source[relationId] ?? [];
+	if (!sourceList.includes(edgeArg.target)) {
+		log("add edge", {
+			source: edgeArg.source,
+			target: edgeArg.target,
+			relation: relationId
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 1109,
+			S: void 0
+		});
+		internal._registry.set(sourceAtom, {
+			...source,
+			[relationId]: [...sourceList, edgeArg.target]
+		});
+	}
+	const targetAtom = internal._edges(edgeArg.target);
+	const target = internal._registry.get(targetAtom);
+	const targetList = target[inverseId] ?? [];
+	if (!targetList.includes(edgeArg.source)) {
+		log("add inverse edge", {
+			source: edgeArg.source,
+			target: edgeArg.target,
+			relation: inverseId
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 1117,
+			S: void 0
+		});
+		internal._registry.set(targetAtom, {
+			...target,
+			[inverseId]: [...targetList, edgeArg.source]
+		});
+	}
+	return graph;
+};
+function addEdge(graphOrEdgeArg, edgeArg) {
+	if (edgeArg === void 0) {
+		const edgeArg = graphOrEdgeArg;
+		return (graph) => addEdgeImpl(graph, edgeArg);
+	} else return addEdgeImpl(graphOrEdgeArg, edgeArg);
+}
+/**
+* Implementation helper for removeEdges.
+*/
+var removeEdgesImpl = (graph, edges, removeOrphans = false) => {
+	Atom.batch(() => {
+		edges.map((edge) => removeEdgeImpl(graph, edge, removeOrphans));
+	});
+	return graph;
+};
+function removeEdges(graphOrEdges, edgesOrRemoveOrphans, removeOrphans) {
+	if (Array.isArray(graphOrEdges)) {
+		const edges = graphOrEdges;
+		const removeOrphansArg = typeof edgesOrRemoveOrphans === "boolean" ? edgesOrRemoveOrphans : false;
+		return (graph) => removeEdgesImpl(graph, edges, removeOrphansArg);
+	} else return removeEdgesImpl(graphOrEdges, edgesOrRemoveOrphans, removeOrphans ?? false);
+}
+/**
+* Implementation helper for removeEdge.
+*/
+var removeEdgeImpl = (graph, edgeArg, removeOrphans = false) => {
+	const relation = normalizeRelation(edgeArg.relation);
+	const relationId = relationKey(relation);
+	const inverseId = relationKey(inverseRelation(relation));
+	const internal = getInternal(graph);
+	const sourceAtom = internal._edges(edgeArg.source);
+	const source = internal._registry.get(sourceAtom);
+	const sourceList = source[relationId] ?? [];
+	if (sourceList.includes(edgeArg.target)) internal._registry.set(sourceAtom, {
+		...source,
+		[relationId]: sourceList.filter((id) => id !== edgeArg.target)
+	});
+	const targetAtom = internal._edges(edgeArg.target);
+	const target = internal._registry.get(targetAtom);
+	const targetList = target[inverseId] ?? [];
+	if (targetList.includes(edgeArg.source)) internal._registry.set(targetAtom, {
+		...target,
+		[inverseId]: targetList.filter((id) => id !== edgeArg.source)
+	});
+	if (removeOrphans) {
+		const sourceAfter = internal._registry.get(sourceAtom);
+		const targetAfter = internal._registry.get(targetAtom);
+		const isEmpty = (edges) => Object.values(edges).every((ids) => ids.length === 0);
+		if (isEmpty(sourceAfter) && edgeArg.source !== "root") removeNodesImpl(graph, [edgeArg.source]);
+		if (isEmpty(targetAfter) && edgeArg.target !== "root") removeNodesImpl(graph, [edgeArg.target]);
+	}
+	return graph;
+};
+function removeEdge(graphOrEdgeArg, edgeArgOrRemoveOrphans, removeOrphans) {
+	if (edgeArgOrRemoveOrphans === void 0 || typeof edgeArgOrRemoveOrphans === "boolean" || "source" in graphOrEdgeArg) {
+		const edgeArg = graphOrEdgeArg;
+		const removeOrphansArg = typeof edgeArgOrRemoveOrphans === "boolean" ? edgeArgOrRemoveOrphans : false;
+		return (graph) => removeEdgeImpl(graph, edgeArg, removeOrphansArg);
+	} else return removeEdgeImpl(graphOrEdgeArg, edgeArgOrRemoveOrphans, removeOrphans ?? false);
+}
+/**
+* Creates a new Graph instance.
+*/
+var make$1 = (params) => {
+	return new GraphImpl(params);
+};
+var relationKey = (relation) => {
+	const normalized = normalizeRelation(relation);
+	return secondaryKey(normalized.kind, normalized.direction);
+};
+var relationFromKey = (encoded) => {
+	const parts = secondaryParts(encoded);
+	invariant(parts.length === 2 && parts[0].length > 0 && parts[1].length > 0, `Invalid relation key: ${encoded}`, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 1262,
+		S: void 0,
+		A: ["parts.length === 2 && parts[0].length > 0 && parts[1].length > 0", "`Invalid relation key: ${encoded}`"]
+	});
+	const [kind, directionRaw] = parts;
+	invariant(directionRaw === "outbound" || directionRaw === "inbound", `Invalid relation direction: ${directionRaw}`, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 1264,
+		S: void 0,
+		A: ["directionRaw === 'outbound' || directionRaw === 'inbound'", "`Invalid relation direction: ${directionRaw}`"]
+	});
+	return relation(kind, directionRaw);
+};
+var connectionKey = (id, relation) => primaryKey(id, relationKey(relation));
+var relationFromConnectionKey = (key) => {
+	const [id, encodedRelation] = primaryParts(key);
+	invariant(id && encodedRelation, `Invalid connection key: ${key}`, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file$1,
+		L: 1272,
+		S: void 0,
+		A: ["id && encodedRelation", "`Invalid connection key: ${key}`"]
+	});
+	return {
+		id,
+		relation: relationFromKey(encodedRelation)
+	};
+};
+var inverseRelation = (relation$1) => {
+	const normalized = normalizeRelation(relation$1);
+	return relation(normalized.kind, normalized.direction === "outbound" ? "inbound" : "outbound");
+};
+//#endregion
+//#region src/node-matcher.ts
+var node_matcher_exports = /* @__PURE__ */ __exportAll({
+	whenAll: () => whenAll,
+	whenAny: () => whenAny,
+	whenEchoObject: () => whenEchoObject,
+	whenEchoObjectMatches: () => whenEchoObjectMatches,
+	whenEchoType: () => whenEchoType,
+	whenEchoTypeMatches: () => whenEchoTypeMatches,
+	whenId: () => whenId,
+	whenNodeType: () => whenNodeType,
+	whenNot: () => whenNot,
+	whenRoot: () => whenRoot
+});
+/**
+* Matches the root node of the graph.
+*
+* @returns Option.some(node) if the node is the root, Option.none() otherwise.
+*
+* @example
+* ```ts
+* GraphBuilder.createExtension({
+*   id: 'myExtension',
+*   match: NodeMatcher.whenRoot,
+*   connector: (node) => Effect.succeed([...]),
+* });
+* ```
+*/
+var whenRoot = (node) => node.id === "root" ? Option.some(node) : Option.none();
+/**
+* Matches a node by its exact ID.
+*
+* @param id - The node ID to match against.
+* @returns A matcher that returns Option.some(node) if IDs match, Option.none() otherwise.
+*
+* @example
+* ```ts
+* GraphBuilder.createExtension({
+*   id: 'spacesExtension',
+*   match: NodeMatcher.whenId('spaces'),
+*   connector: (node) => Effect.succeed([...]),
+* });
+* ```
+*/
+var whenId = (id) => (node) => node.id === id ? Option.some(node) : Option.none();
+/**
+* Matches a node by its type string (the `node.type` property).
+*
+* @param type - The node type string to match against.
+* @returns A matcher that returns Option.some(node) if types match, Option.none() otherwise.
+*
+* @example
+* ```ts
+* GraphBuilder.createExtension({
+*   id: 'spaceSettingsExtension',
+*   match: NodeMatcher.whenNodeType('org.dxos.plugin.space.settings'),
+*   connector: (node) => Effect.succeed([...]),
+* });
+* ```
+*/
+var whenNodeType = (type) => (node) => node.type === type ? Option.some(node) : Option.none();
+/**
+* Matches a node whose data is an instance of the given ECHO schema type.
+* Returns the **typed entity data** (not the node) for direct use in callbacks.
+*
+* Use this when you need to work directly with the typed ECHO entity in your
+* connector or actions callback.
+*
+* @template T - The ECHO schema type to match against.
+* @param type - The ECHO schema (e.g., `Collection.Collection`, `Document.Document`).
+* @returns A matcher that returns Option.some(entity) if the data matches, Option.none() otherwise.
+*
+* @example
+* ```ts
+* GraphBuilder.createExtension({
+*   id: 'collectionExtension',
+*   match: NodeMatcher.whenEchoType(Collection.Collection),
+*   connector: (collection) => {
+*     // `collection` is typed as Collection.Collection
+*     return Effect.succeed(collection.objects.map(...));
+*   },
+* });
+* ```
+*
+* Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+* preserving the typed entity data in the result.
+*
+* @see {@link whenEchoTypeMatches} - Returns the node instead of data for legacy composition.
+*/
+var whenEchoType = (type) => (node) => Entity.instanceOf(type, node.data) ? Option.some(node.data) : Option.none();
+/**
+* Matches a node whose data is any ECHO object.
+* Returns the **object data** (not the node) for direct use in callbacks.
+*
+* Use this when you need to work with any ECHO object regardless of its specific type.
+*
+* @returns Option.some(object) if the node's data is an ECHO object, Option.none() otherwise.
+*
+* @example
+* ```ts
+* GraphBuilder.createExtension({
+*   id: 'objectProperties',
+*   match: NodeMatcher.whenEchoObject,
+*   connector: (object) => {
+*     // `object` is typed as Obj.Unknown
+*     const id = Obj.getURI(object);
+*     return Effect.succeed([{ id: `${id}.settings`, ... }]);
+*   },
+* });
+* ```
+*
+* Can be composed directly with {@link whenAll}/{@link whenAny}/{@link whenNot} while
+* preserving the `Obj.Unknown` data type in the result.
+*
+* @see {@link whenEchoObjectMatches} - Returns the node instead of data for legacy composition.
+*/
+var whenEchoObject = (node) => Obj.isObject(node.data) ? Option.some(node.data) : Option.none();
+/**
+* Composes multiple matchers with AND logic - all matchers must match for success.
+* The result data type is the intersection of all matchers' data types.
+* Filter matchers like {@link whenNot} return `unknown`, making them transparent
+* in the intersection (since `T & unknown = T`).
+*
+* @param matchers - The matchers to combine. All must return Option.some for success.
+* @returns A matcher whose data type is the intersection of all input matchers' data types.
+*   Returns the first matcher's value when all match, Option.none() otherwise.
+*
+* @example
+* ```ts
+* // Match ECHO objects that are NOT Channels — result is NodeMatcher<Obj.Unknown>.
+* const whenCommentable = NodeMatcher.whenAll(
+*   NodeMatcher.whenEchoObject,
+*   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
+* );
+* ```
+*/
+var whenAll = (...matchers) => (node, get) => {
+	let first = Option.none();
+	for (const candidate of matchers) {
+		const result = candidate(node, get);
+		if (Option.isNone(result)) return Option.none();
+		if (Option.isNone(first)) first = result;
+	}
+	return first;
+};
+/**
+* Composes multiple matchers with OR logic - at least one matcher must match.
+* The result data type is the union of all matchers' data types.
+*
+* @param matchers - The matchers to combine. At least one must return Option.some.
+* @returns A matcher whose data type is the union of all input matchers' data types.
+*   Returns the first matching matcher's value, or Option.none() if none match.
+*
+* @example
+* ```ts
+* // Match nodes that are either Sequences or Routines
+* const whenInvocable = NodeMatcher.whenAny(
+*   NodeMatcher.whenEchoTypeMatches(Sequence),
+*   NodeMatcher.whenEchoTypeMatches(Routine.Routine),
+* );
+* ```
+*/
+var whenAny = (...matchers) => (node, get) => {
+	for (const candidate of matchers) {
+		const result = candidate(node, get);
+		if (Option.isSome(result)) return result;
+	}
+	return Option.none();
+};
+/**
+* Matches a node whose data is an instance of the given ECHO schema type.
+* Returns the **node** (not the data) to enable composition with whenAll/whenAny/whenNot.
+*
+* Use this instead of {@link whenEchoType} when you need to combine matchers.
+* The difference is what's returned:
+* - `whenEchoType` returns the typed entity (for direct use)
+* - `whenEchoTypeMatches` returns the node (for composition)
+*
+* @template T - The ECHO schema type to match against.
+* @param type - The ECHO schema (e.g., `Channel.Channel`, `Document.Document`).
+* @returns A matcher that returns Option.some(node) if the data matches, Option.none() otherwise.
+*
+* @example
+* ```ts
+* // Use with whenAny for OR logic
+* const whenPresentable = NodeMatcher.whenAny(
+*   NodeMatcher.whenEchoTypeMatches(Collection.Collection),
+*   NodeMatcher.whenEchoTypeMatches(Markdown.Document),
+* );
+*
+* // Use with whenNot for exclusion
+* const whenNotChannel = NodeMatcher.whenNot(
+*   NodeMatcher.whenEchoTypeMatches(Channel.Channel),
+* );
+* ```
+*
+* @see {@link whenEchoType} - Use instead when you need the typed entity directly.
+*/
+var whenEchoTypeMatches = (type) => (node) => Entity.instanceOf(type, node.data) ? Option.some(node) : Option.none();
+/**
+* Matches a node whose data is any ECHO object.
+* Returns the **node** (not the data) to enable composition with whenAll/whenAny/whenNot.
+*
+* Use this instead of {@link whenEchoObject} when you need to combine matchers.
+* The difference is what's returned:
+* - `whenEchoObject` returns the object data (for direct use)
+* - `whenEchoObjectMatches` returns the node (for composition)
+*
+* @returns Option.some(node) if the node's data is an ECHO object, Option.none() otherwise.
+*
+* @example
+* ```ts
+* // Match ECHO objects that are not system types
+* const whenUserObject = NodeMatcher.whenAll(
+*   NodeMatcher.whenEchoObjectMatches,
+*   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(SystemType)),
+* );
+* ```
+*
+* @see {@link whenEchoObject} - Use instead when you need the object data directly.
+*/
+var whenEchoObjectMatches = (node) => Obj.isObject(node.data) ? Option.some(node) : Option.none();
+/**
+* Negates a matcher - matches when the given matcher does NOT match.
+* Useful for exclusion patterns like "any object EXCEPT type X".
+*
+* Returns `NodeMatcher<unknown>` because negation is a filter — it doesn't provide
+* typed data. This makes it transparent in {@link whenAll} intersections
+* (since `T & unknown = T`).
+*
+* @param matcher - The matcher to negate.
+* @returns A matcher that returns Option.some(node) if the input matcher returns none,
+*   and Option.none() if the input matcher returns some.
+*
+* @example
+* ```ts
+* // Match any ECHO object that is NOT a Channel — result is NodeMatcher<Obj.Unknown>.
+* const whenCommentable = NodeMatcher.whenAll(
+*   NodeMatcher.whenEchoObject,
+*   NodeMatcher.whenNot(NodeMatcher.whenEchoTypeMatches(Channel.Channel)),
+* );
+*
+* // Match any node that is NOT the root
+* const whenNotRoot = NodeMatcher.whenNot(NodeMatcher.whenRoot);
+* ```
+*/
+var whenNot = (matcher) => (node, get) => Option.isNone(matcher(node, get)) ? Option.some(node) : Option.none();
+//#endregion
+//#region src/graph-builder.ts
+var graph_builder_exports = /* @__PURE__ */ __exportAll({
+	GraphBuilderTypeId: () => GraphBuilderTypeId,
+	addExtension: () => addExtension,
+	createConnector: () => createConnector,
+	createExtension: () => createExtension,
+	createExtensionRaw: () => createExtensionRaw,
+	createTypeExtension: () => createTypeExtension,
+	destroy: () => destroy,
+	explore: () => explore,
+	flattenExtensions: () => flattenExtensions,
+	flush: () => flush,
+	from: () => from,
+	make: () => make,
+	nodeUrlSegment: () => nodeUrlSegment,
+	removeExtension: () => removeExtension,
+	urlRepresentation: () => urlRepresentation
+});
+var __dxlog_file = "/__w/dxos/dxos/packages/sdk/app-graph/src/graph-builder.ts";
+/** Default linked-segment prefix; mirrors `@dxos/react-ui-attention`'s `linkedSegment`. Internal: read
+* the resolved value from `builder.urlGrammar` rather than the default. */
+var DEFAULT_LINKED_PREFIX = "~";
+/** Default tail separator; never appears in an entity id or a type slug. Internal, as above. */
+var DEFAULT_TAIL_SEPARATOR = "+";
+/**
+* The `(key, id?)` URL representation of a node under a given {@link UrlBinding} — the reverse of forward
+* resolution, minus the workspace (always the node id's second segment). A singleton has no id; a
+* resolver-backed key keeps just the object id; a static path encodes the segments between the path and
+* the id, `+`-joined (empty when the node sits at the path — a container whose children are the items).
+*/
+var urlRepresentation = (nodeId, url, tailSeparator = DEFAULT_TAIL_SEPARATOR) => {
+	if (url.kind === "singleton") return { key: url.key };
+	const segments = nodeId.split("/");
+	const id = typeof url.path === "function" ? segments[segments.length - 1] : segments.slice(2 + url.path.length).join(tailSeparator);
+	return {
+		key: url.key,
+		id
+	};
+};
+/**
+* A node's own URL pair segment — `/<key>[/<id>]`, with no workspace/anchor prefix — or `undefined` when
+* the node is not addressable in its own right (a container node sitting at the binding's `path`, whose
+* children are the addressable items). A full URL is composed by prefixing `/w/<workspace>`.
+*/
+var nodeUrlSegment = (nodeId, url, tailSeparator = DEFAULT_TAIL_SEPARATOR) => {
+	const { key, id } = urlRepresentation(nodeId, url, tailSeparator);
+	if (id === void 0) return `/${key}`;
+	return id === "" ? void 0 : `/${key}/${id}`;
+};
+/**
+* Return a copy of `node` (and its inline descendants) with `properties.urlSegment` stamped. A linked
+* node (id ending in a `~<variant>` segment) is stamped from the `linked` tier key, independent of its
+* producing extension's binding; any other node is stamped from `url` (its producer's binding), if any.
+*/
+var stampUrlSegment = (node, url, grammar) => {
+	const lastSegment = node.id.slice(node.id.lastIndexOf("/") + 1);
+	const segment = lastSegment.startsWith(grammar.linkedPrefix) ? grammar.linkedKey && `/${grammar.linkedKey}/${lastSegment.slice(grammar.linkedPrefix.length)}` : url && nodeUrlSegment(node.id, url, grammar.tailSeparator);
+	const nodes = node.nodes?.map((child) => stampUrlSegment(child, url, grammar));
+	if (!segment && !nodes) return node;
+	return {
+		...node,
+		...segment && { properties: {
+			...node.properties,
+			urlSegment: segment
+		} },
+		...nodes && { nodes }
+	};
+};
+/**
+* Identifier denoting a GraphBuilder.
+*/
+var GraphBuilderTypeId = Symbol.for("@dxos/app-graph/GraphBuilder");
+/**
+* The builder provides an extensible way to compose the construction of the graph.
+* @internal
+*/
+var GraphBuilderImpl = class {
+	[GraphBuilderTypeId] = GraphBuilderTypeId;
+	pipe() {
+		return Pipeable.pipeArguments(this, arguments);
+	}
+	/** Active subscriptions keyed by composite ID, cleaned up on node removal. */
+	_subscriptions = /* @__PURE__ */ new Map();
+	/** Connector updates pending flush, keyed by connector key. */
+	_dirtyConnectors = /* @__PURE__ */ new Map();
+	/** Last-flushed node IDs per connector key, used for edge removal on update. */
+	_connectorPrevious = /* @__PURE__ */ new Map();
+	/** All inline-descendant IDs per connector key, used to remove stale inline nodes on update. */
+	_connectorPreviousInlineIds = /* @__PURE__ */ new Map();
+	/** Last-flushed node args per connector key, used for change detection. */
+	_connectorPreviousArgs = /* @__PURE__ */ new Map();
+	/** Whether a dirty-flush task is already scheduled. */
+	_flushScheduled = false;
+	/** Resolves when the current flush completes. */
+	_flushPromise = Promise.resolve();
+	/** Registered builder extensions keyed by extension ID. */
+	_extensions = Atom.make(Record.empty()).pipe(Atom.keepAlive, Atom.withLabel("graph-builder:extensions"));
+	/**
+	* Node id -> id of the extension whose connector produced it. Non-reactive: updated directly
+	* as connectors materialize/remove nodes, so reverse (node → URL) mapping in
+	* `path-resolution.ts` can look up the producing extension without a reactive read.
+	*/
+	_nodeExtensions = /* @__PURE__ */ new Map();
+	/** Triggers signalling that a node's resolver has fired at least once. */
+	_initialized = {};
+	/** The URL grammar (see {@link UrlGrammar}); the keys are absent when URLs are not in play. */
+	urlGrammar;
+	/** Shared atom registry for reactive subscriptions. */
+	_registry;
+	/** Backing graph with internal accessors for node atoms and construction. */
+	_graph;
+	constructor({ registry, urlGrammar, ...params } = {}) {
+		this.urlGrammar = {
+			linkedPrefix: DEFAULT_LINKED_PREFIX,
+			tailSeparator: DEFAULT_TAIL_SEPARATOR,
+			...urlGrammar
+		};
+		this._registry = registry ?? Registry.make();
+		const graph = make$1({
+			...params,
+			registry: this._registry,
+			onExpand: (id, relation) => this._onExpand(id, relation),
+			onInitialize: (id) => this._onInitialize(id),
+			onRemoveNode: (id) => this._onRemoveNode(id)
+		});
+		this._graph = graph;
+	}
+	get graph() {
+		return this._graph;
+	}
+	get extensions() {
+		return this._extensions;
+	}
+	getExtensions() {
+		return this._registry.get(this._extensions);
+	}
+	getNodeExtensionId(nodeId) {
+		return this._nodeExtensions.get(nodeId);
+	}
+	/** Record `extensionId` as the producer of a qualified node and all of its inline `nodes` descendants. */
+	_recordProvenance(node, extensionId) {
+		this._nodeExtensions.set(node.id, extensionId);
+		for (const child of node.nodes ?? []) this._recordProvenance(child, extensionId);
+	}
+	/** Apply a set of node changes for a single connector key. */
+	_applyConnectorUpdate(key, nodes, previous) {
+		const { id, relation } = relationFromConnectorKey(key);
+		const ids = nodes.map((node) => node.id);
+		const removed = previous.filter((pid) => !ids.includes(pid));
+		this._connectorPrevious.set(key, ids);
+		this._connectorPreviousArgs.set(key, nodes);
+		const currentInlineIds = collectAllInlineIds(nodes);
+		const staleInlineIds = (this._connectorPreviousInlineIds.get(key) ?? []).filter((pid) => !currentInlineIds.includes(pid));
+		this._connectorPreviousInlineIds.set(key, currentInlineIds);
+		removeNodes(this._graph, staleInlineIds, true);
+		removeEdges(this._graph, removed.map((target) => ({
+			source: id,
+			target,
+			relation
+		})), true);
+		addNodes(this._graph, nodes);
+		addEdges(this._graph, nodes.map((node) => ({
+			source: id,
+			target: node.id,
+			relation
+		})));
+		if (ids.length > 0) {
+			const sortedIds = [...nodes].sort((a, b) => Position.compare({ position: a.properties?.position }, { position: b.properties?.position })).map((n) => n.id);
+			sortEdges(this._graph, id, relation, sortedIds);
+		}
+	}
+	_scheduleDirtyFlush() {
+		if (!this._flushScheduled) {
+			this._flushScheduled = true;
+			this._flushPromise = scheduleTask(() => {
+				this._flushScheduled = false;
+				while (this._dirtyConnectors.size > 0) {
+					const entries = [...this._dirtyConnectors.entries()];
+					this._dirtyConnectors.clear();
+					Atom.batch(() => {
+						for (const [key, { nodes, previous }] of entries) this._applyConnectorUpdate(key, nodes, previous);
+					});
+				}
+			}, { strategy: "smooth" });
+		}
+	}
+	/** A connector-produced node, tagged with the id of the extension that produced it (provenance). */
+	_resolvers = Atom.family((id) => {
+		return Atom.make((get) => {
+			return Function.pipe(get(this._extensions), Record.values, Array$1.sortBy(Position.compare), Array$1.map(({ resolver }) => resolver), Array$1.filter(isNonNullable), Array$1.map((resolver) => get(resolver(id))), Array$1.filter(isNonNullable), Array$1.head);
+		});
+	});
+	_connectors = Atom.family((key) => {
+		return Atom.make((get) => {
+			const { id, relation } = relationFromConnectorKey(key);
+			const node = this._graph.node(id);
+			if (!Option.getOrElse(get(node), () => void 0)) return [];
+			const extensions = Function.pipe(get(this._extensions), Record.values, Array$1.sortBy(Position.compare), Array$1.filter((ext) => relationKey(ext.relation ?? "child") === relationKey(relation) && ext.connector != null));
+			const entries = [];
+			for (const ext of extensions) {
+				const result = get(ext.connector(node));
+				for (const nodeArg of result) entries.push({
+					extensionId: ext.id,
+					node: nodeArg
+				});
+			}
+			return entries;
+		}).pipe(Atom.withLabel(`graph-builder:connectors:${key}`));
+	});
+	_onExpand(id, relation) {
+		log("onExpand", {
+			id,
+			relation,
+			registry: getDebugName(this._registry)
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 473,
+			S: this
+		});
+		this._expandRelation(id, relation);
+		if (relation.kind === "child" && relation.direction === "outbound") expand(this._graph, id, "action");
+	}
+	_expandRelation(id, relation) {
+		const key = connectorKey(id, relation);
+		const connectors = this._connectors(key);
+		const cancel = this._registry.subscribe(connectors, (entries) => {
+			const extensions = this.getExtensions();
+			const grammar = this.urlGrammar;
+			const nodes = qualifyNodeArgs(id)(entries.map((entry) => entry.node)).map((node, index) => stampUrlSegment(node, extensions[entries[index].extensionId]?.url, grammar));
+			entries.forEach((entry, index) => {
+				this._recordProvenance(nodes[index], entry.extensionId);
+			});
+			const previous = this._connectorPrevious.get(key) ?? [];
+			const ids = nodes.map((n) => n.id);
+			if (ids.length === previous.length && ids.every((nodeId, idx) => nodeId === previous[idx])) {
+				const prevArgs = this._connectorPreviousArgs.get(key);
+				if (prevArgs && nodeArgsUnchanged(prevArgs, nodes)) return;
+			}
+			log("update", {
+				id,
+				relation,
+				ids
+			}, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file,
+				L: 515,
+				S: this
+			});
+			this._dirtyConnectors.set(key, {
+				nodes,
+				previous
+			});
+			this._scheduleDirtyFlush();
+		}, { immediate: true });
+		this._subscriptions.set(subscriptionKey(id, "expand", key), cancel);
+	}
+	async _onInitialize(id) {
+		log("onInitialize", { id }, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 526,
+			S: this
+		});
+		const resolver = this._resolvers(id);
+		const cancel = this._registry.subscribe(resolver, (node) => {
+			const trigger = this._initialized[id];
+			const connectorOwned = [...this._connectorPrevious.values()].some((ids) => ids.includes(id));
+			Option.match(node, {
+				onSome: (node) => {
+					if (!connectorOwned) {
+						addNodes(this._graph, [node]);
+						const parentId = getParentId(id);
+						if (parentId) addEdges(this._graph, [{
+							source: parentId,
+							target: id,
+							relation: "child"
+						}]);
+					}
+					trigger?.wake();
+				},
+				onNone: () => {
+					trigger?.wake();
+					if (!connectorOwned) removeNodes(this._graph, [id]);
+				}
+			});
+		}, { immediate: true });
+		this._subscriptions.set(subscriptionKey(id, "init"), cancel);
+	}
+	_onRemoveNode(id) {
+		this._nodeExtensions.delete(id);
+		for (const [key, cleanup] of this._subscriptions) if (primaryParts(key)[0] === id) {
+			cleanup();
+			this._subscriptions.delete(key);
+		}
+	}
+};
+/**
+* Creates a new GraphBuilder instance.
+*/
+var make = (params) => {
+	return new GraphBuilderImpl(params);
+};
+/**
+* Creates a GraphBuilder from a serialized pickle string.
+*/
+var from = (pickle, registry, urlGrammar) => {
+	if (!pickle) return make({
+		registry,
+		urlGrammar
+	});
+	const { nodes, edges } = JSON.parse(pickle);
+	return make({
+		nodes,
+		edges,
+		registry,
+		urlGrammar
+	});
+};
+/**
+* Implementation helper for addExtension.
+*/
+var addExtensionImpl = (builder, extensions) => {
+	const internal = builder;
+	flattenExtensions(extensions).forEach((extension) => {
+		const extensions = internal._registry.get(internal._extensions);
+		internal._registry.set(internal._extensions, Record.set(extensions, extension.id, extension));
+	});
+	return builder;
+};
+function addExtension(builderOrExtensions, extensions) {
+	if (extensions === void 0) {
+		const extensions = builderOrExtensions;
+		return (builder) => addExtensionImpl(builder, extensions);
+	} else return addExtensionImpl(builderOrExtensions, extensions);
+}
+/**
+* Implementation helper for removeExtension.
+*/
+var removeExtensionImpl = (builder, id) => {
+	const internal = builder;
+	const extensions = internal._registry.get(internal._extensions);
+	internal._registry.set(internal._extensions, Record.remove(extensions, id));
+	return builder;
+};
+function removeExtension(builderOrId, id) {
+	if (typeof builderOrId === "string") {
+		const id = builderOrId;
+		return (builder) => removeExtensionImpl(builder, id);
+	} else return removeExtensionImpl(builderOrId, id);
+}
+/**
+* Implementation helper for explore.
+*/
+var exploreImpl = async (builder, options, path = []) => {
+	const internal = builder;
+	const { registry = Registry.make(), source = RootId, relation, visitor } = options;
+	if (path.includes(source)) return;
+	await yieldOrContinue("idle");
+	const node = registry.get(internal._graph.nodeOrThrow(source));
+	if (await visitor(node, [...path, node.id]) === false) return;
+	const nodes = Function.pipe(internal._registry.get(internal._extensions), Record.values, Array$1.map((extension) => extension.connector), Array$1.filter(isNonNullable), Array$1.flatMap((connector) => registry.get(connector(internal._graph.node(source)))), qualifyNodeArgs(source));
+	await Promise.all(nodes.map((nodeArg) => {
+		registry.set(internal._graph._node(nodeArg.id), internal._graph._constructNode(nodeArg));
+		return exploreImpl(builder, {
+			registry,
+			source: nodeArg.id,
+			relation,
+			visitor
+		}, [...path, node.id]);
+	}));
+	if (registry !== internal._registry) {
+		registry.reset();
+		registry.dispose();
+	}
+};
+function explore(builderOrOptions, optionsOrPath, path) {
+	if (typeof builderOrOptions === "object" && "visitor" in builderOrOptions) {
+		const options = builderOrOptions;
+		const path = Array$1.isArray(optionsOrPath) ? optionsOrPath : void 0;
+		return (builder) => exploreImpl(builder, options, path);
+	} else return exploreImpl(builderOrOptions, optionsOrPath, path ?? (Array$1.isArray(optionsOrPath) ? optionsOrPath : void 0));
+}
+/**
+* Implementation helper for destroy.
+*/
+var destroyImpl = (builder) => {
+	const internal = builder;
+	internal._subscriptions.forEach((unsubscribe) => unsubscribe());
+	internal._subscriptions.clear();
+};
+function destroy(builder) {
+	if (builder === void 0) return (builder) => destroyImpl(builder);
+	else return destroyImpl(builder);
+}
+/**
+* Wait for all pending connector updates to be flushed.
+*/
+var flush = (builder) => {
+	return builder._flushPromise;
+};
+/**
+* Whether a graph 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.
+*
+* An extension with an invalid id is dropped rather than rejected, so a single
+* malformed contribution cannot crash plugin activation.
+*
+* @example Valid:   'about', 'devtools', 'integrationsSection'
+* @example Invalid: 'integration-article', 'plugin-spec'
+*/
+var isValidLocalId = (id) => /^[a-zA-Z][a-zA-Z0-9]*$/.test(id.split(".").pop() ?? "");
+/**
+* Create a graph builder extension (low-level API that works directly with Atoms).
+*/
+var createExtensionRaw = (extension) => {
+	const { id, position, relation = "child", url, resolver: _resolver, connector: _connector, actions: _actions, actionGroups: _actionGroups } = extension;
+	if (!isValidLocalId(id)) {
+		log.warn("dropping graph extension with invalid id; the final segment must be camelCase (no hyphens or underscores)", { id }, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 815,
+			S: void 0
+		});
+		return [];
+	}
+	const normalizedRelation = normalizeRelation(relation);
+	const getId = (key) => `${id}/${key}`;
+	const resolver = _resolver && Atom.family((id) => _resolver(id).pipe(Atom.withLabel(`graph-builder:_resolver:${id}`)));
+	const connector = _connector && Atom.family((node) => _connector(node).pipe(Atom.withLabel(`graph-builder:_connector:${id}`)));
+	const actionGroups = _actionGroups && Atom.family((node) => _actionGroups(node).pipe(Atom.withLabel(`graph-builder:_actionGroups:${id}`)));
+	const actions = _actions && Atom.family((node) => _actions(node).pipe(Atom.withLabel(`graph-builder:_actions:${id}`)));
+	const extensions = [
+		resolver ? {
+			id: getId("resolver"),
+			position,
+			resolver
+		} : void 0,
+		connector ? {
+			id: getId("connector"),
+			position,
+			relation: normalizedRelation,
+			url,
+			connector: Atom.family((node) => Atom.make((get) => {
+				try {
+					return get(connector(node));
+				} catch (error) {
+					log.warn("Error in connector", {
+						id: getId("connector"),
+						node,
+						error
+					}, {
+						"~LogMeta": "~LogMeta",
+						F: __dxlog_file,
+						L: 860,
+						S: void 0
+					});
+					return [];
+				}
+			}).pipe(Atom.withLabel(`graph-builder:connector:${id}`)))
+		} : void 0,
+		actionGroups ? {
+			id: getId("actionGroups"),
+			position,
+			relation: actionRelation(),
+			connector: Atom.family((node) => Atom.make((get) => {
+				try {
+					return get(actionGroups(node)).map((arg) => ({
+						...arg,
+						data: actionGroupSymbol,
+						type: ActionGroupType
+					}));
+				} catch (error) {
+					log.warn("Error in actionGroups", {
+						id: getId("actionGroups"),
+						node,
+						error
+					}, {
+						"~LogMeta": "~LogMeta",
+						F: __dxlog_file,
+						L: 881,
+						S: void 0
+					});
+					return [];
+				}
+			}).pipe(Atom.withLabel(`graph-builder:connector:actionGroups:${id}`)))
+		} : void 0,
+		actions ? {
+			id: getId("actions"),
+			position,
+			relation: actionRelation(),
+			connector: Atom.family((node) => Atom.make((get) => {
+				try {
+					return get(actions(node)).map((arg) => ({
+						...arg,
+						type: ActionType
+					}));
+				} catch (error) {
+					log.warn("Error in actions", {
+						id: getId("actions"),
+						node,
+						error
+					}, {
+						"~LogMeta": "~LogMeta",
+						F: __dxlog_file,
+						L: 898,
+						S: void 0
+					});
+					return [];
+				}
+			}).pipe(Atom.withLabel(`graph-builder:connector:actions:${id}`)))
+		} : void 0
+	].filter(isNonNullable);
+	if (extensions.length === 0 && url) return [{
+		id,
+		position,
+		relation: normalizedRelation,
+		url
+	}];
+	return extensions;
+};
+/**
+* Run an Effect synchronously with the provided context.
+* Defects are caught, logged, and the fallback value is returned.
+* @internal
+*/
+var runEffectSyncWithFallback = (effect, context, extensionId, fallback) => {
+	return Effect.runSync(effect.pipe(Effect.provide(context), Effect.catchAllDefect((defect) => {
+		log.warn("Extension failed", {
+			extension: extensionId,
+			defect
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 959,
+			S: void 0
+		});
+		return Effect.succeed(fallback);
+	})));
+};
+/**
+* Create a graph builder extension with simplified API.
+* Returns an Effect to allow callbacks to access services via dependency injection.
+*/
+var createExtension = (options) => Effect.map(Effect.context(), (context) => {
+	const { id, match, actions, actionGroups, connector, resolver, relation, position, url } = options;
+	const connectorExtension = connector ? createConnectorWithRuntime(id, match, connector, context) : void 0;
+	return createExtensionRaw({
+		id,
+		relation,
+		position,
+		url,
+		resolver: resolver ? (nodeId) => Atom.make((get) => runEffectSyncWithFallback(resolver(nodeId, get), context, id, null) ?? null) : void 0,
+		connector: connectorExtension,
+		actions: actions ? (node) => Atom.make((get) => Function.pipe(get(node), Option.flatMap((matchedNode) => match(matchedNode, get)), Option.map((matched) => runEffectSyncWithFallback(actions(matched, get), context, id, []).map((action) => ({
+			...action,
+			_actionContext: context
+		}))), Option.getOrElse(() => []))) : void 0,
+		actionGroups: actionGroups ? (node) => Atom.make((get) => Function.pipe(get(node), Option.flatMap((matchedNode) => match(matchedNode, get)), Option.map((matched) => runEffectSyncWithFallback(actionGroups(matched, get), context, id, []).map((group) => ({
+			...group,
+			actions: group.actions?.map((action) => ({
+				...action,
+				_actionContext: context
+			}))
+		}))), Option.getOrElse(() => []))) : void 0
+	});
+});
+/**
+* Create a connector extension from a matcher and factory function.
+* The factory's data type is inferred from the matcher's return type.
+*/
+var createConnector = (matcher, factory) => {
+	return (node) => Atom.make((get) => Function.pipe(get(node), Option.flatMap((matchedNode) => matcher(matchedNode, get)), Option.map((data) => factory(data, get)), Option.getOrElse(() => [])));
+};
+/**
+* Create a connector extension from a matcher and factory function with Effect support.
+* The factory must return an Effect. Errors are caught and logged.
+* @internal
+*/
+var createConnectorWithRuntime = (extensionId, matcher, factory, context) => {
+	return (node) => Atom.make((get) => Function.pipe(get(node), Option.flatMap((matchedNode) => matcher(matchedNode, get)), Option.map((data) => runEffectSyncWithFallback(factory(data, get), context, extensionId, [])), Option.getOrElse(() => [])));
+};
+/**
+* Create an extension that matches nodes by schema type.
+* The entity type is inferred from the schema type and works for both object and relation schemas.
+* Returns an Effect to allow callbacks to access services via dependency injection.
+*/
+var createTypeExtension = (options) => {
+	const { id, type, actions, actionGroups, connector, relation, position } = options;
+	return createExtension({
+		id,
+		match: whenEchoType(type),
+		actions,
+		actionGroups,
+		connector,
+		relation,
+		position
+	});
+};
+/**
+* Qualify node IDs by prefixing with the parent path.
+* Validates that segment IDs do not contain the path separator.
+* Recursively qualifies inline child nodes.
+*/
+var qualifyNodeArgs = (parentId) => (nodes) => nodes.map((node) => {
+	validateSegmentId(node.id);
+	const qualified = qualifyId(parentId, node.id);
+	return {
+		...node,
+		id: qualified,
+		nodes: node.nodes ? qualifyNodeArgs(qualified)(node.nodes) : void 0,
+		actions: node.actions ? qualifyNodeArgs(qualified)(node.actions) : void 0
+	};
+});
+/**
+* Recursively collect all inline-descendant IDs (the `nodes` arrays at every level)
+* from a list of top-level NodeArgs. Top-level IDs are excluded because they are
+* already tracked via `_connectorPrevious`.
+*/
+var collectAllInlineIds = (nodes) => nodes.flatMap((node) => {
+	const childNodes = node.nodes ?? [];
+	const actionNodes = node.actions ?? [];
+	const allInline = [...childNodes, ...actionNodes];
+	return allInline.length > 0 ? [...allInline.map((child) => child.id), ...collectAllInlineIds(allInline)] : [];
+});
+var connectorKey = (id, relation) => primaryKey(id, relationKey(relation));
+var relationFromConnectorKey = (key) => {
+	const [id, encodedRelation] = primaryParts(key);
+	return {
+		id,
+		relation: relationFromKey(encodedRelation)
+	};
+};
+var subscriptionKey = (id, kind, detail) => detail != null ? primaryKey(id, kind, detail) : primaryKey(id, kind);
+var flattenExtensions = (extension, acc = []) => {
+	if (Array$1.isArray(extension)) return [...acc, ...extension.flatMap((ext) => flattenExtensions(ext, acc))];
+	else return [...acc, extension];
+};
+//#endregion
+export { urlRepresentation as a, getConnections as c, getParentId as d, getSegmentId as f, __exportAll as g, node_exports as h, make as i, getNode as l, RootId as m, flush as n, node_matcher_exports as o, qualifyId as p, graph_builder_exports as r, expand as s, addExtension as t, graph_exports as u };
+
+//# sourceMappingURL=chunk-graph-builder.mjs.map