rspress-plugin-api-extractor 0.10.0 → 0.11.0

package/og-resolver.js

@@ -1,19 +1,6 @@
-import { PluginEvent } from "./observability/events.js";
-import fs from "node:fs";
-import path from "node:path";
-import { imageSizeFromFile } from "image-size/fromFile";
-
 //#region src/og-resolver.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setOgResolverEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
-* MIME type mappings for common image formats.
-* Used to determine the `og:image:type` meta tag value.
+* MIME type mappings for common image formats, used for `og:image:type`.
 */
 const IMAGE_MIME_TYPES = {
 	jpg: "image/jpeg",
@@ -24,282 +11,54 @@ const IMAGE_MIME_TYPES = {
 	svg: "image/svg+xml"
 };
 /**
-* Resolves Open Graph image configurations into fully-qualified metadata.
+* The `og:image:type` value for a detected image format, or `undefined` for a
+* format with no mapping.
+*/
+function imageMimeType(type) {
+	if (type == null) return void 0;
+	return IMAGE_MIME_TYPES[type.toLowerCase()];
+}
+/**
+* Turn a configured image URL into an absolute one.
 *
-* This class handles the conversion of flexible OG image configuration formats
-* (strings or metadata objects) into complete `OpenGraphImageMetadata` objects
-* with resolved URLs and auto-detected dimensions for local images.
+* @returns The absolute URL, or `undefined` when the input is neither an
+* absolute `http(s)` URL nor a site-root-relative path. A bare relative path
+* is deliberately rejected rather than guessed at — there is no base to
+* resolve it against that would not silently produce a broken link.
+*/
+function resolveOgUrl(siteUrl, url) {
+	if (url.startsWith("http://") || url.startsWith("https://")) return url;
+	if (url.startsWith("/")) return `${siteUrl}${url}`;
+}
+/** Descriptive alt text for a package's (or one API's) OG image. */
+function ogAltText(packageName, apiName) {
+	return apiName ? `${apiName} - ${packageName} API Documentation` : `${packageName} API Documentation`;
+}
+/**
+* Assemble the complete Open Graph metadata for one documentation page.
 *
 * @remarks
-* The resolver supports two input formats:
-* - **String format**: A URL or path that will be resolved and optionally enhanced
-*   with auto-detected dimensions if pointing to a local file.
-* - **Object format**: Detailed metadata with explicit properties that will be
-*   validated and URL-resolved.
-*
-* @example Basic usage with a relative path
-* ```typescript
-* const resolver = new OpenGraphResolver({
-*   siteUrl: "https://example.com",
-*   docsRoot: "/path/to/docs"
-* });
-*
-* const metadata = await resolver.resolve(
-*   "/images/og-api.png",
-*   "my-package",
-*   "MyClass"
-* );
-* // Result: { url: "https://example.com/images/og-api.png", width: 1200, height: 630, ... }
-* ```
-*
-* @example Using detailed configuration
-* ```typescript
-* const metadata = await resolver.resolve(
-*   {
-*     url: "/images/og.png",
-*     alt: "Custom alt text",
-*     width: 1200,
-*     height: 630
-*   },
-*   "my-package"
-* );
-* ```
+* Was `OpenGraphResolver.createPageMetadata`. It never touched the resolver's
+* instance state, so it is a free function now rather than a static on a class
+* that no longer exists.
 */
-var OpenGraphResolver = class {
-	siteUrl;
-	docsRoot;
-	/**
-	* Creates a new OpenGraphResolver instance.
-	*
-	* @param options - Configuration options for the resolver.
-	*   `siteUrl`: Base URL for the website (e.g., "https://example.com"),
-	*   used to construct absolute URLs from relative paths.
-	*   `docsRoot`: Optional root directory for documentation files;
-	*   when provided, enables auto-detection of image dimensions for local files
-	*   by looking in the `public` subdirectory.
-	*/
-	constructor(options) {
-		this.siteUrl = options.siteUrl;
-		if (options.docsRoot != null) this.docsRoot = options.docsRoot;
-	}
-	/**
-	* Resolves an Open Graph image configuration into complete metadata.
-	*
-	* Handles both string URLs/paths and detailed metadata objects, converting them
-	* into fully-qualified `OpenGraphImageMetadata` with absolute URLs.
-	*
-	* @param config - The OG image configuration to resolve. Can be:
-	*   - A string URL (absolute or relative path starting with `/`)
-	*   - An `OpenGraphImageMetadata` object with explicit properties
-	*   - `undefined` to indicate no OG image
-	* @param packageName - The package name for generating default alt text
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with absolute URLs, or `undefined` if:
-	*   - `config` is `undefined`
-	*   - The URL format is invalid
-	*
-	* @example Resolve a relative path
-	* ```typescript
-	* const metadata = await resolver.resolve("/images/og.png", "my-lib");
-	* // Returns: { url: "https://example.com/images/og.png", alt: "my-lib API Documentation", ... }
-	* ```
-	*
-	* @example Resolve an absolute URL
-	* ```typescript
-	* const metadata = await resolver.resolve("https://cdn.example.com/og.png", "my-lib");
-	* // Returns: { url: "https://cdn.example.com/og.png", alt: "my-lib API Documentation" }
-	* ```
-	*/
-	async resolve(config, packageName, apiName) {
-		if (!config) return;
-		if (typeof config === "object") return this.resolveFromMetadata(config, packageName, apiName);
-		return this.resolveFromString(config, packageName, apiName);
-	}
-	/**
-	* Resolves a metadata object configuration into complete OG image metadata.
-	*
-	* Validates and resolves URLs in the provided metadata object, ensuring all
-	* URLs are absolute and properly formatted.
-	*
-	* @param metadata - The metadata object containing OG image properties
-	* @param packageName - Package name for default alt text generation
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with absolute URLs, or `undefined` if URL is invalid
-	*/
-	async resolveFromMetadata(metadata, packageName, apiName) {
-		const { url, secureUrl, type, width, height, alt } = metadata;
-		const resolvedUrl = this.resolveUrl(url);
-		if (!resolvedUrl) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage.url",
-				value: url,
-				reason: "invalid URL format",
-				level: "warn"
-			}));
-			return;
-		}
-		let resolvedSecureUrl;
-		if (secureUrl) {
-			if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
-			else emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage.secureUrl",
-				value: secureUrl,
-				reason: "secureUrl must be absolute HTTPS",
-				level: "warn"
-			}));
-		}
-		return {
-			url: resolvedUrl,
-			secureUrl: resolvedSecureUrl,
-			type,
-			width,
-			height,
-			alt: alt ?? this.generateAltText(packageName, apiName)
-		};
-	}
-	/**
-	* Resolves a string URL/path into complete OG image metadata.
-	*
-	* For relative paths pointing to local files, this method will attempt to:
-	* 1. Locate the file in the docs `public` directory
-	* 2. Read the image dimensions using `image-size`
-	* 3. Determine the MIME type from the file extension
-	*
-	* @param imageUrl - The image URL or path to resolve
-	* @param packageName - Package name for alt text generation
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with auto-detected dimensions for local files,
-	*   or `undefined` if the URL format is invalid
-	*/
-	async resolveFromString(imageUrl, packageName, apiName) {
-		const resolvedUrl = this.resolveUrl(imageUrl);
-		if (!resolvedUrl) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage",
-				value: imageUrl,
-				reason: "invalid URL format",
-				level: "warn"
-			}));
-			return;
-		}
-		const localPath = this.findLocalImage(imageUrl);
-		const dimensions = localPath ? await this.readImageDimensions(localPath) : void 0;
-		return {
-			url: resolvedUrl,
-			type: dimensions?.type,
-			width: dimensions?.width,
-			height: dimensions?.height,
-			alt: this.generateAltText(packageName, apiName)
-		};
-	}
-	/**
-	* Resolves a URL string to an absolute URL.
-	*
-	* @param url - The URL to resolve (absolute URL or relative path)
-	* @returns The absolute URL, or `undefined` if the format is invalid
-	*/
-	resolveUrl(url) {
-		if (url.startsWith("http://") || url.startsWith("https://")) return url;
-		if (url.startsWith("/")) return `${this.siteUrl}${url}`;
-	}
-	/**
-	* Attempts to find a local image file in the docs public directory.
-	*
-	* @param imagePath - The relative image path (starting with `/`)
-	* @returns The absolute file path if found, or `undefined` if not found
-	*   or if `docsRoot` is not configured
-	*/
-	findLocalImage(imagePath) {
-		if (!this.docsRoot || !imagePath.startsWith("/")) return;
-		const publicPath = path.join(this.docsRoot, "public", imagePath);
-		if (fs.existsSync(publicPath)) return publicPath;
-	}
-	/**
-	* Reads image dimensions and type from a local file.
-	*
-	* @param filePath - Absolute path to the image file
-	* @returns Object containing width, height, and MIME type if successful,
-	*   or `undefined` if the file cannot be read or analyzed
-	*/
-	async readImageDimensions(filePath) {
-		try {
-			const dimensions = await imageSizeFromFile(filePath);
-			let mimeType;
-			if (dimensions.type) mimeType = IMAGE_MIME_TYPES[dimensions.type.toLowerCase()];
-			return {
-				width: dimensions.width,
-				height: dimensions.height,
-				...mimeType != null ? { type: mimeType } : {}
-			};
-		} catch (error) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage",
-				value: filePath,
-				reason: error.message ?? String(error),
-				level: "warn"
-			}));
-			return;
-		}
-	}
-	/**
-	* Generates descriptive alt text for the OG image.
-	*
-	* @param packageName - The package name
-	* @param apiName - Optional API name for more specific text
-	* @returns Generated alt text string
-	*/
-	generateAltText(packageName, apiName) {
-		if (apiName) return `${apiName} - ${packageName} API Documentation`;
-		return `${packageName} API Documentation`;
-	}
-	/**
-	* Creates complete Open Graph metadata for an API documentation page.
-	*
-	* This static factory method builds a complete `OpenGraphMetadata` object
-	* suitable for inclusion in page frontmatter, combining resolved image
-	* metadata with article-specific information.
-	*
-	* @param options - Configuration for the OG metadata.
-	*   Includes `siteUrl`, `pageRoute`, `description`, `publishedTime`,
-	*   `modifiedTime`, `section`, `packageName`, and optional `ogImage`.
-	* @returns Complete Open Graph metadata object
-	*
-	* @example
-	* ```typescript
-	* const ogMetadata = OpenGraphResolver.createPageMetadata({
-	*   siteUrl: "https://example.com",
-	*   pageRoute: "/api/classes/MyClass",
-	*   description: "MyClass provides...",
-	*   publishedTime: "2024-01-15T10:00:00Z",
-	*   modifiedTime: "2024-01-20T15:30:00Z",
-	*   section: "Classes",
-	*   packageName: "my-library",
-	*   ogImage: resolvedImageMetadata
-	* });
-	* ```
-	*/
-	static createPageMetadata(options) {
-		return {
-			siteUrl: options.siteUrl,
-			pageRoute: options.pageRoute,
-			description: options.description,
-			publishedTime: options.publishedTime,
-			modifiedTime: options.modifiedTime,
-			section: options.section,
-			tags: [
-				"TypeScript",
-				"API",
-				options.packageName
-			],
-			...options.ogImage != null ? { ogImage: options.ogImage } : {},
-			ogType: "article"
-		};
-	}
-};
+function createPageMetadata(options) {
+	return {
+		siteUrl: options.siteUrl,
+		pageRoute: options.pageRoute,
+		description: options.description,
+		publishedTime: options.publishedTime,
+		modifiedTime: options.modifiedTime,
+		section: options.section,
+		tags: [
+			"TypeScript",
+			"API",
+			options.packageName
+		],
+		...options.ogImage != null ? { ogImage: options.ogImage } : {},
+		ogType: "article"
+	};
+}
 
 //#endregion
