@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/prop-surface.d.ts

@@ -0,0 +1,132 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/prop-surface.d.ts
+/** What a prop IS — the config's own prop types, and nothing invented. */
+type SurfacePropKind = 'variant' | 'styleProperty' | 'composite' | 'motion' | 'slot' | 'string' | 'number' | 'boolean';
+interface SurfacePropBase {
+  readonly name: string;
+  readonly required: boolean;
+}
+interface SurfaceVariantProp extends SurfacePropBase {
+  readonly kind: 'variant';
+  /** The values it offers, as the leaves a consumer authors. */
+  readonly values: string[];
+  /** An icon LIBRARY the values delegate to, when the domain is the group itself — a surface
+   *  offers the glyph picker rather than a select over every member. A FACET ref
+   *  (`icon:phosphor#variants`) stays a plain list: its leaves are the group node's own field
+   *  values, a menu-sized set. Mirrors {@link SurfaceSlotProp.acceptsIconLibrary}. */
+  readonly iconLibrary?: string;
+}
+interface SurfaceStylePropertyProp extends SurfacePropBase {
+  readonly kind: 'styleProperty';
+  /** The style property this prop writes through. */
+  readonly styleProperty: string;
+}
+interface SurfaceCompositeProp extends SurfacePropBase {
+  readonly kind: 'composite';
+  readonly compositeName: string;
+}
+interface SurfaceScalarProp extends SurfacePropBase {
+  readonly kind: 'string' | 'number' | 'boolean' | 'motion';
+}
+interface SurfaceSlotProp extends SurfacePropBase {
+  readonly kind: 'slot';
+  /** Declared a TEXT surface — content typed in place rather than dropped into. */
+  readonly text: boolean;
+  /** The layer this routes into, when it targets one. */
+  readonly targetLayer?: string;
+  /** The prop on that layer's element it arrives as (`children` unless stated). */
+  readonly into?: string;
+  /** Components this slot may be filled with (`accepts`), as paths. Empty when unconstrained. */
+  readonly accepts: string[];
+  /** The icon library this slot accepts, when `accepts` names one — the picker offers its glyphs
+   *  beside any accepted components. The library is the group the glyphs live in; Studio labels it
+   *  the slot's icon set. */
+  readonly acceptsIconLibrary?: string;
+  /** What the prop on the other end of the routing is, when this slot targets a layer. Absent for an
+   *  open slot (content the render places itself). */
+  readonly valueKind?: SurfacePropKind;
+  /** That prop's own value domain, for the kinds that have one. */
+  readonly valueOptions?: string[];
+  /** That prop's composite, when it forwards into one. */
+  readonly compositeName?: string;
+}
+type SurfaceProp = SurfaceVariantProp | SurfaceStylePropertyProp | SurfaceCompositeProp | SurfaceScalarProp | SurfaceSlotProp;
+/** A prop declaration, as far as this reads it. An index signature because `propValueDomain` takes a
+ *  declaration as an open record — it resolves the domain off `type`/`value` generically. */
+interface PropDecl extends Record<string, unknown> {
+  type?: string;
+  value?: unknown;
+  required?: boolean;
+  target?: unknown;
+  into?: string;
+  text?: boolean;
+  accepts?: unknown;
+}
+/**
+ * The prop a slot routes INTO, resolved through the layer it targets: the layer's element is a
+ * component, and `into` names one of that component's props. `undefined` when the slot targets
+ * nothing, when the layer renders a bare tag (which declares no props), or when the named prop isn't
+ * one that component exposes.
+ */
+/**
+ * The prop name a route addresses, whichever spelling `into` is in.
+ *
+ * A NAME between the schema's target split and registration; a MEMBER REF once `storedForward` has
+ * minted one (`component:Input#props/disabled`), which is the form that puts the edge in the dependency
+ * graph. Readers want the name either way, and `'children'` is the default a content route means.
+ */
+declare function intoName(into: unknown): string;
+/**
+ * The prop a route ROUTES INTO — the declaration at `<layer>/<prop>`, reached through the layer's
+ * element.
+ *
+ * `undefined` when the layer's element is a TAG rather than a component: a tag's props are the DOM's and
+ * there is no declaration to resolve. That is not a failure, and {@link routesContent} reads it as one
+ * of the two answers it needs.
+ */
+declare function routedPropIn(config: Config, layers: Readonly<Record<string, unknown>> | undefined, decl: {
+  target?: unknown;
+  into?: unknown;
+}): PropDecl | undefined;
+/** {@link routedPropIn} for a component the config already holds. The layers are what the resolution
+ *  needs; a path is the convenience for a caller that has one instead. */
+declare function routedProp(config: Config, componentPath: string, decl: {
+  target?: unknown;
+  into?: unknown;
+}): PropDecl | undefined;
+declare function routesContent(config: Config, layers: Readonly<Record<string, unknown>> | undefined, decl: {
+  target?: unknown;
+  into?: unknown;
+}): boolean;
+/**
+ * Every prop a component exposes, in declaration order, projected for a control surface.
+ *
+ * A `motion` prop is included as a scalar so it can't silently disappear from a surface that lists
+ * what a component accepts; a caller with no editor for it can fall back to a generic one.
+ */
+declare function surfaceProps(config: Config, componentPath: string, /** Forwards already followed, so a routing loop terminates. Internal — callers pass nothing. */
+
+seen?: ReadonlySet<string>): SurfaceProp[];
+/** One prop by name, or `undefined` when the component doesn't expose it. */
+declare function surfaceProp(config: Config, componentPath: string, name: string): SurfaceProp | undefined;
+/**
+ * Each non-root layer a component forwards to, and the sorted prop names each one receives — the
+ * emitter's view, which writes a literal key set per layer. Root is absent on purpose: it takes
+ * whatever is left, which every emitter already gives it unconditionally.
+ */
+declare function forwardedLayers(config: Config, componentPath: string): Map<string, string[]>;
+/**
+ * Who delivers each name a consumer can pass to this component: the component's own declaration, or
+ * the layer whose `forwards` entry exposes it. Root is included, since a picker attributing a claim
+ * needs to name root as a claimer; `forwardedLayers` is the emitter's view and leaves root out.
+ */
+interface ForwardClaims {
+  /** Names declared in the component's own `props`. A forward of one of these never reaches a consumer. */
+  readonly own: ReadonlySet<string>;
+  /** Forwarded name → the layer whose entry delivers it. The first entry in key order wins an overlap. */
+  readonly forwarded: ReadonlyMap<string, string>;
+}
+declare function forwardClaims(config: Config, componentPath: string): ForwardClaims;
+//#endregion
+export { ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };

