@yahoo/uds-create-utils 1.1.1

package/dist/array-utils/closestItem.d.ts

@@ -0,0 +1,4 @@
+//#region src/array-utils/closestItem.d.ts
+declare function closestItem<T>(arr: T[], item: T): T;
+//#endregion
+export { closestItem };

package/dist/array-utils/closestItem.js

@@ -0,0 +1,9 @@
+//#region src/array-utils/closestItem.ts
+function closestItem(arr, item) {
+	const index = arr.indexOf(item);
+	if (index === -1) return arr[0];
+	if (index === arr.length - 1) return arr[arr.length - 2];
+	return arr[index + 1];
+}
+//#endregion
+export { closestItem };

package/dist/array-utils/removeItem.d.ts

@@ -0,0 +1,4 @@
+//#region src/array-utils/removeItem.d.ts
+declare function removeItem<T>([...arr]: T[], item: T): T[];
+//#endregion
+export { removeItem };

package/dist/array-utils/removeItem.js

@@ -0,0 +1,8 @@
+//#region src/array-utils/removeItem.ts
+function removeItem([ ...arr], item) {
+	const index = arr.indexOf(item);
+	index > -1 && arr.splice(index, 1);
+	return arr;
+}
+//#endregion
+export { removeItem };

package/dist/arrayUtils.d.ts

@@ -0,0 +1,4 @@
+//#region src/arrayUtils.d.ts
+declare function closestItem<T>(arr: T[], item: T): T;
+//#endregion
+export { closestItem };

package/dist/arrayUtils.js

@@ -0,0 +1,9 @@
+//#region src/arrayUtils.ts
+function closestItem(arr, item) {
+	const index = arr.indexOf(item);
+	if (index === -1) return arr[0];
+	if (index === arr.length - 1) return arr[arr.length - 2];
+	return arr[index + 1];
+}
+//#endregion
+export { closestItem };

package/dist/component-style-defaults.d.ts

@@ -0,0 +1,5 @@
+//#region src/component-style-defaults.d.ts
+type ComponentStyleDefaultsInput = Record<string, unknown>;
+declare function applyComponentStyleDefaults(componentName: string, styleProps: ComponentStyleDefaultsInput): ComponentStyleDefaultsInput;
+//#endregion
+export { ComponentStyleDefaultsInput, applyComponentStyleDefaults };

package/dist/component-style-defaults.js

@@ -0,0 +1,68 @@
+//#region src/component-style-defaults.ts
+function toStringValue(value) {
+	return typeof value === "string" ? value : String(value);
+}
+function applyComponentStyleDefaults(componentName, styleProps) {
+	if (componentName === "HStack") {
+		const { gap, display = "flex", flexDirection = display === "flex" ? "row" : void 0, alignItems = display === "flex" ? "center" : void 0, ...rest } = styleProps;
+		return {
+			flexDirection,
+			display,
+			alignItems,
+			gapX: gap,
+			...rest
+		};
+	}
+	if (componentName === "VStack") {
+		const { gap, display = "flex", flexDirection = display === "flex" ? "col" : void 0, ...rest } = styleProps;
+		return {
+			flexDirection,
+			display,
+			gapY: gap,
+			...rest
+		};
+	}
+	if (componentName === "Grid") {
+		const { columns, rows, autoFit, autoFill, inline, display, gridTemplateColumns, gridTemplateRows, ...rest } = styleProps;
+		return {
+			display: display ?? (inline ? "inline-grid" : "grid"),
+			gridTemplateColumns: gridTemplateColumns ?? (autoFit ? `[repeat(auto-fit,minmax(${toStringValue(autoFit)},1fr))]` : autoFill ? `[repeat(auto-fill,minmax(${toStringValue(autoFill)},1fr))]` : columns),
+			gridTemplateRows: gridTemplateRows ?? rows,
+			...rest
+		};
+	}
+	if (componentName === "GridItem") {
+		const { colSpan, rowSpan, colStart, colEnd, rowStart, rowEnd, gridColumnSpan, gridRowSpan, gridColumnStart, gridColumnEnd, gridRowStart, gridRowEnd, ...rest } = styleProps;
+		return {
+			gridColumnSpan: gridColumnSpan ?? colSpan,
+			gridRowSpan: gridRowSpan ?? rowSpan,
+			gridColumnStart: gridColumnStart ?? colStart,
+			gridColumnEnd: gridColumnEnd ?? colEnd,
+			gridRowStart: gridRowStart ?? rowStart,
+			gridRowEnd: gridRowEnd ?? rowEnd,
+			...rest
+		};
+	}
+	if (componentName === "Button") return {
+		cursor: "pointer",
+		...styleProps
+	};
+	if (componentName === "Avatar") {
+		const { shape, ...rest } = styleProps;
+		return {
+			borderRadius: shape,
+			...rest
+		};
+	}
+	if (componentName === "Svg") {
+		const { viewBox, width, height, strokeWidth, ...rest } = styleProps;
+		return {
+			minWidth: viewBox && width && height ? "fit" : void 0,
+			...rest,
+			strokeWidth
+		};
+	}
+	return styleProps;
+}
+//#endregion
+export { applyComponentStyleDefaults };