-export { OpenGraphResolver, setOgResolverEventEmitter };
+export { createPageMetadata, imageMimeType, ogAltText, resolveOgUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -53,7 +53,7 @@
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
 		"@tsdoctor/bundle": "0.2.0",
-		"@tsdoctor/model": "0.2.2",
+		"@tsdoctor/model": "0.3.0",
 		"@tsdoctor/registry": "0.2.1",
 		"@tsdoctor/snapshot": "0.1.1",
 		"@typescript/vfs": "^1.6.4",
@@ -62,7 +62,6 @@
 		"hast-util-to-jsx-runtime": "^2.3.6",
 		"image-size": "^2.0.2",
 		"ioredis": "^5.7.0",
-		"mdast-util-from-markdown": "^2.0.3",
 		"mdast-util-to-hast": "^13.2.1",
 		"open": "^11.0.0",
 		"prettier": "^3.9.6",

package/path-derivation.js

@@ -43,6 +43,24 @@ function deriveOutputPaths(input) {
 	}
 	return results;
 }
+/**
+* The API scope key derived from a base route.
+*
+* @remarks
+* Load-bearing and previously duplicated. Config resolution registers each
+* API's Twoslash environment under this key and the build program looks it up
+* by the same key; if the two derivations disagree, every lookup misses and
+* `getTransformer` falls back to the build-wide environment. Per-scope
+* type-checking degrades to build-wide with no error and nothing visibly
+* wrong in the output — the failure mode is silent, which is why one
+* definition matters more here than the duplication was costing.
+*
+* Falls back to the package name so a single-API site mounted at `/` still
+* gets a non-empty scope.
+*/
+function apiScopeOf(baseRoute, packageName) {
+	return baseRoute.replace(/^\//, "").split("/")[0] || packageName;
+}
 
 //#endregion
-export { deriveOutputPaths, normalizeBaseRoute, unscopedName };
+export { apiScopeOf, deriveOutputPaths, normalizeBaseRoute, unscopedName };

package/plugin.js

@@ -1,39 +1,44 @@
+import { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds } from "./BuildEnv.js";
 import { PluginEvent } from "./observability/events.js";
-import { emit, makeRuntimeEmitter } from "./observability/EventBus.js";
+import { emit } from "./observability/EventBus.js";
 import { codeBlockReport } from "./observability/metric-report.js";
 import { runHeartbeat } from "./observability/heartbeat.js";
 import { writeIssuesJson } from "./observability/sinks/issues-sink.js";
 import { writeRenderPhaseJson } from "./observability/sinks/render-sink.js";
 import { buildEventBus, logBuildSummary, makeSummaryLoggerLayer } from "./layers/ObservabilityLive.js";
-import { setPrettierEventEmitter } from "./prettier-formatter.js";
-import { setOgResolverEventEmitter } from "./og-resolver.js";
-import { setBuildStagesEventEmitter } from "./build-stages.js";
-import { TwoslashManager, setEventEmitter } from "./twoslash-transformer.js";
+import { emitSync, installSyncEmitter } from "./observability/sync-emitter.js";
+import { TwoslashEnvironments } from "./services/TwoslashEnvironments.js";
+import { clearTypeRoutes } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateApiDocs } from "./build-program.js";
 import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
 import { fromDir, fromParentDir } from "./config-helpers.js";
 import { classifyApiConfig, mergeLlmsPluginConfig } from "./config-utils.js";
