@salesforce/storefront-next-dev 1.0.1 → 1.1.0-alpha.1

package/dist/index.js

@@ -1,19 +1,21 @@
-import path from "node:path";
+import path, { resolve } from "node:path";
 import fs from "fs-extra";
 import chalk from "chalk";
-import path$1, { dirname, join, relative, resolve } from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { createRequire } from "module";
+import path$1, { dirname, join, relative, resolve as resolve$1 } from "path";
+import { fileURLToPath } from "url";
 import { parse } from "@babel/parser";
-import { booleanLiteral, identifier, importDeclaration, importSpecifier, isArrayPattern, isClassDeclaration, isExportSpecifier, isFunctionDeclaration, isIdentifier, isJSXAttribute, isJSXElement, isJSXFragment, isJSXIdentifier, isMemberExpression, isObjectPattern, isObjectProperty, isRestElement, isStringLiteral, isVariableDeclaration, jsxAttribute, jsxClosingElement, jsxClosingFragment, jsxElement, jsxExpressionContainer, jsxFragment, jsxIdentifier, jsxOpeningElement, jsxOpeningFragment, jsxText, stringLiteral } from "@babel/types";
+import { isArrayPattern, isClassDeclaration, isExportSpecifier, isFunctionDeclaration, isIdentifier, isJSXAttribute, isJSXElement, isJSXFragment, isJSXIdentifier, isMemberExpression, isObjectPattern, isObjectProperty, isRestElement, isVariableDeclaration, jsxClosingElement, jsxClosingFragment, jsxElement, jsxFragment, jsxIdentifier, jsxOpeningElement, jsxOpeningFragment, jsxText } from "@babel/types";
 import { generate } from "@babel/generator";
 import traverseModule from "@babel/traverse";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { glob } from "glob";
 import { Node, Project, ts } from "ts-morph";
-import fs$1 from "node:fs";
+import fs$1, { existsSync as existsSync$1, readFileSync as readFileSync$1 } from "node:fs";
 import { deadCodeElimination, findReferencedIdentifiers } from "babel-dead-code-elimination";
 import httpProxy from "http-proxy";
 import { brotliDecompressSync, gunzipSync, inflateSync } from "zlib";