package/dist/framework/prop-surface.js

@@ -0,0 +1,278 @@
+import { isRef, kindOf, memberOf, pathOf } from "./utils/refs.js";
+import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
+import { propValueDomain, resolveComponentProps } from "./projections.js";
+import { Component } from "../entities/system/Component.js";
+//#region src/framework/prop-surface.ts
+/**
+* A component's public API, projected for a surface that has to render a CONTROL per prop.
+*
+* The config states each prop as a declaration keyed by name — its type, and what it delegates its
+* value domain to. A control needs one more thing the declarations only imply: for a SLOT that routes
+* into a layer, *what does the prop on the other end accept?* A `label` slot targeting a Text layer's
+* `children` is a text input; one targeting a Pressable layer's `variant` is a select over that
+* component's variant values. So the routing is resolved here, once, and callers switch on the answer
+* instead of re-walking layers per control — which is the whole reason this is a projection rather
+* than each surface reading `props` itself.
+*
+* Everything else is a straight read: `resolveComponentProps` merges what a component exposes through
+* `forwards`, and `propValueDomain` answers what each prop accepts — including a prop that DELEGATES
+* its domain (an icon prop drawing its names from the icon library rather than copying them in),
+* which is why value lists are never read straight off `value`.
+*/
+/** The tail of a ref, when the value is one. */
+function refPath(value) {
+	return isRef(value) ? pathOf(value.__ref) : void 0;
+}
+/** Every ref in an `accepts` declaration (one, or a list). */
+function acceptsRefs(accepts) {
+	return (Array.isArray(accepts) ? accepts : [accepts]).filter(isRef).map((ref) => ref.__ref);
+}
+/**
+* The icon library a variant's value domain delegates to, when the domain is
+* the GROUP itself (`icon:phosphor` — one leaf per glyph). A facet ref keeps
+* its `#field` marker and is not a library: its leaves are the group node's
+* own field values, which a plain list control serves fine. A ref at one ITEM
+* (`icon:phosphor/StarIcon`) is a single-leaf domain, not a library either.
+*/
+function variantIconLibrary(config, value) {
+	if (!isRef(value) || kindOf(value) !== "icon") return void 0;
+	if (memberOf(value) !== void 0) return void 0;
+	const path = pathOf(value);
+	if (config.resolve("icon", path)) return void 0;
+	return path;
+}
+/**
+* The prop a slot routes INTO, resolved through the layer it targets: the layer's element is a
+* component, and `into` names one of that component's props. `undefined` when the slot targets
+* nothing, when the layer renders a bare tag (which declares no props), or when the named prop isn't
+* one that component exposes.
+*/
+/**
+* The prop name a route addresses, whichever spelling `into` is in.
+*
+* A NAME between the schema's target split and registration; a MEMBER REF once `storedForward` has
+* minted one (`component:Input#props/disabled`), which is the form that puts the edge in the dependency
+* graph. Readers want the name either way, and `'children'` is the default a content route means.
+*/
+function intoName(into) {
+	if (typeof into === "string") return into;
+	if (!isRef(into)) return "children";
+	const member = memberOf(into) ?? into.__ref;
+	return member.slice(member.indexOf("/") + 1);
+}
+/**
+* The prop a route ROUTES INTO — the declaration at `<layer>/<prop>`, reached through the layer's
+* element.
+*
+* `undefined` when the layer's element is a TAG rather than a component: a tag's props are the DOM's and
+* there is no declaration to resolve. That is not a failure, and {@link routesContent} reads it as one
+* of the two answers it needs.
+*/
+function routedPropIn(config, layers, decl) {
+	const layerKey = refPath(decl.target);
+	if (!layerKey) return void 0;
+	const target = refPath(layers?.[layerKey]);
+	if (!target) return void 0;
+	return resolveComponentProps(config, target)[intoName(decl.into)];
+}
+/** {@link routedPropIn} for a component the config already holds. The layers are what the resolution
+*  needs; a path is the convenience for a caller that has one instead. */
+function routedProp(config, componentPath, decl) {
+	const body = Component.get(config, componentPath)?.toJSON();
+	return routedPropIn(config, body?.layers, decl);
+}
+function routesContent(config, layers, decl) {
+	const routed = routedPropIn(config, layers, decl);
+	if (routed) return routed.type === "slot";
+	return refPath(decl.target) !== void 0 && intoName(decl.into) === "children";
+}
+function slotProp(config, componentPath, name, decl) {
+	const refs = acceptsRefs(decl.accepts);
+	const icons = refs.find((ref) => kindOf(ref) === "icon");
+	const routed = routedProp(config, componentPath, decl);
+	const routedKind = routed?.type;
+	const targetLayer = refPath(decl.target);
+	const routesIntoText = routed?.type === "slot" && routed.text === true;
+	return {
+		name,
+		kind: "slot",
+		required: decl.required === true,
+		text: decl.text === true || routesIntoText,
+		...targetLayer ? {
+			targetLayer,
+			into: decl.into ?? "children"
+		} : {},
+		accepts: refs.filter((ref) => kindOf(ref) === "component").map((ref) => pathOf(ref)),
+		...icons ? { acceptsIconLibrary: pathOf(icons) } : {},
+		...routedKind ? { valueKind: routedKind } : {},
+		...routed ? { valueOptions: propValueDomain(config, routed)?.leaves } : {},
+		...routedKind === "composite" ? { compositeName: refPath(routed?.value) } : {}
+	};
+}
+/**
+* Every prop a component exposes, in declaration order, projected for a control surface.
+*
+* A `motion` prop is included as a scalar so it can't silently disappear from a surface that lists
+* what a component accepts; a caller with no editor for it can fall back to a generic one.
+*/
+function surfaceProps(config, componentPath, seen = /* @__PURE__ */ new Set()) {
+	const declared = resolveComponentProps(config, componentPath);
+	const layers = (Component.get(config, componentPath)?.toJSON())?.layers;
+	const props = [];
+	for (const [name, decl] of Object.entries(declared)) {
+		const required = decl.required === true;
+		if (decl.type === "forward") {
+			if (routesContent(config, layers, decl)) {
+				props.push(slotProp(config, componentPath, name, decl));
+				continue;
+			}
+			const routed = boundProp(config, layers, decl, seen);
+			if (routed) props.push({
+				...routed,
+				name,
+				required
+			});
+			continue;
+		}
+		if (decl.type === "slot") {
+			props.push(slotProp(config, componentPath, name, decl));
+			continue;
+		}
+		if (decl.type === "variant") {
+			const iconLibrary = variantIconLibrary(config, decl.value);
+			props.push({
+				name,
+				kind: "variant",
+				required,
+				values: propValueDomain(config, decl)?.leaves ?? [],
+				...iconLibrary !== void 0 ? { iconLibrary } : {}
+			});
+			continue;
+		}
+		if (decl.type === "styleProperty") {
+			const styleProperty = refPath(decl.value);
+			if (!styleProperty) continue;
+			props.push({
+				name,
+				kind: "styleProperty",
+				required,
+				styleProperty
+			});
+			continue;
+		}
+		if (decl.type === "composite") {
+			const compositeName = refPath(decl.value);
+			if (!compositeName) continue;
+			props.push({
+				name,
+				kind: "composite",
+				required,
+				compositeName
+			});
+			continue;
+		}
+		if (decl.type === "string" || decl.type === "number" || decl.type === "boolean" || decl.type === "motion") props.push({
+			name,
+			kind: decl.type,
+			required
+		});
+	}
+	return props;
+}
+/**
+* The prop a forward routes to, resolved as a surface prop of its own.
+*
+* `seen` guards a forward that routes to a forward that routes back: the chain is data, so nothing
+* stops an author writing a loop, and the surface is read on every panel render.
+*/
+function boundProp(config, layers, decl, seen) {
+	const propName = intoName(decl.into);
+	const target = isRef(decl.into) ? pathOf(decl.into) : refPath(layers?.[refPath(decl.target) ?? ""]);
+	if (!target) return void 0;
+	const key = `${target}#${propName}`;
+	if (seen.has(key)) return void 0;
+	return surfaceProps(config, target, new Set([...seen, key])).find((prop) => prop.name === propName);
+}
+/** One prop by name, or `undefined` when the component doesn't expose it. */
+function surfaceProp(config, componentPath, name) {
+	return surfaceProps(config, componentPath).find((prop) => prop.name === name);
+}
+/**
+* The one precedence walk behind {@link forwardedLayers} and {@link forwardClaims}: every name a
+* `forwards` entry exposes, attributed to the layer that delivers it.
+*
+* The other half of prop routing. {@link surfaceProps} answers what a prop IS by resolving a forward
+* THROUGH to the declaration on the far end; this answers the inverse — given a layer, which of the
+* call site's props land on it. An emitter needs that to write a literal key set per layer, and a
+* design surface needs it to say which layer an edit will actually reach.
+*
+* Two precedence rules, and both are failure modes somebody has already paid for:
+*
+*  - **Own props beat every forward, tombstones included.** A tombstone means the prop is declared
+*    GONE, not merely undeclared; treating it as absent routed the dropped prop to an inner layer at
+*    runtime even though every config projection agreed it did not exist.
+*  - **Among forwards, the first entry wins.** Validation rejects overlaps on write, but a later
+*    rename or an added prop can create one without rewriting this component, so the total
+*    resolution is implemented here rather than assumed.
+*
+* Root claims its forwarded names like any other layer, so a later layer cannot also receive one when
+* an overlap appears after validation.
+*
+* Lives here because prop routing is the config's to answer — the web and native emitters each had
+* their own copy of this walk, and two copies of a precedence rule is two chances for a prop to reach
+* a different layer depending on which platform you built for.
+*/
+function computeForwardClaims(config, componentPath) {
+	const body = Component.get(config, componentPath)?.toJSON();
+	const own = /* @__PURE__ */ new Set();
+	const forwarded = /* @__PURE__ */ new Map();
+	if (!body) return {
+		own,
+		forwarded,
+		rootLayer: void 0
+	};
+	const { layers = {}, props = {}, forwards } = body;
+	const [rootLayer] = rootLayerOf(layers);
+	for (const name of Object.keys(props)) own.add(name);
+	for (const [layer, entry] of Object.entries(forwardsOf({ forwards }))) {
+		const element = layers[layer];
+		if (!isRef(element)) continue;
+		const exposed = resolveComponentProps(config, pathOf(element.__ref));
+		const names = entry === "*" ? Object.keys(exposed) : (Array.isArray(entry) ? entry : []).map((ref) => isRef(ref) ? memberOf(ref)?.split("/").pop() : void 0).filter((name) => !!name && name in exposed);
+		for (const name of names) {
+			if (own.has(name) || forwarded.has(name)) continue;
+			forwarded.set(name, layer);
+		}
+	}
+	return {
+		own,
+		forwarded,
+		rootLayer
+	};
+}
+/**
+* Each non-root layer a component forwards to, and the sorted prop names each one receives — the
+* emitter's view, which writes a literal key set per layer. Root is absent on purpose: it takes
+* whatever is left, which every emitter already gives it unconditionally.
+*/
+function forwardedLayers(config, componentPath) {
+	const { forwarded, rootLayer } = computeForwardClaims(config, componentPath);
+	const out = /* @__PURE__ */ new Map();
+	for (const [name, layer] of forwarded) {
+		if (layer === rootLayer) continue;
+		const names = out.get(layer);
+		if (names) names.push(name);
+		else out.set(layer, [name]);
+	}
+	for (const names of out.values()) names.sort();
+	return out;
+}
+function forwardClaims(config, componentPath) {
+	const { own, forwarded } = computeForwardClaims(config, componentPath);
+	return {
+		own,
+		forwarded
+	};
+}
+//#endregion
+export { forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };

