rspress-plugin-api-extractor 0.2.2 → 0.3.0

package/layers/ConfigServiceLive.js

@@ -1,6 +1,11 @@
-import { BuildMetrics } from "./ObservabilityLive.js";
+import { hashContent } from "../content-hash.js";
+import { PluginEvent } from "../observability/events.js";
+import { emit, wantsLevel } from "../observability/EventBus.js";
+import { BuildMetrics } from "./build-metrics.js";
+import "./ObservabilityLive.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 import { OpenGraphResolver } from "../og-resolver.js";
+import { withPhase } from "../observability/spans.js";
 import { resolveTypeScriptConfig } from "../typescript-config.js";
 import { TwoslashManager } from "../twoslash-transformer.js";
 import { extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
@@ -21,6 +26,14 @@ import os from "node:os";
 import { createHighlighter } from "shiki";
 
 //#region src/layers/ConfigServiceLive.ts
+const DEFAULT_THRESHOLDS = {
+	slowCodeBlock: 100,
+	slowPageGeneration: 500,
+	slowApiLoad: 1e3,
+	slowFileOperation: 50,
+	slowHttpRequest: 2e3,
+	slowDbOperation: 100
+};
 /**
 * Normalize theme configuration from user input to a consistent format.
 */
@@ -41,18 +54,40 @@ function normalizeThemeConfig(theme) {
 }
 /**
 * Prepend import statements for external type references to the VFS declaration files.
+* Returns per-entry payloads for event emission (heavy content/importRefs gated on wantTrace).
 */
-function prependImportsToVfs(vfs, apiPackage, packageName) {
+function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
 	const extractor = new TypeReferenceExtractor(apiPackage, packageName);
+	const payloads = [];
 	for (const entryPoint of apiPackage.entryPoints) {
-		const imports = extractor.extractImportsForEntryPoint(entryPoint);
+		const entryEp = entryPoint;
+		const imports = extractor.extractImportsForEntryPoint(entryEp);
 		const importStatements = TypeReferenceExtractor.formatImports(imports);
-		if (importStatements.length === 0) continue;
-		const entryName = entryPoint.displayName || "";
-		const key = `node_modules/${packageName}/${entryName ? `${entryName}.d.ts` : "index.d.ts"}`;
-		const existing = vfs.get(key);
-		if (existing) vfs.set(key, `${importStatements.join("\n")}\n\n${existing}`);
+		const entryName = entryEp.displayName || "";
+		const file = `node_modules/${packageName}/${entryName ? `${entryName}.d.ts` : "index.d.ts"}`;
+		const hasImports = importStatements.length > 0;
+		if (hasImports) {
+			const existing = vfs.get(file);
+			if (existing) vfs.set(file, `${importStatements.join("\n")}\n\n${existing}`);
+		}
+		const content = vfs.get(file) ?? "";
+		const declCount = entryEp.members.length;
+		const contentHash = hashContent(content);
+		const importRefs = wantTrace && hasImports ? imports.map((i) => ({
+			from: i.packageName,
+			symbols: [...i.symbols]
+		})) : [];
+		payloads.push({
+			file,
+			entryPoint: entryName,
+			declCount,
+			contentHash,
+			content: wantTrace ? content : "",
+			hasImports,
+			importRefs
+		});
 	}
+	return payloads;
 }
 /**
 * Validate plugin options and return an Effect that fails with ConfigValidationError.
@@ -92,7 +127,13 @@ function validateOptions(options, rspressConfig) {
 				reason: `api.versions keys [${[...pluginKeys].join(", ")}] must exactly match multiVersion.versions [${[...rspressKeys].join(", ")}].`
 			});
 		} else {
-			if (api.versions) yield* Effect.logWarning("api.versions is provided but RSPress multiVersion is not configured. Versions will be ignored.");
+			if (api.versions) yield* emit(PluginEvent.ConfigCascadeWarning({
+				ctx: { buildId: "" },
+				level: "warn",
+				field: "versions",
+				chosen: "(none — multiVersion not configured)",
+				ignored: ["api.versions"]
+			}));
 			if (!api.model) return yield* new ConfigValidationError({
 				field: "api.model",
 				reason: "'model' is required when multiVersion is not active."
@@ -105,12 +146,13 @@ function validateOptions(options, rspressConfig) {
 * Resolves plugin options + RSPress config into a fully prepared build context
 * with loaded models, type system, and resources.
 */
-function ConfigServiceLive(options, shikiCrossLinker) {
+function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThresholds) {
 	return Layer.effect(ConfigService, Effect.gen(function* () {
 		const typeRegistry = yield* TypeRegistryService;
 		const pathService = yield* PathDerivationService;
 		return { resolve: (rspressConfig) => Effect.gen(function* () {
 			const loadStart = performance.now();
+			const wantTrace = yield* wantsLevel("trace");
 			yield* validateOptions(options, { ...rspressConfig.multiVersion ? { multiVersion: {
 				default: rspressConfig.multiVersion.default,
 				versions: [...rspressConfig.multiVersion.versions]
@@ -130,7 +172,7 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 			/**
 			* Helper to process a single API model (shared by single and multi modes).
 			*/
-			const processSimpleApi = (api, model, outputDir, fullRoute) => Effect.promise(async () => {
+			const processSimpleApi = (api, model, outputDir, fullRoute, wantTrace) => Effect.promise(async () => {
 				const { apiPackage, source: loaderSource } = await ApiModelLoader.loadApiModel(model);
 				const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories);
 				const resolvedSource = categoryResolver.resolveSourceConfig(api.source, loaderSource);
@@ -140,11 +182,12 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 				const externalPackages = api.externalPackages || extractAutoDetectedPackages(packageJson, api.autoDetectDependencies);
 				if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.incrementBy(BuildMetrics.externalPackagesTotal, externalPackages.length));
 				const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
-				prependImportsToVfs(vfs, apiPackage, api.packageName);
+				const vfsPayloads = prependImportsToVfs(vfs, apiPackage, api.packageName, wantTrace);
 				const resolvedOgImage = api.ogImage ?? options.ogImage;
 				const resolvedTheme = normalizeThemeConfig(api.theme);
 				return {
 					vfs,
+					vfsPayloads,
 					externalPackages: externalPackages || [],
 					config: {
 						apiPackage,
@@ -164,123 +207,216 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 					}
 				};
 			});
-			if (options.api) {
-				const api = options.api;
-				const baseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? "/");
-				firstApiTsconfig = api.tsconfig;
-				firstApiCompilerOptions = api.compilerOptions;
-				if (rspressMultiVersion && api.versions) {
-					const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
-						const versionDp = (yield* pathService.derivePaths({
+			yield* withPhase("modelLoad", { buildId }, Effect.gen(function* () {
+				if (options.api) {
+					const api = options.api;
+					const baseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? "/");
+					firstApiTsconfig = api.tsconfig;
+					firstApiCompilerOptions = api.compilerOptions;
+					if (rspressMultiVersion && api.versions) {
+						const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
+							const versionDp = (yield* pathService.derivePaths({
+								mode: "single",
+								docsRoot: rspressRoot,
+								baseRoute,
+								apiFolder: api.apiFolder ?? "api",
+								locales: rspressLocales,
+								defaultLang: rspressLang,
+								versions: [version],
+								defaultVersion: rspressMultiVersion?.default
+							}))[0];
+							if (!versionDp) return {
+								vfs: /* @__PURE__ */ new Map(),
+								vfsPayloads: [],
+								externalPackages: [],
+								config: null
+							};
+							return yield* Effect.promise(async () => {
+								const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
+								const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = await ApiModelLoader.loadVersionModel(versionConfig);
+								Effect.runSync(Metric.increment(BuildMetrics.apiVersionsLoaded));
+								const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories, versionCategories);
+								const resolvedSource = categoryResolver.resolveSourceConfig(api.source, versionSource);
+								const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin, versionLlms);
+								const packageJson = versionPackageJson || (api.packageJson ? await ApiModelLoader.loadPackageJson(api.packageJson) : void 0);
+								validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson);
+								const autoDetectOptions = versionAutoDetectDependencies || api.autoDetectDependencies;
+								const externalPackages = versionExternalPackages || api.externalPackages || extractAutoDetectedPackages(packageJson, autoDetectOptions);
+								if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.incrementBy(BuildMetrics.externalPackagesTotal, externalPackages.length));
+								const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
+								const vfsPayloads = prependImportsToVfs(vfs, apiPackage, api.packageName, wantTrace);
+								const resolvedOgImage = versionOgImage ?? api.ogImage ?? options.ogImage;
+								const resolvedTheme = normalizeThemeConfig(api.theme);
+								const outputDir = versionDp.outputDir;
+								const fullRoute = versionDp.routeBase;
+								return {
+									vfs,
+									vfsPayloads,
+									externalPackages: externalPackages || [],
+									config: {
+										apiPackage,
+										packageName: `${api.packageName} (${version})`,
+										...api.name != null ? { apiName: api.name } : {},
+										outputDir,
+										baseRoute: fullRoute,
+										categories: resolvedCategories,
+										...resolvedSource != null ? { source: resolvedSource } : {},
+										...packageJson != null ? { packageJson } : {},
+										...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
+										...options.siteUrl != null ? { siteUrl: options.siteUrl } : {},
+										...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
+										docsDir: path.dirname(outputDir),
+										...docsRoot != null ? { docsRoot } : {},
+										...resolvedTheme != null ? { theme: resolvedTheme } : {}
+									}
+								};
+							});
+						}), { concurrency: "unbounded" });
+						for (const result of versionResults) {
+							for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
+							if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
+							if (result.config) apiConfigs.push(result.config);
+							for (const payload of result.vfsPayloads) {
+								yield* emit(PluginEvent.VfsGenerated({
+									ctx: {
+										buildId: "",
+										packageName: api.packageName,
+										...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+									},
+									level: "debug",
+									file: payload.file,
+									declCount: payload.declCount,
+									contentHash: payload.contentHash,
+									...wantTrace && payload.content ? { content: payload.content } : {}
+								}));
+								if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
+									ctx: {
+										buildId: "",
+										packageName: api.packageName,
+										...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+									},
+									level: "debug",
+									file: payload.file,
+									imports: wantTrace ? payload.importRefs : []
+								}));
+							}
+						}
+					} else if (api.model) {
+						const dp = (yield* pathService.derivePaths({
 							mode: "single",
 							docsRoot: rspressRoot,
 							baseRoute,
 							apiFolder: api.apiFolder ?? "api",
 							locales: rspressLocales,
 							defaultLang: rspressLang,
-							versions: [version],
-							defaultVersion: rspressMultiVersion?.default
+							versions: [],
+							defaultVersion: void 0
 						}))[0];
-						if (!versionDp) return {
-							vfs: /* @__PURE__ */ new Map(),
-							externalPackages: [],
-							config: null
-						};
-						return yield* Effect.promise(async () => {
-							const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
-							const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = await ApiModelLoader.loadVersionModel(versionConfig);
-							Effect.runSync(Metric.increment(BuildMetrics.apiVersionsLoaded));
-							const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories, versionCategories);
-							const resolvedSource = categoryResolver.resolveSourceConfig(api.source, versionSource);
-							const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin, versionLlms);
-							const packageJson = versionPackageJson || (api.packageJson ? await ApiModelLoader.loadPackageJson(api.packageJson) : void 0);
-							validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson);
-							const autoDetectOptions = versionAutoDetectDependencies || api.autoDetectDependencies;
-							const externalPackages = versionExternalPackages || api.externalPackages || extractAutoDetectedPackages(packageJson, autoDetectOptions);
-							if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.incrementBy(BuildMetrics.externalPackagesTotal, externalPackages.length));
-							const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
-							prependImportsToVfs(vfs, apiPackage, api.packageName);
-							const resolvedOgImage = versionOgImage ?? api.ogImage ?? options.ogImage;
-							const resolvedTheme = normalizeThemeConfig(api.theme);
-							const outputDir = versionDp.outputDir;
-							const fullRoute = versionDp.routeBase;
-							return {
-								vfs,
-								externalPackages: externalPackages || [],
-								config: {
-									apiPackage,
-									packageName: `${api.packageName} (${version})`,
-									...api.name != null ? { apiName: api.name } : {},
-									outputDir,
-									baseRoute: fullRoute,
-									categories: resolvedCategories,
-									...resolvedSource != null ? { source: resolvedSource } : {},
-									...packageJson != null ? { packageJson } : {},
-									...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
-									...options.siteUrl != null ? { siteUrl: options.siteUrl } : {},
-									...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
-									docsDir: path.dirname(outputDir),
-									...docsRoot != null ? { docsRoot } : {},
-									...resolvedTheme != null ? { theme: resolvedTheme } : {}
-								}
-							};
-						});
-					}), { concurrency: "unbounded" });
-					for (const result of versionResults) {
-						for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
-						if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
-						if (result.config) apiConfigs.push(result.config);
+						if (dp) {
+							const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
+							for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
+							if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
+							apiConfigs.push(result.config);
+							for (const payload of result.vfsPayloads) {
+								yield* emit(PluginEvent.VfsGenerated({
+									ctx: {
+										buildId: "",
+										packageName: api.packageName,
+										...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+									},
+									level: "debug",
+									file: payload.file,
+									declCount: payload.declCount,
+									contentHash: payload.contentHash,
+									...wantTrace && payload.content ? { content: payload.content } : {}
+								}));
+								if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
+									ctx: {
+										buildId: "",
+										packageName: api.packageName,
+										...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+									},
+									level: "debug",
+									file: payload.file,
+									imports: wantTrace ? payload.importRefs : []
+								}));
+							}
+						}
+					}
+				} else if (options.apis) {
+					const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
+					if (apisWithTsconfig.length > 0) {
+						firstApiTsconfig = apisWithTsconfig[0].tsconfig;
+						const uniqueTsconfigs = new Set(apisWithTsconfig.map((a) => String(a.tsconfig)));
+						if (uniqueTsconfigs.size > 1) {
+							const chosen = String(firstApiTsconfig);
+							const ignored = [...uniqueTsconfigs].filter((t) => t !== chosen);
+							yield* emit(PluginEvent.ConfigCascadeWarning({
+								ctx: { buildId: "" },
+								level: "warn",
+								field: "tsconfig",
+								chosen,
+								ignored
+							}));
+						}
 					}
-				} else if (api.model) {
-					const dp = (yield* pathService.derivePaths({
-						mode: "single",
-						docsRoot: rspressRoot,
-						baseRoute,
-						apiFolder: api.apiFolder ?? "api",
-						locales: rspressLocales,
-						defaultLang: rspressLang,
-						versions: [],
-						defaultVersion: void 0
-					}))[0];
-					if (dp) {
-						const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase);
+					const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
+					if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
+					const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
+						const apiBaseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
+						const dp = (yield* pathService.derivePaths({
+							mode: "multi",
+							docsRoot: rspressRoot,
+							baseRoute: apiBaseRoute,
+							apiFolder: api.apiFolder ?? "api",
+							locales: rspressLocales,
+							defaultLang: rspressLang,
+							versions: [],
+							defaultVersion: void 0
+						}))[0];
+						if (!dp) return [];
+						const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
+						for (const payload of result.vfsPayloads) {
+							yield* emit(PluginEvent.VfsGenerated({
+								ctx: {
+									buildId: "",
+									packageName: api.packageName,
+									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+								},
+								level: "debug",
+								file: payload.file,
+								declCount: payload.declCount,
+								contentHash: payload.contentHash,
+								...wantTrace && payload.content ? { content: payload.content } : {}
+							}));
+							if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
+								ctx: {
+									buildId: "",
+									packageName: api.packageName,
+									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+								},
+								level: "debug",
+								file: payload.file,
+								imports: wantTrace ? payload.importRefs : []
+							}));
+						}
+						return [result];
+					}), { concurrency: "unbounded" });
+					for (const results of multiResults) for (const result of results) {
 						for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
 						if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
 						apiConfigs.push(result.config);
 					}
 				}
