@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/StyleProp.js

@@ -0,0 +1,197 @@
+import { compact } from "./entity-utils.js";
+import { isTokenGroupRef } from "./refs.js";
+//#region ../config/dist/StyleProp.js
+/**
+* `StyleProp` — a JSX prop that emits CSS (`bg`, `padding`).
+*
+* Authored field set mirrors the `StylePropDefinition` shape. The
+* `derived.tokens` projection walks the `values` array (which may
+* carry `tokenGroup()` markers) and resolves it to a flat list of
+* `Token` instances. That walk reads the parent Config's tokens map,
+* which can grow after the StyleProp is constructed, so the derived
+* tokens list recomputes on each access.
+*/
+var StyleProp = class StyleProp {
+	name;
+	cssProperty;
+	classPrefix;
+	values;
+	arbitrary;
+	/**
+	* When true, the prop emits its value negated (`calc(<value> * -1)`) — the
+	* single source of negativity, read by the emitter, the runtime injector,
+	* and the MCP/guidance/lint. See {@link StylePropDefinition.negative}.
+	*/
+	negative;
+	cssType;
+	metadata;
+	opacityPair;
+	/**
+	* Optional value→CSS adapter (`gridTemplateColumns`'s `4` →
+	* `repeat(4, minmax(0, 1fr))`). Applied to enumerated `values` when deriving
+	* the utility-class body, so the native emitter produces real CSS without a
+	* Tailwind built-in. Keyword strings (`'none'`) pass through unchanged.
+	*/
+	transform;
+	#tokenLookup;
+	/** Live getter for the owning Config's class-name prefix — mirrors the
+	*  lazy `prefixGetter` pattern on Component / CompositeStyle / TokenGroup
+	*  so the prop reflects `configure({ prefix })` regardless of chain
+	*  ordering. Defaults to `'uds'` when built without an owning Config. */
+	#prefixGetter;
+	#derived;
+	/**
+	* Build the utility-class name a style prop emits for a given
+	* JSX-level value. Single source of truth shared by codegen
+	* (`@utility` emission), loader (build-time class derivation), and
+	* the runtime renderer — all three must agree byte-for-byte.
+	*
+	* Conventions (the `prefix` namespaces the whole utility body the same
+	* way component classes and CSS variables are namespaced; empty prefix
+	* yields the bare form):
+	*  - `classPrefix === ''` → the value IS the class body (`display="block"`
+	*    → `.yos-block`).
+	*  - Boolean `true` → bare `classPrefix` body (`<Box border>` →
+	*    `.yos-border`, never `.border-true`). Falsy → `undefined` (caller
+	*    omits the class).
+	*  - Bracketed arbitrary values (`'[#abc]'`) pass through verbatim.
+	*  - Otherwise `${classPrefix}-${safeTokenName(value)}` where
+	*    safeTokenName maps `.` → `_` and `/` → `-`.
+	*
+	* Static so callers without a StyleProp instance (loader's
+	* className builder, codegen's safelist scanner) can derive a class
+	* from just the prefix + value pair. Instance callers reach
+	* `styleProp.classNameFor(value)`, which supplies the owning Config's
+	* prefix automatically.
+	*/
+	static classNameFor(styleProp, value, prefix = "") {
+		if (value === void 0 || value === null || value === false) return void 0;
+		let body;
+		if (value === true) body = styleProp.classPrefix;
+		else {
+			const stringValue = String(value);
+			const safeValue = stringValue.startsWith("[") && stringValue.endsWith("]") ? stringValue : stringValue.replace(/\./g, "_").replace(/\//g, "-");
+			body = styleProp.classPrefix === "" ? safeValue : `${styleProp.classPrefix}-${safeValue}`;
+		}
+		if (!body) return void 0;
+		return prefix ? `${prefix}-${body}` : body;
+	}
+	/** Instance form of {@link StyleProp.classNameFor} — supplies the owning
+	*  Config's class-name prefix. */
+	classNameFor(value) {
+		return StyleProp.classNameFor(this, value, this.#prefixGetter());
+	}
+	/** The `classPrefix` namespaced with the owning Config's prefix
+	*  (`bg` → `yos-bg`). The wildcard `@utility` emitter needs the
+	*  prefixed stem (`yos-bg-*`) since it has no concrete value to run
+	*  through {@link classNameFor}. Empty when this prop has no class
+	*  prefix (value-as-class props emit no wildcard utility). */
+	get prefixedClassPrefix() {
+		if (this.classPrefix === "") return "";
+		const prefix = this.#prefixGetter();
+		return prefix ? `${prefix}-${this.classPrefix}` : this.classPrefix;
+	}
+	constructor(args) {
+		this.#prefixGetter = args.prefixGetter ?? (() => "uds");
+		this.name = args.name;
+		this.cssProperty = args.definition.cssProperty;
+		this.classPrefix = args.definition.classPrefix;
+		this.values = args.definition.values ?? [];
+		const arbInput = args.definition.arbitrary;
+		if (arbInput === true) this.arbitrary = {};
+		else if (arbInput === false || arbInput === void 0) this.arbitrary = void 0;
+		else if (typeof arbInput === "string") this.arbitrary = { type: arbInput };
+		else this.arbitrary = arbInput;
+		this.negative = args.definition.negative === true;
+		this.cssType = args.definition.cssType;
+		this.metadata = args.definition.metadata ?? {};
+		this.opacityPair = args.definition.opacityPair;
+		this.transform = args.definition.transform;
+		this.#tokenLookup = args.tokenLookup;
+	}
+	get derived() {
+		if (!this.#derived) {
+			const values = this.values;
+			const lookup = this.#tokenLookup;
+			const keywords = /* @__PURE__ */ new Map();
+			for (const entry of values) if (typeof entry === "string") keywords.set(entry, this.transform ? this.transform(entry) : entry);
+			else if (typeof entry === "number") keywords.set(entry, this.transform ? this.transform(entry) : String(entry));
+			else if (typeof entry === "object" && entry !== null && "alias" in entry && "value" in entry) keywords.set(entry.alias, entry.value);
+			this.#derived = {
+				keywords,
+				get tokens() {
+					const out = [];
+					for (const entry of values) if (isTokenGroupRef(entry)) for (const token of lookup(entry.ref)) out.push(token);
+					return out;
+				}
+			};
+		}
+		return this.#derived;
+	}
+	/**
+	* Token-group namespaces this prop consumes. Used by
+	* `TokenGroup.derived.styleProperties` to answer the reverse question.
+	*/
+	consumedTokenGroups() {
+		const out = [];
+		for (const entry of this.values) if (isTokenGroupRef(entry)) out.push(entry.ref);
+		return out;
+	}
+	/**
+	* The values this prop accepts, split by how each is written at the JSX site:
+	*  - `tokens` — token names from the prop's token groups (`gap="2"`).
+	*  - `keywords` — literal CSS keywords written verbatim (`display="flex"`).
+	*  - `aliases` — short keys resolving to a CSS keyword (`flexDirection="col"`
+	*    → `column`).
+	* A bracketed `[...]` arbitrary literal is governed by `this.arbitrary`, not
+	* enumerated here. Rendered by `uds_get_style_prop` / `uds_list_style_props`;
+	* `accepts()` validates against the same set.
+	*/
+	allowedValues() {
+		const keywords = [];
+		const aliases = [];
+		for (const [key, value] of this.derived.keywords) {
+			const alias = String(key);
+			if (typeof value === "string" && value !== alias) aliases.push({
+				alias,
+				value
+			});
+			else keywords.push(alias);
+		}
+		return {
+			tokens: this.derived.tokens.map((t) => t.name),
+			keywords,
+			aliases
+		};
+	}
+	/**
+	* Whether a JSX-site value is accepted: a token name, a literal keyword, an
+	* alias key, or a bracketed `[...]` literal when the prop enables `arbitrary`
+	* values. The validation primitive behind `uds_validate_props` — a non-token
+	* keyword prop (`display`) and an arbitrary-only prop (`fontSize`) both work,
+	* not just token-group props.
+	*/
+	accepts(value) {
+		if (value.startsWith("[") && value.endsWith("]")) return this.arbitrary !== void 0;
+		for (const key of this.derived.keywords.keys()) if (String(key) === value) return true;
+		for (const token of this.derived.tokens) if (token.name === value) return true;
+		return false;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			cssProperty: this.cssProperty,
+			classPrefix: this.classPrefix,
+			values: this.values,
+			...compact({
+				arbitrary: this.arbitrary,
+				negative: this.negative || void 0,
+				cssType: this.cssType,
+				metadata: Object.keys(this.metadata).length > 0 ? this.metadata : void 0,
+				opacityPair: this.opacityPair
+			})
+		};
+	}
+};
+//#endregion
+export { StyleProp };