package/dist/framework/ref-graph.d.ts

@@ -0,0 +1,71 @@
+import { Ref } from "./utils/refs.js";
+
+//#region src/framework/ref-graph.d.ts
+/** One entity to index: its own `kind:path` ref, and the data to harvest refs from. */
+interface RefGraphEntry {
+  readonly ref: string;
+  readonly data: unknown;
+  /**
+   * Edges this entity's data implies by NAME rather than by ref — a style bag keyed `bg` depends on
+   * `style-property:bg`, and no `{ __ref }` says so.
+   *
+   * Supplied by the caller (a kind declares how to read its own names — see `EntityKind.nameEdges`)
+   * because nothing generic can find identity in a KEY. Kept a PURE function of the entity's own
+   * data, which is what lets these edges ride the same incremental update as the ref-borne ones: an
+   * edge that needed another kind's state to compute would go stale whenever that state moved and
+   * this entity didn't.
+   */
+  readonly extra?: readonly string[];
+}
+interface TraverseOptions {
+  /** Follow chains rather than stopping at direct edges (default false). */
+  readonly transitive?: boolean;
+}
+/** A node to ask about: the entity's own ref (`Token.ref('color/brand')`) or its string form.
+ *  Taking the ref itself means a caller names an entity the way it names one everywhere else. */
+type RefTarget = string | Ref;
+interface RefGraph {
+  /** Entities that point AT `target` — what breaks if it changes or goes away. */
+  dependents(target: RefTarget, opts?: TraverseOptions): string[];
+  /** Entities `target` points at — what it needs in order to resolve. */
+  dependencies(target: RefTarget, opts?: TraverseOptions): string[];
+  /**
+   * The shortest dependency chain `from` → … → `to`, inclusive of both ends, or `undefined` when
+   * `from` doesn't reach `to`. This is what turns "42 things affected" into a sentence a person can
+   * act on: `token:color/brand → modifier:dark → mode:colorMode/dark`.
+   */
+  path(from: RefTarget, to: RefTarget): string[] | undefined;
+}
+/**
+ * The raw two-way index behind a {@link RefGraph} — separated from the query facade so it can be
+ * carried on an immutable `Snapshot` and UPDATED for the handful of entities a patch touched,
+ * instead of rebuilt by a full pass over every item on each mutation.
+ */
+interface RefIndex {
+  /** `ref` → the refs it points at. */
+  readonly out: ReadonlyMap<string, ReadonlySet<string>>;
+  /** `ref` → the refs pointing at it. */
+  readonly incoming: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/** One entity's edges changing — `data: undefined` means the entity went away. */
+interface RefIndexChange {
+  readonly ref: string;
+  readonly data: unknown | undefined;
+  /** Name-borne edges for the new data — see {@link RefGraphEntry.extra}. */
+  readonly extra?: readonly string[];
+}
+/** Index `entries` in both directions. Pure — callers memoize (see `Snapshot.refs`). */
+declare function buildRefIndex(entries: readonly RefGraphEntry[], linkKinds?: readonly string[], singletonKinds?: readonly string[]): RefIndex;
+/**
+ * Re-index only the entities in `changes`, returning a new index that shares nothing mutable with
+ * the old one. The top-level maps are copied per CALL (a batch), and only the edge sets actually
+ * touched are copied — so the deep `collectRefs` walk, which is the expensive part, runs for the
+ * changed entities alone rather than for the whole config.
+ */
+declare function updateRefIndex(index: RefIndex, changes: readonly RefIndexChange[], linkKinds?: readonly string[], singletonKinds?: readonly string[]): RefIndex;
+/** The query facade over a built index — the shape every consumer asks questions through. */
+declare function refGraphOf(index: RefIndex): RefGraph;
+/** Build and query in one step — for a caller with no snapshot to carry the index on. */
+declare function buildRefGraph(entries: readonly RefGraphEntry[]): RefGraph;
+//#endregion
+export { RefGraph, RefGraphEntry, RefIndex, RefIndexChange, RefTarget, TraverseOptions, buildRefGraph, buildRefIndex, refGraphOf, updateRefIndex };

package/dist/framework/ref-graph.js

@@ -0,0 +1,158 @@
+import { collectRefs, entityRefOf, isRef, kindOf, singletonRef, sourceOf } from "./utils/refs.js";
+//#region src/framework/ref-graph.ts
+/**
+* The reference graph — every `{ __ref }` in the config, indexed both ways.
+*
+* `collectRefs` already harvests an entity's outgoing edges generically, so the graph needs no
+* per-entity wiring; this just runs it over every item once and keeps both directions. That one
+* index answers the questions each surface asks separately today: what breaks if I delete this
+* (dependents), what does this pull in (dependencies), and — because renames and deletes have to be
+* explained, not just counted — the CHAIN between two entities.
+*
+* Traversal is transitive on request: an edge chain like `token → modifier → mode` is the norm once
+* an entity can point at another that points on, so "which tokens vary in dark mode" is a closure
+* question, not a one-hop one.
+*
+* A MEMBER ref (`component:Pressable#props/gap`) is indexed under both its own form and its
+* entity's, so a lookup by either resolves; traversal normalizes to the entity, since only entities
+* have data to walk on from.
+*/
+/** A target's string form — the key both indexes are built on. */
+const key = (target) => isRef(target) ? target.__ref : target;
+/** The refs `data` points at plus any name-borne ones, minus self-references (never a dependency). */
+function edgesOf(ref, data, extra = [], linkKinds = [], singletonKinds = []) {
+	const collected = collectRefs(data);
+	const targets = new Set(collected);
+	if (singletonKinds.length > 0) for (const target of collected) {
+		if (!singletonKinds.includes(kindOf(target))) continue;
+		const canonical = singletonRef(target);
+		if (canonical === target) continue;
+		targets.add(entityRefOf(canonical));
+		targets.add(canonical);
+	}
+	if (linkKinds.length > 0) for (const target of collected) {
+		const slug = sourceOf(target);
+		if (slug === void 0) continue;
+		for (const kind of linkKinds) targets.add(`${kind}:${slug}`);
+	}
+	for (const target of extra) targets.add(target);
+	targets.delete(ref);
+	return targets;
+}
+function link(index, from, to) {
+	const set = index.get(from) ?? /* @__PURE__ */ new Set();
+	set.add(to);
+	index.set(from, set);
+}
+/** Index `entries` in both directions. Pure — callers memoize (see `Snapshot.refs`). */
+function buildRefIndex(entries, linkKinds = [], singletonKinds = []) {
+	const out = /* @__PURE__ */ new Map();
+	const incoming = /* @__PURE__ */ new Map();
+	for (const { ref, data, extra } of entries) for (const target of edgesOf(ref, data, extra, linkKinds, singletonKinds)) {
+		link(out, ref, target);
+		link(incoming, target, ref);
+	}
+	return {
+		out,
+		incoming
+	};
+}
+/**
+* Re-index only the entities in `changes`, returning a new index that shares nothing mutable with
+* the old one. The top-level maps are copied per CALL (a batch), and only the edge sets actually
+* touched are copied — so the deep `collectRefs` walk, which is the expensive part, runs for the
+* changed entities alone rather than for the whole config.
+*/
+function updateRefIndex(index, changes, linkKinds = [], singletonKinds = []) {
+	if (changes.length === 0) return index;
+	const out = /* @__PURE__ */ new Map();
+	for (const [node, set] of index.out) out.set(node, set);
+	const incoming = /* @__PURE__ */ new Map();
+	for (const [node, set] of index.incoming) incoming.set(node, set);
+	/** Copy-on-write a single edge set, so sets shared with the previous index are never mutated. */
+	const mutable = (map, node) => {
+		const next = new Set(map.get(node));
+		map.set(node, next);
+		return next;
+	};
+	for (const { ref, data, extra } of changes) {
+		for (const target of index.out.get(ref) ?? []) {
+			const back = mutable(incoming, target);
+			back.delete(ref);
+			if (back.size === 0) incoming.delete(target);
+		}
+		out.delete(ref);
+		if (data === void 0) continue;
+		const targets = edgesOf(ref, data, extra, linkKinds, singletonKinds);
+		if (targets.size === 0) continue;
+		out.set(ref, targets);
+		for (const target of targets) mutable(incoming, target).add(ref);
+	}
+	return {
+		out,
+		incoming
+	};
+}
+/** The query facade over a built index — the shape every consumer asks questions through. */
+function refGraphOf(index) {
+	const { out, incoming } = index;
+	/** Outgoing edges of a node — a member ref has none of its own, so read its entity's. */
+	const edgesOut = (node) => out.get(node) ?? out.get(entityRefOf(node));
+	const walk = (start, step) => {
+		const seen = /* @__PURE__ */ new Set();
+		const queue = [start];
+		while (queue.length) {
+			const node = queue.shift();
+			for (const next of step(node) ?? []) {
+				if (seen.has(next)) continue;
+				seen.add(next);
+				queue.push(next);
+			}
+		}
+		seen.delete(start);
+		return [...seen];
+	};
+	return {
+		dependents(target, opts) {
+			const node = key(target);
+			if (!opts?.transitive) return [...incoming.get(node) ?? []];
+			return walk(node, (at) => incoming.get(at));
+		},
+		dependencies(target, opts) {
+			const node = key(target);
+			if (!opts?.transitive) return [...edgesOut(node) ?? []];
+			return walk(node, edgesOut);
+		},
+		path(fromTarget, toTarget) {
+			const from = key(fromTarget);
+			const to = key(toTarget);
+			if (from === to) return [from];
+			const cameFrom = new Map([[from, from]]);
+			const queue = [from];
+			while (queue.length) {
+				const node = queue.shift();
+				for (const next of edgesOut(node) ?? []) {
+					if (cameFrom.has(next)) continue;
+					cameFrom.set(next, node);
+					if (next === to) {
+						const chain = [next];
+						let step = node;
+						while (step !== from) {
+							chain.unshift(step);
+							step = cameFrom.get(step);
+						}
+						chain.unshift(from);
+						return chain;
+					}
+					queue.push(next);
+				}
+			}
+		}
+	};
+}
+/** Build and query in one step — for a caller with no snapshot to carry the index on. */
+function buildRefGraph(entries) {
+	return refGraphOf(buildRefIndex(entries));
+}
+//#endregion
+export { buildRefGraph, buildRefIndex, refGraphOf, updateRefIndex };