-			} else if (options.apis) {
-				const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
-				if (apisWithTsconfig.length > 0) {
-					firstApiTsconfig = apisWithTsconfig[0].tsconfig;
-					const uniqueTsconfigs = new Set(apisWithTsconfig.map((a) => String(a.tsconfig)));
-					if (uniqueTsconfigs.size > 1) yield* Effect.logWarning(`Multiple APIs specify different tsconfig values: ${[...uniqueTsconfigs].join(", ")}. Using '${String(firstApiTsconfig)}' for TypeScript resolution. Per-API tsconfig resolution will be supported in a future release.`);
-				}
-				const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
-				if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
-				const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
-					const apiBaseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
-					const dp = (yield* pathService.derivePaths({
-						mode: "multi",
-						docsRoot: rspressRoot,
-						baseRoute: apiBaseRoute,
-						apiFolder: api.apiFolder ?? "api",
-						locales: rspressLocales,
-						defaultLang: rspressLang,
-						versions: [],
-						defaultVersion: void 0
-					}))[0];
-					if (!dp) return [];
-					return [yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase)];
-				}), { concurrency: "unbounded" });
-				for (const results of multiResults) for (const result of results) {
-					for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
-					if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
-					apiConfigs.push(result.config);
-				}
-			}
+			}), resolvedThresholds ?? DEFAULT_THRESHOLDS);
 			const loadMs = performance.now() - loadStart;