package/dist/config/dist/Token.d.ts

@@ -0,0 +1,56 @@
+import { CssValueTypeName, CssVarRef } from "./types/css-values.js";
+import { TokenDefinition, TokenModifierKey, TokenModifierValue, TokenType, TokenValue } from "./types.js";
+import { CssClassName, CssVar } from "./brands.js";
+
+//#region ../config/dist/Token.d.ts
+//#region src/Token.d.ts
+/**
+ * Resolved literal value — `token()` refs chased; modifier nesting
+ * flattened to the base value.
+ */
+type ResolvedTokenLiteral = string | number | boolean | undefined;
+/**
+ * Looks up another token by `namespace/name`. Injected by the parent
+ * Config so `Token.derived.value` can chase `token()` aliases without
+ * holding a back-ref to the whole config object.
+ */
+type TokenSiblingLookup = (qualifiedName: string) => Token | undefined;
+declare class Token {
+  #private;
+  readonly name: string;
+  readonly namespace: string;
+  readonly value: TokenValue;
+  readonly type?: TokenType;
+  readonly modifiers?: Record<TokenModifierKey, TokenModifierValue>;
+  constructor(args: {
+    name: string;
+    namespace: string;
+    prefixGetter: () => string;
+    definition: TokenDefinition;
+    lookup: TokenSiblingLookup;
+    groupTypeGetter: () => TokenType | undefined;
+  });
+  /**
+   * Sniff a raw value to its best-guess CSS value type. Static so
+   * picker UIs (authoring a new token with no `Token` instance yet)
+   * can reach the same heuristic the class uses internally. Returns
+   * `undefined` when no confident match is possible (e.g. `var(...)`
+   * references).
+   */
+  static sniffValueType(value: string): TokenType | undefined;
+  get derived(): {
+    readonly namespace: string;
+    readonly qualifiedName: string;
+    readonly cssSafeName: CssClassName;
+    readonly cssVar: CssVar;
+    readonly cssVarRef: CssVarRef;
+    readonly value: ResolvedTokenLiteral;
+    readonly cssValueType: CssValueTypeName | undefined;
+    modifierValues(): Iterable<[TokenModifierKey, ResolvedTokenLiteral]>;
+  };
+  toJSON(): TokenDefinition & {
+    name: string;
+  };
+} //#endregion
+//#endregion
+export { ResolvedTokenLiteral, Token, TokenSiblingLookup };

