rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/layers/ConfigServiceLive.js

@@ -1,57 +1,32 @@
+import { BuildId } from "../BuildEnv.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 { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
 import { resolveTypeScriptConfig } from "../typescript-config.js";
-import { TwoslashManager } from "../twoslash-transformer.js";
+import { apiScopeOf, deriveOutputPaths, normalizeBaseRoute, unscopedName } from "../path-derivation.js";
 import { classifyApiConfig, extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
 import { ApiExtractedPackage } from "../api-extracted-package.js";
 import { CategoryResolver } from "../category-resolver.js";
 import { ConfigValidationError } from "../errors.js";
-import { HideCutLinesTransformer, MemberFormatTransformer } from "../hide-cut-transformer.js";
-import { DEFAULT_SHIKI_THEMES } from "../markdown/shiki-utils.js";
+import { normalizeThemeConfig } from "../markdown/shiki-utils.js";
 import { loadApiModel, loadPackageJson, loadVersionModel } from "../model-loader.js";
 import { DEFAULT_CATEGORIES } from "../schemas/config.js";
 import "../schemas/index.js";
 import { ConfigService } from "../services/ConfigService.js";
-import { PathDerivationService } from "../services/PathDerivationService.js";
+import { PluginConfig } from "../services/PluginConfig.js";
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
+import { twoslashEnvHash } from "../twoslash-cache.js";
 import path from "node:path";
 import { hashContent } from "@tsdoctor/snapshot";
 import { Effect, Layer, Metric } from "effect";
-import os from "node:os";
-import { createHighlighter } from "shiki";
+import ts from "typescript";
 
 //#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.
-*/
-function normalizeThemeConfig(theme) {
-	if (!theme) return { ...DEFAULT_SHIKI_THEMES };
-	if (typeof theme === "string") return {
-		light: theme,
-		dark: theme
-	};
-	if ("light" in theme && "dark" in theme && typeof theme.light === "string" && typeof theme.dark === "string") return {
-		light: theme.light,
-		dark: theme.dark
-	};
-	return {
-		light: theme,
-		dark: 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).
@@ -129,7 +104,7 @@ function validateOptions(options, rspressConfig) {
 				});
 			} else {
 				if (api.versions) yield* emit(PluginEvent.ConfigCascadeWarning({
-					ctx: { buildId: "" },
+					ctx: {},
 					level: "warn",
 					field: "versions",
 					chosen: "(none — multiVersion not configured)",
@@ -144,258 +119,210 @@ function validateOptions(options, rspressConfig) {
 	});
 }
 /**
-* Create ConfigServiceLive from plugin options.
-* Resolves plugin options + RSPress config into a fully prepared build context
-* with loaded models, type system, and resources.
+* Resolve plugin options + RSPress config into the API configs the pipeline
+* runs over.
+*
+* @remarks
+* A module-level `const`, not a factory. It took the plugin options as an
+* argument and was called inline at the merge site, which made it a
+* layer-returning function: layers memoize by reference, so a second call
+* would build a second `ConfigService` with its own captured `TypeRegistry`.
+* The options come from {@link PluginConfig} now, so there is nothing to pass
+* and nothing to call twice.
 */
-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]
-			} } : {} });
-			const rspressMultiVersion = rspressConfig.multiVersion;
-			const rspressLocales = rspressConfig.locales?.map((l) => l.lang) ?? [];
-			const rspressLang = rspressConfig.lang;
-			const docsRoot = rspressConfig.root;
-			const rspressRoot = docsRoot || process.cwd();
-			const categoryResolver = new CategoryResolver();
-			const pluginDefaults = categoryResolver.mergeCategories(DEFAULT_CATEGORIES, options.defaultCategories);
-			const apiConfigs = [];
-			const combinedVfs = /* @__PURE__ */ new Map();
-			const allExternalPackages = [];
-			let firstApiTsconfig;
-			let firstApiCompilerOptions;
-			/**
-			* Emit a typed ModelLoadFailed event for a failed model load, then
-			* convert the typed failure to a defect — a missing or unparsable
-			* model remains fatal to the build, exactly as before, but the
-			* event now rides the error channel instead of a sync-island seam.
-			*/
-			const withModelLoadEvents = (self) => self.pipe(Effect.tapError((error) => emit(PluginEvent.ModelLoadFailed({
-				ctx: { buildId },
-				level: "error",
-				modelPath: "modelPath" in error ? error.modelPath : "<loader function>",
-				reason: error.message
-			}))), Effect.orDie);
-			/**
-			* Helper to process a single API model (shared by single and multi modes).
-			*/
-			const processSimpleApi = (api, model, outputDir, fullRoute, wantTrace) => Effect.gen(function* () {
-				const { apiPackage, source: loaderSource } = yield* withModelLoadEvents(loadApiModel(model));
-				return yield* Effect.promise(async () => {
-					const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories);
-					const resolvedSource = categoryResolver.resolveSourceConfig(api.source, loaderSource);
-					const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin);
-					const packageJson = api.packageJson ? await loadPackageJson(api.packageJson) : void 0;
-					validateExternalPackages(api.externalPackages, packageJson);
-					const externalPackages = api.externalPackages || extractAutoDetectedPackages(packageJson, api.autoDetectDependencies);
-					if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length));
-					const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
-					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,
-							packageName: api.packageName,
-							...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 } : {}
-						}
-					};
-				});
+const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
+	const typeRegistry = yield* TypeRegistryService;
+	const options = yield* PluginConfig;
+	return { resolve: (rspressConfig) => Effect.gen(function* () {
+		const buildId = yield* BuildId;
+		const loadStart = performance.now();
+		const wantTrace = yield* wantsLevel("trace");
+		yield* validateOptions(options, { ...rspressConfig.multiVersion ? { multiVersion: {
+			default: rspressConfig.multiVersion.default,
+			versions: [...rspressConfig.multiVersion.versions]
+		} } : {} });
+		const rspressMultiVersion = rspressConfig.multiVersion;
+		const rspressLocales = rspressConfig.locales?.map((l) => l.lang) ?? [];
+		const rspressLang = rspressConfig.lang;
+		const docsRoot = rspressConfig.root;
+		const rspressRoot = docsRoot || process.cwd();
+		const categoryResolver = new CategoryResolver();
+		const pluginDefaults = categoryResolver.mergeCategories(DEFAULT_CATEGORIES, options.defaultCategories);
+		const apiConfigs = [];
+		const combinedVfs = /* @__PURE__ */ new Map();
+		const allExternalPackages = [];
+		let firstApiTsconfig;
+		let firstApiCompilerOptions;
+		/**
+		* Raw TypeScript config per API scope. Each documented package is
+		* type-checked under its OWN configuration; the build no longer picks
+		* one and applies it to everything.
+		*/
+		const scopeTsConfigs = /* @__PURE__ */ new Map();
+		/**
+		* Emit a typed ModelLoadFailed event for a failed model load, then
+		* convert the typed failure to a defect — a missing or unparsable
+		* model remains fatal to the build, exactly as before, but the
+		* event now rides the error channel instead of a sync-island seam.
+		*/
+		const withModelLoadEvents = (self) => self.pipe(Effect.tapError((error) => emit(PluginEvent.ModelLoadFailed({
+			ctx: { buildId },
+			level: "error",
+			modelPath: "modelPath" in error ? error.modelPath : "<loader function>",
+			reason: error.message
+		}))), Effect.orDie);
+		/**
+		* Helper to process a single API model (shared by single and multi modes).
+		*/
+		const processSimpleApi = (api, model, outputDir, fullRoute, wantTrace) => Effect.gen(function* () {
+			const { apiPackage, source: loaderSource } = yield* withModelLoadEvents(loadApiModel(model));
+			return yield* Effect.promise(async () => {
+				const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories);
+				const resolvedSource = categoryResolver.resolveSourceConfig(api.source, loaderSource);
+				const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin);
+				const packageJson = api.packageJson ? await loadPackageJson(api.packageJson) : void 0;
+				validateExternalPackages(api.externalPackages, packageJson);
+				const externalPackages = api.externalPackages || extractAutoDetectedPackages(packageJson, api.autoDetectDependencies);
+				if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length));
+				const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
+				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,
+						packageName: api.packageName,
+						...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 } : {}
+					}
+				};
 			});
