@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/ComponentGroup.d.ts

@@ -0,0 +1,21 @@
+import { SerializedComponentGroup } from "./types.js";
+
+//#region ../config/dist/ComponentGroup.d.ts
+//#region src/ComponentGroup.d.ts
+declare class ComponentGroup {
+  readonly name: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly components: readonly string[];
+  constructor(args: {
+    name: string;
+    label: string;
+    description?: string;
+    components: readonly string[];
+  });
+  toJSON(): SerializedComponentGroup & {
+    name: string;
+  };
+} //#endregion
+//#endregion
+export { ComponentGroup };

package/dist/config/dist/ComponentGroup.js

@@ -0,0 +1,46 @@
+import { compact } from "./entity-utils.js";
+//#region ../config/dist/ComponentGroup.js
+/**
+* `ComponentGroup` — a labeled bundle of registered components, surfaced
+* together in the Studio palette, the codegen-emitted catalog, and the
+* AI prompt.
+*
+* Authored shape:
+*
+*     const primitives = defineComponentGroup({
+*       label: 'Primitives',
+*       description: 'Low-level components that map to HTML elements.',
+*       components: { Box, Text },
+*     });
+*
+*     uds.registerComponentGroups({ primitives });
+*
+* After registration, `ComponentGroup.components` is a JSON-safe ref
+* list (just the registration names) — the `ComponentDefinition`s
+* themselves live on `Config.components`. Each member's
+* `Component.derived.componentGroup` carries the group key, so
+* consumers can answer "which group does X belong to?" without a
+* parallel projection.
+*/
+var ComponentGroup = class {
+	name;
+	label;
+	description;
+	components;
+	constructor(args) {
+		this.name = args.name;
+		this.label = args.label;
+		this.description = args.description;
+		this.components = args.components;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			label: this.label,
+			...compact({ description: this.description }),
+			components: this.components
+		};
+	}
+};
+//#endregion
+export { ComponentGroup };

package/dist/config/dist/CompositeStyle.d.ts

@@ -0,0 +1,28 @@
+import { CompositeStyleDefinition, CompositeStyleObject } from "./types.js";
+import { CssClassName, CssVar } from "./brands.js";
+
+//#region ../config/dist/CompositeStyle.d.ts
+//#region src/CompositeStyle.d.ts
+declare class CompositeStyle {
+  #private;
+  readonly name: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly styles: ReadonlyMap<string, CompositeStyleObject>;
+  constructor(args: {
+    name: string;
+    definition: CompositeStyleDefinition;
+    prefixGetter?: () => string;
+  });
+  get derived(): {
+    readonly cssClassNames: ReadonlyMap<string, CssClassName>;
+    readonly markerVarName: CssVar;
+    cssClassName(variant: string): CssClassName;
+    markerVarValue(variant: string): string;
+  };
+  toJSON(): CompositeStyleDefinition & {
+    name: string;
+  };
+} //#endregion
+//#endregion
+export { CompositeStyle };

package/dist/config/dist/CompositeStyle.js

@@ -0,0 +1,52 @@
+import { buildCompositeClassName, buildCompositeMarkerVarName, compact, cssSafeSegment } from "./entity-utils.js";
+//#region ../config/dist/CompositeStyle.js
+var CompositeStyle = class {
+	name;
+	label;
+	description;
+	styles;
+	#prefixGetter;
+	#derived;
+	constructor(args) {
+		this.name = args.name;
+		this.label = args.definition.label;
+		this.description = args.definition.description;
+		this.#prefixGetter = args.prefixGetter ?? (() => "uds");
+		const styles = /* @__PURE__ */ new Map();
+		for (const [variant, bag] of Object.entries(args.definition.styles)) styles.set(variant, bag);
+		this.styles = styles;
+	}
+	get derived() {
+		if (!this.#derived) {
+			const name = this.name;
+			const prefixGetter = this.#prefixGetter;
+			const cssClassNames = /* @__PURE__ */ new Map();
+			for (const key of this.styles.keys()) cssClassNames.set(key, buildCompositeClassName(prefixGetter(), name, key));
+			this.#derived = {
+				cssClassNames,
+				get markerVarName() {
+					return buildCompositeMarkerVarName(prefixGetter(), name);
+				},
+				cssClassName(variant) {
+					return buildCompositeClassName(prefixGetter(), name, variant);
+				},
+				markerVarValue(variant) {
+					return cssSafeSegment(variant);
+				}
+			};
+		}
+		return this.#derived;
+	}
+	toJSON() {
+		const styles = {};
+		for (const [key, value] of this.styles) styles[key] = value;
+		return {
+			name: this.name,
+			label: this.label,
+			...compact({ description: this.description }),
+			styles
+		};
+	}
+};
+//#endregion
+export { CompositeStyle };