package/dist/config/dist/Token.js

@@ -0,0 +1,112 @@
+import { buildCssVar, kebabCase, toCssSafeName } from "./entity-utils.js";
+import { isTokenRef } from "./refs.js";
+import { resolveTokenValueType, sniffTokenType } from "./tokenValueType.js";
+//#region ../config/dist/Token.js
+var Token = class {
+	name;
+	namespace;
+	value;
+	type;
+	modifiers;
+	#prefixGetter;
+	#lookup;
+	#groupTypeGetter;
+	#derived;
+	constructor(args) {
+		this.name = args.name;
+		this.namespace = args.namespace;
+		this.value = args.definition.value;
+		this.type = args.definition.type;
+		this.modifiers = collectModifiers(args.definition);
+		this.#prefixGetter = args.prefixGetter;
+		this.#lookup = args.lookup;
+		this.#groupTypeGetter = args.groupTypeGetter;
+	}
+	/**
+	* Sniff a raw value to its best-guess CSS value type. Static so
+	* picker UIs (authoring a new token with no `Token` instance yet)
+	* can reach the same heuristic the class uses internally. Returns
+	* `undefined` when no confident match is possible (e.g. `var(...)`
+	* references).
+	*/
+	static sniffValueType(value) {
+		return sniffTokenType(value);
+	}
+	get derived() {
+		if (!this.#derived) {
+			const name = this.name;
+			const namespace = this.namespace;
+			const tokenValue = this.value;
+			const tokenType = this.type;
+			const modifiers = this.modifiers;
+			const prefixGetter = this.#prefixGetter;
+			const lookup = this.#lookup;
+			const groupTypeGetter = this.#groupTypeGetter;
+			this.#derived = {
+				namespace,
+				qualifiedName: `${kebabCase(namespace)}/${kebabCase(name)}`,
+				cssSafeName: toCssSafeName(name),
+				get cssVar() {
+					return buildCssVar(prefixGetter(), namespace, name);
+				},
+				get cssVarRef() {
+					return `var(${buildCssVar(prefixGetter(), namespace, name)})`;
+				},
+				get value() {
+					return chaseLiteral(tokenValue, lookup);
+				},
+				get cssValueType() {
+					const literal = chaseLiteral(tokenValue, lookup);
+					return resolveTokenValueType({
+						value: typeof literal === "string" ? literal : String(tokenValue),
+						type: tokenType
+					}, groupTypeGetter());
+				},
+				*modifierValues() {
+					if (!modifiers) return;
+					for (const [key, value] of Object.entries(modifiers)) yield [key, resolveModifierLiteral(value, lookup)];
+				}
+			};
+		}
+		return this.#derived;
+	}
+	toJSON() {
+		const out = {
+			name: this.name,
+			value: this.value
+		};
+		if (this.type !== void 0) out.type = this.type;
+		if (this.modifiers) for (const [key, value] of Object.entries(this.modifiers)) out[key] = value;
+		return out;
+	}
+};
+/**
+* Scan a `TokenDefinition` for flat `_${string}` modifier keys and pack
+* them into a single `modifiers` map. Returns `undefined` when no
+* modifier keys are present so the class field can stay optional.
+*/
+function collectModifiers(definition) {
+	const modifiers = {};
+	let count = 0;
+	for (const [key, value] of Object.entries(definition)) if (key.startsWith("_")) {
+		modifiers[key] = value;
+		count++;
+	}
+	return count > 0 ? modifiers : void 0;
+}
+function chaseLiteral(value, lookup, seen = /* @__PURE__ */ new Set()) {
+	if (isTokenRef(value)) {
+		if (seen.has(value.ref)) return void 0;
+		seen.add(value.ref);
+		const next = lookup(value.ref);
+		if (!next) return void 0;
+		return chaseLiteral(next.value, lookup, seen);
+	}
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+}
+function resolveModifierLiteral(value, lookup) {
+	if (typeof value === "object" && value !== null && "value" in value) return chaseLiteral(value.value, lookup);
+	return chaseLiteral(value, lookup);
+}
+//#endregion
+export { Token };