-import { DEFAULT_SHIKI_THEMES, setShikiUtilsEventEmitter } from "./markdown/shiki-utils.js";
+import { collectShikiThemes, normalizeThemeConfig } from "./markdown/shiki-utils.js";
 import { resolveObservability } from "./schemas/observability.js";
 import { PluginOptions } from "./schemas/config.js";
 import "./schemas/index.js";
 import { ConfigService } from "./services/ConfigService.js";
+import { PluginConfig } from "./services/PluginConfig.js";
 import { TwoslashCacheService } from "./services/TwoslashCacheService.js";
 import { ConfigServiceLive } from "./layers/ConfigServiceLive.js";
-import { PathDerivationServiceLive } from "./layers/PathDerivationServiceLive.js";
+import { HighlighterServiceLive } from "./layers/HighlighterServiceLive.js";
+import { OgServiceLive } from "./layers/OgServiceLive.js";
+import { PlatformLive } from "./layers/xdg.js";
 import { TwoslashCacheServiceLive } from "./layers/TwoslashCacheServiceLive.js";
+import { TwoslashEnvironmentsLive } from "./layers/TwoslashEnvironmentsLive.js";
 import { TypeRegistryServiceLive } from "./layers/TypeRegistryServiceLive.js";
-import { remarkApiCodeblocks, setRemarkApiCodeblocksEventEmitter } from "./remark-api-codeblocks.js";
-import { remarkWithApi, setRemarkWithApiEventEmitter } from "./remark-with-api.js";
-import { ShikiCrossLinker } from "./shiki-transformer.js";
+import { clearTwoslashAccess, installTwoslashAccess, twoslashTransformerFor } from "./twoslash-access.js";
+import { remarkApiCodeblocks } from "./remark-api-codeblocks.js";
+import { remarkWithApi } from "./remark-with-api.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { NodeFileSystem } from "@effect/platform-node";
 import { SnapshotServiceLive } from "@tsdoctor/snapshot";