-			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
-							};
-							const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
-							const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = yield* withModelLoadEvents(loadVersionModel(versionConfig));
-							return yield* Effect.promise(async () => {
-								Effect.runSync(Metric.update(BuildMetrics.apiVersionsLoaded, 1));
-								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 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.update(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({
+		});
+		yield* withPhase("modelLoad", { buildId }, Effect.gen(function* () {
+			if (options.api) {
+				const api = options.api;
+				const baseRoute = normalizeBaseRoute(api.baseRoute ?? "/");
+				firstApiTsconfig = api.tsconfig;
+				firstApiCompilerOptions = api.compilerOptions;
+				scopeTsConfigs.set(apiScopeOf(baseRoute, api.packageName), rawTsConfig(api));
+				if (rspressMultiVersion && api.versions) {
+					const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
+						const versionDp = deriveOutputPaths({
 							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, 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
+							versions: [version],
+							defaultVersion: rspressMultiVersion?.default
+						})[0];
+						if (!versionDp) return {
+							vfs: /* @__PURE__ */ new Map(),
+							vfsPayloads: [],
+							externalPackages: [],
+							config: null
+						};
+						const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
+						const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = yield* withModelLoadEvents(loadVersionModel(versionConfig));
+						return yield* Effect.promise(async () => {
+							Effect.runSync(Metric.update(BuildMetrics.apiVersionsLoaded, 1));
+							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 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.update(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: {
+									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: {
+									packageName: api.packageName,
+									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+								},
+								level: "debug",
+								file: payload.file,
+								imports: wantTrace ? payload.importRefs : []
 							}));
 						}
 					}
-					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 [];
+				} else if (api.model) {
+					const dp = deriveOutputPaths({
+						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, 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 } : {}
 								},
@@ -407,7 +334,6 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 							}));
 							if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
 								ctx: {
-									buildId: "",
 									packageName: api.packageName,
 									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
 								},
@@ -416,141 +342,164 @@ function ConfigServiceLive(options, shikiCrossLinker, buildId = "", resolvedThre
 								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);
 					}
 				}
-			}), resolvedThresholds ?? DEFAULT_THRESHOLDS);
-			const loadMs = performance.now() - loadStart;
-			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) {
-				globalTsConfig = {};
-				if (firstApiTsconfig != null) globalTsConfig.tsconfig = firstApiTsconfig;
-				if (firstApiCompilerOptions != null) globalTsConfig.compilerOptions = firstApiCompilerOptions;
-			}
-			const resolvedCompilerOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, globalTsConfig));
-			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.result(Effect.gen(function* () {
-				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: "" },
+			} else if (options.apis) {
+				const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
+				if (apisWithTsconfig.length > 0) firstApiTsconfig = apisWithTsconfig[0].tsconfig;
+				const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
+				if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
+				for (const a of options.apis) {
+					const scopeRoute = normalizeBaseRoute(a.baseRoute ?? `/${unscopedName(a.packageName)}`);
+					scopeTsConfigs.set(apiScopeOf(scopeRoute, a.packageName), rawTsConfig(a));
+				}
+				const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
+					const apiBaseRoute = normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
+					const dp = deriveOutputPaths({
+						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: {
+								packageName: api.packageName,
+								...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+							},
 							level: "debug",
-							totalFiles: result.vfs.size,
-							packages: resolvedPackages.map((p) => p.name)
+							file: payload.file,
+							declCount: payload.declCount,
+							contentHash: payload.contentHash,
+							...wantTrace && payload.content ? { content: payload.content } : {}
+						}));
+						if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
+							ctx: {
+								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);
 				}