+import { extractPrefixParamValues, stripPathPrefix } from "@salesforce/storefront-next-runtime/site-context";
 
 //#region src/utils/logger.ts
 const LEVEL_PRIORITY = {
@@ -367,7 +369,7 @@ const patchReactRouterPlugin = () => {
 
 //#endregion
 //#region src/extensibility/target-utils.ts
-const traverse$2 = traverseModule.default || traverseModule;
+const traverse$1 = traverseModule.default || traverseModule;
 const TARGET_COMPONENT_TAG = "UITarget";
 const TARGET_PROVIDERS_TAG = "UITargetProviders";
 const TARGET_ID_ATTRIBUTE = "targetId";
@@ -442,7 +444,7 @@ function runReplacementPass(ast, tagName, targetRegistry = null, contextProvider
 			if (replacedId) targetIdsReplaced.add(replacedId);
 		} else if (contextProviders) findAndReplaceProviders(pathToReplace, contextProviders);
 	};
-	traverse$2(ast, {
+	traverse$1(ast, {
 		VariableDeclaration(nodePath) {
 			const declarationPaths = nodePath.get("declarations");
 			const declarationsArray = Array.isArray(declarationPaths) ? declarationPaths : [declarationPaths];
@@ -495,7 +497,7 @@ function transformTargets(code, targetRegistry, contextProviders) {
 	});
 	if (TARGET_COMPONENT_JSX_RE.test(code)) {
 		const replacementImportStatements = buildReplacementImportStatements(runReplacementPass(ast, TARGET_COMPONENT_TAG, targetRegistry, null), targetRegistry);
-		traverse$2(ast, { ImportDeclaration(nodePath) {
+		traverse$1(ast, { ImportDeclaration(nodePath) {
 			if (nodePath.node.source.value === "@/targets/ui-target") nodePath.replaceWith(jsxText(replacementImportStatements));
 		} });
 	}
@@ -503,7 +505,7 @@ function transformTargets(code, targetRegistry, contextProviders) {
 		const importStatements = /* @__PURE__ */ new Set();
 		for (const contextProvider of contextProviders) importStatements.add(`import ${contextProvider.componentName} from '@/${contextProvider.path.replace(".tsx", "")}';`);
 		const replacementImportStatements = Array.from(importStatements).join("\n");
-		traverse$2(ast, { ImportDeclaration(nodePath) {
+		traverse$1(ast, { ImportDeclaration(nodePath) {
 			if (nodePath.node.source.value === "@/targets/ui-target-providers") nodePath.replaceWith(jsxText(replacementImportStatements));
 		} });
 		runReplacementPass(ast, TARGET_PROVIDERS_TAG, null, contextProviders);
@@ -605,6 +607,44 @@ function buildTargetRegistry(rootDir, options = {}) {
 		actionHookRegistry
 	};
 }
+const TARGET_ID_PATTERN = /<UITarget[\s][^>]*targetId=["']([^"']+)["']/g;
+/**
+* Recursively collect all UITarget IDs declared in template source files.
+* Excludes extension directories so only "real" UITarget placements are counted.
+*/
+function collectUITargetIds(sourceDir) {
+	const result = /* @__PURE__ */ new Set();
+	function walk(dir) {
+		const entries = fs.readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = path$1.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "extensions") continue;
+				walk(fullPath);
+			} else if (entry.isFile() && /\.(tsx?|jsx?)$/.test(entry.name) && !/\.test\.(tsx?|jsx?)$/.test(entry.name)) {
+				const content = fs.readFileSync(fullPath, "utf-8");
+				TARGET_ID_PATTERN.lastIndex = 0;
+				let match;
+				while ((match = TARGET_ID_PATTERN.exec(content)) !== null) result.add(match[1]);
+			}
+		}
+	}
+	walk(sourceDir);
+	return result;
+}
+/**
+* Validate that all targetIds in the component registry correspond to
+* UITarget declarations in the template source. Returns orphaned entries.
+*/
+function validateTargetRegistry(componentRegistry, declaredTargetIds) {
+	const orphaned = [];
+	for (const targetId in componentRegistry) if (!declaredTargetIds.has(targetId)) for (const entry of componentRegistry[targetId]) orphaned.push({
+		targetId,
+		extension: entry.namespace,
+		componentPath: entry.path
+	});
+	return orphaned;
+}
 
 //#endregion
 //#region src/plugins/transformTargets.ts
@@ -622,9 +662,14 @@ function transformTargetPlaceholderPlugin() {
 		},
 		buildStart() {
 			({componentRegistry, contextProviders} = buildTargetRegistry(sourceDir, { isProduction }));
+			const declaredTargetIds = collectUITargetIds(sourceDir);
+			const orphaned = validateTargetRegistry(componentRegistry, declaredTargetIds);
+			if (orphaned.length > 0) {
+				const lines = orphaned.map((o) => `  • "${o.targetId}" (extension: ${o.extension}, component: ${o.componentPath})`);
+				throw new Error(`[storefront-next] ${orphaned.length} extension component(s) target UITarget IDs that do not exist in the template:\n${lines.join("\n")}\n\nEither add a <UITarget targetId="..."> to the template or remove/disable the component in target-config.json.`);
+			}
 		},
 		transform(code, id) {
-			if (process.env.VITE_UI_TARGET_DEV_MODE === "true") return null;
 			try {
 				const transformedCode = transformTargets(code, componentRegistry, contextProviders);
 				if (transformedCode) return {
@@ -833,7 +878,7 @@ async function scanComponents(project, projectRoot, componentPath, registryPath)
 	});
 	logger.debug(`🔍 Scanning ${componentFiles.length} files in ${componentPath}...`);
 	const components = [];
-	const registryDir = dirname(resolve(projectRoot, registryPath));
+	const registryDir = dirname(resolve$1(projectRoot, registryPath));
 	for (const filePath of componentFiles) try {
 		const content = readFileSync(filePath, "utf-8");
 		const sourceFile = project.createSourceFile(filePath, content, { overwrite: true });
@@ -876,11 +921,10 @@ async function scanComponents(project, projectRoot, componentPath, registryPath)
 function generateRegistryCode(components, registryIdentifier = "registry") {
 	const sorted = [...components].sort((a, b) => a.id.localeCompare(b.id) || a.relativePath.localeCompare(b.relativePath));
 	if (sorted.length === 0) return `
-/* eslint-disable */
 /**
  * Initialize the static component registry.
  * This function is auto-generated by the staticRegistry Vite plugin.
- * 
+ *
  * DO NOT EDIT THIS FUNCTION MANUALLY - it will be overwritten on next build.
  */
 export function initializeRegistry(targetRegistry = ${registryIdentifier}): void {
@@ -897,13 +941,12 @@ export function initializeRegistry(targetRegistry = ${registryIdentifier}): void
 		} else return `    targetRegistry.registerImporter('${id}', () => import('${relativePath}'));`;
 	}).join("\n");
 	return `
-/* eslint-disable */
 /**
  * Initialize the static component registry.
  * This function is auto-generated by the staticRegistry Vite plugin.
- * 
+ *
  * DO NOT EDIT THIS FUNCTION MANUALLY - it will be overwritten on next build.
- * 
+ *
  * Components registered: ${sorted.map((c) => c.id).join(", ")}
  */
 export function initializeRegistry(targetRegistry = ${registryIdentifier}): void {
@@ -912,9 +955,42 @@ ${registrations}
 `;
 }
 /**
+* Formats registry file content with the project's own Prettier so the written file
+* matches what the project's formatter would produce.
+*
+* Without this, a standalone `prettier --write` (pre-commit hook, format-on-save) rewrites
+* the generated file on every commit: the generator emits one `registerImporter` call per
+* line and cannot anticipate an arbitrary `printWidth`, so Prettier re-wraps long lines and
+* the regenerate -> format -> regenerate loop never settles.
+*
+* Prettier is resolved from the registry file's own location — i.e. the consuming project's
+* `node_modules`, not the SDK bundle (which keeps `node_modules` external). It is the project's
+* Prettier version and config whose output must be matched. Returns the content unchanged when
+* Prettier is absent or fails, so registry generation never breaks a build over formatting.
+*/
+let warnedNoPrettier = false;
+async function formatWithProjectPrettier(content, registryFilePath) {
+	try {
+		const prettier = createRequire(registryFilePath)("prettier");
+		const config = await prettier.resolveConfig(registryFilePath, { editorconfig: true });
+		return await prettier.format(content, {
+			...config,
+			filepath: registryFilePath
+		});
+	} catch (error) {
+		if (error.code === "MODULE_NOT_FOUND") {
+			if (!warnedNoPrettier) {
+				logger.warn("⚠️  Prettier not found in the project; static registry will be written unformatted.");
+				warnedNoPrettier = true;
+			}
+		} else logger.warn(`⚠️  Skipping Prettier formatting for registry file: ${error.message}`);
+		return content;
+	}
+}
+/**
 * Updates the registry.ts file with the generated code
 */
-function updateRegistryFile(registryFilePath, generatedCode) {
+async function updateRegistryFile(registryFilePath, generatedCode) {
 	let existingContent;
 	if (!existsSync(registryFilePath)) {
 		logger.debug("📝 Creating new registry file...");
@@ -939,7 +1015,7 @@ export const registry = new ComponentRegistry();
 	const startIndex = existingContent.indexOf(startMarker);
 	const endIndex = existingContent.indexOf(endMarker);
 	if (startIndex === -1 || endIndex === -1) throw new Error(`Registry file ${registryFilePath} is missing static registry markers. Please add "${startMarker}" and "${endMarker}" markers to define the generated content area.`);
-	const updatedContent = `${existingContent.slice(0, startIndex + 24)}\n${generatedCode}\n${existingContent.slice(endIndex)}`;
+	const updatedContent = await formatWithProjectPrettier(`${existingContent.slice(0, startIndex + 24)}\n${generatedCode}\n${existingContent.slice(endIndex)}`, registryFilePath);
 	if (updatedContent === existingContent) {
 		logger.debug(`⏭️  Registry unchanged, skipping write: ${registryFilePath}`);
 		return false;
@@ -990,8 +1066,8 @@ const staticRegistryPlugin = (config = {}) => {
 		} }), projectRoot, componentPath, registryPath);
 		logger.debug(`📦 Found ${components.length} components with @Component decorators`);
 		const generatedCode = generateRegistryCode(components, registryIdentifier);
-		const registryFilePath = resolve(projectRoot, registryPath);
-		const changed = updateRegistryFile(registryFilePath, generatedCode);
+		const registryFilePath = resolve$1(projectRoot, registryPath);
+		const changed = await updateRegistryFile(registryFilePath, generatedCode);
 		logger.debug("✅ Static registry generation complete!");
 		return {
 			registryFilePath,
@@ -1033,15 +1109,68 @@ const staticRegistryPlugin = (config = {}) => {
 	};
 };
 
+//#endregion
+//#region src/server/ts-import.ts
+/**
+* Parse TypeScript paths from tsconfig.json and convert to jiti alias format.
+*
+* @param tsconfigPath - Path to tsconfig.json
+* @param projectDirectory - Project root directory for resolving relative paths
+* @returns Record of alias mappings for jiti
+*
+* @example
+* // tsconfig.json: { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
+* // Returns: { "@/": "/absolute/path/to/src/" }
+*/
+function parseTsconfigPaths(tsconfigPath, projectDirectory) {
+	const alias = {};
+	if (!existsSync$1(tsconfigPath)) return alias;
+	try {
+		const tsconfigContent = readFileSync$1(tsconfigPath, "utf-8");
+		const tsconfig = JSON.parse(tsconfigContent);
+		const paths = tsconfig.compilerOptions?.paths;
+		const baseUrl = tsconfig.compilerOptions?.baseUrl || ".";
+		if (paths) {
+			for (const [key, values] of Object.entries(paths)) if (values && values.length > 0) {
+				const aliasKey = key.replace(/\/\*$/, "/");
+				alias[aliasKey] = resolve(projectDirectory, baseUrl, values[0].replace(/\/\*$/, "/").replace(/^\.\//, ""));
+			}
+		}
+	} catch {}
+	const sortedAlias = {};
+	Object.keys(alias).sort((a, b) => b.length - a.length).forEach((key) => {
+		sortedAlias[key] = alias[key];
+	});
+	return sortedAlias;
+}
+/**
+* Import a TypeScript file using jiti with proper path alias resolution.
+* This is a cross-platform alternative to tsx that works on Windows.
+*
+* @param filePath - Absolute path to the TypeScript file to import
+* @param options - Import options including project directory
+* @returns The imported module
+*/
+async function importTypescript(filePath, options) {
+	const { projectDirectory, tsconfigPath = resolve(projectDirectory, "tsconfig.json") } = options;
+	const { createJiti } = await import("jiti");
+	const alias = parseTsconfigPaths(tsconfigPath, projectDirectory);
+	return createJiti(import.meta.url, {
+		fsCache: false,
+		interopDefault: true,
+		alias
+	}).import(filePath);
+}
+
 //#endregion
 //#region src/plugins/configLoader.ts
 /**
 * Load the engagement config from config.server.ts
 */
 async function loadEngagementConfig(projectRoot, configPath) {
-	const absoluteConfigPath = resolve(projectRoot, configPath);
+	const absoluteConfigPath = resolve$1(projectRoot, configPath);
 	try {
-		const config = (await import(pathToFileURL(absoluteConfigPath).href)).default;
+		const config = (await importTypescript(absoluteConfigPath, { projectDirectory: projectRoot })).default;
 		logger.debug(`📄 Loaded config from ${configPath}`);
 		const engagement = config?.app?.engagement;
 		if (!engagement) {
@@ -1066,7 +1195,7 @@ async function scanForInstrumentedEvents(projectRoot, scanPaths) {
 	const sendViewPagePattern = /sendViewPageEvent\s*\(/g;
 	const createEventPattern = /createEvent\s*\(\s*['"]([^'"]+)['"]/g;
 	for (const scanPath of scanPaths) {
-		const files = await glob(join(resolve(projectRoot, scanPath), "**/*.{ts,tsx}"), { ignore: [
+		const files = await glob(join(resolve$1(projectRoot, scanPath), "**/*.{ts,tsx}"), { ignore: [
 			"**/*.test.ts",
 			"**/*.test.tsx",
 			"**/*.spec.ts",
@@ -1218,17 +1347,17 @@ const buildMiddlewareRegistryPlugin = () => {
 		configResolved(config) {
 			resolvedConfig = config;
 			const rr = config.__reactRouterPluginContext?.reactRouterConfig ?? {};
-			buildDirectory = rr.buildDirectory ?? resolve(config.root, "build");
+			buildDirectory = rr.buildDirectory ?? resolve$1(config.root, "build");
 			appDirectory = rr.appDirectory ?? "src";
 		},
 		buildApp: {
 			order: "post",
 			handler: async () => {
 				const projectRoot = resolvedConfig.root;
-				const middlewareRegistryPath = resolve(projectRoot, appDirectory, SERVER_OUT_SUBDIR, MIDDLEWARE_REGISTRY_SOURCE_FILE);
+				const middlewareRegistryPath = resolve$1(projectRoot, appDirectory, SERVER_OUT_SUBDIR, MIDDLEWARE_REGISTRY_SOURCE_FILE);
 				if (!existsSync(middlewareRegistryPath)) return;
 				const { build } = await import("tsdown");
-				const serverOutDir = resolve(projectRoot, buildDirectory, SERVER_OUT_SUBDIR);
+				const serverOutDir = resolve$1(projectRoot, buildDirectory, SERVER_OUT_SUBDIR);
 				await build({
 					cwd: projectRoot,
 					entry: { [MIDDLEWARE_REGISTRY_SOURCE_FILE.replace(/\.ts$/, "")]: middlewareRegistryPath },
@@ -1308,7 +1437,7 @@ export * from ${importPath};
 export default _composed.default;
 export const handleDataRequest = _composed.handleDataRequest;
 export const handleError = _composed.handleError;
-export const unstable_instrumentations = _composed.unstable_instrumentations;
+export const instrumentations = _composed.instrumentations;
 export const streamTimeout = _composed.streamTimeout;
 `.trim();
 }
@@ -1453,7 +1582,7 @@ const workspacePlugin = () => {
 
 //#endregion
 //#region src/plugins/componentLoaders.ts
-const traverse$1 = traverseModule.default || traverseModule;
+const traverse = traverseModule.default || traverseModule;
 const generate$1 = generate.default || generate;
 /**
 * Names of exports to strip per environment.
@@ -1483,7 +1612,7 @@ function hasExportCandidate(code, names) {
 */
 function hasComponentDecorator(ast) {
 	let found = false;
-	traverse$1(ast, { ClassDeclaration(path$2) {
+	traverse(ast, { ClassDeclaration(path$2) {
 		const decorators = path$2.node.decorators;
 		if (!decorators) return;
 		for (const decorator of decorators) if (decorator.expression.type === "CallExpression" && isIdentifier(decorator.expression.callee) && decorator.expression.callee.name === "Component") {
@@ -1530,7 +1659,7 @@ function stripExports(code, exportsToStrip, preParsedAst) {
 	let changed = false;
 	const previouslyReferencedIdentifiers = findReferencedIdentifiers(ast);
 	const removedExportLocalNames = /* @__PURE__ */ new Set();
-	traverse$1(ast, { ExportNamedDeclaration(path$2) {
+	traverse(ast, { ExportNamedDeclaration(path$2) {
 		const { declaration, specifiers } = path$2.node;
 		if (declaration && isVariableDeclaration(declaration)) {
 			const remaining = declaration.declarations.filter((decl) => {
@@ -1588,7 +1717,7 @@ function stripExports(code, exportsToStrip, preParsedAst) {
 			}
 		}
 	} });
-	if (changed) traverse$1(ast, { ExpressionStatement(path$2) {
+	if (changed) traverse(ast, { ExpressionStatement(path$2) {
 		if (!path$2.parentPath?.isProgram()) return;
 		if (path$2.node.expression.type === "AssignmentExpression") {
 			const left = path$2.node.expression.left;
@@ -1907,93 +2036,19 @@ function storefrontNextTargets(config = {}) {
 
 //#endregion
 //#region src/plugins/uiTargetDevMode.ts
-const traverse = traverseModule.default || traverseModule;
-const UI_TARGET_JSX_RE = /<UITarget[\s/>]/;
 /**
-* Vite plugin that adds visual markers to UITarget components in development.
+* @deprecated This plugin has been removed. It was an internal-only debugging aid
+* that could cause build failures when extensions were trimmed. The export is kept
+* as a no-op for backward compatibility and will be removed in v2.
 *
-* PRODUCTION: This plugin is completely inactive - zero overhead.
-* DEVELOPMENT: Transforms UITarget JSX to add visual debugging markers.
+* **Migration:** Remove any `uiTargetDevMode()` plugin from your `vite.config.ts`,
+* delete `vite-plugins/ui-target-dev-mode.ts` if it exists, and remove the plugin
+* from the Vite plugins array.
 *
-* @example
-* // Source code:
-* <UITarget targetId="pdp.loyalty.badge">
-*   <Widget />
-* </UITarget>
-*
-* // Transformed in DEV mode:
-* <UITargetDevMarker
-*   targetId="pdp.loyalty.badge"
-*   __file__="/src/components/product.tsx"
-*   __hasChildren__={true}
-* >
-*   <Widget />
-* </UITargetDevMarker>
-*/
-function uiTargetDevModePlugin(config = {}) {
-	if (process.env.NODE_ENV === "production") return { name: "storefront-next:ui-target-dev-mode-noop" };
-	if (!(config.enabled ?? process.env.VITE_UI_TARGET_DEV_MODE === "true")) return { name: "storefront-next:ui-target-dev-mode-disabled" };
-	logger.info("🎯 UITarget Dev Mode enabled");
-	if (config.filterCategory) logger.info(`   Filtering to category: ${config.filterCategory} (build-time)`);
-	return {
-		name: "storefront-next:ui-target-dev-mode",
-		enforce: "pre",
-		transform(code, id) {
-			if (!id.match(/\.(tsx|jsx)$/)) return null;
-			if (id.includes("node_modules")) return null;
-			if (id.includes("/targets/ui-target.tsx")) return null;
-			if (!UI_TARGET_JSX_RE.test(code) || !code.includes("from '@/targets/ui-target'")) return null;
-			try {
-				const ast = parse(code, {
-					sourceType: "module",
-					plugins: [
-						"typescript",
-						"jsx",
-						"decorators-legacy"
-					]
-				});
-				let hasTransforms = false;
-				const targetIds = [];
-				traverse(ast, { JSXElement(path$2) {
-					const openingElement = path$2.node.openingElement;
-					if (!isJSXIdentifier(openingElement.name) || openingElement.name.name !== "UITarget") return;
-					const targetIdAttr = openingElement.attributes.find((attr) => isJSXAttribute(attr) && isJSXIdentifier(attr.name) && attr.name.name === "targetId");
-					if (!targetIdAttr) {
-						logger.warn(`UITarget without targetId in ${id}`);
-						return;
-					}
-					const targetId = isStringLiteral(targetIdAttr.value) ? targetIdAttr.value.value : null;
-					if (!targetId) {
-						logger.warn(`UITarget with non-string targetId in ${id}`);
-						return;
-					}
-					if (config.filterCategory && !targetId.startsWith(`${config.filterCategory}.`)) return;
-					const hasChildren = path$2.node.children.length > 0;
-					openingElement.name = jsxIdentifier("UITargetDevMarker");
-					if (path$2.node.closingElement) path$2.node.closingElement.name = jsxIdentifier("UITargetDevMarker");
-					const hint = config.hintMap?.[targetId];
-					openingElement.attributes.push(jsxAttribute(jsxIdentifier("__file__"), stringLiteral(id)), jsxAttribute(jsxIdentifier("__hasChildren__"), jsxExpressionContainer(booleanLiteral(hasChildren))), ...hint ? [jsxAttribute(jsxIdentifier("__hint__"), stringLiteral(hint))] : []);
-					hasTransforms = true;
-					targetIds.push(targetId);
-				} });
-				if (!hasTransforms) return null;
-				const devMarkerImport = importDeclaration([importSpecifier(identifier("UITargetDevMarker"), identifier("UITargetDevMarker"))], stringLiteral("@/lib/ui-target-dev-mode/marker"));
-				ast.program.body.unshift(devMarkerImport);
-				const output = generate(ast, {
-					retainLines: true,
-					compact: false
-				}, code);
-				logger.debug(`Transformed ${targetIds.length} targets in ${id.split("/").pop()}`);
-				return {
-					code: output.code,
-					map: output.map
-				};
-			} catch (error) {
-				logger.error(`Failed to transform UITarget in ${id}:`, error);
-				return null;
-			}
-		}
-	};
+* @returns A no-op Vite plugin
+*/
+function uiTargetDevModePlugin(_config) {
+	return { name: "storefront-next:ui-target-dev-mode-deprecated-noop" };
 }
 
 //#endregion
@@ -2098,6 +2153,82 @@ function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
+* Resolve a captured prefix segment to its canonical-cased alias, case-insensitively.
+* Returns the matching entry from `aliases` (preserving the catalog's casing) so the value
+* forwarded to SFRA is always the expected canonical form, or `undefined` when the segment
+* isn't a known site/locale identifier.
+*/
+function matchAlias(segment, aliases) {
+	if (segment === void 0) return void 0;
+	const lower = segment.toLowerCase();
+	return aliases.find((alias) => alias.toLowerCase() === lower);
+}
+/**
+* Rewrite an incoming proxy pathname to the SFRA `/s/{siteId}/{locale}/…` shape.
+*
+* This is the OOTB path transform. It is `url.prefix`-aware: when `urlPrefix` is set
+* it strips the configured prefix to recover the bare functional path AND reuses the
+* site/locale the path already carried — so a prefixed request like `/uk/cart` becomes
+* `/s/{siteId}/uk/cart` rather than the double-stacked `/s/{siteId}/{locale}/uk/cart`.
+*
+* It handles every standard prefix shape uniformly:
+* - no prefix (`''`/`/`):     `/cart`            → `/s/{site}/{locale}/cart`
+* - `/:localeId`:             `/uk/cart`         → `/s/{site}/uk/cart`
+* - `/:siteId/:localeId`:     `/global/uk/cart`  → `/s/global/uk/cart`
+*
+* Disambiguation: a captured prefix segment is only treated as a site/locale when it is
+* a known identifier (`siteAliases`/`localeAliases`). This stops a bare path like `/cart`
+* under a `/:localeId` prefix — which is structurally indistinguishable from a locale
+* home `/uk` — from being mis-stripped (here `cart` isn't a known locale, so the whole
+* path is treated as the bare functional path and decorated with the `defaultSiteId`/
+* `defaultLocale` fallbacks). When a prefix segment IS a known site/locale, that value is
+* passed straight through as the SFRA path segment; SFRA resolves both the BM site-path
+* alias (`uk`) and the canonical id (`en-GB`).
+*
+* Paths already in SFCC shape (`/s/…`, `/on/demandware.…`) are returned unchanged — the
+* caller is expected to skip them, but this stays defensive.
+*
+* Pure function (query string handled by the caller) so it's unit-testable in isolation.
+*
+* @param pathname - Incoming pathname on the proxy (no query string).
+* @param opts.defaultSiteId - Site to use when the path doesn't carry one.
+* @param opts.defaultLocale - Locale to use when the path doesn't carry one.
+* @param opts.urlPrefix - The storefront's `url.prefix` (e.g. `'/:siteId/:localeId'`).
+* @param opts.localeAliases - Known locale ids + aliases.
+* @param opts.siteAliases - Known site ids + aliases.
+*/
+function rewriteToSfraPath(pathname, opts) {
+	const { defaultSiteId, defaultLocale, urlPrefix, localeAliases = [], siteAliases = [] } = opts;
+	if (pathname.startsWith("/s/") || pathname.startsWith("/on/demandware.")) return pathname;
+	let site = defaultSiteId;
+	let locale = defaultLocale;
+	let barePath = pathname;
+	let localeFromPath = false;
+	if (urlPrefix && urlPrefix !== "/") {
+		const captured = extractPrefixParamValues({
+			pathname,
+			prefix: urlPrefix
+		});
+		const matchedSite = "siteId" in captured ? matchAlias(captured.siteId, siteAliases) : void 0;
+		const matchedLocale = "localeId" in captured ? matchAlias(captured.localeId, localeAliases) : void 0;
+		const siteOk = !("siteId" in captured) || matchedSite !== void 0;
+		const localeOk = !("localeId" in captured) || matchedLocale !== void 0;
+		if (Object.keys(captured).length > 0 && siteOk && localeOk) {
+			if (matchedSite) site = matchedSite;
+			if (matchedLocale) {
+				locale = matchedLocale;
+				localeFromPath = true;
+			}
+			barePath = stripPathPrefix({
+				pathname,
+				prefix: urlPrefix
+			}) || "/";
+		}
+	}
+	if (barePath === "/") return localeFromPath ? `/s/${site}/${locale}/` : `/s/${site}`;
+	return `/s/${site}/${locale}${barePath}`;
+}
+/**
 * Rewrite an SFCC Location header so the user stays on the proxy origin AND so
 * any query params from the original request survive an SFCC redirect.
 *
@@ -2173,7 +2304,8 @@ function hybridProxyPlugin(options) {
 	logger.debug(`Hybrid proxy routing rules: ${options.routingRules.slice(0, 100)}...`);
 	const locale = options.locale || "default";
 	const defaultSiteId = options.defaultSiteId;
-	logger.debug(`Hybrid proxy path transformation: / → /s/${defaultSiteId}, /path → /s/${defaultSiteId}/${locale}/path`);
+	const { urlPrefix, localeAliases, siteAliases, rewritePath } = options;
+	logger.debug(urlPrefix ? `Hybrid proxy path transformation: url.prefix=${urlPrefix} → /s/${defaultSiteId}/{locale}/{bare path}` : `Hybrid proxy path transformation: / → /s/${defaultSiteId}, /path → /s/${defaultSiteId}/${locale}/path`);
 	const targetOriginPattern = new RegExp(escapeRegExp(options.targetOrigin), "g");
 	const proxy = httpProxy.createProxyServer({
 		changeOrigin: true,
@@ -2185,13 +2317,13 @@ function hybridProxyPlugin(options) {
 		const pathname = url.pathname;
 		if (!pathname.startsWith("/s/") && !pathname.startsWith("/on/demandware.")) {
 			const originalPath = proxyReq.path;
-			/**
-			* "/" maps to the SFRA/SiteGenesis site root — no locale in the path
-			* This would simply proxy to SFCC hostname (eg.: https://zzrf-001.dx.commercecloud.salesforce.com/s/{siteId}/{locale}/) which is not a valid storefront URL.
-			* We need to rewrite the path to /s/{siteId} so that it can be proxied to the correct SFCC URL.
-			*/
-			if (pathname === "/") proxyReq.path = `/s/${defaultSiteId}${url.search}`;
-			else proxyReq.path = `/s/${defaultSiteId}/${locale}${pathname}${url.search}`;
+			proxyReq.path = `${rewritePath?.(pathname) ?? null ?? rewriteToSfraPath(pathname, {
+				defaultSiteId,
+				defaultLocale: locale,
+				urlPrefix,
+				localeAliases,
+				siteAliases
+			})}${url.search}`;
 			logger.debug(`Hybrid proxy path rewrite: ${originalPath} → ${proxyReq.path}`);
 		}
 	});