package/dist/config/dist/TokenGroup.d.ts

@@ -0,0 +1,33 @@
+import { SerializedTokenGroup, TokenGroupDefinition } from "./types.js";
+import { Token, TokenSiblingLookup } from "./Token.js";
+
+//#region ../config/dist/TokenGroup.d.ts
+//#region src/TokenGroup.d.ts
+type StylePropertiesLookup = (namespace: string) => readonly string[];
+declare class TokenGroup {
+  #private;
+  readonly namespace: string;
+  readonly label?: string;
+  readonly description?: string;
+  readonly tokens: ReadonlyMap<string, Token>;
+  constructor(args: {
+    namespace: string;
+    prefixGetter: () => string;
+    definition: TokenGroupDefinition;
+    tokenLookup: TokenSiblingLookup;
+    stylePropertiesLookup: StylePropertiesLookup;
+  });
+  get derived(): {
+    readonly cssPrefix: string;
+    readonly styleProperties: readonly string[];
+  };
+  /**
+   * Wire shape: `{ tokens, label?, description? }`. Token entries live
+   * nested under `tokens` so meta keys can never collide with token
+   * names — a token named `'label'` is fine. The parent record's key
+   * carries the namespace, so it's omitted here.
+   */
+  toJSON(): SerializedTokenGroup;
+} //#endregion
+//#endregion
+export { TokenGroup };