package/dist/config-snippet.d.ts

@@ -0,0 +1,15 @@
+//#region src/config-snippet.d.ts
+/**
+ * Shared utilities for extracting and formatting UDS component config snippets.
+ * Used by both the docs app and codegen to display component configuration.
+ */
+/**
+ * Build a formatted component config snippet from raw config source code.
+ *
+ * @param componentName - PascalCase component name (e.g. "Button")
+ * @param componentConfigSource - Raw source code of the config file
+ * @param modifierMappings - Map of modifier names to Tailwind prefixes (e.g. { _hover: "hover:" })
+ */
+declare function buildComponentConfigSnippet(componentName: string, componentConfigSource: string, modifierMappings?: Record<string, string>): string;
+//#endregion
+export { buildComponentConfigSnippet };

package/dist/config-snippet.js

@@ -0,0 +1,261 @@
+//#region src/config-snippet.ts
+/**
+* Shared utilities for extracting and formatting UDS component config snippets.
+* Used by both the docs app and codegen to display component configuration.
+*/
+function findMatchingBrace(source, openBraceIndex) {
+	let depth = 0;
+	let inSingle = false;
+	let inDouble = false;
+	let inTemplate = false;
+	let inLineComment = false;
+	let inBlockComment = false;
+	for (let i = openBraceIndex; i < source.length; i += 1) {
+		const ch = source[i];
+		const next = source[i + 1];
+		const prev = source[i - 1];
+		if (inLineComment) {
+			if (ch === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			if (prev === "*" && ch === "/") inBlockComment = false;
+			continue;
+		}
+		if (!inSingle && !inDouble && !inTemplate) {
+			if (ch === "/" && next === "/") {
+				inLineComment = true;
+				i += 1;
+				continue;
+			}
+			if (ch === "/" && next === "*") {
+				inBlockComment = true;
+				i += 1;
+				continue;
+			}
+		}
+		if (!inDouble && !inTemplate && ch === "'" && prev !== "\\") {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (!inSingle && !inTemplate && ch === "\"" && prev !== "\\") {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (!inSingle && !inDouble && ch === "`" && prev !== "\\") {
+			inTemplate = !inTemplate;
+			continue;
+		}
+		if (inSingle || inDouble || inTemplate) continue;
+		if (ch === "{") depth += 1;
+		if (ch === "}") {
+			depth -= 1;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Match a new-API single-call form:
+*
+*   export const Box = defineComponent('div').config(({ styleProp }) => ({...}));
+*   export const VStack = defineComponent(Box).config(() => ({ defaultProps: {...} }));
+*
+* Returns the full `defineComponent(...)` call expression as a snippet
+* (suitable for direct display in a source-config tab) or `null` when
+* the pattern isn't present.
+*/
+function extractNewApiComponentBlock(source, componentName) {
+	const match = new RegExp(`(?:^|[\\s;])(?:export\\s+)?const\\s+${componentName}\\s*=\\s*defineComponent\\s*\\(`, "m").exec(source);
+	if (!match) return null;
+	const openParenIndex = match.index + match[0].length - 1;
+	let depth = 0;
+	let inSingle = false;
+	let inDouble = false;
+	let inTemplate = false;
+	for (let i = openParenIndex; i < source.length; i += 1) {
+		const ch = source[i];
+		const prev = source[i - 1];
+		if (!inDouble && !inTemplate && ch === "'" && prev !== "\\") {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (!inSingle && !inTemplate && ch === "\"" && prev !== "\\") {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (!inSingle && !inDouble && ch === "`" && prev !== "\\") {
+			inTemplate = !inTemplate;
+			continue;
+		}
+		if (inSingle || inDouble || inTemplate) continue;
+		if (ch === "(") depth += 1;
+		if (ch === ")") {
+			depth -= 1;
+			if (depth === 0) {
+				const callStart = match.index + match[0].indexOf("defineComponent");
+				let end = i + 1;
+				while (end < source.length) {
+					const chainMatch = /^\s*\.(config|render|metadata)\s*\(/.exec(source.slice(end));
+					if (!chainMatch) break;
+					let chainDepth = 0;
+					let chainInSingle = false;
+					let chainInDouble = false;
+					let chainInTemplate = false;
+					let j = end + chainMatch[0].length - 1;
+					for (; j < source.length; j += 1) {
+						const cch = source[j];
+						const cprev = source[j - 1];
+						if (!chainInDouble && !chainInTemplate && cch === "'" && cprev !== "\\") {
+							chainInSingle = !chainInSingle;
+							continue;
+						}
+						if (!chainInSingle && !chainInTemplate && cch === "\"" && cprev !== "\\") {
+							chainInDouble = !chainInDouble;
+							continue;
+						}
+						if (!chainInSingle && !chainInDouble && cch === "`" && cprev !== "\\") {
+							chainInTemplate = !chainInTemplate;
+							continue;
+						}
+						if (chainInSingle || chainInDouble || chainInTemplate) continue;
+						if (cch === "(") chainDepth += 1;
+						if (cch === ")") {
+							chainDepth -= 1;
+							if (chainDepth === 0) {
+								end = j + 1;
+								break;
+							}
+						}
+					}
+					if (chainDepth !== 0) break;
+				}
+				return source.slice(callStart, end);
+			}
+		}
+	}
+	return null;
+}
+function extractDefinitionComponentBlock(source, componentName) {
+	const newApi = extractNewApiComponentBlock(source, componentName);
+	if (newApi) return newApi;
+	const defineComponentIndex = source.indexOf("defineComponent");
+	if (defineComponentIndex < 0) return null;
+	const quotedNameIndex = [`'${componentName}'`, `"${componentName}"`].map((pattern) => source.indexOf(pattern, defineComponentIndex)).find((index) => index >= 0);
+	if (quotedNameIndex != null && quotedNameIndex >= 0) {
+		const arrowIndex = source.indexOf("=>", quotedNameIndex);
+		if (arrowIndex < 0) return null;
+		const openParenIndex = source.indexOf("(", arrowIndex);
+		if (openParenIndex < 0) return null;
+		const openBraceIndex = source.indexOf("{", openParenIndex);
+		if (openBraceIndex < 0) return null;
+		const closeBraceIndex = findMatchingBrace(source, openBraceIndex);
+		if (closeBraceIndex < 0) return null;
+		return `  ${componentName}: ${source.slice(openBraceIndex, closeBraceIndex + 1)},`;
+	}
+	const keyMatch = new RegExp(`(?:^|[\\s,({])${componentName}\\s*:\\s*\\{`, "m").exec(source.slice(defineComponentIndex));
+	if (!keyMatch) return null;
+	const matchStart = defineComponentIndex + keyMatch.index;
+	const braceOffset = source.indexOf("{", matchStart + keyMatch[0].indexOf(componentName));
+	if (braceOffset < 0) return null;
+	const closeBraceIndex = findMatchingBrace(source, braceOffset);
+	if (closeBraceIndex < 0) return null;
+	return `  ${componentName}: ${source.slice(braceOffset, closeBraceIndex + 1)},`;
+}
+function extractAtomicTokenAliases(source) {
+	const aliasesByGroup = /* @__PURE__ */ new Map();
+	const addAlias = (group, alias) => {
+		if (!group || !alias) return;
+		const aliases = aliasesByGroup.get(group) ?? /* @__PURE__ */ new Set();
+		aliases.add(alias);
+		aliasesByGroup.set(group, aliases);
+	};
+	for (const match of source.matchAll(/tokens\.([a-zA-Z_$][a-zA-Z0-9_$]*)\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g)) addAlias(match[1], match[2]);
+	for (const match of source.matchAll(/tokens\.([a-zA-Z_$][a-zA-Z0-9_$]*)\[['"]([^'"\\]+)['"]\]/g)) addAlias(match[1], match[2]);
+	return aliasesByGroup;
+}
+function buildTokenHeaderComment(componentName, block) {
+	const groups = [...extractAtomicTokenAliases(block).entries()].sort(([a], [b]) => a.localeCompare(b));
+	if (groups.length === 0) return "";
+	return `// Required token aliases for this ${componentName} config:\n${groups.map(([group, aliases]) => {
+		return `// - ${group}: ${[...aliases].sort((a, b) => a.localeCompare(b)).join(", ")}`;
+	}).join("\n")}`;
+}
+/**
+* Replace `textVariants.<variant>.root` with `components.Text.variant.<variant>`
+* so the snippet is self-contained without the internal textVariants import.
+*/
+function expandTextVariantRefs(block) {
+	return block.replace(/textVariants\.([a-zA-Z0-9_]+)\.root/g, "components.Text.variant.$1");
+}
+/**
+* Extract modifier prop names (`_foo`) used as object keys in the config block.
+*/
+function extractModifierNames(block) {
+	const pattern = /\b(_[a-zA-Z][a-zA-Z0-9]*)\s*:/g;
+	const names = /* @__PURE__ */ new Set();
+	for (const match of block.matchAll(pattern)) names.add(match[1]);
+	return [...names].sort((a, b) => a.localeCompare(b));
+}
+/**
+* Convert a Tailwind modifier prefix to a CSS selector.
+* e.g. "hover:" -> "&:hover"
+*      "data-[state=open]:" -> "&[data-state=open]"
+*      "aria-expanded:" -> "&[aria-expanded=true]"
+*/
+function tailwindPrefixToSelector(prefix) {
+	const raw = prefix.replace(/:$/, "");
+	if (raw.startsWith("data-[") && raw.endsWith("]")) return `&[data-${raw.slice(6, -1)}]`;
+	if (raw.startsWith("aria-")) return `&[${raw}=true]`;
+	if (raw.startsWith("*::")) return `& ${raw.slice(1)}`;
+	if (raw === "starting-style") return "@starting-style";
+	return `&:${raw}`;
+}
+/**
+* Build a modifier comment + `.defineModifiers([...])` snippet
+* for modifiers used in the config block.
+*/
+function buildModifierSnippet(block, modifierMappings) {
+	const names = extractModifierNames(block);
+	if (names.length === 0) return "";
+	const matched = names.filter((name) => name in modifierMappings);
+	if (matched.length === 0) return "";
+	return `${`// Modifiers used:\n${matched.map((name) => `//   ${name} → ${modifierMappings[name]}`).join("\n")}\n`}${`.defineModifiers([\n${matched.map((name) => {
+		return `    { modifier: '${name}', selector: '${tailwindPrefixToSelector(modifierMappings[name])}' },`;
+	}).join("\n")}\n  ])\n  `}`;
+}
+/**
+* Build a formatted component config snippet from raw config source code.
+*
+* @param componentName - PascalCase component name (e.g. "Button")
+* @param componentConfigSource - Raw source code of the config file
+* @param modifierMappings - Map of modifier names to Tailwind prefixes (e.g. { _hover: "hover:" })
+*/
+function buildComponentConfigSnippet(componentName, componentConfigSource, modifierMappings = {}) {
+	const newApi = extractNewApiComponentBlock(componentConfigSource, componentName);
+	if (newApi) return `import { defineComponent } from '@yahoo/uds-create-config';
+
+export const ${componentName} = ${newApi};`;
+	let block = extractDefinitionComponentBlock(componentConfigSource, componentName);
+	if (block) {
+		block = expandTextVariantRefs(block);
+		const params = block.includes("components.") ? "{ tokens, components }" : "{ tokens }";
+		const modifierSnippet = buildModifierSnippet(block, modifierMappings);
+		return `${buildTokenHeaderComment(componentName, block)}
+${modifierSnippet}.defineComponents((${params}) => ({
+${block}
+}))`;
+	}
+	return `// ${componentName} config file was not found or could not be parsed.
+// Add this builder snippet to override it:
+// ${componentName} required token aliases: none detected
+.defineComponents(({ tokens }) => ({
+  ${componentName}: {
+    base: {
+      root: {},
+    },
+  },
+}))`;
+}
+//#endregion
+export { buildComponentConfigSnippet };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { ComponentStyleDefaultsInput, applyComponentStyleDefaults } from "./component-style-defaults.js";
+import { closestItem } from "./array-utils/closestItem.js";
+import { removeItem } from "./array-utils/removeItem.js";
+import { clamp } from "./math-utils/clamp.js";
+import { interpolate } from "./motion-utils/interpolate.js";
+import { resolveInterpolate, resolveMotionState } from "./motion-utils/resolveMotionState.js";
+import { entries } from "./object-utils/entries.js";
+import { flattenObj } from "./object-utils/flattenObj.js";
+import { fromEntries } from "./object-utils/fromEntries.js";
+import { keys } from "./object-utils/keys.js";
+import { mapKeys } from "./object-utils/mapKeys.js";
+import { mapValues } from "./object-utils/mapValues.js";
+import { arrayToUnion } from "./string-utils/arrayToUnion.js";
+import { capitalize } from "./string-utils/capitalize.js";
+import { ComponentClassNames, componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass } from "./string-utils/componentClassName.js";
+import { createTemplate, interfaceTemplate, template, typeTemplate } from "./string-utils/createTemplate.js";
+import { KebabCase, kebabCase } from "./string-utils/kebabCase.js";
+import { CssVar, CssVarName, cssVar, cssVarDeclarations, cssVarName, safeTokenName } from "./string-utils/cssVar.js";
+import { cssVars } from "./string-utils/cssVars.js";
+import { dedent, dedentTS } from "./string-utils/dedent.js";
+import { indent } from "./string-utils/indent.js";
+import { join } from "./string-utils/join.js";
+import { split } from "./string-utils/split.js";
+import { tsProperties, tsTypes } from "./string-utils/tsProperties.js";
+export { type ComponentClassNames, type ComponentStyleDefaultsInput, type CssVar, type CssVarName, type KebabCase, applyComponentStyleDefaults, arrayToUnion, capitalize, clamp, closestItem, componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass, createTemplate, cssVar, cssVarDeclarations, cssVarName, cssVars, dedent, dedentTS, entries, flattenObj, fromEntries, indent, interfaceTemplate, interpolate, join, kebabCase, keys, mapKeys, mapValues, removeItem, resolveInterpolate, resolveMotionState, safeTokenName, split, template, tsProperties, tsTypes, typeTemplate };

package/dist/index.js

@@ -0,0 +1,25 @@
+import { applyComponentStyleDefaults } from "./component-style-defaults.js";
+import { closestItem } from "./array-utils/closestItem.js";
+import { removeItem } from "./array-utils/removeItem.js";
+import { clamp } from "./math-utils/clamp.js";
+import { interpolate } from "./motion-utils/interpolate.js";
+import { resolveInterpolate, resolveMotionState } from "./motion-utils/resolveMotionState.js";
+import { entries } from "./object-utils/entries.js";
+import { flattenObj } from "./object-utils/flattenObj.js";
+import { fromEntries } from "./object-utils/fromEntries.js";
+import { keys } from "./object-utils/keys.js";
+import { mapKeys } from "./object-utils/mapKeys.js";
+import { mapValues } from "./object-utils/mapValues.js";
+import { arrayToUnion } from "./string-utils/arrayToUnion.js";
+import { capitalize } from "./string-utils/capitalize.js";
+import { kebabCase } from "./string-utils/kebabCase.js";
+import { componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass } from "./string-utils/componentClassName.js";
+import { createTemplate, interfaceTemplate, template, typeTemplate } from "./string-utils/createTemplate.js";
+import { cssVar, cssVarDeclarations, cssVarName, safeTokenName } from "./string-utils/cssVar.js";
+import { cssVars } from "./string-utils/cssVars.js";
+import { dedent, dedentTS } from "./string-utils/dedent.js";
+import { indent } from "./string-utils/indent.js";
+import { join } from "./string-utils/join.js";
+import { split } from "./string-utils/split.js";
+import { tsProperties, tsTypes } from "./string-utils/tsProperties.js";
+export { applyComponentStyleDefaults, arrayToUnion, capitalize, clamp, closestItem, componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass, createTemplate, cssVar, cssVarDeclarations, cssVarName, cssVars, dedent, dedentTS, entries, flattenObj, fromEntries, indent, interfaceTemplate, interpolate, join, kebabCase, keys, mapKeys, mapValues, removeItem, resolveInterpolate, resolveMotionState, safeTokenName, split, template, tsProperties, tsTypes, typeTemplate };

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+//#region src/logger.d.ts
+declare const logger: {
+  /** Enable `logger.debug()` output (set via `--verbose` flag). */setVerbose(value: boolean): void; /** Suppress everything except errors (set via `--quiet` flag). */
+  setQuiet(value: boolean): void;
+  /**
+   * Route stdout-bound logs to stderr. Enable when stdout carries a protocol
+   * stream that must stay free of log noise — e.g. the MCP stdio transport,
+   * where a stray banner line corrupts the JSON-RPC framing.
+   */
+  setStderr(value: boolean): void; /** Green check — a step completed successfully. */
+  success(message: string): void; /** Neutral informational message. */
+  info(message: string): void; /** Yellow warning — something is off but not fatal. */
+  warn(message: string): void; /** Red error — always printed, even in quiet mode. */
+  error(message: string, cause?: unknown): void; /** Indented sub-line for detail beneath a success/info message. */
+  detail(message: string): void; /** Only printed when `--verbose` is active. */
+  debug(message: string): void; /** Highlight a file path or URL inside a message. */
+  path(value: string): string;
+};
+//#endregion
+export { logger };

package/dist/logger.js

@@ -0,0 +1,79 @@
+//#region src/logger.ts
+const PREFIX = "[uds]";
+const isColorSupported = !process.env.NO_COLOR && process.stderr.isTTY !== false && process.stdout.isTTY !== false;
+function green(text) {
+	return isColorSupported ? `\x1b[32m${text}\x1b[39m` : text;
+}
+function yellow(text) {
+	return isColorSupported ? `\x1b[33m${text}\x1b[39m` : text;
+}
+function red(text) {
+	return isColorSupported ? `\x1b[31m${text}\x1b[39m` : text;
+}
+function dim(text) {
+	return isColorSupported ? `\x1b[2m${text}\x1b[22m` : text;
+}
+function cyan(text) {
+	return isColorSupported ? `\x1b[36m${text}\x1b[39m` : text;
+}
+let verboseEnabled = false;
+let quietEnabled = false;
+let stderrEnabled = false;
+function out(message) {
+	if (stderrEnabled) console.error(message);
+	else console.log(message);
+}
+const logger = {
+	/** Enable `logger.debug()` output (set via `--verbose` flag). */
+	setVerbose(value) {
+		verboseEnabled = value;
+	},
+	/** Suppress everything except errors (set via `--quiet` flag). */
+	setQuiet(value) {
+		quietEnabled = value;
+	},
+	/**
+	* Route stdout-bound logs to stderr. Enable when stdout carries a protocol
+	* stream that must stay free of log noise — e.g. the MCP stdio transport,
+	* where a stray banner line corrupts the JSON-RPC framing.
+	*/
+	setStderr(value) {
+		stderrEnabled = value;
+	},
+	/** Green check — a step completed successfully. */
+	success(message) {
+		if (quietEnabled) return;
+		out(`${PREFIX} ${green("✓")} ${message}`);
+	},
+	/** Neutral informational message. */
+	info(message) {
+		if (quietEnabled) return;
+		out(`${PREFIX} ${message}`);
+	},
+	/** Yellow warning — something is off but not fatal. */
+	warn(message) {
+		if (quietEnabled) return;
+		console.warn(`${PREFIX} ${yellow("⚠")} ${message}`);
+	},
+	/** Red error — always printed, even in quiet mode. */
+	error(message, cause) {
+		if (cause !== void 0) console.error("%s %s %s", PREFIX, red("✗"), message, cause);
+		else console.error("%s %s %s", PREFIX, red("✗"), message);
+	},
+	/** Indented sub-line for detail beneath a success/info message. */
+	detail(message) {
+		if (quietEnabled) return;
+		out(`${PREFIX}   ${dim(message)}`);
+	},
+	/** Only printed when `--verbose` is active. */
+	debug(message) {
+		if (!verboseEnabled) return;
+		out(dim(`${PREFIX} ${message}`));
+	},
+	/** Highlight a file path or URL inside a message. */
+	path(value) {
+		return cyan(value);
+	}
+};
+//#endregion
+export { logger };

package/dist/math-utils/clamp.d.ts

@@ -0,0 +1,12 @@
+//#region src/math-utils/clamp.d.ts
+/**
+ * Clamps a value between a lower and upper bound.
+ *
+ * @param value - The value to clamp.
+ * @param lower - The lower bound.
+ * @param upper - The upper bound.
+ * @returns The clamped value.
+ */
+declare function clamp(value: number, lower: number, upper: number): number;
+//#endregion
+export { clamp };

package/dist/math-utils/clamp.js

@@ -0,0 +1,14 @@
+//#region src/math-utils/clamp.ts
+/**
+* Clamps a value between a lower and upper bound.
+*
+* @param value - The value to clamp.
+* @param lower - The lower bound.
+* @param upper - The upper bound.
+* @returns The clamped value.
+*/
+function clamp(value, lower, upper) {
+	return Math.max(lower, Math.min(value, upper));
+}
+//#endregion
+export { clamp };

package/dist/motion-utils/interpolate.d.ts

@@ -0,0 +1,10 @@
+//#region src/motion-utils/interpolate.d.ts
+type ExtrapolateType = 'extend' | 'identity' | 'clamp';
+declare function interpolate(input: number, inputRange: number[], outputRange: number[], options?: {
+  easing?: (input: number) => number;
+  extrapolate?: ExtrapolateType;
+  extrapolateLeft?: ExtrapolateType;
+  extrapolateRight?: ExtrapolateType;
+}): number;
+//#endregion
+export { interpolate };

package/dist/motion-utils/interpolate.js

@@ -0,0 +1,25 @@
+import { clamp } from "../math-utils/clamp.js";
+//#region src/motion-utils/interpolate.ts
+function interpolate(input, inputRange, outputRange, options = {}) {
+	const { easing, extrapolate = "extend", extrapolateLeft = extrapolate, extrapolateRight = extrapolate } = options;
+	if (inputRange.length !== outputRange.length) throw new Error("inputRange and outputRange must have the same length");
+	let segmentIndex = inputRange.findIndex((value, i) => input < value && i > 0) - 1;
+	if (segmentIndex === -2) segmentIndex = inputRange.length - 2;
+	let extrapolationType = extrapolate;
+	if (segmentIndex < 0) extrapolationType = extrapolateLeft;
+	else if (segmentIndex >= inputRange.length - 2) extrapolationType = extrapolateRight;
+	if (extrapolationType === "clamp") {
+		if (segmentIndex < 0) return outputRange[0];
+		if (segmentIndex >= inputRange.length - 2) return outputRange[outputRange.length - 1];
+	} else if (extrapolationType === "identity") return input;
+	const inputStart = inputRange[segmentIndex];
+	const inputEnd = inputRange[segmentIndex + 1];
+	const outputStart = outputRange[segmentIndex];
+	const outputEnd = outputRange[segmentIndex + 1];
+	let ratio = (input - inputStart) / (inputEnd - inputStart);
+	ratio = clamp(ratio, 0, 1);
+	if (easing) ratio = easing(ratio);
+	return outputStart + ratio * (outputEnd - outputStart);
+}
+//#endregion
+export { interpolate };

package/dist/motion-utils/resolveMotionState.d.ts

@@ -0,0 +1,34 @@
+//#region src/motion-utils/resolveMotionState.d.ts
+/**
+ * Runtime helper for codegen's `__rms(stateKeyframe, index)` calls in
+ * multi-layer authoring sources that use `interpolate(...)` markers
+ * inside per-state motion keyframes. Given a state keyframe object
+ * whose values are either scalars or `interpolate({ output, extrapolate })`
+ * markers, resolves each marker against `index` and returns a plain
+ * keyframe object ready to spread onto `motion.<x>` props.
+ *
+ * Inlined `InterpolateMarker` shape rather than imported from
+ * `@yahoo/uds-create-config` so this stays a small leaf runtime helper.
+ */
+interface InterpolateMarker {
+  __type: 'interpolate';
+  output: number[];
+  extrapolate: 'clamp' | 'extend' | 'identity';
+}
+/**
+ * Resolve a single `interpolate({ output, extrapolate })` marker against
+ * an integer-ish `index`. Output is a discrete lookup by index for
+ * `index < output.length`; beyond that, `extrapolate` chooses the
+ * extension rule (clamp / linear-extend / identity).
+ */
+declare function resolveInterpolate(marker: InterpolateMarker, index: number): number;
+/**
+ * Resolve every InterpolateMarker in a state keyframe object against
+ * `index`, leaving non-marker values unchanged. Used by codegen-emitted
+ * `__rms(...)` call sites — see
+ * `packages/codegen/src/build/get-styles/motion-transform.ts` for the
+ * call-site generation.
+ */
+declare function resolveMotionState(stateKeyframe: Record<string, unknown>, index: number): Record<string, unknown>;
+//#endregion
+export { resolveInterpolate, resolveMotionState };