-import { Effect, FileSystem, Layer, ManagedRuntime, Ref, Schema } from "effect";
+import { Effect, FileSystem, Layer, ManagedRuntime, Option, Ref, Schema } from "effect";
 
 //#region src/plugin.ts
 /* v8 ignore start -- RSPress plugin adapter, requires RSPress runtime */
@@ -53,30 +58,11 @@ const readSitePackageName = Effect.gen(function* () {
 	return "unknown";
 });
 /**
-* 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
-	};
-}
-/**
 * RSPress plugin for generating API documentation from API Extractor model files
 */
 function ApiExtractorPluginImpl(rawOptions) {
 	const options = Schema.decodeUnknownSync(PluginOptions)(rawOptions);
 	const isInert = classifyApiConfig(options) === "disabled";
-	const shikiCrossLinker = new ShikiCrossLinker();
 	const envLogLevel = process.env.LOG_LEVEL?.toLowerCase();
 	const buildId = `${process.pid}-${performance.now().toString(36)}`;
 	const { resolved: obs, deprecations } = resolveObservability({
@@ -90,22 +76,14 @@ function ApiExtractorPluginImpl(rawOptions) {
 	const { layer: eventBusLayer, trace: traceSink, issues: issuesSink, render: renderSink, metrics: metricStore } = buildEventBus(obs);
 	const dbPath = path.resolve(process.cwd(), ".api-docs", "snapshot", "api-docs.db");
 	fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-	const BaseLayer = Layer.mergeAll(PathDerivationServiceLive, eventBusLayer, metricStore.layer, TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath), TwoslashCacheServiceLive, makeSummaryLoggerLayer(obs.logLevel));
-	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive(options, shikiCrossLinker, buildId, obs.thresholds), BaseLayer);
+	const BuildEnvLayer = Layer.mergeAll(Layer.succeed(BuildId, buildId), Layer.succeed(Thresholds, obs.thresholds), Layer.succeed(PageConcurrency, os.cpus().length), Layer.succeed(SuppressExampleErrors, options.errors?.example !== "show"));
+	const PluginConfigLive = Layer.succeed(PluginConfig, options);
+	const HighlighterLive = HighlighterServiceLive(collectShikiThemes(options.api ? [options.api] : options.apis ?? []));
+	const BaseLayer = Layer.mergeAll(eventBusLayer, PluginConfigLive, HighlighterLive, TwoslashEnvironmentsLive, Layer.provide(OgServiceLive, PlatformLive), BuildEnvLayer, metricStore.layer, TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath), TwoslashCacheServiceLive, makeSummaryLoggerLayer(obs.logLevel));
+	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive, BaseLayer);
 	const effectRuntime = ManagedRuntime.make(EffectAppLayer);