package/dist/config/dist/TokenGroup.js

@@ -0,0 +1,68 @@
+import { kebabCase } from "./entity-utils.js";
+import { Token } from "./Token.js";
+//#region ../config/dist/TokenGroup.js
+/**
+* `TokenGroup` — a namespace of tokens (`color`, `spacing`).
+*
+* Owns its tokens and exposes `.derived.styleProperties` — the
+* style-prop names whose `values` array references this group. The
+* `styleProperties` computation needs sibling style-props, supplied by
+* the parent `Config` via the `styleProperties` callable.
+*/
+var TokenGroup = class {
+	namespace;
+	label;
+	description;
+	tokens;
+	#stylePropertiesLookup;
+	#derived;
+	constructor(args) {
+		this.namespace = args.namespace;
+		const groupTypeGetter = () => void 0;
+		if (args.definition.label !== void 0) this.label = args.definition.label;
+		if (args.definition.description !== void 0) this.description = args.definition.description;
+		const tokens = /* @__PURE__ */ new Map();
+		for (const [name, tokenDef] of Object.entries(args.definition.tokens)) tokens.set(name, new Token({
+			name,
+			namespace: args.namespace,
+			prefixGetter: args.prefixGetter,
+			definition: tokenDef,
+			lookup: args.tokenLookup,
+			groupTypeGetter
+		}));
+		this.tokens = tokens;
+		this.#stylePropertiesLookup = args.stylePropertiesLookup;
+	}
+	get derived() {
+		if (!this.#derived) {
+			const namespace = this.namespace;
+			const lookup = this.#stylePropertiesLookup;
+			this.#derived = {
+				cssPrefix: kebabCase(namespace),
+				get styleProperties() {
+					return lookup(namespace);
+				}
+			};
+		}
+		return this.#derived;
+	}
+	/**
+	* Wire shape: `{ tokens, label?, description? }`. Token entries live
+	* nested under `tokens` so meta keys can never collide with token
+	* names — a token named `'label'` is fine. The parent record's key
+	* carries the namespace, so it's omitted here.
+	*/
+	toJSON() {
+		const tokens = {};
+		for (const [name, token] of this.tokens) {
+			const { name: _omit, ...rest } = token.toJSON();
+			tokens[name] = rest;
+		}
+		const out = { tokens };
+		if (this.label !== void 0) out.label = this.label;
+		if (this.description !== void 0) out.description = this.description;
+		return out;
+	}
+};
+//#endregion
+export { TokenGroup };

package/dist/config/dist/asset-kind.d.ts

