@kimesh/kit 0.2.6 → 0.2.7-nightly.20260124083945

package/dist/index.mjs

@@ -8,7 +8,8 @@ import consola from "consola";
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import fg from "fast-glob";
-import { basename, extname, isAbsolute as isAbsolute$1, join as join$1, relative, resolve as resolve$1 } from "pathe";
+import { basename, dirname as dirname$1, extname, isAbsolute as isAbsolute$1, join as join$1, relative, resolve as resolve$1 } from "pathe";
+import { resolveModulePath } from "exsolve";
 import ignore from "ignore";
 import pc from "picocolors";
 import { defu } from "defu";
@@ -97,18 +98,18 @@ function hasConfigPath(config, keys) {
 function getPossiblePaths(envKey) {
 	const parts = envKey.toLowerCase().split("_");
 	const paths = [];
-	function generateGroupings(parts$1, current, start) {
-		if (start >= parts$1.length) {
+	function generateGroupings(parts, current, start) {
+		if (start >= parts.length) {
 			paths.push([...current]);
 			return;
 		}
-		for (let end = start + 1; end <= parts$1.length; end++) {
-			const segment = parts$1.slice(start, end).reduce((acc, part, i) => {
+		for (let end = start + 1; end <= parts.length; end++) {
+			const segment = parts.slice(start, end).reduce((acc, part, i) => {
 				if (i === 0) return part;
 				return acc + part.charAt(0).toUpperCase() + part.slice(1);
 			}, "");
 			current.push(segment);
-			generateGroupings(parts$1, current, end);
+			generateGroupings(parts, current, end);
 			current.pop();
 		}
 	}
@@ -949,11 +950,11 @@ function buildPluginGlobPattern(extensions) {
 async function scanPluginsDir(pluginsDir, options = {}) {
 	if (!existsSync(pluginsDir)) return [];
 	const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
-	const ignore$1 = options.ignore ?? DEFAULT_IGNORE;
+	const ignore = options.ignore ?? DEFAULT_IGNORE;
 	return (await fg(buildPluginGlobPattern(extensions), {
 		cwd: pluginsDir,
 		onlyFiles: true,
-		ignore: ignore$1,
+		ignore,
 		absolute: false
 	})).map((file) => {
 		const { name, order } = parsePluginFilename(file);
@@ -1031,7 +1032,7 @@ function generatePluginsTemplate(options) {
 		imports.push("// Module-registered plugins");
 		for (const plugin of pluginsWithSrc) {
 			const varName = toVariableName(plugin.name || "module", index);
-			const importPath = plugin.src.startsWith("@") || plugin.src.startsWith(".") ? plugin.src : relative(buildDir, plugin.src).replace(/\.ts$/, "");
+			const importPath = plugin.src.startsWith("@") || plugin.src.startsWith(".") || plugin.src.startsWith("#") || plugin.src.startsWith("kimesh/") ? plugin.src : relative(buildDir, plugin.src).replace(/\.ts$/, "");
 			imports.push(`import ${varName} from '${importPath}'`);
 			pluginVars.push(varName);
 			index++;
@@ -1077,6 +1078,121 @@ function addPluginsTemplate(kimesh, discoveredPlugins) {
 	});
 }
 
+//#endregion
+//#region src/kit/internal-alias-template.ts
+/**
+* Internal Alias Template Generator
+*
+* Generates wrapper templates for internal aliases (prefixed with #).
+* These templates re-export the actual package using **resolved absolute paths**,
+* which works correctly across all environments:
+* - Normal npm/pnpm/yarn/bun installs
+* - Workspace development with link:kimesh
+* - PR preview packages
+*
+* The key insight is that @kimesh/kit can resolve @kimesh/* packages because
+* they're peer dependencies. We resolve the paths at build time and generate
+* templates with absolute paths, avoiding the transitive dependency resolution
+* problem in pnpm's strict mode.
+*
+* @module internal-alias-template
+*/
+/**
+* Internal aliases that should be resolved via generated templates.
+*
+* Each entry maps an internal alias (#kimesh/...) to the actual internal
+* package subpath export (@kimesh/...) that should be resolved and re-exported.
+*/
+const INTERNAL_ALIASES = [{
+	alias: "#kimesh/head/plugin",
+	packageSpecifier: "@kimesh/head/plugin",
+	filename: "head-plugin.mjs"
+}, {
+	alias: "#kimesh/router-runtime/default-app",
+	packageSpecifier: "@kimesh/router-runtime/default-app",
+	filename: "router-runtime-default-app.mjs"
+}];
+/**
+* Resolve a package specifier to an absolute file path.
+* This uses exsolve/createRequire to find the package from @kimesh/kit's location.
+*
+* @param specifier - Package specifier like '@kimesh/head/plugin'
+* @returns Resolved absolute path or null if not found
+*/
+function resolvePackagePath(specifier) {
+	const fromUrl = import.meta.url;
+	try {
+		return resolveModulePath(specifier, {
+			from: fromUrl,
+			try: true
+		}) || null;
+	} catch {
+		try {
+			return createRequire(fromUrl).resolve(specifier);
+		} catch {
+			return null;
+		}
+	}
+}
+/**
+* Generate the content for an internal alias template file.
+*
+* The generated file re-exports everything from the **resolved absolute path**,
+* not from a package specifier. This ensures the import works correctly even
+* when the package is a transitive dependency that can't be directly resolved
+* from the host app.
+*
+* @param config - The internal alias configuration
+* @param resolvedPath - The resolved absolute path to the module
+* @returns Generated template content
+*/
+function generateInternalAliasTemplate(config, resolvedPath) {
+	return `/**
+ * Kimesh Internal Alias - ${config.alias}
+ * Auto-generated wrapper for ${config.packageSpecifier}
+ * Resolved to: ${resolvedPath}
+ * DO NOT EDIT - This file is regenerated by Kimesh
+ */
+
+export * from '${resolvedPath}'
+export { default } from '${resolvedPath}'
+`;
+}
+/**
+* Register internal alias templates with the Kimesh context.
+*
+* This function resolves the actual paths to @kimesh/* packages at build time
+* and generates templates that use those absolute paths. This ensures the
+* imports work correctly across all environments including PR preview packages.
+*
+* @param kimesh - The Kimesh context
+*/
+function addInternalAliasTemplates(kimesh) {
+	for (const config of INTERNAL_ALIASES) {
+		const resolvedPath = resolvePackagePath(config.packageSpecifier);
+		if (resolvedPath) kimesh._registries.templates.push({
+			filename: config.filename,
+			getContents: () => generateInternalAliasTemplate(config, resolvedPath)
+		});
+		else console.warn(`[Kimesh] Could not resolve internal alias ${config.alias} (${config.packageSpecifier})`);
+	}
+}
+/**
+* Build a map of internal alias to generated template file path.
+*
+* This is used to configure Vite's resolve.alias so that imports
+* like '#kimesh/head/plugin' are resolved to the generated template
+* file in .kimesh/.
+*
+* @param buildDir - The .kimesh build directory path
+* @returns Record mapping alias to generated file path
+*/
+function buildInternalAliasMap(buildDir) {
+	const aliases = {};
+	for (const config of INTERNAL_ALIASES) aliases[config.alias] = `${buildDir}/${config.filename}`;
+	return aliases;
+}
+
 //#endregion
 //#region src/types/config.ts
 /**
@@ -1178,9 +1294,9 @@ function toTsConfigPaths(aliases, rootDir) {
 * @param debug - Debug config from KimeshConfig (boolean or DebugConfig)
 * @returns Normalized DebugConfig
 */
-function normalizeDebugConfig(debug$1) {
-	if (!debug$1) return {};
-	if (debug$1 === true) return {
+function normalizeDebugConfig(debug) {
+	if (!debug) return {};
+	if (debug === true) return {
 		hooks: true,
 		modules: true,
 		layers: true,
@@ -1189,7 +1305,7 @@ function normalizeDebugConfig(debug$1) {
 		routes: true,
 		imports: true
 	};
-	return debug$1;
+	return debug;
 }
 /**
 * Check if a specific debug option is enabled
@@ -1198,10 +1314,10 @@ function normalizeDebugConfig(debug$1) {
 * @param option - Debug option to check
 * @returns Whether the option is enabled
 */
-function isDebugEnabled(debug$1, option) {
-	if (!debug$1) return false;
-	if (debug$1 === true) return true;
-	return !!debug$1[option];
+function isDebugEnabled(debug, option) {
+	if (!debug) return false;
+	if (debug === true) return true;
+	return !!debug[option];
 }
 
 //#endregion
@@ -1288,7 +1404,7 @@ function matchRoutePattern(pattern, routePath) {
 	const normalizedPattern = pattern.replace(/\/+/g, "/").replace(/\/$/, "");
 	const normalizedPath = routePath.replace(/\/+/g, "/").replace(/\/$/, "");
 	let regexPattern = normalizedPattern.replace(/\/\*\*/g, "___DOUBLE_WILDCARD___").replace(/\*/g, "___SINGLE_WILDCARD___").replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/___DOUBLE_WILDCARD___/g, "(?:/.*)?").replace(/___SINGLE_WILDCARD___/g, "[^/]+");
-	return (/* @__PURE__ */ new RegExp(`^${regexPattern}$`)).test(normalizedPath);
+	return new RegExp(`^${regexPattern}$`).test(normalizedPath);
 }
 /**
 * Find matching route rules for a given path
@@ -1579,6 +1695,46 @@ function writeTsConfig(options) {
 	mkdirSync(buildDir, { recursive: true });
 	const tsconfig = generateTsConfig(options);
 	writeFileSync(join$1(buildDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2), "utf-8");
+	writeFileSync(join$1(buildDir, "kimesh.d.ts"), generateKimeshDts(), "utf-8");
+}
+/**
+* Generate kimesh.d.ts content with global type declarations
+*
+* This file directly declares global types instead of using triple-slash references,
+* ensuring compatibility with various package manager setups (npm, pnpm, bun, workspace links).
+*/
+function generateKimeshDts() {
+	return `/* eslint-disable */
+/* prettier-ignore */
+
+/**
+ * Kimesh Framework Type Declarations
+ *
+ * This file provides global type declarations for the Kimesh framework.
+ *
+ * DO NOT EDIT - This file is auto-generated by Kimesh.
+ */
+
+export {}
+
+declare global {
+  /**
+   * Define Kimesh configuration with type inference.
+   * This function is available globally in kimesh.config.ts files.
+   *
+   * @example
+   * \`\`\`ts
+   * export default defineKmConfig({
+   *   name: 'my-app',
+   *   dev: {
+   *     port: 3000,
+   *   },
+   * })
+   * \`\`\`
+   */
+  const defineKmConfig: <T extends Record<string, unknown>>(config: T) => T
+}
+`;
 }
 
 //#endregion
@@ -1784,17 +1940,17 @@ function toViteWatchOptions(config) {
 * Generate the entry point code for a Kimesh app
 */
 function generateEntryCode(options) {
-	const { hasContext, hasPlugins: hasPlugins$1 } = options;
+	const { hasContext, hasPlugins } = options;
 	const imports = [
 		`import { createKimeshApp } from '@kimesh/router-runtime'`,
 		`import { routes } from '#kimesh/routes'`,
 		`import App from '#kimesh/app'`
 	];
 	if (hasContext) imports.push(`import createContext from '#kimesh/context'`);
-	if (hasPlugins$1) imports.push(`import { plugins } from '#kimesh/plugins'`);
+	if (hasPlugins) imports.push(`import { plugins } from '#kimesh/plugins'`);
 	const optionLines = [`  runtimeConfig: __KIMESH_CONFIG__,`, `  layersConfig: __KIMESH_LAYERS_CONFIG__,`];
 	if (hasContext) optionLines.push(`  context: createContext(),`);
-	if (hasPlugins$1) optionLines.push(`  plugins,`);
+	if (hasPlugins) optionLines.push(`  plugins,`);
 	const optionsBlock = `\n${optionLines.join("\n")}`;
 	return `${imports.join("\n")}
 
@@ -1877,9 +2033,9 @@ function generateHtml(title) {
 * Create HMR watcher for Kimesh layers
 */
 function createHMRWatcher(options) {
-	const { server, layers, debug: debug$1 } = options;
+	const { server, layers, debug } = options;
 	const log = (...args) => {
-		if (debug$1) consola.debug("[kimesh:hmr]", ...args);
+		if (debug) consola.debug("[kimesh:hmr]", ...args);
 	};
 	/**
 	* Detect which layer a file belongs to
@@ -2132,11 +2288,11 @@ function formatTiming(operation, timeMs, details) {
 /**
 * Create a timing logger
 */
-function createTimer(operation, debug$1 = false) {
+function createTimer(operation, debug = false) {
 	const start = performance.now();
 	return { end(details) {
 		const elapsed = performance.now() - start;
-		if (debug$1) console.log(formatTiming(operation, elapsed, details));
+		if (debug) console.log(formatTiming(operation, elapsed, details));
 		return elapsed;
 	} };
 }
@@ -2163,12 +2319,233 @@ function findWorkspaceRoot(startDir) {
 	return startDir;
 }
 /**
+* Try to resolve a package or subpath export using exsolve.
+* This handles various package manager layouts (npm, pnpm, bun, yarn)
+* and properly resolves subpath exports like "@kimesh/head/plugin"
+*
+* @param specifier - Full package specifier (e.g., "@kimesh/head" or "@kimesh/head/plugin")
+* @param fromDir - Directory to resolve from
+* @returns Resolved file path or null if not found
+*/
+function tryResolveModule(specifier, fromUrl) {
+	try {
+		return resolveModulePath(specifier, {
+			from: fromUrl,
+			try: true
+		}) || null;
+	} catch {
+		try {
+			return createRequire(fromUrl).resolve(specifier);
+		} catch {
+			return null;
+		}
+	}
+}
+/**
+* Try to resolve a package directory (not a specific file).
+* Used for aliasing the base package.
+*/
+function tryResolvePackage(packageName, fromUrl) {
+	try {
+		const resolved = resolveModulePath(packageName, {
+			from: fromUrl,
+			try: true
+		});
+		if (resolved) {
+			const parts = resolved.split("/");
+			const nodeModulesIndex = parts.lastIndexOf("node_modules");
+			if (nodeModulesIndex !== -1) {
+				const pkgPathLength = packageName.split("/")[0].startsWith("@") ? 2 : 1;
+				return parts.slice(0, nodeModulesIndex + 1 + pkgPathLength).join("/");
+			}
+			return dirname$1(dirname$1(resolved));
+		}
+	} catch {}
+	return null;
+}
+/**
+* Find the kimesh packages location.
+* This handles both installed packages (in node_modules) and workspace development.
+*
+* The search strategy:
+* 1. Check if we're in a workspace development setup (kimesh/packages/*)
+* 2. From @kimesh/kit's location, traverse up to find the parent "kimesh" package
+* 3. In pnpm/bun workspace: kit -> ../kimesh/node_modules
+* 4. In npm flat layout: kit is in node_modules/@kimesh/kit, umbrella is in node_modules/kimesh
+*/
+function findKimeshPackagesLocation(kitPath, debug) {
+	const kitDir = dirname$1(dirname$1(kitPath.replace(/^file:\/\//, "")));
+	consola.debug(`[Kimesh] kitPath: ${kitPath}`);
+	consola.debug(`[Kimesh] kitDir (after 2x dirname): ${kitDir}`);
+	const packagesDir = dirname$1(kitDir);
+	const headSibling = resolve$1(packagesDir, "head");
+	const routerRuntimeSibling = resolve$1(packagesDir, "router-runtime");
+	consola.debug(`[Kimesh] packagesDir: ${packagesDir}`);
+	consola.debug(`[Kimesh] headSibling: ${headSibling}, exists: ${existsSync(headSibling)}`);
+	consola.debug(`[Kimesh] routerRuntimeSibling: ${routerRuntimeSibling}, exists: ${existsSync(routerRuntimeSibling)}`);
+	if (existsSync(headSibling) && existsSync(routerRuntimeSibling)) {
+		const headPkgPath = join$1(headSibling, "package.json");
+		const routerPkgPath = join$1(routerRuntimeSibling, "package.json");
+		consola.debug(`[Kimesh] headPkgPath: ${headPkgPath}, exists: ${existsSync(headPkgPath)}`);
+		consola.debug(`[Kimesh] routerPkgPath: ${routerPkgPath}, exists: ${existsSync(routerPkgPath)}`);
+		if (existsSync(headPkgPath) && existsSync(routerPkgPath)) try {
+			const headPkg = JSON.parse(readFileSync(headPkgPath, "utf-8"));
+			const routerPkg = JSON.parse(readFileSync(routerPkgPath, "utf-8"));
+			consola.debug(`[Kimesh] headPkg.name: ${headPkg.name}`);
+			consola.debug(`[Kimesh] routerPkg.name: ${routerPkg.name}`);
+			if (headPkg.name === "@kimesh/head" && routerPkg.name === "@kimesh/router-runtime") {
+				consola.debug(`[Kimesh] Found workspace development (sibling packages): ${packagesDir}`);
+				return {
+					type: "workspace-packages",
+					path: packagesDir
+				};
+			}
+		} catch (e) {
+			consola.warn(`[Kimesh] Error reading package.json: ${e}`);
+		}
+	}
+	const workspaceUmbrella = resolve$1(kitDir, "..", "kimesh", "node_modules");
+	if (existsSync(join$1(workspaceUmbrella, "@kimesh"))) {
+		if (debug) consola.info(`[Kimesh] Found umbrella node_modules (workspace): ${workspaceUmbrella}`);
+		return {
+			type: "node_modules",
+			path: workspaceUmbrella
+		};
+	}
+	const parts = kitDir.split("/");
+	const nmIndex = parts.lastIndexOf("node_modules");
+	if (nmIndex !== -1) {
+		const parentNodeModules = parts.slice(0, nmIndex + 1).join("/");
+		if (existsSync(join$1(parentNodeModules, "@kimesh", "router-runtime"))) {
+			if (debug) consola.info(`[Kimesh] Found umbrella node_modules (installed): ${parentNodeModules}`);
+			return {
+				type: "node_modules",
+				path: parentNodeModules
+			};
+		}
+	}
+	if (debug) consola.warn(`[Kimesh] Could not find kimesh packages location from: ${kitDir}`);
+	return null;
+}
+/**
+* Map from @kimesh/* package name to the directory name in kimesh/packages/
+* Most follow the pattern @kimesh/{name} -> {name}, but some differ
+*/
+const PACKAGE_DIR_MAP = {
+	"@kimesh/router-runtime": "router-runtime",
+	"@kimesh/head": "head",
+	"@kimesh/query": "query",
+	"@kimesh/kit": "kit",
+	"@kimesh/layers": "layers",
+	"@kimesh/auto-import": "auto-import",
+	"@kimesh/router-generator": "router-generator"
+};
+/**
+* Map subpath exports to their actual dist file paths
+*
+* This map is used for workspace development (link:kimesh) where we need to
+* resolve subpath exports directly to dist files since symlinked packages
+* don't resolve subpath exports correctly via Vite's alias system.
+*
+* NOTE: We now prefer using `kimesh/head/plugin` (umbrella package subpath)
+* over `@kimesh/head/plugin` (direct internal package) because the umbrella
+* package re-exports work correctly in PR preview packages and all setups.
+*/
+const SUBPATH_EXPORT_MAP = {
+	"@kimesh/head/plugin": {
+		pkg: "head",
+		file: "dist/plugin.mjs"
+	},
+	"@kimesh/router-runtime/default-app": {
+		pkg: "router-runtime",
+		file: "dist/default-app.mjs"
+	},
+	"kimesh/head/plugin": {
+		pkg: "head",
+		file: "dist/plugin.mjs"
+	},
+	"kimesh/router-runtime/default-app": {
+		pkg: "router-runtime",
+		file: "dist/default-app.mjs"
+	}
+};
+/**
+* Build aliases for @kimesh/* packages and their subpath exports.
+* This ensures Vite can resolve these packages regardless of package manager.
+*
+* KEY INSIGHT: We find the "kimesh" umbrella package's node_modules, then
+* resolve all @kimesh/* packages from there. This works because:
+* 1. User's project depends on the umbrella "kimesh" package
+* 2. The umbrella package has @kimesh/kit, @kimesh/head, etc. as dependencies
+* 3. Those dependencies are installed in the umbrella's node_modules
+*
+* For workspace development (link:kimesh), we directly resolve from sibling packages.
+*
+* Unlike simple package aliases, this also handles subpath exports like:
+* - "@kimesh/head/plugin" -> actual file path
+* - "@kimesh/router-runtime/default-app" -> actual file path
+*/
+function buildKimeshPackageAliases(_rootDir, debug) {
+	const kitUrl = import.meta.url;
+	const location = findKimeshPackagesLocation(kitUrl, debug);
+	if (debug) consola.debug(`[Kimesh] Package location detected: type=${location?.type}, path=${location?.path}`);
+	const aliases = {};
+	const packages = Object.keys(PACKAGE_DIR_MAP);
+	const subpathExports = Object.keys(SUBPATH_EXPORT_MAP);
+	if (location?.type === "workspace-packages") {
+		if (debug) consola.info(`[Kimesh] Resolving packages from workspace: ${location.path}`);
+		for (const pkg of packages) {
+			const dirName = PACKAGE_DIR_MAP[pkg];
+			const pkgDir = join$1(location.path, dirName);
+			if (existsSync(pkgDir)) {
+				aliases[pkg] = pkgDir;
+				if (debug) consola.debug(`[Kimesh] Resolved ${pkg} -> ${pkgDir}`);
+			} else if (debug) consola.warn(`[Kimesh] Could not find workspace package: ${pkgDir}`);
+		}
+		for (const specifier of subpathExports) {
+			const mapping = SUBPATH_EXPORT_MAP[specifier];
+			const filePath = join$1(location.path, mapping.pkg, mapping.file);
+			if (existsSync(filePath)) {
+				aliases[specifier] = filePath;
+				if (debug) consola.debug(`[Kimesh] Resolved subpath ${specifier} -> ${filePath}`);
+			} else if (debug) consola.warn(`[Kimesh] Could not find workspace subpath: ${filePath}`);
+		}
+		if (debug) {
+			consola.debug(`[Kimesh] Generated ${Object.keys(aliases).length} workspace aliases`);
+			for (const [key, value] of Object.entries(aliases)) consola.debug(`[Kimesh]   ${key} -> ${value}`);
+		}
+		return aliases;
+	}
+	let fromUrl;
+	if (location?.type === "node_modules") fromUrl = "file://" + join$1(location.path, "package.json");
+	else {
+		fromUrl = kitUrl;
+		if (debug) consola.warn(`[Kimesh] Falling back to kit location for package resolution`);
+	}
+	if (debug) consola.info(`[Kimesh] Resolving @kimesh/* packages from: ${fromUrl}`);
+	for (const pkg of packages) {
+		const resolved = tryResolvePackage(pkg, fromUrl);
+		if (resolved) {
+			aliases[pkg] = resolved;
+			if (debug) consola.debug(`[Kimesh] Resolved ${pkg} -> ${resolved}`);
+		} else if (debug) consola.warn(`[Kimesh] Could not resolve ${pkg}`);
+	}
+	for (const specifier of subpathExports) {
+		const resolved = tryResolveModule(specifier, fromUrl);
+		if (resolved) {
+			aliases[specifier] = resolved;
+			if (debug) consola.debug(`[Kimesh] Resolved subpath ${specifier} -> ${resolved}`);
+		} else if (debug) consola.warn(`[Kimesh] Could not resolve subpath ${specifier}`);
+	}
+	return aliases;
+}
+/**
 * Process all configured modules using the new v2 system
 */
-async function processModules(kimesh, debug$1) {
+async function processModules(kimesh, debug) {
 	const modules = kimesh.options.config.modules;
 	if (!modules || modules.length === 0) return;
-	const moduleTimer = createTimer("Module processing", debug$1);
+	const moduleTimer = createTimer("Module processing", debug);
 	try {
 		await executeModules(modules, kimesh);
 		moduleTimer.end({ count: modules.length });
@@ -2215,7 +2592,7 @@ ${imports}
 */
 function kimeshPlugin(options = {}) {
 	const config = options.config || {};
-	const debug$1 = options.debug ?? false;
+	const debug = options.debug ?? false;
 	const { plugins: userPlugins = [], ...userViteOptions } = config.vite || {};
 	const allUserPlugins = [...userPlugins, ...options.additionalPlugins || []];
 	const state = {
@@ -2229,9 +2606,21 @@ function kimeshPlugin(options = {}) {
 		enabled: options.layers?.enabled ?? config.layers?.enabled ?? "all",
 		excluded: options.layers?.excluded ?? config.layers?.excluded ?? []
 	};
+	let kimeshPackagesPath = null;
 	const mainPlugin = {
 		name: "kimesh:main",
 		enforce: "pre",
+		resolveId(id) {
+			if (kimeshPackagesPath && SUBPATH_EXPORT_MAP[id]) {
+				const mapping = SUBPATH_EXPORT_MAP[id];
+				const filePath = join$1(kimeshPackagesPath, mapping.pkg, mapping.file);
+				if (existsSync(filePath)) {
+					consola.debug(`[Kimesh:resolveId] Resolved ${id} -> ${filePath}`);
+					return filePath;
+				}
+			}
+			return null;
+		},
 		async config(viteConfig, { command, mode }) {
 			consola.debug(`[Kimesh] Configuring for ${command} mode`);
 			const configRoot = viteConfig.root || process.cwd();
@@ -2241,28 +2630,38 @@ function kimeshPlugin(options = {}) {
 			const resolvedBuildConfig = resolveBuildConfig(config.build);
 			const resolvedDevConfig = resolveDevConfig(config.dev);
 			const resolvedWatchConfig = resolveWatchConfig(config.watch, config.watchers);
-			if (debug$1) {
+			if (debug) {
 				consola.info(`[Kimesh] Resolved directories:`);
 				consola.info(`  - srcDir: ${resolvedDirs.srcDir}`);
 				consola.info(`  - buildDir: ${resolvedDirs.buildDir}`);
 				consola.info(`  - pluginsDir: ${resolvedDirs.pluginsDir}`);
 			}
 			const envVars = loadEnv(mode, configRoot, "KIMESH_");
-			const layerTimer = createTimer("Layer resolution", debug$1);
+			const layerTimer = createTimer("Layer resolution", debug);
 			try {
 				state.resolvedLayers = await prepareLayers$1(configRoot, {
 					enabled: layersConfig.enabled,
 					excluded: layersConfig.excluded
 				});
 				layerTimer.end({ count: state.resolvedLayers.length });
-				if (debug$1 || state.resolvedLayers.length > 1) {
-					consola.info(`[Kimesh] Resolved ${state.resolvedLayers.length} layers:`);
-					for (const layer of state.resolvedLayers) consola.info(`  - ${layer.name} (priority: ${layer.priority}, path: ${layer.path})`);
+				if (state.resolvedLayers.length > 1) {
+					const layerNames = state.resolvedLayers.map((l) => l.name).join(", ");
+					consola.info(`Layers: ${layerNames}`);
+				}
+				if (debug) {
+					consola.debug(`[Kimesh] Resolved ${state.resolvedLayers.length} layers:`);
+					for (const layer of state.resolvedLayers) consola.debug(`  - ${layer.name} (priority: ${layer.priority}, path: ${layer.path})`);
 				}
 			} catch (error) {
 				layerTimer.end({ error: true });
 				consola.warn(`[Kimesh] Layer resolution failed: ${error}`);
-				state.resolvedLayers = [];
+				state.resolvedLayers = [{
+					name: "app",
+					path: configRoot,
+					priority: 0,
+					isApp: true,
+					config: {}
+				}];
 			}
 			const layerAliases = generateLayerAliases$1(state.resolvedLayers);
 			state.kimesh = createKimesh({
@@ -2272,15 +2671,18 @@ function kimeshPlugin(options = {}) {
 				buildDir: state.generatedDir,
 				dev: command === "serve"
 			});
-			await processModules(state.kimesh, debug$1);
+			addInternalAliasTemplates(state.kimesh);
+			await processModules(state.kimesh, debug);
+			const kitUrl = import.meta.url;
+			const packagesLocation = findKimeshPackagesLocation(kitUrl, debug);
 			if (config.app?.head) {
-				const headPluginSrc = "@kimesh/head/plugin";
-				if (!state.kimesh._registries.runtimePlugins.some((p) => p.src === headPluginSrc)) {
+				const headPluginSrc = "#kimesh/head/plugin";
+				if (!state.kimesh._registries.runtimePlugins.some((p) => p.src === headPluginSrc || p.src === "kimesh/head/plugin" || p.src === "@kimesh/head/plugin")) {
 					state.kimesh._registries.runtimePlugins.unshift({
 						src: headPluginSrc,
 						name: "head"
 					});
-					if (debug$1) consola.info("[Kimesh] Auto-registered @kimesh/head plugin (app.head configured)");
+					if (debug) consola.info(`[Kimesh] Auto-registered head plugin (app.head configured), src: ${headPluginSrc}`);
 				}
 			}
 			let discoveredPlugins = await scanPluginsDir(resolvedDirs.pluginsDir);
@@ -2292,7 +2694,7 @@ function kimeshPlugin(options = {}) {
 			state.hasPlugins = discoveredPlugins.length > 0 || hasRegisteredPlugins;
 			if (state.hasPlugins) {
 				addPluginsTemplate(state.kimesh, discoveredPlugins);
-				if (debug$1) {
+				if (debug) {
 					consola.info(`[Kimesh] Found ${discoveredPlugins.length} auto-discovered plugins`);
 					consola.info(`[Kimesh] Found ${state.kimesh._registries.runtimePlugins.length} module-registered plugins`);
 				}
@@ -2300,6 +2702,8 @@ function kimeshPlugin(options = {}) {
 			generateModulesTypeDeclaration(config.modules, state.generatedDir);
 			await writeTemplates(state.kimesh);
 			const userAliases = buildAliases(config, resolvedDirs.srcDir, configRoot);
+			const kimeshPackageAliases = buildKimeshPackageAliases(configRoot, debug);
+			if (packagesLocation?.type === "workspace-packages") kimeshPackagesPath = packagesLocation.path;
 			const moduleAliases = {};
 			for (const alias of state.kimesh._registries.aliases) if (typeof alias.find === "string") moduleAliases[alias.find] = alias.replacement;
 			const appVuePath = resolve$1(resolvedDirs.srcDir, "app.vue");
@@ -2324,7 +2728,7 @@ function kimeshPlugin(options = {}) {
 				],
 				exclude: ["../node_modules"]
 			});
-			if (debug$1) consola.info(`[Kimesh] Generated .kimesh/tsconfig.json with ${Object.keys(userAliases).length} aliases`);
+			if (debug) consola.info(`[Kimesh] Generated .kimesh/tsconfig.json with ${Object.keys(userAliases).length} aliases`);
 			const layerDirs = state.resolvedLayers.map((layer) => layer.path);
 			const workspaceRoot = findWorkspaceRoot(configRoot);
 			const workspacePackages = resolve$1(workspaceRoot, "packages");
@@ -2352,6 +2756,8 @@ function kimeshPlugin(options = {}) {
 					__KIMESH_LAYERS_CONFIG__: JSON.stringify(layerConfigMap)
 				},
 				resolve: { alias: {
+					...kimeshPackageAliases,
+					...buildInternalAliasMap(resolvedDirs.buildDir),
 					"#kimesh/routes": join$1(resolvedDirs.buildDir, "routes.gen.ts"),
 					"#kimesh/app": existsSync(appVuePath) ? appVuePath : "@kimesh/router-runtime/default-app",
 					"#kimesh/context": join$1(resolvedDirs.srcDir, "app.context.ts"),
@@ -2370,7 +2776,8 @@ function kimeshPlugin(options = {}) {
 						...layerDirs,
 						workspaceRoot,
 						workspacePackages,
-						nodeModules
+						nodeModules,
+						...kimeshPackagesPath ? [kimeshPackagesPath] : []
 					] },
 					watch: toViteWatchOptions(resolvedWatchConfig)
 				},
@@ -2401,19 +2808,40 @@ function kimeshPlugin(options = {}) {
 				const contextTypesPath = join$1(state.generatedDir, "context.d.ts");
 				writeFileSync(contextTypesPath, generateContextTypes(), "utf-8");
 				consola.debug(`[Kimesh] Generated context types: ${contextTypesPath}`);
-				for (const layer of state.resolvedLayers) {
-					if (layer.isApp) continue;
-					let layerRoot = layer.path;
-					try {
-						layerRoot = realpathSync(layer.path);
-					} catch {}
-					const layerKimeshDir = join$1(layerRoot, ".kimesh");
-					if (!existsSync(layerKimeshDir)) mkdirSync(layerKimeshDir, { recursive: true });
+			}
+			for (const layer of state.resolvedLayers) {
+				if (layer.isApp) continue;
+				let layerRoot = layer.path;
+				try {
+					layerRoot = realpathSync(layer.path);
+				} catch {}
+				const layerKimeshDir = join$1(layerRoot, ".kimesh");
+				if (!existsSync(layerKimeshDir)) mkdirSync(layerKimeshDir, { recursive: true });
+				if (hasContext) {
 					const hostContextPath = relative(layerKimeshDir, contextPath).replace(/\.ts$/, "");
 					const layerContextTypesPath = join$1(layerKimeshDir, "context.d.ts");
 					writeFileSync(layerContextTypesPath, generateLayerContextTypes(hostContextPath), "utf-8");
 					consola.debug(`[Kimesh] Generated layer context types: ${layerContextTypesPath}`);
 				}
+				const layerTsConfigPath = join$1(layerKimeshDir, "tsconfig.json");
+				writeFileSync(layerTsConfigPath, JSON.stringify({
+					compilerOptions: {
+						target: "ESNext",
+						module: "ESNext",
+						moduleResolution: "bundler",
+						strict: true,
+						jsx: "preserve",
+						sourceMap: true,
+						resolveJsonModule: true,
+						esModuleInterop: true,
+						lib: ["ESNext", "DOM"],
+						skipLibCheck: true,
+						noEmit: true
+					},
+					include: ["../src/**/*", "./**/*"],
+					exclude: ["../node_modules"]
+				}, null, 2), "utf-8");
+				consola.debug(`[Kimesh] Generated layer tsconfig: ${layerTsConfigPath}`);
 			}
 			const htmlPath = join$1(state.generatedDir, "index.html");
 			writeFileSync(htmlPath, generateHtml(config.name || "Kimesh App"), "utf-8");
@@ -2423,7 +2851,7 @@ function kimeshPlugin(options = {}) {
 			const hmrWatcher = createHMRWatcher({
 				server,
 				layers: state.resolvedLayers,
-				debug: debug$1
+				debug
 			});
 			for (const layer of state.resolvedLayers) if (!layer.isApp) {
 				server.watcher.add(layer.path);
@@ -2453,7 +2881,7 @@ function kimeshPlugin(options = {}) {
 	const routerPlugin = kimeshRouterGenerator({
 		routesDir: config.router?.routesDir ?? "routes",
 		importMode: config.router?.importMode ?? "async",
-		debug: debug$1,
+		debug,
 		getLayerRoutes: () => {
 			return state.resolvedLayers.filter((l) => !l.isApp).map((layer) => {
 				const routesFolder = layer.config.routes?.folder || "routes";
@@ -2500,42 +2928,42 @@ function kimeshPlugin(options = {}) {
 				}));
 			},
 			dts: config.autoImport?.dts !== false ? state.generatedDir || ".kimesh" : false,
-			debug: debug$1
+			debug
 		}),
 		vue(),
 		routerPlugin
 	];
 	const modulePluginsWrapper = {
 		name: "kimesh:module-plugins-wrapper",
-		async resolveId(id, importer, options$1) {
+		async resolveId(id, importer, options) {
 			const modulePlugins = state.kimesh?._registries.vitePlugins ?? [];
 			for (const entry of modulePlugins) {
 				const plugin = entry.plugin;
 				if (typeof plugin.resolveId === "function") {
-					const result = await plugin.resolveId.call(this, id, importer, options$1);
+					const result = await plugin.resolveId.call(this, id, importer, options);
 					if (result != null) return result;
 				}
 			}
 			return null;
 		},
-		async load(id, options$1) {
+		async load(id, options) {
 			const modulePlugins = state.kimesh?._registries.vitePlugins ?? [];
 			for (const entry of modulePlugins) {
 				const plugin = entry.plugin;
 				if (typeof plugin.load === "function") {
-					const result = await plugin.load.call(this, id, options$1);
+					const result = await plugin.load.call(this, id, options);
 					if (result != null) return result;
 				}
 			}
 			return null;
 		},
-		async transform(code, id, options$1) {
+		async transform(code, id, options) {
 			let currentCode = code;
 			const modulePlugins = state.kimesh?._registries.vitePlugins ?? [];
 			for (const entry of modulePlugins) {
 				const plugin = entry.plugin;
 				if (typeof plugin.transform === "function") {
-					const result = await plugin.transform.call(this, currentCode, id, options$1);
+					const result = await plugin.transform.call(this, currentCode, id, options);
 					if (result != null) currentCode = typeof result === "string" ? result : result.code;
 				}
 			}
@@ -2555,13 +2983,20 @@ function kimeshPlugin(options = {}) {
 * Wrap a function with defineKmConfig injected into globalThis.
 * This allows kimesh.config.ts to use defineKmConfig without explicit import (like Nuxt).
 *
+* Unlike importing a real function, we use a simple passthrough function here.
+* This is necessary because c12/jiti evaluates config files in a sandboxed environment
+* that may not share globalThis with the parent Node.js process.
+*
+* Following Nuxt's approach: the function is just a passthrough identity function.
+* @see https://github.com/nuxt/nuxt/blob/main/packages/kit/src/loader/config.ts
+*
 * @internal
 */
 async function withDefineKmConfig(fn) {
 	const key = "defineKmConfig";
 	const globalSelf = globalThis;
 	if (!globalSelf[key]) {
-		globalSelf[key] = defineKmConfig;
+		globalSelf[key] = (c) => c;
 		globalSelf[key].count = 0;
 	}
 	globalSelf[key].count++;
@@ -2813,4 +3248,4 @@ function extractModuleNames(modules) {
 }
 
 //#endregion
-export { DEFAULT_ALIASES, DEFAULT_IGNORE_PATTERNS, addAlias, addBuildPlugin, addComponent, addComponentResolver, addComponentsDir, addImports, addImportsDir, addImportsPreset, addPluginsTemplate, addRuntimePlugin, addTemplate, addTypeTemplate, addVitePlugin, applyEnv, buildAliases, buildImportRegistry, createDebugLogger, createDefaultRuntimeConfig, createHMRWatcher, createIgnoreFilter, createIgnoreMatcher, createKimesh, createResolver, createTimer, debug, debugTable, defineKimeshModule, defineKimeshPlugin, defineKmConfig, envToKey, executeModule, executeModules, filterIgnored, findMatchingRules, formatConflictWarning, formatError, formatTiming, formatWarning, generateDts, generateLayerAliases, generatePluginsTemplate, generateRouteRulesManifest, getIgnorePatterns, getRedirectInfo, getRouteRule, getRuntimePlugins, hasPlugins, hasRuntimePlugin, isDebug, isDebugEnabled, keyToEnv, kimeshAutoImport, kimeshPlugin, loadConfig, matchRoutePattern, mergeLayerConfigs, mergeRouteRules, normalizeDebugConfig, normalizeModuleInput, prepare, prepareLayers, removeRuntimePlugin, resolveAlias, resolveAliasPath, resolveLayers, resolvePathFromBuild, resolvePathFromRoot, scanExports, scanPluginsDir, setDebugConfig, shouldIgnore, toTsConfigPaths, toViteAliases, tryUseKimesh, updateTemplates, useKimesh, writeTemplates };
+export { DEFAULT_ALIASES, DEFAULT_IGNORE_PATTERNS, INTERNAL_ALIASES, addAlias, addBuildPlugin, addComponent, addComponentResolver, addComponentsDir, addImports, addImportsDir, addImportsPreset, addInternalAliasTemplates, addPluginsTemplate, addRuntimePlugin, addTemplate, addTypeTemplate, addVitePlugin, applyEnv, buildAliases, buildImportRegistry, buildInternalAliasMap, createDebugLogger, createDefaultRuntimeConfig, createHMRWatcher, createIgnoreFilter, createIgnoreMatcher, createKimesh, createResolver, createTimer, debug, debugTable, defineKimeshModule, defineKimeshPlugin, defineKmConfig, envToKey, executeModule, executeModules, filterIgnored, findMatchingRules, formatConflictWarning, formatError, formatTiming, formatWarning, generateDts, generateInternalAliasTemplate, generateLayerAliases, generatePluginsTemplate, generateRouteRulesManifest, getIgnorePatterns, getRedirectInfo, getRouteRule, getRuntimePlugins, hasPlugins, hasRuntimePlugin, isDebug, isDebugEnabled, keyToEnv, kimeshAutoImport, kimeshPlugin, loadConfig, matchRoutePattern, mergeLayerConfigs, mergeRouteRules, normalizeDebugConfig, normalizeModuleInput, prepare, prepareLayers, removeRuntimePlugin, resolveAlias, resolveAliasPath, resolveLayers, resolvePathFromBuild, resolvePathFromRoot, scanExports, scanPluginsDir, setDebugConfig, shouldIgnore, toTsConfigPaths, toViteAliases, tryUseKimesh, updateTemplates, useKimesh, writeTemplates };