-	const emitSync = makeRuntimeEmitter(effectRuntime);
-	setEventEmitter(emitSync, buildId);
-	setShikiUtilsEventEmitter(emitSync, buildId);
-	setPrettierEventEmitter(emitSync, buildId);
-	setOgResolverEventEmitter(emitSync, buildId);
-	setRemarkWithApiEventEmitter(emitSync, buildId, obs.thresholds.slowCodeBlock);
-	setRemarkApiCodeblocksEventEmitter(emitSync, buildId, obs.thresholds.slowCodeBlock);
-	setBuildStagesEventEmitter(emitSync, buildId);
-	/**
-	* The build's Twoslash result cache, captured in `config()` and persisted in
-	* `afterBuild` — the render phase that populates it runs in between.
-	*/
-	let twoslashCacheHandle = null;
+	const emitterRuntime = ManagedRuntime.make(Layer.mergeAll(eventBusLayer, metricStore.layer, makeSummaryLoggerLayer(obs.logLevel), BuildEnvLayer));
+	installSyncEmitter(emitterRuntime);
 	const fileContextMap = /* @__PURE__ */ new Map();
 	let docsRoot;
 	let isFirstBuild = true;
@@ -121,22 +99,20 @@ function ApiExtractorPluginImpl(rawOptions) {
 			if (isFirstBuild && !isInert) {
 				const renderSamples = renderSink.snapshot();
 				const report = await effectRuntime.runPromise(codeBlockReport);
-				if (twoslashCacheHandle) {
-					const { cache, envHash } = twoslashCacheHandle;
-					const stats = cache.stats();
-					await effectRuntime.runPromise(Effect.gen(function* () {
-						if (stats.dirty) yield* (yield* TwoslashCacheService).save(envHash, cache.entries());
-						yield* emit(PluginEvent.TwoslashCacheSaved({
-							ctx: { buildId },
-							level: "info",
-							envHash,
-							hits: stats.hits,
-							misses: stats.misses,
-							entries: stats.entries,
-							persisted: stats.dirty
-						}));
+				await effectRuntime.runPromise(Effect.gen(function* () {
+					const saved = yield* (yield* TwoslashCacheService).persist();
+					if (Option.isNone(saved)) return;
+					const stats = saved.value;
+					yield* emit(PluginEvent.TwoslashCacheSaved({
+						ctx: { buildId },
+						level: "info",
+						envHash: stats.envHash,
+						hits: stats.hits,
+						misses: stats.misses,
+						entries: stats.entries,
+						persisted: stats.dirty
 					}));
-				}
+				}));
 				await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock, report));
 				if (isProd) await effectRuntime.runPromise(Effect.gen(function* () {
 					const packageName = yield* readSitePackageName;
@@ -165,7 +141,10 @@ function ApiExtractorPluginImpl(rawOptions) {
 				isFirstBuild = false;
 			}
 			if (traceSink) traceSink.flush();
-			if (isProd) await effectRuntime.dispose();
+			if (isProd) {
+				await effectRuntime.dispose();
+				await emitterRuntime.dispose();
+			}
 		},
 		async config(_config, _utils, isProd) {
 			const buildStartTime = performance.now();
@@ -206,6 +185,8 @@ function ApiExtractorPluginImpl(rawOptions) {
 				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
 			}
 			VfsRegistry.clear();
+			clearTwoslashAccess();
+			clearTypeRoutes();
 			fileContextMap.clear();
 			issuesSink.reset();
 			for (const dep of deprecations) emitSync(PluginEvent.DeprecatedConfigUsed({
@@ -237,17 +218,11 @@ function ApiExtractorPluginImpl(rawOptions) {
 						apisTotal: apiCount,
 						buildId
 					}));
-					const buildContext = yield* (yield* ConfigService).resolve(rspressConfigSubset);
-					twoslashCacheHandle = {
-						cache: buildContext.twoslashCache,
-						envHash: buildContext.twoslashEnvHash
-					};
+					installTwoslashAccess(yield* TwoslashEnvironments);
+					const apiConfigs = yield* (yield* ConfigService).resolve(rspressConfigSubset);
 					buildResults.length = 0;
 					yield* Ref.set(phaseRef, "generate");
-					yield* Effect.forEach(buildContext.apiConfigs, (apiConfig) => generateApiDocs({
-						...apiConfig,
-						suppressExampleErrors: buildContext.suppressExampleErrors
-					}, buildContext, fileContextMap).pipe(Effect.tap((result) => {
+					yield* Effect.forEach(apiConfigs, (apiConfig) => generateApiDocs(apiConfig, fileContextMap).pipe(Effect.tap((result) => {
 						buildResults.push(result);
 						return emit(PluginEvent.ApiDocsCompleted({
 							ctx: { buildId },
@@ -305,10 +280,10 @@ function ApiExtractorPluginImpl(rawOptions) {
 			if (!existingInclude.includes("rspress-plugin-api-extractor/runtime")) updatedConfig.builderConfig.source.include = [...existingInclude, "rspress-plugin-api-extractor/runtime"];
 			if (!updatedConfig.markdown) updatedConfig.markdown = {};
 			if (!updatedConfig.markdown.remarkPlugins) updatedConfig.markdown.remarkPlugins = [];
-			const remarkTheme = normalizeThemeConfig(options.api?.theme ?? options.apis?.[0]?.theme);
+			const firstApiTheme = options.api?.theme ?? options.apis?.[0]?.theme;
+			const remarkTheme = normalizeThemeConfig(firstApiTheme);
 			updatedConfig.markdown.remarkPlugins.push([remarkWithApi, {
-				shikiCrossLinker,
-				getTransformer: (apiScope) => TwoslashManager.getInstance().getTransformer(apiScope),
+				getTransformer: (apiScope) => twoslashTransformerFor(apiScope),
 				theme: remarkTheme
 			}]);
 			updatedConfig.markdown.remarkPlugins.push([remarkApiCodeblocks]);

package/prettier-formatter.js

@@ -1,16 +1,10 @@
 import { PluginEvent } from "./observability/events.js";
 import { addLogicalBlankLines } from "./code-post-processor.js";
+import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
 import { format } from "prettier";
 
 //#region src/prettier-formatter.ts
 /* v8 ignore start -- Prettier integration wrapper, tested via page generator integration tests */
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setPrettierEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
 * Map code fence languages to Prettier parsers
 */
@@ -65,8 +59,8 @@ async function formatCode(code, language) {
 	} catch (error) {
 		const formatTime = performance.now() - start;
 		const errorMsg = error instanceof Error ? error.message : String(error);
-		emitEvent(PluginEvent.PrettierError({
-			ctx: { buildId: currentBuildId },
+		emitSync(PluginEvent.PrettierError({
+			ctx: { buildId: syncBuildId() },
 			file: "unknown",
 			reason: errorMsg,
 			level: "warn"
@@ -81,4 +75,4 @@ async function formatCode(code, language) {
 }
 
 //#endregion
-export { formatCode, setPrettierEventEmitter };
+export { formatCode };