package/dist/config/dist/Config.d.ts

@@ -0,0 +1,422 @@
+import { CssVarRef } from "./types/css-values.js";
+import { AssetGroupDefinition } from "./defineAssetGroup.js";
+import { AnyStylePropDefinition, BuildOptions, ComponentDefinition, ComponentGroupDefinition, CompositeStyleDefinition, GlobalStylesDef, ModeDefinition, ModifierDefinition, MotionDefinitionInput, SerializedConfig, TokenGroupDefinition, TokenModifierKey } from "./types.js";
+import { AssetGroup } from "./AssetGroup.js";
+import { Component } from "./Component.js";
+import { ComponentGroup } from "./ComponentGroup.js";
+import { CompositeStyle } from "./CompositeStyle.js";
+import { ProviderComponent } from "./factories.js";
+import { Mode, ModeOption } from "./Mode.js";
+import { Modifier } from "./Modifier.js";
+import { MotionDef } from "./MotionDef.js";
+import { Provider } from "./Provider.js";
+import { Token } from "./Token.js";
+import { StyleProp } from "./StyleProp.js";
+import { TokenGroup } from "./TokenGroup.js";
+
+//#region ../config/dist/Config.d.ts
+//#region src/Config.d.ts
+/**
+ * The entity kinds the dependency graph addresses — the discriminant for both
+ * {@link Config.dependentsOf} (inbound) and {@link Config.dependenciesOf}
+ * (outbound), and the single source of truth for the surface. The query unions
+ * are mapped over this type, so adding a kind here automatically widens both
+ * queries, which makes each method's `switch` non-exhaustive — its trailing
+ * `assertNever(query)` then fails to compile until a `case` is added. A new
+ * kind therefore can't ship without logic in *both* directions.
+ */
+type DependencyKind = 'component' | 'compositeStyle' | 'styleProp' | 'modifier' | 'token' | 'tokenGroup';
+/**
+ * A tagged node in a dependency result. `value` is populated only for a
+ * style-prop *keyword* edge — `{ kind: 'styleProp', name: 'display', value:
+ * 'flex' }` — where the prop alone doesn't identify the dependency.
+ */
+interface DependencyRef {
+  readonly kind: DependencyKind;
+  readonly name: string;
+  readonly value?: string;
+}
+/** Per-kind edge-narrowing options for the inbound {@link DependentsQuery}.
+ *  Only kinds that take options appear here; the rest get none. */
+interface DependentsOptionsByKind {
+  /** Narrow to components that use this keyword *value* of the prop
+   *  (`display`=`flex`) for value-removal impact; omit for the components that
+   *  expose the prop. */
+  styleProp: {
+    value?: string;
+  };
+}
+/** Inbound query for {@link Config.dependentsOf} — "what references this?".
+ *  Mapped over {@link DependencyKind} so it always covers every kind. */
+type DependentsQuery = { [K in DependencyKind]: {
+  kind: K;
+  name: string;
+} & (K extends keyof DependentsOptionsByKind ? DependentsOptionsByKind[K] : unknown) }[DependencyKind];
+/** Outbound query for {@link Config.dependenciesOf} — "what does this use?".
+ *  Mapped over {@link DependencyKind} for the same exhaustiveness guarantee. */
+type DependenciesQuery = { [K in DependencyKind]: {
+  kind: K;
+  name: string;
+} }[DependencyKind];
+declare class Config {
+  #private;
+  static readonly SCHEMA_VERSION = 1;
+  prefix: string;
+  /**
+   * 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?: string;
+  preflight: boolean;
+  globalStyles: GlobalStylesDef;
+  rawCss: string[];
+  designPrinciples: string[];
+  buildOptions: BuildOptions;
+  readonly tokenGroups: Map<string, TokenGroup>;
+  readonly styleProps: Map<string, StyleProp>;
+  readonly modifiers: Map<`_${string}`, Modifier>;
+  readonly modes: Map<string, Mode>;
+  readonly compositeStyles: Map<string, CompositeStyle>;
+  readonly components: Map<string, Component>;
+  readonly componentGroups: Map<string, ComponentGroup>;
+  readonly assetGroups: Map<string, AssetGroup>;
+  readonly providers: Map<string, Provider>;
+  readonly motion: Map<string, MotionDef>;
+  /**
+   * 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: {
+    namespace?: string;
+    prefix?: string | false;
+    preflight?: boolean;
+    designPrinciples?: readonly string[];
+    buildOptions?: BuildOptions;
+  }): 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: string): Component | undefined;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): Component[];
+  /**
+   * 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: string, opts?: {
+    negative?: boolean;
+  }): StyleProp[];
+  /**
+   * 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: string, jsxProp: string): StyleProp | undefined;
+  /**
+   * 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(): {
+    total: number;
+    used: number;
+    unused: number;
+    usagePercent: number;
+  };
+  /**
+   * 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?: {
+    property?: string;
+  }): Array<{
+    value: string;
+    count: number;
+    property: string;
+  }>;
+  /**
+   * 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: DependentsQuery): DependencyRef[];
+  /**
+   * 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: DependenciesQuery): DependencyRef[];
+  /**
+   * 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: DependencyKind): Map<string, number>;
+  /**
+   * 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: Component): {
+    own: readonly string[];
+    base: readonly string[];
+    baseSource?: string;
+    adds: readonly string[];
+    removes: readonly string[];
+  };
+  /**
+   * 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 `@uds/config` `defineGlobalStyles` chain.
+   */
+  defineGlobalStyles(input: GlobalStylesDef | ((tokens: Readonly<Record<string, Readonly<Record<string, CssVarRef>>>>) => GlobalStylesDef)): 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: string): this;
+  registerModes(modes: Record<string, ModeDefinition>): this;
+  registerModifiers(modifiers: Record<string, ModifierDefinition>): this;
+  registerTokenGroups(groups: Record<string, TokenGroupDefinition>): this;
+  registerStyleProps(props: Record<string, AnyStylePropDefinition>): this;
+  registerComposites(composites: Record<string, CompositeStyleDefinition>): this;
+  registerMotion(motion: Record<string, MotionDefinitionInput>): this;
+  registerComponents(components: Record<string, ComponentDefinition>): 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: string, definition: ComponentDefinition, meta?: {
+    componentGroup?: string;
+    subcomponentOf?: string;
+    subcomponents?: readonly string[];
+  }): 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: Record<string, ComponentGroupDefinition>): 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: Record<string, AssetGroupDefinition>): this;
+  registerProviders(providers: Record<string, ProviderComponent<Record<never, never>>>): this;
+  get derived(): {
+    readonly tokens: ReadonlyMap<string, Token>;
+    readonly cssVarRefs: Readonly<Record<string, Readonly<Record<string, CssVarRef>>>>;
+    /**
+     * Reverse lookup: a style modifier key (`_dark`) → the mode option that
+     * owns it. Built from `modes`, so a modifier auto-created by a mode
+     * (`colorMode: { dark }` → `_dark`) is recognizable as mode-tied — used to
+     * group/describe such modifiers as modes rather than bare custom states.
+     */
+    readonly modeOptionsByModifier: ReadonlyMap<TokenModifierKey, ModeOption>;
+  };
+  /**
+   * Validate cross-references. Throws on cycles in token aliases or on
+   * unknown refs in markers (`token()`, `composite()`, `mode()`,
+   * `styleProp()`, `tokenGroup()`).
+   */
+  validate(): void;
+  /**
+   * 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?: Partial<SerializedConfig>): Config;
+  /**
+   * 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?: {
+    builtAt?: string;
+    projectRoot?: string;
+  }): SerializedConfig;
+  /**
+   * 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: SerializedConfig): Config;
+}
+/**
+ * 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}.
+ */
+declare function parseRegistryKey(type: string): {
+  namespace?: string;
+  name: string;
+}; //#endregion
+//#endregion
+export { Config, DependenciesQuery, DependencyKind, DependencyRef, DependentsQuery, parseRegistryKey };