@@ -0,0 +1,56 @@
+//#region ../config/dist/asset-kind.d.ts
+//#region src/asset-kind.d.ts
+/**
+ * `assetKind` — what class of asset a group holds (icons, fonts, …).
+ *
+ * Every asset group picks one of these labels when it's defined (via
+ * `.config({ type })`), and we store it on the group as `assetKind`.
+ *
+ * Why `assetKind` and not just `kind`? Asset groups already carry a
+ * separate tag, `__kind: 'assetGroup'`, that marks them as asset-group
+ * refs. That tag is the same for every group regardless of class, and
+ * the check that relies on it (`isAssetGroupRef()`) must stay that way.
+ * If we also called this field `kind`, the two would collide and blur
+ * the distinction between "is this an asset group?" and "what kind of
+ * asset is in it?". So this field gets its own name: `__kind` answers
+ * the first question, `assetKind` answers the second.
+ *
+ * Behavior differences between classes live in one table below and are
+ * read through small helpers like `isPlaceable()`. That keeps callers
+ * from branching on the class directly (no "is this a font?" checks
+ * scattered around), and adding a new class means adding one row here
+ * plus its member contract — not new branches everywhere.
+ */
+type AssetKind = 'icon' | 'font';
+/**
+ * Per-class capability record. `placeable` — whether members of this
+ * class become canvas nodes (icons do; fonts are consumed via
+ * `font-family` token refs and never placed). Both hard guards read
+ * this through `isPlaceable()`: the `makeRegistry` asset loop and the
+ * `.accepts()` config-load throw.
+ *
+ * Classes we expect to add later (each is one new row here plus its
+ * member contract — and likely `placeable: true`):
+ * - images — bitmap assets (PNG/JPEG/WebP) dropped onto the canvas
+ * - illustrations — vector artwork (SVG) placed as canvas nodes
+ * - logos — brand marks, a constrained flavor of image/vector asset
+ * - videos — playable media placed as canvas nodes
+ */
+declare const ASSET_CLASS_CAPABILITIES: {
+  readonly icon: {
+    readonly placeable: true;
+  };
+  readonly font: {
+    readonly placeable: false;
+  };
+};
+/**
+ * Whether a group's members can fill slots and become canvas nodes.
+ * Accepts anything carrying the stamped `assetKind` — both the
+ * authored `AssetGroupDefinition` and the registered `AssetGroup`.
+ */
+declare function isPlaceable(group: {
+  readonly assetKind: AssetKind;
+}): boolean; //#endregion
+//#endregion
+export { ASSET_CLASS_CAPABILITIES, AssetKind, isPlaceable };

package/dist/config/dist/asset-kind.js

@@ -0,0 +1,29 @@
+//#region ../config/dist/asset-kind.js
+/**
+* Per-class capability record. `placeable` — whether members of this
+* class become canvas nodes (icons do; fonts are consumed via
+* `font-family` token refs and never placed). Both hard guards read
+* this through `isPlaceable()`: the `makeRegistry` asset loop and the
+* `.accepts()` config-load throw.
+*
+* Classes we expect to add later (each is one new row here plus its
+* member contract — and likely `placeable: true`):
+* - images — bitmap assets (PNG/JPEG/WebP) dropped onto the canvas
+* - illustrations — vector artwork (SVG) placed as canvas nodes
+* - logos — brand marks, a constrained flavor of image/vector asset
+* - videos — playable media placed as canvas nodes
+*/
+const ASSET_CLASS_CAPABILITIES = {
+	icon: { placeable: true },
+	font: { placeable: false }
+};
+/**
+* Whether a group's members can fill slots and become canvas nodes.
+* Accepts anything carrying the stamped `assetKind` — both the
+* authored `AssetGroupDefinition` and the registered `AssetGroup`.
+*/
+function isPlaceable(group) {
+	return ASSET_CLASS_CAPABILITIES[group.assetKind].placeable;
+}
+//#endregion
+export { ASSET_CLASS_CAPABILITIES, isPlaceable };

package/dist/config/dist/brands.d.ts