-			}));
-			if (typeLoadResult._tag === "Failure") yield* emit(PluginEvent.ConfigCascadeWarning({
-				ctx: { buildId: "" },
-				level: "warn",
-				field: "externalTypes",
-				chosen: "empty VFS",
-				ignored: [typeLoadResult.failure.message ?? String(typeLoadResult.failure)]
-			}));
-			const twoslashStartMs = performance.now();
-			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 = [];
-			for (const config of apiConfigs) {
-				const theme = config.theme ?? {
-					light: DEFAULT_SHIKI_THEMES.light,
-					dark: DEFAULT_SHIKI_THEMES.dark
-				};
-				if (typeof theme.light === "string") themeSet.add(theme.light);
-				else if (typeof theme.light === "object") customThemes.push(theme.light);
-				if (typeof theme.dark === "string") themeSet.add(theme.dark);
-				else if (typeof theme.dark === "object") customThemes.push(theme.dark);
 			}
-			if (typeof DEFAULT_SHIKI_THEMES.light === "string") themeSet.add(DEFAULT_SHIKI_THEMES.light);
-			if (typeof DEFAULT_SHIKI_THEMES.dark === "string") themeSet.add(DEFAULT_SHIKI_THEMES.dark);
-			const themes = [...themeSet, ...customThemes];
-			const langs = [
-				"typescript",
-				"javascript",
-				"json",
-				"bash",
-				"sh"
-			];
-			const highlighter = yield* Effect.promise(() => createHighlighter({
-				themes,
-				langs
-			}));
-			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 } : {}
-			}) : null;
-			const hideCutTransformer = MemberFormatTransformer;
-			const hideCutLinesTransformer = HideCutLinesTransformer;
-			const twoslashTransformer = TwoslashManager.getInstance().getTransformer() ?? void 0;
-			const logLevel = options.logLevel ?? "info";
-			const suppressExampleErrors = options.errors?.example !== "show";
-			return {
-				apiConfigs,
-				combinedVfs,
-				highlighter,
-				resolvedCompilerOptions,
-				ogResolver,
-				shikiCrossLinker,
-				hideCutTransformer,
-				hideCutLinesTransformer,
-				twoslashTransformer,
-				pageConcurrency: os.cpus().length,
-				logLevel: logLevel === "none" ? "info" : logLevel,
-				suppressExampleErrors,
-				thresholds: resolvedThresholds ?? DEFAULT_THRESHOLDS,
-				buildId
-			};
-		}) };
-	}));
-}
-/**
-* Strip npm scope from a package name.
-*/
-function unscopedName(packageName) {
-	return packageName.startsWith("@") ? packageName.split("/")[1] ?? packageName : packageName;
+		}));
+		const loadMs = performance.now() - loadStart;
+		yield* emit(PluginEvent.ModelLoaded({
+			ctx: {},
+			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) {
+			globalTsConfig = {};
+			if (firstApiTsconfig != null) globalTsConfig.tsconfig = firstApiTsconfig;
+			if (firstApiCompilerOptions != null) globalTsConfig.compilerOptions = firstApiCompilerOptions;
+		}
+		const resolvedCompilerOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, globalTsConfig));
+		yield* emit(PluginEvent.TsCacheCreated({
+			ctx: {},
+			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.result(Effect.gen(function* () {
+			if (externalPackagesToLoad.length > 0) {
+				const resolvedPackages = yield* typeRegistry.resolveVersions(externalPackagesToLoad);
+				const droppedCount = externalPackagesToLoad.length - resolvedPackages.length;
+				if (droppedCount > 0) yield* emit(PluginEvent.ExternalPackageSkipped({
+					ctx: {},
+					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: {},
+						level: "debug",
+						totalFiles: result.vfs.size,
+						packages: resolvedPackages.map((p) => p.name)
+					}));
+				}
+			}
+		}));
+		if (typeLoadResult._tag === "Failure") yield* emit(PluginEvent.ConfigCascadeWarning({
+			ctx: {},
+			level: "warn",
+			field: "externalTypes",
+			chosen: "empty VFS",
+			ignored: [typeLoadResult.failure.message ?? String(typeLoadResult.failure)]
+		}));
+		const twoslashEnv = twoslashEnvHash(combinedVfs, `typescript@${ts.version}`);
+		const twoslashCache = yield* (yield* TwoslashCacheService).open(twoslashEnv);
+		yield* emit(PluginEvent.TwoslashCacheLoaded({
+			ctx: {},
+			level: "debug",
+			envHash: twoslashEnv,
+			entries: twoslashCache.entries().size
+		}));
+		const twoslashStartMs = performance.now();
+		const environments = yield* TwoslashEnvironments;
+		environments.registerEnvironment({
+			vfs: combinedVfs,
+			compilerOptions: resolvedCompilerOptions,
+			typesCache: twoslashCache
+		});
+		const resolvedByRawConfig = /* @__PURE__ */ new Map();
+		for (const [apiScope, rawConfig] of scopeTsConfigs) {
+			if (rawConfig === void 0) {
+				environments.registerScope(apiScope, resolvedCompilerOptions);
+				continue;
+			}
+			const rawKey = JSON.stringify([String(rawConfig.tsconfig ?? ""), rawConfig.compilerOptions ?? null]);
+			let scopeOptions = resolvedByRawConfig.get(rawKey);
+			if (scopeOptions === void 0) {
+				scopeOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, rawConfig));
+				resolvedByRawConfig.set(rawKey, scopeOptions);
+			}
+			environments.registerEnvironment({
+				vfs: combinedVfs,
+				compilerOptions: scopeOptions,
+				typesCache: twoslashCache
+			});
+			environments.registerScope(apiScope, scopeOptions);
+		}
+		yield* emit(PluginEvent.TwoslashInitialized({
+			ctx: {},
+			level: "debug",
+			durationMs: Math.round(performance.now() - twoslashStartMs),
+			vfsFileCount: combinedVfs.size
+		}));
+		return apiConfigs;
+	}) };
+}));
+/** The raw TypeScript config an API declares, or undefined when it declares none. */
+function rawTsConfig(api) {
+	if (api.tsconfig == null && api.compilerOptions == null) return void 0;
+	const cfg = {};
+	if (api.tsconfig != null) cfg.tsconfig = api.tsconfig;
+	if (api.compilerOptions != null) cfg.compilerOptions = api.compilerOptions;
+	return cfg;
 }
 
 //#endregion