@primeuicom/mcp 1.2.1 → 1.2.3

package/dist/service.js

@@ -229,6 +229,7 @@ function buildProjectRootHint() {
 var primeUiProjectConfigSchema = z2.object({
   projectId: z2.string().trim().min(1),
   apiKey: z2.string().trim().min(1),
+  apiBaseUrl: z2.string().trim().url().optional(),
   targetProjectPath: z2.string().trim().regex(/^\.\/.*$/).optional()
 }).passthrough();
 var primeUiProjectConfigWithTargetPathSchema = primeUiProjectConfigSchema.superRefine((value, ctx) => {
@@ -519,6 +520,23 @@ async function resolvePrimeUiApiKey(options) {
     hint: "Set PRIMEUI_API_KEY or ensure apiKey is present in .primeui/project.json."
   });
 }
+function resolvePrimeUiApiBaseUrlDetails(options) {
+  const envBaseUrl = options.baseUrlFromEnv?.trim();
+  const configBaseUrl = options.projectConfig?.apiBaseUrl?.trim();
+  const envProvided = Boolean(envBaseUrl);
+  const configProvided = Boolean(configBaseUrl);
+  const resolvedBaseUrl = envBaseUrl || configBaseUrl;
+  return {
+    baseUrl: resolvedBaseUrl,
+    source: envProvided ? "env" : configProvided ? "config" : "default",
+    envProvided,
+    configProvided,
+    valuesMatch: envProvided && configProvided ? envBaseUrl === configBaseUrl : void 0
+  };
+}
+function resolvePrimeUiApiBaseUrl(options) {
+  return resolvePrimeUiApiBaseUrlDetails(options).baseUrl;
+}
 
 // src/sources/api-provider.ts
 import { createWriteStream } from "fs";
@@ -529,6 +547,9 @@ import { pipeline } from "stream/promises";
 
 // src/lib/api-v1-contract.ts
 import { z as z3 } from "zod";
+var primeUiPageSlugInputSchema = z3.string().refine((value) => value.trim().length > 0, {
+  message: "pageSlug must be a non-empty string"
+});
 var primeUiExportStatusSchema = z3.enum(
   ["in_progress", "completed", "failed"]
 );
@@ -639,6 +660,105 @@ var primeUiPageGenerationTypeSchema = z3.enum([
   "docs",
   "legal"
 ]);
+var primeUiComponentCandidateOperationSchema = z3.discriminatedUnion("type", [
+  z3.object({
+    type: z3.literal("append")
+  }),
+  z3.object({
+    type: z3.literal("insert"),
+    index: z3.number().int()
+  }),
+  z3.object({
+    type: z3.literal("replace"),
+    index: z3.number().int()
+  })
+]);
+var primeUiComponentCandidateConstraintsSchema = z3.object({
+  spreadDegree: z3.enum(["any-group", "same-group", "same-family"]).optional(),
+  allowedGroups: z3.array(z3.string()).optional(),
+  excludedGroups: z3.array(z3.string()).optional(),
+  excludeComponentIds: z3.array(z3.string()).optional()
+});
+var primeUiComponentCandidatesInputSchema = z3.object({
+  pageSlug: primeUiPageSlugInputSchema,
+  pageType: primeUiPageGenerationTypeSchema,
+  blocks: z3.array(
+    z3.object({
+      componentId: z3.string()
+    })
+  ),
+  operation: primeUiComponentCandidateOperationSchema,
+  count: z3.number().int().positive().optional(),
+  constraints: primeUiComponentCandidateConstraintsSchema.optional()
+});
+var primeUiComponentCandidateRequestEchoSchema = z3.object({
+  pageSlug: z3.string(),
+  pageType: z3.string(),
+  operation: primeUiComponentCandidateOperationSchema,
+  count: z3.number()
+});
+var requiredUnknownSchema = z3.custom((value) => value !== void 0);
+var primeUiComponentCandidateLayoutObjectSchema = z3.object({
+  container: requiredUnknownSchema,
+  textAlignment: requiredUnknownSchema,
+  bottomWeight: requiredUnknownSchema,
+  entryWidth: requiredUnknownSchema,
+  exitWidth: requiredUnknownSchema,
+  orientation: requiredUnknownSchema,
+  structure: requiredUnknownSchema
+});
+var primeUiComponentCandidateLayoutSchema = z3.custom(
+  (value) => primeUiComponentCandidateLayoutObjectSchema.safeParse(value).success
+);
+var primeUiComponentCandidateObjectSchema = z3.object({
+  componentId: z3.string(),
+  name: z3.string(),
+  group: z3.string(),
+  familyId: z3.string(),
+  uxScore: z3.number(),
+  insertionScore: z3.number(),
+  followingScore: z3.number(),
+  layout: primeUiComponentCandidateLayoutSchema,
+  defaultProps: requiredUnknownSchema,
+  exportReady: z3.boolean(),
+  copyHints: z3.object({
+    deliveryToolchain: z3.array(z3.string())
+  }),
+  description: z3.string().nullable().optional(),
+  functionality: z3.string().nullable().optional(),
+  impression: z3.string().nullable().optional(),
+  visualStyle: z3.unknown().optional(),
+  compactSchema: z3.string().nullable().optional(),
+  jsonSchema: z3.record(z3.unknown()).nullable().optional()
+});
+var primeUiComponentCandidateSchema = z3.custom(
+  (value) => primeUiComponentCandidateObjectSchema.safeParse(value).success
+);
+var primeUiComponentCandidatesResponseSchema = z3.object({
+  request: primeUiComponentCandidateRequestEchoSchema,
+  candidates: z3.array(primeUiComponentCandidateSchema)
+});
+var primeUiComponentPropsValidateInputSchema = z3.object({
+  pageSlug: primeUiPageSlugInputSchema,
+  componentId: z3.string(),
+  props: z3.record(z3.unknown())
+});
+var primeUiComponentPropsValidationErrorSchema = z3.object({
+  path: z3.string(),
+  message: z3.string()
+});
+var primeUiComponentPropsRenderCheckSchema = z3.object({
+  attempted: z3.boolean(),
+  passed: z3.boolean(),
+  message: z3.string()
+});
+var primeUiComponentPropsValidateResponseSchema = z3.object({
+  valid: z3.boolean(),
+  normalizedProps: z3.record(z3.unknown()).nullable(),
+  errors: z3.array(primeUiComponentPropsValidationErrorSchema),
+  hints: z3.array(z3.string()),
+  renderCheck: primeUiComponentPropsRenderCheckSchema
+});
 var primeUiProjectApiWireframeStatusSchema = z3.enum(["pending", "generating", "ready", "error"]);
 var primeUiProjectApiVariantSummarySchema = z3.object({
   id: z3.string(),
@@ -1145,6 +1265,20 @@ var ApiProjectDataProvider = class {
       primeUiProjectPageDetailsSchema
     );
   }
+  async getComponentCandidates(input) {
+    return this.requestJson(
+      "component-planning/candidates",
+      primeUiComponentCandidatesResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
+  async validateComponentProps(input) {
+    return this.requestJson(
+      "component-planning/props/validate",
+      primeUiComponentPropsValidateResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
   async listExports() {
     const response = await this.requestJson(
       "project/exports",
@@ -1856,19 +1990,23 @@ async function runHealthCheck(options) {
     apiKeyFromEnv: env.PRIMEUI_API_KEY
   });
   const configApiKeyState = resolvedProjectConfig ? "set" : configStatus === "missing" || configStatus === "unresolved" ? "missing" : "unknown";
-  const apiBaseUrlSource = env.PRIMEUI_API_BASE_URL?.trim() ? "env" : "default";
+  const apiBaseUrlDetails = resolvePrimeUiApiBaseUrlDetails({
+    projectConfig: resolvedProjectConfig?.projectConfig,
+    baseUrlFromEnv: env.PRIMEUI_API_BASE_URL
+  });
+  const apiBaseUrlSource = apiBaseUrlDetails.source;
   const defaultApiRoot = normalizePrimeUiApiRoot(DEFAULT_API_BASE_URL);
   let apiRoot;
   let projectInfoUrl;
   let apiCheck;
   try {
-    apiRoot = normalizePrimeUiApiRoot(env.PRIMEUI_API_BASE_URL);
+    apiRoot = normalizePrimeUiApiRoot(apiBaseUrlDetails.baseUrl);
     projectInfoUrl = buildPrimeUiApiUrl(apiRoot, "project");
   } catch (error) {
     apiCheck = {
       status: "skipped",
       apiBaseUrlSource,
-      nonStandardBaseUrl: Boolean(env.PRIMEUI_API_BASE_URL?.trim()),
+      nonStandardBaseUrl: Boolean(apiBaseUrlDetails.baseUrl?.trim()),
       message: error instanceof Error ? error.message : String(error),
       errorKind: "configuration"
     };
@@ -1886,10 +2024,10 @@ async function runHealthCheck(options) {
     } else {
       const provider = options.createProvider?.({
         apiKey: apiKeyDetails.apiKey,
-        baseUrl: env.PRIMEUI_API_BASE_URL
+        baseUrl: apiBaseUrlDetails.baseUrl
       }) ?? new ApiProjectDataProvider({
         apiKey: apiKeyDetails.apiKey,
-        baseUrl: env.PRIMEUI_API_BASE_URL
+        baseUrl: apiBaseUrlDetails.baseUrl
       });
       try {
         await provider.getProjectInfo();
@@ -3741,6 +3879,15 @@ var PACKAGE_JSON_RELATIVE_PATH2 = "package.json";
 var VIRTUAL_ROUTE_SEGMENT = "__primeui-component-export";
 var COMPONENT_PAGES_PREFIX = "src/components/pages/";
 var COMPONENT_UI_PREFIX = "src/components/ui/";
+var COMPONENT_SHARED_PREFIX = "src/components/shared/";
+var NATURAL_SUPPORT_PREFIXES = [
+  COMPONENT_UI_PREFIX,
+  "src/lib/",
+  "src/types/",
+  "src/contexts/"
+];
+var PUBLIC_PREFIX = "public/";
+var PUBLIC_ASSET_REFERENCE_RE = /["'`(]\/([^"'`()\s]+\.(?:avif|gif|ico|jpeg|jpg|json|mp4|otf|png|svg|ttf|txt|webm|webmanifest|webp|woff|woff2|xml))(?:\?[^"'`()\s]*)?["'`)]/giu;
 function normalizeComponentId(componentId) {
   const trimmed = componentId.trim();
   if (!trimmed) {
@@ -3773,6 +3920,35 @@ function isVirtualRouteFile(relativePath) {
   const segments = relativePath.split("/");
   return segments[0] === "src" && segments[1] === "app" && segments.includes(VIRTUAL_ROUTE_SEGMENT);
 }
+function getVirtualComponentRelativePath(relativePath, componentId) {
+  const prefix = `${COMPONENT_PAGES_PREFIX}${VIRTUAL_ROUTE_SEGMENT}/${componentId}/`;
+  if (!relativePath.startsWith(prefix)) {
+    return null;
+  }
+  const componentRelativePath = relativePath.slice(prefix.length);
+  return componentRelativePath || null;
+}
+function getComponentPageSourceArea(relativePath) {
+  if (!relativePath.startsWith(COMPONENT_PAGES_PREFIX)) {
+    return null;
+  }
+  const rest = relativePath.slice(COMPONENT_PAGES_PREFIX.length);
+  const slashIndex = rest.indexOf("/");
+  if (slashIndex <= 0) {
+    return null;
+  }
+  const sourceArea = rest.slice(0, slashIndex);
+  return sourceArea === VIRTUAL_ROUTE_SEGMENT ? null : sourceArea;
+}
+function getSourceAreaComponentRelativePath(relativePath, sourceAreas) {
+  const sourceArea = getComponentPageSourceArea(relativePath);
+  if (!sourceArea || !sourceAreas.has(sourceArea)) {
+    return null;
+  }
+  const prefix = `${COMPONENT_PAGES_PREFIX}${sourceArea}/`;
+  const componentRelativePath = relativePath.slice(prefix.length);
+  return componentRelativePath || null;
+}
 function isComponentEntryFile(relativePath, componentId) {
   if (!relativePath.startsWith(COMPONENT_PAGES_PREFIX)) {
     return false;
@@ -3788,7 +3964,155 @@ function isComponentEntryFile(relativePath, componentId) {
   return basename === "index" && path13.basename(path13.dirname(relativePath)) === componentId;
 }
 function isManifestSupportFile(relativePath) {
-  return relativePath.startsWith(COMPONENT_UI_PREFIX);
+  return NATURAL_SUPPORT_PREFIXES.some(
+    (prefix) => relativePath.startsWith(prefix)
+  );
+}
+function isEnvFile(relativePath) {
+  return relativePath === ".env" || relativePath.startsWith(".env.");
+}
+function isSearchRuntimeFile(relativePath) {
+  return relativePath.startsWith("src/app/api/search/") || relativePath.startsWith("src/lib/search/") || relativePath.startsWith("src/lib/search-runtime/") || relativePath.startsWith("src/search/");
+}
+function isProjectLevelFile(relativePath) {
+  return isEnvFile(relativePath) || isSearchRuntimeFile(relativePath) || relativePath.startsWith("scripts/") || relativePath.startsWith("src/app/") || relativePath.startsWith("src/components/header/") || relativePath.startsWith("src/components/footer/") || relativePath.startsWith("src/components/layout/");
+}
+function toComponentSharedTargetPath(componentRelativePath) {
+  return `${COMPONENT_SHARED_PREFIX}${componentRelativePath}`;
+}
+function toImportPath(relativePath) {
+  const withoutExtension = relativePath.replace(/\.[cm]?[jt]sx?$/u, "");
+  const withoutIndex = withoutExtension.replace(/\/index$/u, "");
+  return `@/${withoutIndex.replace(/^src\//u, "")}`;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function sourceImportSpecifiers(relativePath) {
+  const withAlias = toImportPath(relativePath);
+  const specifiers = [withAlias];
+  if (withAlias.endsWith("/index")) {
+    specifiers.push(withAlias.replace(/\/index$/u, ""));
+  }
+  return [...new Set(specifiers)];
+}
+function rewriteComponentLocalImports(content, transfers) {
+  let updated = content;
+  for (const transfer of transfers) {
+    const targetSpecifier = toImportPath(transfer.targetPath);
+    for (const sourceSpecifier of sourceImportSpecifiers(transfer.sourcePath)) {
+      updated = updated.replace(
+        new RegExp(escapeRegExp(sourceSpecifier), "gu"),
+        targetSpecifier
+      );
+    }
+  }
+  return updated;
+}
+function collectReferencedPublicAssetFiles(content) {
+  const referencedFiles = /* @__PURE__ */ new Set();
+  let match = null;
+  PUBLIC_ASSET_REFERENCE_RE.lastIndex = 0;
+  while ((match = PUBLIC_ASSET_REFERENCE_RE.exec(content)) !== null) {
+    const referencedPath = match[1]?.trim();
+    if (referencedPath) {
+      referencedFiles.add(
+        `${PUBLIC_PREFIX}${normalizeManifestFilePath(referencedPath)}`
+      );
+    }
+  }
+  return [...referencedFiles];
+}
+function findComponentSourceAreas(relativePaths) {
+  const sourceAreas = /* @__PURE__ */ new Set();
+  for (const relativePath of relativePaths) {
+    const sourceArea = getComponentPageSourceArea(relativePath);
+    if (sourceArea) {
+      sourceAreas.add(sourceArea);
+    }
+  }
+  return sourceAreas;
+}
+function getComponentLocalTargetPath(input) {
+  const virtualRelativePath = getVirtualComponentRelativePath(
+    input.relativePath,
+    input.componentId
+  );
+  if (virtualRelativePath) {
+    return toComponentSharedTargetPath(virtualRelativePath);
+  }
+  const sourceAreaRelativePath = getSourceAreaComponentRelativePath(
+    input.relativePath,
+    input.sourceAreas
+  );
+  if (sourceAreaRelativePath) {
+    return toComponentSharedTargetPath(sourceAreaRelativePath);
+  }
+  return null;
+}
+function getTransferTargetPath(input) {
+  if (input.relativePath === PACKAGE_JSON_RELATIVE_PATH2 || isVirtualRouteFile(input.relativePath) || isProjectLevelFile(input.relativePath)) {
+    return null;
+  }
+  const componentLocalTargetPath = getComponentLocalTargetPath(input);
+  if (componentLocalTargetPath) {
+    return componentLocalTargetPath;
+  }
+  if (isManifestSupportFile(input.relativePath)) {
+    return input.relativePath;
+  }
+  if (input.relativePath.startsWith(PUBLIC_PREFIX) && input.referencedPublicFiles.has(input.relativePath)) {
+    return input.relativePath;
+  }
+  return null;
+}
+async function collectReferencedPublicFiles(input) {
+  const referencedPublicFiles = /* @__PURE__ */ new Set();
+  for (const relativePath of input.graphInternalFiles) {
+    if (!input.manifestFileSet.has(relativePath)) {
+      continue;
+    }
+    const sourcePath = path13.join(input.exportPath, relativePath);
+    let content = "";
+    try {
+      content = await readFile7(sourcePath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const referencedFile of collectReferencedPublicAssetFiles(content)) {
+      if (input.manifestFileSet.has(referencedFile)) {
+        referencedPublicFiles.add(referencedFile);
+      }
+    }
+  }
+  return referencedPublicFiles;
+}
+function buildFileTransfers(input) {
+  const sourceAreas = findComponentSourceAreas([...input.graphInternalFiles]);
+  const transfers = [];
+  const usedTargetPaths = /* @__PURE__ */ new Set();
+  for (const relativePath of input.files) {
+    const isGraphFile = input.graphInternalFiles.has(relativePath);
+    const isReferencedPublicFile = input.referencedPublicFiles.has(relativePath);
+    if (!isGraphFile && !isReferencedPublicFile) {
+      continue;
+    }
+    const targetPath = getTransferTargetPath({
+      relativePath,
+      componentId: input.componentId,
+      sourceAreas,
+      referencedPublicFiles: input.referencedPublicFiles
+    });
+    if (!targetPath || usedTargetPaths.has(targetPath)) {
+      continue;
+    }
+    usedTargetPaths.add(targetPath);
+    transfers.push({
+      sourcePath: relativePath,
+      targetPath
+    });
+  }
+  return transfers.sort((a, b) => a.targetPath.localeCompare(b.targetPath));
 }
 function toSkippedFile(targetPath, reason) {
   return {
@@ -3828,7 +4152,7 @@ function splitManifestFiles(input) {
   };
 }
 async function createConflictReportEntry2(input) {
-  const sourceBuffer = await readFile7(input.sourceFilePath);
+  const sourceBuffer = input.sourceBuffer ?? await readFile7(input.sourceFilePath);
   let targetBuffer = null;
   try {
     targetBuffer = await readFile7(input.targetFilePath);
@@ -3896,7 +4220,7 @@ function buildMessage(input) {
     );
   }
   parts.push(
-    "The virtual component export page was skipped; manually insert the copied component into a real target page."
+    `The virtual component export page was skipped; manually import ${input.componentImportPath} into a real target page.`
   );
   return parts.join(" ");
 }
@@ -3963,23 +4287,39 @@ async function copyRegistryComponentFromExport(input) {
       (filePath) => toProjectRelative(exportPath, filePath)
     )
   );
-  const exportableFileSet = new Set(
-    uniqueNormalizedManifestFiles(getSuccessfulExportableFiles(manifest))
+  const referencedPublicFiles = await collectReferencedPublicFiles({
+    exportPath,
+    graphInternalFiles,
+    manifestFileSet
+  });
+  const fileTransfers = buildFileTransfers({
+    files: initialSelection.manifestFiles,
+    componentId: normalizedComponentId,
+    graphInternalFiles,
+    referencedPublicFiles
+  });
+  const copyableSourceFiles = fileTransfers.map(
+    (transfer) => transfer.sourcePath
+  );
+  const copyableFiles = fileTransfers.map((transfer) => transfer.targetPath);
+  const transferBySourcePath = new Map(
+    fileTransfers.map((transfer) => [transfer.sourcePath, transfer])
+  );
+  const componentEntryTransfer = fileTransfers.find(
+    (transfer) => initialSelection.componentEntryFiles.includes(transfer.sourcePath)
+  );
+  const componentImportPath = toImportPath(
+    componentEntryTransfer?.targetPath ?? `${COMPONENT_SHARED_PREFIX}${normalizedComponentId}.tsx`
   );
-  const copyableFiles = initialSelection.manifestFiles.filter(
-    (relativePath) => graphInternalFiles.has(relativePath) || isManifestSupportFile(relativePath) || exportableFileSet.has(relativePath)
-  ).filter(
-    (relativePath) => relativePath !== PACKAGE_JSON_RELATIVE_PATH2 && !isVirtualRouteFile(relativePath)
-  ).sort((a, b) => a.localeCompare(b));
   const { manifestFiles, skippedFiles } = splitManifestFiles({
     files: initialSelection.manifestFiles,
     componentId: normalizedComponentId,
-    copyableFiles
+    copyableFiles: copyableSourceFiles
   });
   const candidateFiles = await resolveManifestCandidateFiles({
     exportPath,
     manifestOwnerLabel: `registry component "${normalizedComponentId}"`,
-    files: copyableFiles,
+    files: copyableSourceFiles,
     requireExisting: false
   });
   for (const sourceFilePath of candidateFiles) {
@@ -3989,9 +4329,21 @@ async function copyRegistryComponentFromExport(input) {
       missingManifestFiles.add(relativeToExport);
       continue;
     }
-    const targetFilePath = path13.join(input.projectRoot, relativeToExport);
+    const transfer = transferBySourcePath.get(relativeToExport);
+    if (!transfer) {
+      continue;
+    }
+    const targetRelativePath = transfer.targetPath;
+    const targetFilePath = path13.join(input.projectRoot, targetRelativePath);
     ensureSafeTargetPath(input.projectRoot, targetFilePath);
     const sourceBuffer = await readFile7(sourceFilePath);
+    const rewrittenSourceBuffer = isBinaryBuffer(sourceBuffer) ? sourceBuffer : Buffer.from(
+      rewriteComponentLocalImports(
+        sourceBuffer.toString("utf-8"),
+        fileTransfers
+      ),
+      "utf-8"
+    );
     let targetBuffer = null;
     try {
       targetBuffer = await readFile7(targetFilePath);
@@ -4000,19 +4352,20 @@ async function copyRegistryComponentFromExport(input) {
     }
     if (!targetBuffer) {
       await ensureDir(path13.dirname(targetFilePath));
-      await writeFile6(targetFilePath, sourceBuffer);
-      newFiles.push(relativeToExport);
+      await writeFile6(targetFilePath, rewrittenSourceBuffer);
+      newFiles.push(targetRelativePath);
       continue;
     }
-    if (sourceBuffer.equals(targetBuffer)) {
-      identicalFiles.push(relativeToExport);
+    if (rewrittenSourceBuffer.equals(targetBuffer)) {
+      identicalFiles.push(targetRelativePath);
       continue;
     }
     const entry = await createConflictReportEntry2({
       sourceFilePath,
       targetFilePath,
       exportPath,
-      projectRoot: input.projectRoot
+      projectRoot: input.projectRoot,
+      sourceBuffer: rewrittenSourceBuffer
     });
     if (entry) {
       conflictReportEntries.push(entry);
@@ -4053,6 +4406,7 @@ async function copyRegistryComponentFromExport(input) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     exportId,
     componentId: normalizedComponentId,
+    componentImportPath,
     manifestFiles,
     copyableFiles,
     skippedFiles,
@@ -4074,6 +4428,7 @@ async function copyRegistryComponentFromExport(input) {
     status,
     message: buildMessage({
       componentId: normalizedComponentId,
+      componentImportPath,
       status,
       reportPath,
       newFiles: sortedNewFiles,
@@ -4089,6 +4444,7 @@ async function copyRegistryComponentFromExport(input) {
     exportPath,
     manifestPath,
     component: manifest.component,
+    componentImportPath,
     manifestFiles,
     copyableFiles,
     newFiles: sortedNewFiles,
@@ -4111,7 +4467,7 @@ async function copyRegistryComponentFromExport(input) {
     },
     guidance: {
       artifacts: guidanceArtifacts,
-      requiredActions: "Do not install the skipped virtual component export page as a route. Manually import the copied component/support files into a real target page, install newly added dependencies, and resolve any reported conflicts or dependency version mismatches before treating the registry component transfer as complete."
+      requiredActions: `Do not install the skipped virtual component export page as a route. Manually import ${componentImportPath} into a real target page, install newly added dependencies, and resolve any reported conflicts or dependency version mismatches before treating the registry component transfer as complete.`
     }
   };
 }
@@ -4294,6 +4650,12 @@ var ProjectSyncService = class {
       notes: guidanceNotes
     };
   }
+  async getComponentCandidates(input, _context) {
+    return this.provider.getComponentCandidates(input);
+  }
+  async validateComponentProps(input, _context) {
+    return this.provider.validateComponentProps(input);
+  }
   async listExports(_context) {
     await this.ensureTempLayout();
     return this.provider.listExports();
@@ -4552,10 +4914,14 @@ var LazyProjectSyncSource = class {
       projectConfig: resolvedProjectConfig.projectConfig,
       apiKeyFromEnv: this.env.PRIMEUI_API_KEY
     });
+    const baseUrl = resolvePrimeUiApiBaseUrl({
+      projectConfig: resolvedProjectConfig.projectConfig,
+      baseUrlFromEnv: this.env.PRIMEUI_API_BASE_URL
+    });
     this.stickyProjectRoot = projectRoot;
     const provider = this.createProvider({
       apiKey,
-      baseUrl: this.env.PRIMEUI_API_BASE_URL
+      baseUrl
     });
     return new ProjectSyncService({
       projectRoot,
@@ -4738,6 +5104,24 @@ var LazyProjectSyncSource = class {
       (service) => service.syncSearchEnvironment(environmentSlug, context)
     );
   }
+  async getComponentCandidates(input, context) {
+    return this.withService(
+      context,
+      (service) => service.getComponentCandidates(input, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async validateComponentProps(input, context) {
+    return this.withService(
+      context,
+      (service) => service.validateComponentProps(input, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
   async listExports(context) {
     return this.withService(context, (service) => service.listExports(context));
   }
@@ -5032,7 +5416,8 @@ ${WORKFLOW_SUMMARY}
 
 ADDITIONAL CAPABILITIES:
 - PrimeUI MCP also exposes atomic external API tools for project description, project pages, page variants, active-variant selection, and issue reports.
-- These atomic tools are OPTIONAL additional capabilities for extended scenarios.
+- PrimeUI MCP also exposes component planning tools such as component_candidates_get and component_props_validate for exported-project page building.
+- These additional tools are OPTIONAL capabilities for extended scenarios.
 - They are NOT part of the primary import/export workflow above.
 - Do not replace get_project_info/create_export/download_export/copy_* with the additional API tools when the user wants the standard page import/export flow.
 
@@ -5594,10 +5979,12 @@ WHEN TO USE:
 BEHAVIOR:
 - Reads the component sidecar manifest saved by create_component_export.
 - Validates that manifest.component.componentId matches input.componentId.
-- Copies files strictly from page.manifest.files in the component sidecar manifest.
+- Copies only the selected registry component import graph, narrowly referenced public assets, and safe support files from the component sidecar manifest/export.
+- Remaps component-local files into src/components/shared/** and returns componentImportPath for manual insertion.
 - Skips virtual route files that include __primeui-component-export, because those are reference/insertion hints and must not be installed as normal app routes.
+- Skips app/search/layout/header/footer/env/project-shell files instead of copying whole exportable buckets.
 - Never copies package.json directly. package.json is used only to add missing dependency entries and report dependency version conflicts.
-- Preserves export-relative paths for copied files in this first version.
+- Keeps safe support files on their natural target paths, such as src/components/ui/**, src/lib/**, src/types/**, and src/contexts/**.
 - Never overwrites existing conflicting files.
 - Writes full conflict details to .primeui/temp/exports/[exportId].copy-registry-component-report-[copyId].json.
 - Reports copied files, identical files, conflicts, skipped files, dependency additions, dependency version conflicts, missing manifest files, and manual insertion guidance.
@@ -5628,11 +6015,14 @@ ${WORKFLOW_SUMMARY}`,
     component: componentExportComponentSchema.describe(
       "Component metadata from the validated component sidecar manifest."
     ),
+    componentImportPath: z4.string().describe(
+      "Canonical import path for the copied registry component entrypoint, for example @/components/shared/hero--pricing."
+    ),
     manifestFiles: z4.array(z4.string()).describe(
-      "Normalized page.manifest.files from the component sidecar manifest."
+      "Normalized component sidecar manifest files considered by the copy service."
     ),
     copyableFiles: z4.array(z4.string()).describe(
-      "Manifest files considered for copying after filtering virtual route files and package.json."
+      "Relative target paths considered for copying after component remapping and safety filtering."
     ),
     newFiles: z4.array(z4.string()).describe("Relative target paths for new files copied."),
     identicalFiles: z4.array(z4.string()).describe("Relative target paths for existing byte-identical files."),
@@ -5821,6 +6211,122 @@ var pageGenerationTypeSchema = z4.enum([
 ]).describe(
   "Supported PrimeUI page type. Must match the external API page type enum."
 );
+var componentCandidateOperationSchema = z4.discriminatedUnion("type", [
+  z4.object({
+    type: z4.literal("append")
+  }),
+  z4.object({
+    type: z4.literal("insert"),
+    index: z4.number().int().describe("Zero-based insertion index in the ordered blocks list.")
+  }),
+  z4.object({
+    type: z4.literal("replace"),
+    index: z4.number().int().describe("Zero-based index of the block being replaced.")
+  })
+]);
+var componentCandidatesGetInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  pageSlug: z4.string().refine((value) => value.trim().length > 0, {
+    message: "pageSlug must be a non-empty string"
+  }).describe(
+    "Stable PrimeUI page slug used for candidate scoring and automatic diagnostics, for example '/pricing'."
+  ),
+  pageType: pageGenerationTypeSchema,
+  blocks: z4.array(
+    z4.object({
+      componentId: z4.string().describe("PrimeUI component id already present in page order.")
+    })
+  ).describe(
+    "Current ordered page composition before applying the requested operation."
+  ),
+  operation: componentCandidateOperationSchema.optional().default({ type: "append" }).describe(
+    "Candidate placement operation. Omit for the normal append flow."
+  ),
+  count: z4.number().int().positive().optional().describe("Optional maximum candidate count. Studio defaults to 8."),
+  constraints: z4.object({
+    spreadDegree: z4.enum(["any-group", "same-group", "same-family"]).optional().describe("Optional UX scoring spread override."),
+    allowedGroups: z4.array(z4.string()).optional().describe("Optional allow-list of candidate groups."),
+    excludedGroups: z4.array(z4.string()).optional().describe("Optional deny-list of candidate groups."),
+    excludeComponentIds: z4.array(z4.string()).optional().describe("Optional component ids to remove from the candidate pool.")
+  }).optional().describe("Optional advanced candidate pool and spread constraints.")
+});
+var componentCandidatesGetValidationSchema = componentCandidatesGetInputSchema;
+var componentPropsValidateInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  pageSlug: z4.string().refine((value) => value.trim().length > 0, {
+    message: "pageSlug must be a non-empty string"
+  }).describe(
+    "Stable PrimeUI page slug used for validation diagnostics, for example '/pricing'. Use the same pageSlug as candidate retrieval."
+  ),
+  componentId: z4.string().describe("PrimeUI component registry identifier selected by the agent."),
+  props: z4.record(z4.unknown()).describe(
+    "Agent-authored props payload to validate against PrimeUI's registry schema."
+  )
+});
+var componentPropsValidateValidationSchema = componentPropsValidateInputSchema;
+var componentCandidateLayoutSchema = z4.object({
+  container: z4.unknown().describe("Layout container metadata."),
+  textAlignment: z4.unknown().describe("Text alignment metadata."),
+  bottomWeight: z4.unknown().describe("Bottom visual weight metadata."),
+  entryWidth: z4.unknown().describe("Incoming width rhythm metadata."),
+  exitWidth: z4.unknown().describe("Outgoing width rhythm metadata."),
+  orientation: z4.unknown().describe("Optional orientation metadata."),
+  structure: z4.unknown().describe("Optional structure metadata.")
+});
+var componentCandidateSchema = z4.object({
+  componentId: z4.string().describe("PrimeUI component registry identifier to choose or export."),
+  name: z4.string().describe("Human-readable component name."),
+  group: z4.string().describe("Component group used by candidate scoring."),
+  familyId: z4.string().describe("Component family identifier from catalog."),
+  uxScore: z4.number().describe("Total UX score used for ranking."),
+  insertionScore: z4.number().describe("Score for inserting this candidate at the requested position."),
+  followingScore: z4.number().describe("Neighbor compatibility score with the following block."),
+  layout: componentCandidateLayoutSchema.describe(
+    "Layout metadata useful for choosing visual rhythm."
+  ),
+  defaultProps: z4.unknown().describe("Registry default props, when available from PrimeUI."),
+  exportReady: z4.boolean().describe("True when the component is expected to be exportable."),
+  copyHints: z4.object({
+    deliveryToolchain: z4.array(z4.string()).describe(
+      "Recommended tool sequence for delivering this registry component locally."
+    )
+  }).describe("Machine-readable delivery hints for the selected candidate."),
+  description: z4.string().nullable().optional(),
+  functionality: z4.string().nullable().optional(),
+  impression: z4.string().nullable().optional(),
+  visualStyle: z4.unknown().optional(),
+  compactSchema: z4.string().nullable().optional(),
+  jsonSchema: z4.record(z4.unknown()).nullable().optional()
+});
+var componentCandidatesGetOutputSchema = z4.object({
+  request: z4.object({
+    pageSlug: z4.string(),
+    pageType: z4.string(),
+    operation: componentCandidateOperationSchema,
+    count: z4.number()
+  }).describe("Normalized request echo returned by PrimeUI."),
+  candidates: z4.array(componentCandidateSchema).describe("Ranked rich candidate shortlist returned by PrimeUI.")
+});
+var componentPropsValidationErrorSchema = z4.object({
+  path: z4.string().describe("JSON path or root path for the invalid props location."),
+  message: z4.string().describe("Actionable validation message returned by PrimeUI.")
+});
+var componentPropsRenderCheckSchema = z4.object({
+  attempted: z4.boolean().describe("True when PrimeUI attempted a render smoke check."),
+  passed: z4.boolean().describe("True when the render smoke check passed."),
+  message: z4.string().describe("Human-readable render check status or skip reason.")
+});
+var componentPropsValidateOutputSchema = z4.object({
+  valid: z4.boolean().describe("True when props passed schema validation."),
+  normalizedProps: z4.record(z4.unknown()).nullable().describe(
+    "Props normalized by PrimeUI when valid; null when validation failed."
+  ),
+  errors: z4.array(componentPropsValidationErrorSchema).describe("Structured validation errors for invalid props."),
+  hints: z4.array(z4.string()).describe("Agent-facing guidance for correcting invalid props."),
+  renderCheck: componentPropsRenderCheckSchema.describe(
+    "Optional render-smoke status returned by PrimeUI."
+  )
+});
 var projectApiPageResourceSchema = z4.object({
   id: z4.string().describe("Stable PrimeUI page identifier."),
   title: z4.string().describe("Human-readable page title."),
@@ -6254,6 +6760,51 @@ WHEN TO USE:
     openWorldHint: true
   }
 };
+var toolComponentCandidatesGet = {
+  title: "PrimeUI Component Candidates Get",
+  description: `External planning helper. Returns a ranked rich candidate shortlist for adding, inserting, or replacing one PrimeUI component in an exported-project page composition.
+
+WHEN TO USE:
+- Use this when building or editing a local exported-project page and you need PrimeUI scoring guidance for which componentId to choose next.
+- The normal flow is append: pass the current ordered blocks and omit operation, which defaults to { "type": "append" }.
+- Use insert or replace only when the caller is intentionally editing a specific position in the ordered blocks list.
+- Use the returned copyHints.deliveryToolchain when the chosen candidate must be delivered locally: create_component_export, download_component_export, then copy_registry_component.
+
+AFTER CALLING:
+- Choose from candidates using uxScore, insertionScore, followingScore, group/family/layout rhythm, descriptions, defaults, and schemas.
+- Do not mutate Prime page state from this tool result. This is planning guidance only.
+- Keep the same pageSlug across later planning and validation calls so PrimeUI diagnostics stay correlated.`,
+  inputSchema: componentCandidatesGetInputSchema,
+  outputSchema: componentCandidatesGetOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolComponentPropsValidate = {
+  title: "PrimeUI Component Props Validate",
+  description: `External planning helper. Validates agent-authored props for one selected PrimeUI component before editing local exported-project files.
+
+WHEN TO USE:
+- Use this after choosing a component candidate and drafting props from the user's brief, candidate metadata, defaultProps, compactSchema, or jsonSchema.
+- Keep pageSlug stable across candidate retrieval and validation so PrimeUI diagnostics stay correlated.
+- Treat valid: false as actionable feedback, not a transport failure. Fix the props from errors and hints, then call this tool again.
+
+AFTER CALLING:
+- If valid is true, use normalizedProps for local page edits.
+- If valid is false, correct props using errors[].path, errors[].message, and hints before editing local files.
+- Do not mutate Prime page state from this tool result. This is validation guidance only.`,
+  inputSchema: componentPropsValidateInputSchema,
+  outputSchema: componentPropsValidateOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
 var toolProjectIssueReportSubmit = {
   title: "PrimeUI Project Issue Report Submit",
   description: `Atomic external API helper. Submits an issue report for the scoped PrimeUI project.
@@ -6664,6 +7215,32 @@ function createPrimeUiMcpServer(source) {
       }
     }
   );
+  server.registerTool(
+    "component_candidates_get",
+    toolComponentCandidatesGet,
+    async (args) => {
+      try {
+        const { projectRoot, ...input } = componentCandidatesGetValidationSchema.parse(args);
+        const result = await source.getComponentCandidates(input, { projectRoot });
+        return okResult("component_candidates_get", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "component_props_validate",
+    toolComponentPropsValidate,
+    async (args) => {
+      try {
+        const { projectRoot, ...input } = componentPropsValidateValidationSchema.parse(args);
+        const result = await source.validateComponentProps(input, { projectRoot });
+        return okResult("component_props_validate", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
   server.registerTool(
     "list_exports",
     toolListExports,