-			yield* Effect.logDebug(`Loading API models: ${loadMs.toFixed(0)}ms`);
+			yield* emit(PluginEvent.ModelLoaded({
+				ctx: { buildId: "" },
+				level: "debug",
+				entryPoints: apiConfigs.length,
+				itemCount: apiConfigs.reduce((sum, cfg) => sum + cfg.apiPackage.entryPoints.reduce((s, ep) => s + ep.members.length, 0), 0),
+				durationMs: Math.round(loadMs)
+			}));
 			const projectRoot = process.cwd();
 			let globalTsConfig;
 			if (firstApiTsconfig || firstApiCompilerOptions) {
@@ -289,28 +425,50 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 				if (firstApiCompilerOptions != null) globalTsConfig.compilerOptions = firstApiCompilerOptions;
 			}
 			const resolvedCompilerOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, globalTsConfig));
-			yield* Effect.logDebug(`Resolved TypeScript config: target=${resolvedCompilerOptions.target}, module=${resolvedCompilerOptions.module}, lib=[${resolvedCompilerOptions.lib?.join(", ")}]`);
-			let tsEnvCache = /* @__PURE__ */ new Map();
+			yield* emit(PluginEvent.TsCacheCreated({
+				ctx: { buildId: "" },
+				level: "debug",
+				compilerOptions: `target=${resolvedCompilerOptions.target}, module=${resolvedCompilerOptions.module}, lib=[${resolvedCompilerOptions.lib?.join(", ") ?? ""}]`,
+				durationMs: 0
+			}));
+			const documentedPackageNames = new Set(apiConfigs.map((config) => config.packageName));
+			const externalPackagesToLoad = allExternalPackages.filter((pkg) => !documentedPackageNames.has(pkg.name));
 			const typeLoadResult = yield* Effect.either(Effect.gen(function* () {
-				if (allExternalPackages.length > 0) {
-					const typesStart = performance.now();
-					const result = yield* typeRegistry.loadPackages(allExternalPackages);
-					const cache = yield* typeRegistry.createTypeScriptCache(allExternalPackages, resolvedCompilerOptions);
-					for (const [filePath, content] of result.vfs.entries()) combinedVfs.set(filePath, content);
-					yield* Effect.logDebug(`Loading external package types: ${(performance.now() - typesStart).toFixed(0)}ms`);
-					return cache;
+				if (externalPackagesToLoad.length > 0) {
+					const resolvedPackages = yield* typeRegistry.resolveVersions(externalPackagesToLoad);
+					const droppedCount = externalPackagesToLoad.length - resolvedPackages.length;
+					if (droppedCount > 0) yield* emit(PluginEvent.ExternalPackageSkipped({
+						ctx: { buildId: "" },
+						level: "debug",
+						reason: `${droppedCount} unresolvable package(s) (unpublished or workspace-only)`
+					}));
+					if (resolvedPackages.length > 0) {
+						const result = yield* typeRegistry.loadPackages(resolvedPackages);
+						for (const [filePath, content] of result.vfs.entries()) combinedVfs.set(filePath, content);
+						yield* emit(PluginEvent.VfsMerged({
+							ctx: { buildId: "" },
+							level: "debug",
+							totalFiles: result.vfs.size,
+							packages: resolvedPackages.map((p) => p.name)
+						}));
+					}
 				}
-				return yield* typeRegistry.createTypeScriptCache([], resolvedCompilerOptions);
 			}));
-			if (typeLoadResult._tag === "Right") tsEnvCache = typeLoadResult.right;
-			else {
-				yield* Effect.logWarning(`Failed to load external types: ${typeLoadResult.left.message}. Continuing with empty VFS.`);
-				const fallbackCache = yield* Effect.either(typeRegistry.createTypeScriptCache([], resolvedCompilerOptions));
-				if (fallbackCache._tag === "Right") tsEnvCache = fallbackCache.right;
-			}
+			if (typeLoadResult._tag === "Left") yield* emit(PluginEvent.ConfigCascadeWarning({
+				ctx: { buildId: "" },
+				level: "warn",
+				field: "externalTypes",
+				chosen: "empty VFS",
+				ignored: [typeLoadResult.left.message ?? String(typeLoadResult.left)]
+			}));
 			const twoslashStartMs = performance.now();
-			TwoslashManager.getInstance().initialize(combinedVfs, void 0, void 0, tsEnvCache, resolvedCompilerOptions);
-			yield* Effect.logDebug(`Initializing Twoslash: ${(performance.now() - twoslashStartMs).toFixed(0)}ms`);
+			TwoslashManager.getInstance().initialize(combinedVfs, void 0, void 0, void 0, resolvedCompilerOptions);
+			yield* emit(PluginEvent.TwoslashInitialized({
+				ctx: { buildId: "" },
+				level: "debug",
+				durationMs: Math.round(performance.now() - twoslashStartMs),
+				vfsFileCount: combinedVfs.size
+			}));
 			const shikiStartMs = performance.now();
 			const themeSet = /* @__PURE__ */ new Set();
 			const customThemes = [];
@@ -338,7 +496,12 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 				themes,
 				langs
 			}));
-			yield* Effect.logDebug(`Initializing Shiki highlighter: ${(performance.now() - shikiStartMs).toFixed(0)}ms`);
+			yield* emit(PluginEvent.PhaseCompleted({
+				ctx: { buildId: "" },
+				level: "debug",
+				phase: "shikiInit",
+				durationMs: Math.round(performance.now() - shikiStartMs)
+			}));
 			const ogResolver = options.siteUrl ? new OpenGraphResolver({
 				siteUrl: options.siteUrl,
 				...docsRoot != null ? { docsRoot } : {}
@@ -352,7 +515,6 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 				apiConfigs,
 				combinedVfs,
 				highlighter,
-				tsEnvCache,
 				resolvedCompilerOptions,
 				ogResolver,
 				shikiCrossLinker,
@@ -361,7 +523,9 @@ function ConfigServiceLive(options, shikiCrossLinker) {
 				twoslashTransformer,
 				pageConcurrency: os.cpus().length,
 				logLevel: logLevel === "none" ? "info" : logLevel,
-				suppressExampleErrors
+				suppressExampleErrors,
+				thresholds: resolvedThresholds ?? DEFAULT_THRESHOLDS,
+				buildId
 			};
 		}) };
 	}));