@@ -0,0 +1,31 @@
+//#region ../config/dist/brands.d.ts
+//#region src/brands.d.ts
+/**
+ * Branded CSS string types.
+ *
+ * Every member that emits CSS — variable refs, selectors, class names,
+ * declarations — returns a `Css<Kind>` instead of a plain `string`. The
+ * brand erases at runtime; the compiler uses it to catch raw user strings
+ * being passed into a CSS-emission slot.
+ *
+ * Brands are a one-way door: once they flow through the codegen surface
+ * we lean on them at every emission site, so we lock the shape in here.
+ */
+type Css<Kind extends string> = string & {
+  readonly __cssBrand: Kind;
+};
+type CssVar = Css<'var'>;
+type CssSelector = Css<'selector'>;
+type CssClassName = Css<'className'>;
+type CssDeclaration = Css<'declaration'>;
+/**
+ * Stamp a plain string with a CSS brand. The brand is a phantom — no
+ * runtime work. All emission helpers funnel through these so the cast
+ * lives in one place.
+ */
+declare function cssVar(value: string): CssVar;
+declare function cssSelector(value: string): CssSelector;
+declare function cssClassName(value: string): CssClassName;
+declare function cssDeclaration(value: string): CssDeclaration; //#endregion
+//#endregion
+export { Css, CssClassName, CssDeclaration, CssSelector, CssVar, cssClassName, cssDeclaration, cssSelector, cssVar };

package/dist/config/dist/brands.js

@@ -0,0 +1,20 @@
+//#region ../config/dist/brands.js
+/**
+* Stamp a plain string with a CSS brand. The brand is a phantom — no
+* runtime work. All emission helpers funnel through these so the cast
+* lives in one place.
+*/
+function cssVar(value) {
+	return value;
+}
+function cssSelector(value) {
+	return value;
+}
+function cssClassName(value) {
+	return value;
+}
+function cssDeclaration(value) {
+	return value;
+}
+//#endregion
+export { cssClassName, cssDeclaration, cssSelector, cssVar };

package/dist/config/dist/captureCallerPath.d.ts

@@ -0,0 +1,49 @@
+//#region ../config/dist/captureCallerPath.d.ts
+//#region src/captureCallerPath.d.ts
+/**
+ * Inspect the current call stack and return the first frame whose file
+ * path sits outside the `@uds/config` package itself — i.e. the
+ * user's authoring site.
+ *
+ * Stashing the path at definition time gives every config object its
+ * origin for free. Consumers (codegen, CSS scanner, AI prompt builder)
+ * read `__sourcePath` off the config map directly instead of walking
+ * the AST to re-derive where each registration was authored.
+ *
+ * The skip predicate matches `/packages/config/` (workspace
+ * layout) and `/@uds/config/` (consumer node_modules layout) so
+ * internal frames never leak through. Returns `undefined` when no
+ * eligible frame is found.
+ *
+ * Stack format coverage:
+ *  - Bun / V8 in-process: `    at fn (/abs/path.ts:L:C)` or bare
+ *    `    at /abs/path.ts:L:C` (no parens).
+ *  - Node native stacks: `file:///abs/path.ts:L:C` URL form.
+ *  - Source-mapped frames downleveled through tsdown: `.js` files.
+ *
+ * The regex picks the first `(...).ext:line:col` token; the
+ * surrounding `at fn` / paren wrapping is ignored.
+ */
+declare function captureCallerPath(): string | undefined;
+/**
+ * Non-enumerable `__sourcePath` slot key. Centralized so codegen
+ * consumers and authoring helpers agree on one spelling.
+ */
+declare const SOURCE_PATH_KEY: "__sourcePath";
+/**
+ * Attach `__sourcePath` to a config object non-enumerably.
+ * `JSON.stringify` ignores non-enumerable properties so the wire format
+ * stays clean.
+ *
+ * No-op when `path` is `undefined` — keeps the config shape stable
+ * when the stack-walk yields no eligible frame.
+ */
+declare function attachSourcePath<T extends object>(target: T, path: string | undefined): T;
+/**
+ * Read `__sourcePath` off a config object. Returns `undefined` when
+ * the slot was never set (e.g. configs produced outside the `define*`
+ * helpers).
+ */
+declare function readSourcePath(target: unknown): string | undefined; //#endregion
+//#endregion
+export { SOURCE_PATH_KEY, attachSourcePath, captureCallerPath, readSourcePath };