@yahoo/uds-create-config 1.1.1

package/dist/Config.js

@@ -0,0 +1,1429 @@
+import "./brands.js";
+import "./entity-utils.js";
+import { AssetGroup } from "./AssetGroup.js";
+import { attachSourcePath } from "./captureCallerPath.js";
+import { isAssetGroupRef, isModeRef, isTokenRef } from "./refs.js";
+import { ASSET_GROUP_SLUG_KEY, readAssetGroupSlug } from "./defineAssetGroup.js";
+import { FOREIGN_NAMESPACE } from "./foreign-component-name.js";
+import { Component, assertDefinitionAcceptsPlaceable } from "./Component.js";
+import { ComponentGroup } from "./ComponentGroup.js";
+import { CompositeStyle } from "./CompositeStyle.js";
+import { Mode } from "./Mode.js";
+import { Modifier } from "./Modifier.js";
+import { CssMotionDef, JsMotionDef } from "./MotionDef.js";
+import { Provider } from "./Provider.js";
+import { StyleProp } from "./StyleProp.js";
+import { TokenGroup } from "./TokenGroup.js";
+//#region src/Config.ts
+/**
+* `Config` — top-level container for a UDS design system.
+*
+* Authored data lives on bare properties (Maps for collections, scalars
+* for prefix/preflight). Derived data lives under `.derived`, a memoized
+* lazy getter rebuilt whenever a `register*` chain method runs. The
+* single dot to `.derived` is the boundary between "stored" and
+* "computed"; consumers can tell at a glance which side of the line
+* they're reading.
+*/
+/** Compile-time exhaustiveness backstop for the `dependentsOf`/`dependenciesOf`
+*  switches: once every kind is handled, `query` narrows to `never` here; a new,
+*  unhandled kind makes the call a type error at the `default` branch. */
+function assertNever(value) {
+	throw new Error(`Unhandled dependency kind: ${JSON.stringify(value)}`);
+}
+var Config = class Config {
+	static SCHEMA_VERSION = 1;
+	prefix = "uds";
+	/**
+	* Registry namespace — a stable, `package.json`-style identifier
+	* (`uds`, `@acme/system`) that namespaces every component's
+	* `registryKey` as `<namespace>:<ComponentName>` (the spec `type`).
+	* Declared in `uds.config.ts` via `configure({ namespace })` so it's
+	* available at build time; the push pipeline validates it for
+	* uniqueness / ownership. `undefined` ⇒ components keep bare-name
+	* registry keys. See Linear doc "RFC: Registry-namespaced component
+	* types".
+	*/
+	namespace;
+	preflight = true;
+	globalStyles = {};
+	rawCss = [];
+	designPrinciples = [];
+	buildOptions = {};
+	tokenGroups = /* @__PURE__ */ new Map();
+	styleProps = /* @__PURE__ */ new Map();
+	modifiers = /* @__PURE__ */ new Map();
+	modes = /* @__PURE__ */ new Map();
+	compositeStyles = /* @__PURE__ */ new Map();
+	components = /* @__PURE__ */ new Map();
+	componentGroups = /* @__PURE__ */ new Map();
+	assetGroups = /* @__PURE__ */ new Map();
+	providers = /* @__PURE__ */ new Map();
+	motion = /* @__PURE__ */ new Map();
+	#derived;
+	/**
+	* Set top-level config metadata in one call — the single scalar-setter,
+	* replacing the former `withPrefix` / `withPreflight` / `withName` /
+	* `withDesignPrinciples` / `withBuildOptions` chain. Partial: only
+	* provided keys are applied, so it can run once or be merged across
+	* calls. `globalStyles` stays on `defineGlobalStyles` — its callback
+	* form needs the derived token refs, so it doesn't fit a plain bag.
+	*
+	*  - `namespace` — the registry namespace (`uds`, `@acme/system`) that
+	*    namespaces every component's `registryKey` as `<namespace>:<Component>`.
+	*    Declared in `uds.config.ts` (the `package.json`-`name` model) so it's
+	*    available at build time; the push pipeline additionally validates it
+	*    for uniqueness / ownership. Throws on a structurally invalid value
+	*    (the `:` separator, whitespace, or empty).
+	*  - `prefix` — class-name + CSS-variable prefix (default `uds`); invalidates
+	*    derived. Pass `''` or `false` to opt out entirely — classes and vars
+	*    emit unprefixed (`bg-primary`, `--color-brand`). `false` is sugar for
+	*    `''`, normalized to the empty string here so the value stays a string.
+	*  - `preflight` — include Tailwind's reset (default `true`).
+	*  - `designPrinciples` — freeform strings surfaced in the AI prompt.
+	*  - `buildOptions` — shallow-merged into existing build options.
+	*/
+	configure(options) {
+		if (options.namespace !== void 0) this.namespace = validateNamespace(options.namespace);
+		if (options.prefix !== void 0) {
+			this.prefix = options.prefix === false ? "" : options.prefix;
+			this.#invalidate();
+		}
+		if (options.preflight !== void 0) this.preflight = options.preflight;
+		if (options.designPrinciples !== void 0) this.designPrinciples = [...options.designPrinciples];
+		if (options.buildOptions !== void 0) this.buildOptions = {
+			...this.buildOptions,
+			...options.buildOptions
+		};
+		return this;
+	}
+	/**
+	* Resolve a spec element `type` (or any component identifier) to its
+	* {@link Component}, namespace-aware and backwards-compatible.
+	*
+	* `components` is keyed by the bare `name`, so:
+	*  - an exact match is tried first — a bare `'Badge'` resolves directly,
+	*    keeping every existing bare-name lookup working;
+	*  - otherwise a namespaced registry key (`'<namespace>:<name>'`, the spec
+	*    `type`) resolves by its bare name **only when the namespace is this
+	*    registry's own**. A key from a different registry (`'other:Badge'`)
+	*    deliberately does not resolve, so specs from multiple registries can
+	*    coexist without colliding on a shared bare name.
+	*
+	* Returns `undefined` for unknown types and foreign (`foreign:`) sentinels.
+	* This is the single resolution path consumers should use instead of
+	* `config.components.get(type)` when `type` may be a spec/registry key.
+	*/
+	getComponent(type) {
+		const direct = this.components.get(type);
+		if (direct) return direct;
+		const { namespace, name } = parseRegistryKey(type);
+		if (namespace !== void 0 && namespace === this.namespace) return this.components.get(name);
+	}
+	/**
+	* The bare, human-readable component name for a spec `type` — strips this
+	* registry's `<namespace>:` prefix (`'uds:Text'` → `'Text'`) for display, and
+	* the `foreign:` sentinel third-party leaves carry (`'foreign:CopyIcon'` →
+	* `'CopyIcon'`) — that prefix marks "not a UDS component," not a peer system,
+	* so the bare name is what every display surface wants. A bare type, an
+	* unknown type, or a key from another *peer* registry (`@acme/system:Button`)
+	* is returned unchanged — there the prefix is meaningful disambiguation.
+	*/
+	componentDisplayName(type) {
+		const { namespace, name } = parseRegistryKey(type);
+		if (namespace === "foreign") return name;
+		return namespace !== void 0 && namespace === this.namespace ? name : type;
+	}
+	/**
+	* Components whose catalog `metadata.label` matches `label` (case-insensitive)
+	* — the display-name lookup that complements `getComponent` (registry key).
+	* Returns an array because labels aren't unique: a collision-dodging export
+	* (`StudioListItem` with `label: 'ListItem'`) can share a label with another
+	* component's key, so callers must handle 0, 1, or many. Empty when no label
+	* matches.
+	*/
+	getComponentsByLabel(label) {
+		const lower = label.toLowerCase();
+		const out = [];
+		for (const component of this.components.values()) if (component.metadata?.label?.toLowerCase() === lower) out.push(component);
+		return out;
+	}
+	/**
+	* Style props that emit a given CSS property — the reverse of
+	* `StyleProp.cssProperty`. A property can be served by more than one prop
+	* (e.g. `border-color` by `borderColor`, `divideColor`; `margin-top` by both
+	* the positive `marginTop` and the `negative` `offsetTop`). Match is exact on
+	* the CSS property name; a prop targeting several properties matches any.
+	*
+	* `negative` props are ordered LAST, so a caller taking the first match
+	* (`getStylePropsByCssProperty(css)[0]`) always gets the primary, positive
+	* prop — the negative variant is only the first result when it's the sole
+	* prop for that property. Registration order is preserved within each group.
+	*
+	* Pass `opts.negative` to filter explicitly: `{ negative: false }` for only
+	* positive props, `{ negative: true }` for only the negative variant(s) (e.g.
+	* the `offsetTop` behind `margin-top`). Omit it to get every match.
+	*/
+	getStylePropsByCssProperty(cssProperty, opts) {
+		const out = [];
+		for (const styleProp of this.styleProps.values()) {
+			const css = styleProp.cssProperty;
+			if (!(Array.isArray(css) ? css.includes(cssProperty) : css === cssProperty)) continue;
+			if (opts?.negative !== void 0 && styleProp.negative !== opts.negative) continue;
+			out.push(styleProp);
+		}
+		return out.sort((a, b) => Number(a.negative) - Number(b.negative));
+	}
+	/**
+	* Resolve the `StyleProp` behind a component's JSX prop, following any
+	* re-alias. A component can expose a style prop under a different JSX name
+	* than the registry key — `Box`'s `backgroundColor` prop binds
+	* `styleProp('bg')` — so this maps the on-component name back to the
+	* registered `StyleProp`. Returns `undefined` if the component has no such
+	* style prop.
+	*/
+	getComponentStyleProp(componentName, jsxProp) {
+		const component = this.getComponent(componentName);
+		if (!component) return void 0;
+		for (const info of component.derived.props) if (info.kind === "styleProp" && info.name === jsxProp) return this.styleProps.get(info.stylePropName);
+	}
+	/**
+	* Components that render `name` as one of their layers — the reverse of
+	* `Layer.renders`. Layer composition only; subcomponent parentage is a
+	* separate edge (`Component.derived.subcomponentOf`). The component slice of
+	* the public {@link Config.dependentsOf} read surface.
+	*/
+	#componentDependents(name) {
+		const out = [];
+		for (const component of this.components.values()) {
+			if (component.name === name) continue;
+			for (const layer of component.layers.values()) {
+				const renders = layer.renders;
+				if (renders?.kind === "component" && renders.ref === name) {
+					out.push(component.name);
+					break;
+				}
+			}
+		}
+		return out;
+	}
+	/**
+	* Components that expose a composite style as a prop (bound via
+	* `composite('<name>')`) — e.g. which components offer an `elevation`
+	* dropdown. The composite-style slice of {@link Config.dependentsOf}.
+	*/
+	#compositeStyleDependents(name) {
+		const out = [];
+		for (const component of this.components.values()) for (const info of component.derived.props) if (info.kind === "composite" && info.compositeName === name) {
+			out.push(component.name);
+			break;
+		}
+		return out;
+	}
+	/**
+	* Components that expose a given style prop. Matches on the registered
+	* style-prop key (`info.stylePropName`), not the on-component JSX name, so a
+	* component that re-aliases the prop under a different name (a
+	* `backgroundColor` prop bound to `styleProp('bg')`) is still found; `as`
+	* carries that on-component name when it differs from the registry key. The
+	* style-prop slice of {@link Config.dependentsOf} (which keeps only the
+	* component name).
+	*/
+	#stylePropDependents(name) {
+		const out = [];
+		for (const component of this.components.values()) for (const info of component.derived.props) if (info.kind === "styleProp" && info.stylePropName === name) {
+			out.push({
+				component: component.name,
+				as: info.name
+			});
+			break;
+		}
+		return out;
+	}
+	/**
+	* Style props that draw their values from a given token group — the group's
+	* "defined in" relation: a style prop references a group through its `values`
+	* array (`bg` ← `tokenGroup('color')`). Only style props reference token
+	* groups today, so the result is style-prop names; empty for an unknown
+	* group. The token-group slice of {@link Config.dependentsOf}; the *member*
+	* usage ("used in") is the separate {@link Config.getTokenGroupUsage}.
+	*/
+	#tokenGroupDependents(namespace) {
+		const group = this.tokenGroups.get(namespace);
+		return group ? [...group.derived.styleProperties] : [];
+	}
+	/**
+	* Components that reference a given token anywhere in their styling. Reads
+	* the structural `Component.derived.tokenRefs` (which captures both
+	* `token(...)` refs and shorthand style-prop values, across base / variants /
+	* compound), so the match is on token *identity*, not CSS-var or substring
+	* matching. `name` may be qualified (`color/brand`) or bare (`brand`) — a
+	* bare name matches the token part in any group. The component half of a
+	* token's referrers in {@link Config.dependentsOf}; the token half is
+	* {@link Config.#tokenTokenDependents}.
+	*/
+	#tokenComponentDependents(name) {
+		const qualified = name.includes("/");
+		const out = [];
+		for (const component of this.components.values()) {
+			const refs = component.derived.tokenRefs;
+			if (qualified ? refs.includes(name) : refs.some((ref) => ref.slice(ref.indexOf("/") + 1) === name)) out.push(component.name);
+		}
+		return out;
+	}
+	/**
+	* Other tokens that reference a given token — the "which tokens alias or
+	* mode-override this one?" lookup. Walks each token's value + modifiers for
+	* `token()` refs (the same structural channel `tokenUsageStats` counts).
+	* Returns qualified token names; `name` may be qualified or bare. Excludes
+	* self. The token half of a token's referrers in {@link Config.dependentsOf}.
+	*/
+	#tokenTokenDependents(name) {
+		const qualified = name.includes("/");
+		const out = [];
+		for (const [qualifiedName, token] of this.derived.tokens) {
+			if (qualifiedName === name) continue;
+			const refs = /* @__PURE__ */ new Set();
+			this.#collectStyleTokenRefs(token.value, refs, /* @__PURE__ */ new WeakSet());
+			if (token.modifiers) this.#collectStyleTokenRefs(token.modifiers, refs, /* @__PURE__ */ new WeakSet());
+			if (qualified ? refs.has(name) : [...refs].some((ref) => ref.slice(ref.indexOf("/") + 1) === name)) out.push(qualifiedName);
+		}
+		return out;
+	}
+	/**
+	* Every qualified token name referenced *anywhere* in the system — the
+	* "used somewhere" set. Three reference channels, so a token reached only
+	* through one of them (e.g. a raw spectrum step a semantic token aliases,
+	* never touched by a component directly) still counts as used:
+	*  - **components** — the structural `tokenRefs` union;
+	*  - **token → token** — a token's value or a mode-override referencing
+	*    another via `token()` (aliases, `_dark` swaps);
+	*  - **composite styles** — `token()` refs and shorthand values in each bag.
+	*/
+	#referencedTokenNames() {
+		const refs = /* @__PURE__ */ new Set();
+		for (const component of this.components.values()) for (const ref of component.derived.tokenRefs) refs.add(ref);
+		for (const token of this.derived.tokens.values()) {
+			this.#collectStyleTokenRefs(token.value, refs, /* @__PURE__ */ new WeakSet());
+			if (token.modifiers) this.#collectStyleTokenRefs(token.modifiers, refs, /* @__PURE__ */ new WeakSet());
+		}
+		for (const composite of this.compositeStyles.values()) for (const bag of composite.styles.values()) this.#collectStyleTokenRefs(bag, refs, /* @__PURE__ */ new WeakSet());
+		return refs;
+	}
+	/**
+	* Walk an arbitrary value (a token value, modifier map, or composite-style
+	* bag), collecting every token it references into `refs`: structured
+	* `token()` refs by identity (including ones nested in a color expression),
+	* and bare style-prop shorthand values resolved through the registry.
+	*/
+	#collectStyleTokenRefs(node, refs, seen) {
+		if (node === null || typeof node !== "object") return;
+		if (isTokenRef(node)) {
+			refs.add(node.ref);
+			return;
+		}
+		if (seen.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const item of node) this.#collectStyleTokenRefs(item, refs, seen);
+			return;
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (key.startsWith("__")) continue;
+			if (typeof value === "string") {
+				const ref = this.#resolveStylePropValueToken(key, value);
+				if (ref) refs.add(ref);
+			} else this.#collectStyleTokenRefs(value, refs, seen);
+		}
+	}
+	/**
+	* Aggregate token-usage stats across the whole registry — how many tokens
+	* are referenced *somewhere* (components, other tokens, or composite styles;
+	* see {@link Config.#referencedTokenNames}) vs not. `usagePercent` is
+	* rounded; `0` total tokens reports `0%`.
+	*/
+	tokenUsageStats() {
+		const referenced = this.#referencedTokenNames();
+		const tokens = [...this.derived.tokens.keys()];
+		const total = tokens.length;
+		const used = tokens.filter((name) => referenced.has(name)).length;
+		const usagePercent = total === 0 ? 0 : Math.round(used / total * 100);
+		return {
+			total,
+			used,
+			unused: total - used,
+			usagePercent
+		};
+	}
+	/**
+	* Token values ranked by how often they appear across component base styles —
+	* the aggregate "what's load-bearing?" companion to `dependentsOf('token')`.
+	* `opts.property` narrows to one CSS property. Descends into `_<modifier>`
+	* sub-objects so a value used only in a hover/dark state still counts.
+	*/
+	tokenValueUsage(opts) {
+		const property = opts?.property;
+		const counts = /* @__PURE__ */ new Map();
+		const collect = (styles) => {
+			for (const [prop, value] of Object.entries(styles)) if (typeof value === "string") {
+				if (property && prop.toLowerCase() !== property.toLowerCase()) continue;
+				const key = `${prop}:${value}`;
+				const existing = counts.get(key);
+				if (existing) existing.count++;
+				else counts.set(key, {
+					count: 1,
+					property: prop
+				});
+			} else if (isStyleRecord(value) && prop.startsWith("_")) collect(value);
+		};
+		for (const component of this.components.values()) {
+			if (!component.base) continue;
+			for (const styles of Object.values(component.base)) if (isStyleRecord(styles)) collect(styles);
+		}
+		return [...counts.entries()].map(([key, data]) => ({
+			value: key.slice(key.indexOf(":") + 1),
+			count: data.count,
+			property: data.property
+		})).sort((a, b) => b.count - a.count);
+	}
+	/**
+	* The reverse-dependency read surface — "what references this entity, and
+	* would break if I delete or rename it?" — uniform across every kind. One
+	* public entry point: callers dispatch by `kind` and get a single tagged
+	* list (the affected entities, each with its own kind), never a per-kind
+	* bespoke shape. The relation is always *references to the entity*; the
+	* per-kind walks behind it are private slices.
+	*
+	* A `token` resolves to BOTH the components that reference it AND the tokens
+	* that alias or mode-override it — a token's full referrer set, not split
+	* across two methods. A `modifier` flattens its components, composite styles,
+	* and token-group namespaces into the one tagged list. A token group's other
+	* relation — what actually *uses* its member tokens — is the separate
+	* {@link Config.getTokenGroupUsage} (only containers have it); ranking every
+	* entity of a kind at once is {@link Config.componentDependentCounts} & co.
+	*/
+	dependentsOf(query) {
+		switch (query.kind) {
+			case "component": return this.#componentDependents(query.name).map((name) => ({
+				kind: "component",
+				name
+			}));
+			case "compositeStyle": return this.#compositeStyleDependents(query.name).map((name) => ({
+				kind: "component",
+				name
+			}));
+			case "styleProp":
+				if (query.value === void 0) return this.#stylePropDependents(query.name).map((d) => ({
+					kind: "component",
+					name: d.component
+				}));
+				return this.#stylePropKeywordDependents(query.name, query.value).map((name) => ({
+					kind: "component",
+					name
+				}));
+			case "token": return [...this.#tokenComponentDependents(query.name).map((name) => ({
+				kind: "component",
+				name
+			})), ...this.#tokenTokenDependents(query.name).map((name) => ({
+				kind: "token",
+				name
+			}))];
+			case "tokenGroup": return this.#tokenGroupDependents(query.name).map((name) => ({
+				kind: "styleProp",
+				name
+			}));
+			case "modifier": {
+				const m = this.#modifierDependents(query.name);
+				return [
+					...m.components.map((name) => ({
+						kind: "component",
+						name
+					})),
+					...m.compositeStyles.map((name) => ({
+						kind: "compositeStyle",
+						name
+					})),
+					...m.tokenGroups.map((name) => ({
+						kind: "tokenGroup",
+						name
+					}))
+				];
+			}
+			default: return assertNever(query);
+		}
+	}
+	/**
+	* The outbound mirror of {@link Config.dependentsOf} — "what does this entity
+	* *use*, and would I have to update if I delete those?". Same tagged
+	* `DependencyRef[]` shape, same `kind`-keyed exhaustiveness. A `component`
+	* reports the tokens it references, the keyword values it sets
+	* (`{ kind: 'styleProp', name, value }`), the composites and style props it
+	* binds, the components it renders as layers, and the modifiers it styles
+	* with; a `token` reports the tokens it aliases and the modifiers in its mode
+	* overrides; a `styleProp` reports the token groups it draws from. `modifier`
+	* and `tokenGroup` are leaves here — a selector and a container don't *use*
+	* other registry entities — so they report nothing.
+	*/
+	dependenciesOf(query) {
+		switch (query.kind) {
+			case "component": return this.#componentDependencies(query.name);
+			case "token": return this.#tokenDependencies(query.name);
+			case "styleProp": {
+				const sp = this.styleProps.get(query.name);
+				if (!sp) return [];
+				return [...new Set(sp.consumedTokenGroups())].map((name) => ({
+					kind: "tokenGroup",
+					name
+				}));
+			}
+			case "compositeStyle": return this.#compositeStyleDependencies(query.name);
+			case "tokenGroup": {
+				const group = this.tokenGroups.get(query.name);
+				if (!group) return [];
+				return [...group.tokens.keys()].map((leaf) => ({
+					kind: "token",
+					name: `${query.name}/${leaf}`
+				}));
+			}
+			case "modifier": return [];
+			default: return assertNever(query);
+		}
+	}
+	/**
+	* Components that use a given style-prop *keyword* value — the "what breaks
+	* if I remove the `flex` value from `display`?" lookup, the value-narrowed
+	* slice of `dependentsOf({ kind: 'styleProp', name, value })`. Scoped to the
+	* `(styleProp, value)` pair (keywords aren't global — `col` on `flexDirection`
+	* is unrelated to `col` elsewhere), reading `derived.stylePropKeywords`.
+	*/
+	#stylePropKeywordDependents(styleProp, value) {
+		const out = [];
+		for (const component of this.components.values()) if (component.derived.stylePropKeywords.some((kw) => kw.styleProp === styleProp && kw.value === value)) out.push(component.name);
+		return out;
+	}
+	/** Outbound edges of a component — its `dependenciesOf` slice: the tokens it
+	*  references, the keyword values it sets, the composites + style props it
+	*  binds, the components it renders as layers, and the modifiers it styles
+	*  with. Deduped across those sources. */
+	#componentDependencies(name) {
+		const component = this.getComponent(name);
+		if (!component) return [];
+		const out = [];
+		const d = component.derived;
+		for (const ref of d.tokenRefs) out.push({
+			kind: "token",
+			name: ref
+		});
+		for (const kw of d.stylePropKeywords) out.push({
+			kind: "styleProp",
+			name: kw.styleProp,
+			value: kw.value
+		});
+		for (const info of d.props) if (info.kind === "composite") out.push({
+			kind: "compositeStyle",
+			name: info.compositeName
+		});
+		else if (info.kind === "styleProp") out.push({
+			kind: "styleProp",
+			name: info.stylePropName
+		});
+		for (const layer of component.layers.values()) {
+			const renders = layer.renders;
+			if (renders?.kind === "component" && renders.ref !== component.name) out.push({
+				kind: "component",
+				name: renders.ref
+			});
+		}
+		const mods = /* @__PURE__ */ new Set();
+		if (component.base) this.#collectModifierKeys(component.base, mods);
+		for (const binding of Object.values(component.props)) this.#collectModifierKeys(binding, mods);
+		for (const entry of component.compoundProps ?? []) this.#collectModifierKeys(entry.layers, mods);
+		for (const mod of mods) out.push({
+			kind: "modifier",
+			name: mod
+		});
+		return this.#dedupeRefs(out);
+	}
+	/** Outbound edges of a token — the tokens it aliases (value + mode overrides)
+	*  and the modifiers carrying those overrides. `name` must be qualified. */
+	#tokenDependencies(name) {
+		const token = this.derived.tokens.get(name);
+		if (!token) return [];
+		const out = [];
+		const refs = /* @__PURE__ */ new Set();
+		this.#collectStyleTokenRefs(token.value, refs, /* @__PURE__ */ new WeakSet());
+		if (token.modifiers) this.#collectStyleTokenRefs(token.modifiers, refs, /* @__PURE__ */ new WeakSet());
+		for (const ref of refs) if (ref !== name) out.push({
+			kind: "token",
+			name: ref
+		});
+		for (const key of Object.keys(token.modifiers ?? {})) if (this.modifiers.has(key)) out.push({
+			kind: "modifier",
+			name: key
+		});
+		return out;
+	}
+	/** Outbound edges of a composite style — the tokens and modifiers across its
+	*  variant style bags. */
+	#compositeStyleDependencies(name) {
+		const cs = this.compositeStyles.get(name);
+		if (!cs) return [];
+		const refs = /* @__PURE__ */ new Set();
+		const mods = /* @__PURE__ */ new Set();
+		for (const bag of cs.styles.values()) {
+			this.#collectStyleTokenRefs(bag, refs, /* @__PURE__ */ new WeakSet());
+			this.#collectModifierKeys(bag, mods);
+		}
+		return [...[...refs].map((name) => ({
+			kind: "token",
+			name
+		})), ...[...mods].map((name) => ({
+			kind: "modifier",
+			name
+		}))];
+	}
+	/** Collect every registered single-underscore modifier key reachable in a
+	*  styling node (skipping `__`-internals), into `into`. */
+	#collectModifierKeys(node, into, seen = /* @__PURE__ */ new WeakSet()) {
+		if (node === null || typeof node !== "object") return;
+		if (seen.has(node)) return;
+		seen.add(node);
+		for (const [key, value] of Object.entries(node)) {
+			if (key.startsWith("__")) continue;
+			if (key.startsWith("_") && this.modifiers.has(key)) into.add(key);
+			this.#collectModifierKeys(value, into, seen);
+		}
+	}
+	/** Dedupe a `DependencyRef[]` by `(kind, name, value)`. */
+	#dedupeRefs(refs) {
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		for (const ref of refs) {
+			const key = `${ref.kind} ${ref.name} ${ref.value ?? ""}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			out.push(ref);
+		}
+		return out;
+	}
+	/**
+	* Everything that references a modifier (`_hover`, `_dataStateOpen`, `_dark`)
+	* in its own styling. Walks all the places a `_<modifier>` key can appear:
+	*  - **components**: `base`, each variant's per-layer styles, and
+	*    `compoundProps` layer overrides;
+	*  - **compositeStyles**: each variant bag;
+	*  - **tokenGroups**: tokens carrying a `_<modifier>` mode override (e.g.
+	*    `{ value, _dark }`) — grouped by namespace since a mode modifier touches
+	*    many tokens at once.
+	* Matches single-underscore modifier keys only (skips `__kind` etc.). The
+	* modifier slice of {@link Config.dependentsOf}, which flattens the three
+	* buckets into one tagged list.
+	*/
+	#modifierDependents(modifier) {
+		const usesModifier = (node, seen = /* @__PURE__ */ new WeakSet()) => {
+			if (node === null || typeof node !== "object") return false;
+			if (seen.has(node)) return false;
+			seen.add(node);
+			for (const [key, value] of Object.entries(node)) {
+				if (key === modifier) return true;
+				if (key.startsWith("__")) continue;
+				if (usesModifier(value, seen)) return true;
+			}
+			return false;
+		};
+		const components = [];
+		for (const component of this.components.values()) {
+			const inBase = component.base ? usesModifier(component.base) : false;
+			const inProps = !inBase && Object.values(component.props).some((binding) => usesModifier(binding));
+			const inCompound = !inBase && !inProps && (component.compoundProps?.some((e) => usesModifier(e.layers)) ?? false);
+			if (inBase || inProps || inCompound) components.push(component.name);
+		}
+		const compositeStyles = [];
+		for (const cs of this.compositeStyles.values()) for (const bag of cs.styles.values()) if (usesModifier(bag)) {
+			compositeStyles.push(cs.name);
+			break;
+		}
+		const tokenGroups = [];
+		for (const group of this.tokenGroups.values()) for (const token of group.tokens.values()) if (token.modifiers && Object.hasOwn(token.modifiers, modifier)) {
+			tokenGroups.push(group.namespace);
+			break;
+		}
+		return {
+			components,
+			compositeStyles,
+			tokenGroups
+		};
+	}
+	/**
+	* The aggregate sibling of {@link Config.dependentsOf} — for *every* entity of
+	* a kind at once, how many dependents each has (`Map<name, count>`, ranked by
+	* `uds_analyze_usage`). A single entity's count is just
+	* `dependentsOf(query).length`; this exists for the all-at-once case, where
+	* calling that per entity would re-walk the component set N times
+	* (O(N × components)) — each private slice walks once (O(components)) and
+	* tallies as it goes, kept consistent with `dependentsOf` (a dependent
+	* counted once per entity, self-references excluded; the cross-check tests
+	* assert the equivalence against the live config).
+	*/
+	dependentCounts(kind) {
+		switch (kind) {
+			case "component": return this.#componentDependentCounts();
+			case "compositeStyle": return this.#compositeStyleDependentCounts();
+			case "styleProp": return this.#stylePropDependentCounts();
+			case "tokenGroup": return this.#tokenGroupDependentCounts();
+			case "modifier": return this.#modifierDependentCounts();
+			case "token": return this.#tokenDependentCounts();
+			default: return assertNever(kind);
+		}
+	}
+	#componentDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const component of this.components.values()) {
+			const refs = /* @__PURE__ */ new Set();
+			for (const layer of component.layers.values()) {
+				const renders = layer.renders;
+				if (renders?.kind === "component" && renders.ref !== component.name) refs.add(renders.ref);
+			}
+			for (const ref of refs) counts.set(ref, (counts.get(ref) ?? 0) + 1);
+		}
+		return counts;
+	}
+	#compositeStyleDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const component of this.components.values()) {
+			const names = /* @__PURE__ */ new Set();
+			for (const info of component.derived.props) if (info.kind === "composite") names.add(info.compositeName);
+			for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+		}
+		return counts;
+	}
+	#stylePropDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const component of this.components.values()) {
+			const names = /* @__PURE__ */ new Set();
+			for (const info of component.derived.props) if (info.kind === "styleProp") names.add(info.stylePropName);
+			for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+		}
+		return counts;
+	}
+	/**
+	* Single-pass companion to `dependentsOf('tokenGroup', …)` — how many style props
+	* draw from each token-group namespace. Walks the style props once (the
+	* forward `consumedTokenGroups` direction) rather than re-deriving each
+	* group's consumer list, counting a prop once per group it references.
+	*/
+	#tokenGroupDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const styleProp of this.styleProps.values()) for (const namespace of new Set(styleProp.consumedTokenGroups())) counts.set(namespace, (counts.get(namespace) ?? 0) + 1);
+		return counts;
+	}
+	/**
+	* Single-pass companion to `dependentsOf('modifier', …)` — the total it sums per
+	* modifier (components + composite styles + token-group namespaces that
+	* reference it). Mirrors the modifier walk's traversal rules: gathers every
+	* single-underscore key (skipping `__`-prefixed internals, so a slot's
+	* `__accepts` child definitions never leak in), counts each source once per
+	* modifier, and tallies only registered modifiers.
+	*/
+	#modifierDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		const bump = (key, into) => {
+			if (this.modifiers.has(key)) into.add(key);
+		};
+		const collect = (node, into, seen = /* @__PURE__ */ new WeakSet()) => {
+			if (node === null || typeof node !== "object") return;
+			if (seen.has(node)) return;
+			seen.add(node);
+			for (const [key, value] of Object.entries(node)) {
+				if (key.startsWith("__")) continue;
+				if (key.startsWith("_")) bump(key, into);
+				collect(value, into, seen);
+			}
+		};
+		const tally = (keys) => {
+			for (const key of keys) counts.set(key, (counts.get(key) ?? 0) + 1);
+		};
+		for (const component of this.components.values()) {
+			const keys = /* @__PURE__ */ new Set();
+			if (component.base) collect(component.base, keys);
+			for (const binding of Object.values(component.props)) collect(binding, keys);
+			for (const entry of component.compoundProps ?? []) collect(entry.layers, keys);
+			tally(keys);
+		}
+		for (const cs of this.compositeStyles.values()) {
+			const keys = /* @__PURE__ */ new Set();
+			for (const bag of cs.styles.values()) collect(bag, keys);
+			tally(keys);
+		}
+		for (const group of this.tokenGroups.values()) {
+			const keys = /* @__PURE__ */ new Set();
+			for (const token of group.tokens.values()) for (const key of Object.keys(token.modifiers ?? {})) bump(key, keys);
+			tally(keys);
+		}
+		return counts;
+	}
+	/** Single-pass `dependentCounts('token')` — referrers per token: each
+	*  component counted once per token it references, plus each token that
+	*  aliases/mode-overrides another (self excluded). Mirrors the union
+	*  `dependentsOf({ kind: 'token' })` returns. */
+	#tokenDependentCounts() {
+		const counts = /* @__PURE__ */ new Map();
+		const bump = (name) => counts.set(name, (counts.get(name) ?? 0) + 1);
+		for (const component of this.components.values()) for (const ref of new Set(component.derived.tokenRefs)) bump(ref);
+		for (const [qualifiedName, token] of this.derived.tokens) {
+			const refs = /* @__PURE__ */ new Set();
+			this.#collectStyleTokenRefs(token.value, refs, /* @__PURE__ */ new WeakSet());
+			if (token.modifiers) this.#collectStyleTokenRefs(token.modifiers, refs, /* @__PURE__ */ new WeakSet());
+			for (const ref of refs) if (ref !== qualifiedName) bump(ref);
+		}
+		return counts;
+	}
+	/**
+	* A component's style-prop surface as a delta against a base set, so
+	* consumers can render "inherits Box (226); adds …; removes …" instead of
+	* re-emitting the full ~226-name list per component. The base is the
+	* `extendsFrom` parent's set when value-extending, else the union across the
+	* `primitives` group (the set every primitive shares). `baseSource` is the
+	* parent's name, or `undefined` when the base is the primitives union — every
+	* `extends:Box` primitive has an identical set today, so `adds`/`removes` are
+	* usually empty, which is the dedup the projection relies on.
+	*/
+	stylePropSummary(component) {
+		const own = component.derived.stylePropNames;
+		const parent = component.extendsFrom ? this.components.get(component.extendsFrom) : void 0;
+		const baseSource = parent ? component.extendsFrom : void 0;
+		const base = parent ? parent.derived.stylePropNames : this.#primitivesStyleProps();
+		const baseSet = new Set(base);
+		const ownSet = new Set(own);
+		return {
+			own,
+			base,
+			baseSource,
+			adds: own.filter((n) => !baseSet.has(n)),
+			removes: baseSource ? base.filter((n) => !ownSet.has(n)) : []
+		};
+	}
+	/** Union of style-prop names across the `primitives` group — the comparison
+	*  base for root components (no `extendsFrom`, e.g. `Box`). */
+	#primitivesStyleProps() {
+		const names = /* @__PURE__ */ new Set();
+		for (const component of this.components.values()) if (component.derived.componentGroup === "primitives") for (const n of component.derived.stylePropNames) names.add(n);
+		return [...names];
+	}
+	/**
+	* Author global CSS — a selector → declarations bag. The callback
+	* form receives the same 2D CSS-var ref table as `derived.cssVarRefs`
+	* (`tokens.bg.primary` resolves to a `var(--uds-bg-primary)` brand)
+	* so consumers can reach for token values without re-deriving them.
+	* Mirrors the old `@yahoo/uds-create-config` `defineGlobalStyles` chain.
+	*/
+	defineGlobalStyles(input) {
+		this.globalStyles = typeof input === "function" ? input(this.derived.cssVarRefs) : input;
+		return this;
+	}
+	/**
+	* Include a raw CSS string verbatim in the generated stylesheet — for
+	* declarations the token/style-prop system can't express, most commonly
+	* `@font-face` blocks (the codegen pipeline emits none on its own) plus
+	* the `:root { --<prefix>-font-family-<id>: … }` definitions that font
+	* tokens reference. Accumulates across calls.
+	*
+	* Takes the CSS *content*, not a path, so `Config` stays free of Node
+	* `fs` and remains importable in the browser/runtime. Read the file in
+	* `uds.config.ts` (Node context) and pass the string:
+	*
+	* ```ts
+	* import { readFileSync } from 'node:fs';
+	* const fontsCss = readFileSync(new URL('./fonts.css', import.meta.url), 'utf8');
+	* export default defineConfig({ … }).includeCss(fontsCss);
+	* ```
+	*
+	* Injected after Tailwind compilation and the unused-var purge, so
+	* `@font-face` families and any custom properties it declares are never
+	* stripped as "unused".
+	*/
+	includeCss(css) {
+		this.rawCss.push(css);
+		return this;
+	}
+	registerModes(modes) {
+		for (const [name, def] of Object.entries(modes)) this.modes.set(name, new Mode({
+			name,
+			definition: def
+		}));
+		return this;
+	}
+	registerModifiers(modifiers) {
+		for (const [name, def] of Object.entries(modifiers)) {
+			const key = name;
+			this.modifiers.set(key, new Modifier({
+				name: key,
+				definition: def,
+				compositeLookup: (ref) => this.#lookupCompositeSelector(ref),
+				modeLookup: (ref) => this.#lookupModeSelector(ref)
+			}));
+		}
+		return this;
+	}
+	registerTokenGroups(groups) {
+		for (const [namespace, def] of Object.entries(groups)) this.tokenGroups.set(namespace, new TokenGroup({
+			namespace,
+			prefixGetter: () => this.prefix,
+			definition: def,
+			tokenLookup: (ref) => this.derived.tokens.get(ref),
+			stylePropertiesLookup: (ns) => this.#stylePropertiesFor(ns)
+		}));
+		this.#invalidate();
+		return this;
+	}
+	registerStyleProps(props) {
+		for (const [name, def] of Object.entries(props)) this.styleProps.set(name, new StyleProp({
+			name,
+			definition: def,
+			tokenLookup: (groupName) => this.#tokensInGroup(groupName),
+			prefixGetter: () => this.prefix
+		}));
+		return this;
+	}
+	registerComposites(composites) {
+		for (const [name, def] of Object.entries(composites)) this.compositeStyles.set(name, new CompositeStyle({
+			name,
+			definition: def,
+			prefixGetter: () => this.prefix
+		}));
+		return this;
+	}
+	registerMotion(motion) {
+		for (const [name, def] of Object.entries(motion)) this.motion.set(name, def.runtime === "js" ? new JsMotionDef({
+			name,
+			definition: def
+		}) : new CssMotionDef({
+			name,
+			definition: def
+		}));
+		return this;
+	}
+	registerComponents(components) {
+		const parentOf = /* @__PURE__ */ new Map();
+		const childrenOf = /* @__PURE__ */ new Map();
+		const flat = new Map(Object.entries(components));
+		for (const [parentName, def] of Object.entries(components)) {
+			const subs = def.__subcomponents;
+			if (!subs) continue;
+			const childNames = [];
+			for (const [childName, child] of Object.entries(subs)) {
+				const existing = parentOf.get(childName);
+				if (existing !== void 0) throw new Error(`registerComponents: subcomponent "${childName}" registered under both "${existing}" and "${parentName}"`);
+				if (Object.hasOwn(components, childName)) throw new Error(`registerComponents: "${childName}" is registered both as a top-level component and as a subcomponent of "${parentName}" — pick one`);
+				flat.set(childName, child);
+				parentOf.set(childName, parentName);
+				childNames.push(childName);
+			}
+			childrenOf.set(parentName, childNames);
+		}
+		for (const [name, def] of flat) Object.defineProperty(def, "__componentName", {
+			enumerable: false,
+			configurable: true,
+			writable: true,
+			value: name
+		});
+		for (const [name, def] of flat) {
+			assertNameAvailable(this.components, name, this.namespace);
+			assertDefinitionAcceptsPlaceable(name, def);
+			this.components.set(name, new Component({
+				name,
+				definition: def,
+				subcomponentOf: parentOf.get(name),
+				subcomponents: childrenOf.get(name),
+				namespaceGetter: () => this.namespace,
+				prefixGetter: () => this.prefix,
+				componentResolver: (ref) => this.getComponent(ref),
+				resolveStylePropValueToken: (prop, value) => this.#resolveStylePropValueToken(prop, value),
+				isStyleProp: (propName) => this.styleProps.has(propName)
+			}));
+		}
+		return this;
+	}
+	/**
+	* Build a single component from its definition with this config's context
+	* getters wired — `prefixGetter`, `namespaceGetter`, `componentResolver` —
+	* and set it on the registry, replacing any existing entry of the same name.
+	*
+	* This is the ONE sanctioned way to put a constructed component into the
+	* config outside `registerComponents`. Constructing a `Component` by hand and
+	* calling `config.components.set(...)` silently drops those getters, so the
+	* component's `derived.classNames` fall back to an empty prefix/namespace and
+	* its anatomy CSS emits unprefixed (`:where(.button-root)`) — it renders
+	* unstyled while the runtime applies the prefixed class. Patch-apply code that
+	* rebuilds a component from a mutated definition (e.g.
+	* `applyComponentStyleUpdatePatch`) routes through here so the wiring can't be
+	* forgotten.
+	*/
+	upsertComponent(name, definition, meta) {
+		this.components.set(name, new Component({
+			name,
+			definition,
+			componentGroup: meta?.componentGroup,
+			subcomponentOf: meta?.subcomponentOf,
+			subcomponents: meta?.subcomponents,
+			namespaceGetter: () => this.namespace,
+			prefixGetter: () => this.prefix,
+			componentResolver: (ref) => this.getComponent(ref),
+			resolveStylePropValueToken: (prop, value) => this.#resolveStylePropValueToken(prop, value),
+			isStyleProp: (propName) => this.styleProps.has(propName)
+		}));
+		return this;
+	}
+	/**
+	* Register one or more labeled bundles of components. Each group's
+	* `components` record is flattened into `this.components` (same
+	* surface as `registerComponents`), and every member's
+	* `Component.derived.componentGroup` carries the group key. The
+	* group entry itself lives on `this.componentGroups[key]` with a
+	* JSON-safe ref list (`components: readonly string[]`).
+	*
+	* Subcomponents declared on a grouped parent via
+	* `.subcomponents({...})` auto-register alongside their parent;
+	* they carry `subcomponentOf` instead of `componentGroup` (a
+	* subcomponent belongs to a parent, not a group).
+	*
+	* Component names are the identity (`<namespace>:<name>`, the spec
+	* `type`) and must be unique across the whole config — the same name
+	* under two groups, repeated in one group, or already registered by a
+	* prior `register*` call throws. Two components that should *display*
+	* the same use distinct names + `metadata.label`.
+	*/
+	registerComponentGroups(groups) {
+		const groupOf = /* @__PURE__ */ new Map();
+		const parentOf = /* @__PURE__ */ new Map();
+		const childrenOf = /* @__PURE__ */ new Map();
+		const flat = /* @__PURE__ */ new Map();
+		const groupRecords = /* @__PURE__ */ new Map();
+		for (const [groupKey, group] of Object.entries(groups)) {
+			const componentNames = [];
+			for (const [name, def] of Object.entries(group.components)) {
+				if (this.components.has(name) || flat.has(name)) throw new Error(`registerComponentGroups: component "${name}" is already registered${groupOf.get(name) ? ` (group "${groupOf.get(name)}")` : ""} — component names must be unique within a registry. Rename one (e.g. "Studio${name}") and give it metadata.label "${name}" for a shared display name.`);
+				flat.set(name, def);
+				groupOf.set(name, groupKey);
+				componentNames.push(name);
+			}
+			groupRecords.set(groupKey, {
+				label: group.label,
+				description: group.description,
+				componentNames
+			});
+		}
+		for (const group of Object.values(groups)) for (const [parentName, def] of Object.entries(group.components)) {
+			const subs = def.__subcomponents;
+			if (!subs) continue;
+			const childNames = [];
+			for (const [childName, child] of Object.entries(subs)) {
+				const existingParent = parentOf.get(childName);
+				if (existingParent !== void 0) throw new Error(`registerComponentGroups: subcomponent "${childName}" registered under both "${existingParent}" and "${parentName}"`);
+				if (groupOf.has(childName)) throw new Error(`registerComponentGroups: "${childName}" is registered both as a top-level component and as a subcomponent of "${parentName}" — pick one`);
+				flat.set(childName, child);
+				parentOf.set(childName, parentName);
+				childNames.push(childName);
+			}
+			childrenOf.set(parentName, childNames);
+		}
+		for (const [name, def] of flat) Object.defineProperty(def, "__componentName", {
+			enumerable: false,
+			configurable: true,
+			writable: true,
+			value: name
+		});
+		for (const [name, def] of flat) {
+			assertNameAvailable(this.components, name, this.namespace);
+			assertDefinitionAcceptsPlaceable(name, def);
+			this.components.set(name, new Component({
+				name,
+				definition: def,
+				componentGroup: groupOf.get(name),
+				subcomponentOf: parentOf.get(name),
+				subcomponents: childrenOf.get(name),
+				namespaceGetter: () => this.namespace,
+				prefixGetter: () => this.prefix,
+				componentResolver: (ref) => this.getComponent(ref),
+				resolveStylePropValueToken: (prop, value) => this.#resolveStylePropValueToken(prop, value),
+				isStyleProp: (propName) => this.styleProps.has(propName)
+			}));
+		}
+		for (const [groupKey, record] of groupRecords) this.componentGroups.set(groupKey, new ComponentGroup({
+			name: groupKey,
+			label: record.label,
+			description: record.description,
+			components: record.componentNames
+		}));
+		return this;
+	}
+	/**
+	* Register one or more asset groups. The record key IS the slug —
+	* stamped onto the group at registration (late-bound, like
+	* `registerComponentGroups` deriving a group's name from its key and
+	* `Component.registryKey` reading the namespace getter). Each member
+	* then resolves to `${namespace}:asset:${slug}/${assetName}` via
+	* `AssetGroup.assetType()`.
+	*
+	* Trade-off (accepted, same as `registerComponentGroups`): the
+	* `{ icons }` shorthand ties the slug to the variable name — write
+	* the key out explicitly (`{ icons: phosphorIcons }`) whenever it
+	* shouldn't track the variable.
+	*/
+	registerAssetGroups(groups) {
+		for (const [slug, def] of Object.entries(groups)) {
+			if (!isAssetGroupRef(def)) {
+				const looksLikeBuilder = typeof def.config === "function";
+				throw new Error(looksLikeBuilder ? `registerAssetGroups: group "${slug}" is missing its .config({...}) call — defineAssetGroup(members).config({ sizes }) is a complete icon registration.` : `registerAssetGroups: value for "${slug}" is not an asset group — author it with defineAssetGroup(members).config({...}).`);
+			}
+			if (!/^[A-Za-z][A-Za-z0-9]*(?:[-_][A-Za-z0-9]+)*$/.test(slug)) throw new Error(`registerAssetGroups: slug "${slug}" is invalid — slugs become the asset-id group segment (alphanumeric segments separated by single "-" or "_").`);
+			if (this.assetGroups.has(slug)) throw new Error(`registerAssetGroups: asset group "${slug}" is already registered — slugs must be unique within a config.`);
+			const priorSlug = readAssetGroupSlug(def);
+			if (priorSlug !== void 0 && priorSlug !== slug) throw new Error(`registerAssetGroups: this group is already registered as "${priorSlug}" — a group has one identity; re-export it instead of registering it twice.`);
+			def[ASSET_GROUP_SLUG_KEY] = slug;
+			this.assetGroups.set(slug, new AssetGroup({
+				name: slug,
+				label: def.label ?? titleCaseSlug(slug),
+				version: def.version,
+				description: def.description,
+				assetKind: def.assetKind,
+				assetNames: Object.keys(def.members),
+				sizes: def.assetKind === "icon" ? def.sizes : void 0,
+				variants: def.assetKind === "icon" ? def.variants : void 0,
+				component: def.assetKind === "icon" ? def.component : void 0,
+				members: def.members,
+				memberMetadata: def.assetKind === "icon" ? def.memberMetadata : void 0,
+				namespaceGetter: () => this.namespace
+			}));
+		}
+		return this;
+	}
+	registerProviders(providers) {
+		for (const [name, ProviderFC] of Object.entries(providers)) {
+			ProviderFC.displayName = name;
+			const marker = ProviderFC.__udsProvider;
+			marker.name = name;
+			this.providers.set(name, new Provider({
+				name,
+				component: ProviderFC
+			}));
+		}
+		return this;
+	}
+	get derived() {
+		if (!this.#derived) {
+			const tokens = /* @__PURE__ */ new Map();
+			const cssVarRefs = {};
+			for (const [namespace, group] of this.tokenGroups) {
+				const groupRefs = {};
+				for (const [name, token] of group.tokens) {
+					tokens.set(`${namespace}/${name}`, token);
+					groupRefs[name] = token.derived.cssVarRef;
+				}
+				cssVarRefs[namespace] = groupRefs;
+			}
+			const modeOptionsByModifier = /* @__PURE__ */ new Map();
+			for (const modifier of this.modifiers.values()) {
+				const selector = modifier.selector;
+				if (!isModeRef(selector)) continue;
+				const option = this.#resolveModeOption(selector.ref);
+				if (option) modeOptionsByModifier.set(modifier.name, option);
+			}
+			this.#derived = {
+				tokens,
+				cssVarRefs,
+				modeOptionsByModifier
+			};
+		}
+		return this.#derived;
+	}
+	#invalidate() {
+		this.#derived = void 0;
+	}
+	#stylePropertiesFor(namespace) {
+		const out = [];
+		for (const styleProp of this.styleProps.values()) if (styleProp.consumedTokenGroups().includes(namespace)) out.push(styleProp.name);
+		return out;
+	}
+	/**
+	* Resolve a shorthand style-prop value to the qualified token it names —
+	* `('bg', 'tertiary')` → `'bg/tertiary'` — by checking the style prop's
+	* token groups for a token of that name. Returns `undefined` when the key
+	* isn't a registered style prop, or the value is a keyword / arbitrary
+	* literal rather than a token. Feeds `Component.derived.tokenRefs` so
+	* shorthand token usage is captured structurally, not by string matching.
+	*/
+	#resolveStylePropValueToken(styleProp, value) {
+		const sp = this.styleProps.get(styleProp);
+		if (!sp) return void 0;
+		for (const namespace of sp.consumedTokenGroups()) if (this.tokenGroups.get(namespace)?.tokens.has(value)) return `${namespace}/${value}`;
+	}
+	*#tokensInGroup(namespace) {
+		const group = this.tokenGroups.get(namespace);
+		if (!group) return;
+		for (const token of group.tokens.values()) yield token;
+	}
+	#lookupCompositeSelector(ref) {
+		const [name, variant] = ref.split("/");
+		if (!name || !variant) return void 0;
+		const composite = this.compositeStyles.get(name);
+		if (!composite) return void 0;
+		if (!composite.styles.has(variant)) return void 0;
+		const { markerVarName, markerVarValue } = composite.derived;
+		return `@container style(${markerVarName}: ${markerVarValue(variant)})`;
+	}
+	/**
+	* Resolve a `mode()` ref (`'colorMode/dark'`) to its `ModeOption`. The single
+	* place that knows the ref's `group/option` shape — both the CSS-selector
+	* lookup and the modifier→mode reverse map go through here, so the ref syntax
+	* lives in exactly one spot.
+	*/
+	#resolveModeOption(ref) {
+		const [name, optionName] = ref.split("/");
+		if (!name || !optionName) return void 0;
+		return this.modes.get(name)?.options.get(optionName);
+	}
+	#lookupModeSelector(ref) {
+		return this.#resolveModeOption(ref)?.css;
+	}
+	/**
+	* Validate cross-references. Throws on cycles in token aliases or on
+	* unknown refs in markers (`token()`, `composite()`, `mode()`,
+	* `styleProp()`, `tokenGroup()`).
+	*/
+	validate() {
+		const tokens = this.derived.tokens;
+		for (const [qualified, token] of tokens) visit(qualified, token, tokens, /* @__PURE__ */ new Set());
+		for (const styleProp of this.styleProps.values()) for (const groupName of styleProp.consumedTokenGroups()) if (!this.tokenGroups.has(groupName)) throw new Error(`Style prop '${styleProp.name}' references unknown token group '${groupName}'`);
+		for (const modifier of this.modifiers.values()) {
+			const selector = modifier.selector;
+			if (typeof selector === "object" && selector !== null) {
+				if (selector.__kind === "composite") {
+					if (this.#lookupCompositeSelector(selector.ref) === void 0) throw new Error(`Modifier '${modifier.name}' references unknown composite '${selector.ref}'`);
+				}
+				if (selector.__kind === "mode") {
+					if (this.#lookupModeSelector(selector.ref) === void 0) throw new Error(`Modifier '${modifier.name}' references unknown mode '${selector.ref}'`);
+				}
+			}
+		}
+	}
+	/**
+	* Deep-fork for Studio drafts. Re-builds every entity from `toJSON` /
+	* `fromJSON` rather than sharing instances so the clone is fully
+	* isolated.
+	*
+	* `overlay` shallow-merges into the serialized form before re-hydration —
+	* lets callers swap top-level slices (`{ components, tokenGroups }`)
+	* without round-tripping through the chain methods. Each overlay key
+	* fully replaces the existing slice (no per-entry merge); pass the
+	* full record you want for that slice.
+	*/
+	clone(overlay) {
+		const base = this.toJSON();
+		return Config.fromJSON(overlay ? {
+			...base,
+			...overlay
+		} : base);
+	}
+	/**
+	* Serialize to the wire format. Derived data is never included.
+	* `meta.builtAt` lands in the JSON when the caller passes it (CLI
+	* stamps it at write time so re-serializing in tests stays stable).
+	* `meta.projectRoot` relativizes per-component `sourceFilePath`
+	* values at the wire boundary — keeps `config.json` portable across
+	* machines. Omitting it leaves paths absolute.
+	*/
+	toJSON(meta) {
+		const out = {
+			schemaVersion: Config.SCHEMA_VERSION,
+			prefix: this.prefix,
+			preflight: this.preflight
+		};
+		if (meta?.builtAt !== void 0) out.builtAt = meta.builtAt;
+		if (this.namespace !== void 0) out.namespace = this.namespace;
+		if (this.designPrinciples.length > 0) out.designPrinciples = this.designPrinciples;
+		if (Object.keys(this.globalStyles).length > 0) out.globalStyles = this.globalStyles;
+		if (this.rawCss.length > 0) out.rawCss = this.rawCss;
+		if (this.modes.size > 0) out.modes = mapToRecord(this.modes, (mode) => mode.toJSON());
+		if (this.modifiers.size > 0) out.modifiers = mapToRecord(this.modifiers, stripName);
+		if (this.tokenGroups.size > 0) out.tokenGroups = mapToRecord(this.tokenGroups, (group) => group.toJSON());
+		if (this.styleProps.size > 0) out.styleProps = mapToRecord(this.styleProps, stripName);
+		if (this.compositeStyles.size > 0) out.compositeStyles = mapToRecord(this.compositeStyles, stripName);
+		if (this.motion.size > 0) {
+			const motionRecord = {};
+			for (const [name, motion] of this.motion) {
+				const { name: _omit, ...rest } = motion.toJSON();
+				motionRecord[name] = rest;
+			}
+			out.motion = motionRecord;
+		}
+		if (this.components.size > 0) out.components = mapToRecord(this.components, (component) => {
+			const { name: _name, ...rest } = component.toJSON({ projectRoot: meta?.projectRoot });
+			return rest;
+		});
+		if (this.componentGroups.size > 0) out.componentGroups = mapToRecord(this.componentGroups, (group) => {
+			const { name: _omit, ...rest } = group.toJSON();
+			return rest;
+		});
+		if (this.assetGroups.size > 0) out.assetGroups = mapToRecord(this.assetGroups, (group) => {
+			const { name: _omit, ...rest } = group.toJSON();
+			return rest;
+		});
+		if (this.providers.size > 0) {
+			const providers = {};
+			for (const name of this.providers.keys()) providers[name] = {};
+			out.providers = providers;
+		}
+		return out;
+	}
+	/**
+	* Hydrate from the wire format. Throws when `schemaVersion` doesn't
+	* match — the CLI's job is to translate the error into "your manifest
+	* is from an older build; run `uds build`."
+	*/
+	static fromJSON(json) {
+		if (json.schemaVersion !== Config.SCHEMA_VERSION) throw new Error(`Config schema version mismatch: file is v${json.schemaVersion}, runtime expects v${Config.SCHEMA_VERSION}. Re-run \`uds build\`.`);
+		const config = new Config();
+		config.prefix = json.prefix;
+		config.preflight = json.preflight;
+		if (json.namespace !== void 0) config.namespace = json.namespace;
+		if (json.designPrinciples) config.designPrinciples = [...json.designPrinciples];
+		if (json.globalStyles) config.globalStyles = json.globalStyles;
+		if (json.rawCss) config.rawCss = [...json.rawCss];
+		if (json.modes) config.registerModes(json.modes);
+		if (json.tokenGroups) config.registerTokenGroups(json.tokenGroups);
+		if (json.styleProps) config.registerStyleProps(json.styleProps);
+		if (json.modifiers) config.registerModifiers(json.modifiers);
+		if (json.compositeStyles) config.registerComposites(json.compositeStyles);
+		if (json.motion) config.registerMotion(json.motion);
+		const componentsByName = json.components ?? {};
+		for (const def of Object.values(componentsByName)) if (def.sourceFilePath) attachSourcePath(def, def.sourceFilePath);
+		const isSubcomponent = /* @__PURE__ */ new Set();
+		for (const parentDef of Object.values(componentsByName)) {
+			const subs = parentDef.subcomponents;
+			if (!subs || subs.length === 0) continue;
+			const childMap = {};
+			for (const childName of subs) {
+				const child = componentsByName[childName];
+				if (!child) continue;
+				childMap[childName] = child;
+				isSubcomponent.add(childName);
+			}
+			if (Object.keys(childMap).length === 0) continue;
+			Object.defineProperty(parentDef, "__subcomponents", {
+				enumerable: false,
+				configurable: true,
+				writable: true,
+				value: childMap
+			});
+		}
+		const grouped = /* @__PURE__ */ new Set();
+		if (json.componentGroups) {
+			const groupDefs = {};
+			for (const [groupKey, group] of Object.entries(json.componentGroups)) {
+				const components = {};
+				for (const name of group.components) {
+					if (isSubcomponent.has(name)) continue;
+					const def = componentsByName[name];
+					if (def === void 0) throw new Error(`Config.fromJSON: componentGroup "${groupKey}" references unknown component "${name}"`);
+					components[name] = def;
+					grouped.add(name);
+				}
+				groupDefs[groupKey] = {
+					label: group.label,
+					...group.description !== void 0 ? { description: group.description } : {},
+					components
+				};
+			}
+			config.registerComponentGroups(groupDefs);
+		}
+		if (json.components) {
+			const ungrouped = {};
+			for (const [name, def] of Object.entries(componentsByName)) {
+				if (grouped.has(name) || isSubcomponent.has(name)) continue;
+				ungrouped[name] = def;
+			}
+			if (Object.keys(ungrouped).length > 0) config.registerComponents(ungrouped);
+		}
+		if (json.assetGroups) for (const [slug, group] of Object.entries(json.assetGroups)) config.assetGroups.set(slug, AssetGroup.fromJSON(slug, group, () => config.namespace));
+		return config;
+	}
+};
+/**
+* Structural validation for a registry namespace. Guards only the
+* invariants the namespacing scheme depends on — non-empty, no `:`
+* (the `<namespace>:<Component>` separator), no whitespace. Stricter
+* format rules and uniqueness / ownership are enforced at push time
+* against the registered systems. Returns the value unchanged on
+* success; throws otherwise.
+*/
+/**
+* Guard against registering two components under the same name. The name
+* is the component's identity (`<namespace>:<name>`, the spec `type`), so
+* a collision is unresolvable — a spec referencing it couldn't tell the
+* two apart. Thrown across every registration path (flat + grouped +
+* cross-call) so author-time mistakes fail loudly instead of silently
+* shadowing a component. Two components that should *display* the same
+* use distinct names + `metadata.label`.
+*/
+/** A non-null object — a nested style bag (per-slot styles or a `_<modifier>`
+*  sub-object) to descend into when walking component base styles. */
+function isStyleRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function assertNameAvailable(components, name, namespace) {
+	if (!components.has(name)) return;
+	const qualified = namespace ? `${namespace}:${name}` : name;
+	throw new Error(`Config: component "${name}" is already registered (identity "${qualified}") — component names must be unique within a registry. Rename one (e.g. "Studio${name}") and give it metadata.label "${name}" for a shared display name.`);
+}
+/**
+* Split a spec element `type` / registry key into its namespace + bare name.
+* `'uds:Text'` → `{ namespace: 'uds', name: 'Text' }`; a bare `'Text'` →
+* `{ name: 'Text' }`. The namespace is everything before the first `:`
+* (namespaces are validated to contain no `:`, see {@link validateNamespace}),
+* so a scoped namespace like `'@acme/system:Button'` still splits on the right
+* colon. The inverse of {@link Component.registryKey}.
+*/
+function parseRegistryKey(type) {
+	const sep = type.indexOf(":");
+	if (sep < 0) return { name: type };
+	return {
+		namespace: type.slice(0, sep),
+		name: type.slice(sep + 1)
+	};
+}
+function validateNamespace(value) {
+	if (value.length === 0) throw new Error("Config.configure: namespace must be non-empty.");
+	if (value.includes(":")) throw new Error(`Config.configure: namespace "${value}" must not contain ":" — it's the reserved \`<namespace>:<Component>\` separator.`);
+	if (/\s/.test(value)) throw new Error(`Config.configure: namespace "${value}" must not contain whitespace.`);
+	if (value === "foreign") throw new Error(`Config.configure: namespace "${FOREIGN_NAMESPACE}" is reserved for third-party leaf components (the \`${FOREIGN_NAMESPACE}:<Component>\` sentinel).`);
+	return value;
+}
+function visit(qualified, token, tokens, seen) {
+	if (seen.has(qualified)) throw new Error(`Token cycle detected at '${qualified}'`);
+	const value = token.value;
+	if (typeof value === "object" && value !== null && "ref" in value && typeof value.ref === "string") {
+		const next = tokens.get(value.ref);
+		if (!next) throw new Error(`Token '${qualified}' references unknown token '${value.ref}'`);
+		visit(value.ref, next, tokens, new Set(seen).add(qualified));
+	}
+}
+function stripName(entity) {
+	const { name: _name, namespace: _namespace, ...rest } = entity.toJSON();
+	return rest;
+}
+/**
+* Default asset-group label from its slug — `'icons'` → `'Icons'`,
+* `'brand-icons'` → `'Brand Icons'`. `label` is optional and defaults
+* to the title-cased registration key.
+*/
+function titleCaseSlug(slug) {
+	return slug.split(/[-_]/).filter(Boolean).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join(" ");
+}
+function mapToRecord(map, serializer) {
+	const out = {};
+	for (const [key, value] of map) out[key] = serializer(value);
+	return out;
+}
+//#endregion
+export { Config, parseRegistryKey };