rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/plugin.js

@@ -1,39 +1,33 @@
 import { PluginEvent } from "./observability/events.js";
-import { emit, makeRuntimeEmitter } 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 { emit } from "./observability/EventBus.js";
+import { emitSync, installSyncEmitter } from "./observability/sync-emitter.js";
+import { normalizeThemeConfig } from "./markdown/shiki-utils.js";
+import { clearTypeRoutes } from "./twoslash-transformer.js";
+import { TwoslashEnvironments } from "./services/TwoslashEnvironments.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 { resolveObservability } from "./schemas/observability.js";
 import { PluginOptions } from "./schemas/config.js";
-import "./schemas/index.js";
-import { ConfigService } from "./services/ConfigService.js";
 import { TwoslashCacheService } from "./services/TwoslashCacheService.js";
-import { ConfigServiceLive } from "./layers/ConfigServiceLive.js";
-import { PathDerivationServiceLive } from "./layers/PathDerivationServiceLive.js";
-import { TwoslashCacheServiceLive } from "./layers/TwoslashCacheServiceLive.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 { ConfigService } from "./services/ConfigService.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 } from "./layers/observability.js";
+import { makeAppLayers } from "./layers/AppLayer.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 fsSync 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, ManagedRuntime, Option, Ref, Schema } from "effect";
 
 //#region src/plugin.ts
 /* v8 ignore start -- RSPress plugin adapter, requires RSPress runtime */
@@ -53,30 +47,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({
@@ -89,23 +64,19 @@ 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 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;
+	fsSync.mkdirSync(path.dirname(dbPath), { recursive: true });
+	const appLayers = makeAppLayers({
+		options,
+		obs,
+		buildId,
+		dbPath,
+		pageConcurrency: os.cpus().length,
+		eventBus: eventBusLayer,
+		metrics: metricStore
+	});
+	const effectRuntime = ManagedRuntime.make(appLayers.app);
+	const emitterRuntime = ManagedRuntime.make(appLayers.emitter);
+	installSyncEmitter(emitterRuntime);
 	const fileContextMap = /* @__PURE__ */ new Map();
 	let docsRoot;
 	let isFirstBuild = true;
@@ -121,22 +92,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 +134,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();
@@ -174,6 +146,8 @@ function ApiExtractorPluginImpl(rawOptions) {
 			const rspressLocales = _config.locales?.map((l) => l.lang) ?? [];
 			const rspressLang = _config.lang;
 			const rspressMultiVersion = _config.multiVersion;
+			const rspressSiteOrigin = _config.siteOrigin;
+			const rspressBase = _config.base;
 			rspressLlmsEnabled = Boolean(_config.llms);
 			rspressOutDir = _config.outDir ?? "dist";
 			if (options.api) {
@@ -190,7 +164,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 					versions,
 					defaultVersion: rspressMultiVersion?.default
 				});
-				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+				for (const dp of derivedPaths) fsSync.mkdirSync(dp.outputDir, { recursive: true });
 			} else if (options.apis) for (const api of options.apis) {
 				const baseRoute = normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
 				const derivedPaths = deriveOutputPaths({
@@ -203,9 +177,11 @@ function ApiExtractorPluginImpl(rawOptions) {
 					versions: [],
 					defaultVersion: void 0
 				});
-				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+				for (const dp of derivedPaths) fsSync.mkdirSync(dp.outputDir, { recursive: true });
 			}
 			VfsRegistry.clear();
+			clearTwoslashAccess();
+			clearTypeRoutes();
 			fileContextMap.clear();
 			issuesSink.reset();
 			for (const dep of deprecations) emitSync(PluginEvent.DeprecatedConfigUsed({
@@ -219,7 +195,9 @@ function ApiExtractorPluginImpl(rawOptions) {
 					...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
 					...rspressLocales.length > 0 ? { locales: rspressLocales.map((lang) => ({ lang })) } : {},
 					...rspressLang != null ? { lang: rspressLang } : {},
-					...docsRoot != null ? { root: docsRoot } : {}
+					...docsRoot != null ? { root: docsRoot } : {},
+					...rspressSiteOrigin != null ? { siteOrigin: rspressSiteOrigin } : {},
+					...rspressBase != null ? { base: rspressBase } : {}
 				};
 				await effectRuntime.runPromise(Effect.gen(function* () {
 					const apiCount = options.api ? 1 : options.apis?.length ?? 0;
@@ -237,17 +215,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 +277,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 { PluginEvent } from "./observability/events.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 };

package/remark-api-codeblocks.js

@@ -1,20 +1,12 @@
 import { PluginEvent } from "./observability/events.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
-import { VfsRegistry } from "./vfs-registry.js";
+import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
 import { generateShikiHast } from "./markdown/shiki-utils.js";
+import { VfsRegistry } from "./vfs-registry.js";
+import { setTwoslashFile } from "./twoslash-access.js";
 import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-api-codeblocks.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-let currentSlowCodeBlockMs = Number.POSITIVE_INFINITY;
-function setRemarkApiCodeblocksEventEmitter(fn, buildId = "", slowCodeBlockMs = Number.POSITIVE_INFINITY) {
-	emitEvent = fn;
-	currentBuildId = buildId;
-	currentSlowCodeBlockMs = slowCodeBlockMs;
-}
 /**
 * Create an MDX JSX attribute value expression with proper estree AST.
 * This ensures the value is properly serialized as a JavaScript string literal.
@@ -94,7 +86,7 @@ const remarkApiCodeblocks = () => {
 		const promises = [];
 		const isSsgMd = import.meta.env?.SSG_MD || process.env.RSBUILD_ENVIRONMENT === "node_md" || process.env.BUILD_TARGET === "node_md";
 		const currentFilePath = file.path || "unknown";
-		if (file.path) TwoslashManager.getInstance().setCurrentFile(file.path);
+		if (file.path) setTwoslashFile(file.path);
 		const jsxComponentNames = /* @__PURE__ */ new Set([
 			"ApiSignature",
 			"ApiMember",
@@ -112,9 +104,9 @@ const remarkApiCodeblocks = () => {
 				}
 				const vfsConfig = VfsRegistry.get(apiScopeValue);
 				if (!vfsConfig) {
-					emitEvent(PluginEvent.ConfigCascadeWarning({
+					emitSync(PluginEvent.ConfigCascadeWarning({
 						ctx: {
-							buildId: currentBuildId,
+							buildId: syncBuildId(),
 							file: currentFilePath
 						},
 						field: "vfs",
@@ -140,11 +132,11 @@ const remarkApiCodeblocks = () => {
 				const renderMs = performance.now() - shikiStart;
 				let hast = await hastPromise;
 				const postStart = performance.now();
-				if (hast && vfsConfig.crossLinker) hast = vfsConfig.crossLinker.transformHast(hast, apiScopeValue);
+				if (hast && vfsConfig.crossLinker) hast = vfsConfig.crossLinker.transformHast(hast);
 				const totalBlockTime = renderMs + (performance.now() - postStart);
-				emitEvent(PluginEvent.CodeBlockProcessed({
+				emitSync(PluginEvent.CodeBlockProcessed({
 					ctx: {
-						buildId: currentBuildId,
+						buildId: syncBuildId(),
 						apiScope: apiScopeValue,
 						file: currentFilePath
 					},
@@ -154,7 +146,7 @@ const remarkApiCodeblocks = () => {
 					twoslashMs,
 					shikiMs: Math.max(0, renderMs - twoslashMs),
 					totalMs: totalBlockTime,
-					slow: totalBlockTime > currentSlowCodeBlockMs,
+					slow: totalBlockTime > syncSlowCodeBlockMs(),
 					level: "debug"
 				}));
 				const hastBase64 = hast ? Buffer.from(JSON.stringify(hast), "utf-8").toString("base64") : "";
@@ -172,4 +164,4 @@ const remarkApiCodeblocks = () => {
 };
 
 //#endregion
-export { remarkApiCodeblocks, setRemarkApiCodeblocksEventEmitter };
+export { remarkApiCodeblocks };

package/remark-with-api.js

@@ -1,22 +1,15 @@
 import { PluginEvent } from "./observability/events.js";
+import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
 import { formatCode } from "./prettier-formatter.js";
 import { stripTwoslashDirectives } from "./markdown/helpers.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
 import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { VfsRegistry } from "./vfs-registry.js";
+import { setTwoslashFile } from "./twoslash-access.js";
 import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { codeToHast, hastToHtml } from "shiki";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-with-api.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-let currentSlowCodeBlockMs = 500;
-function setRemarkWithApiEventEmitter(fn, buildId = "", slowCodeBlockMs = 500) {
-	emitEvent = fn;
-	currentBuildId = buildId;
-	currentSlowCodeBlockMs = slowCodeBlockMs;
-}
 /**
 * Supported languages for with-api code blocks
 * Based on GitHub Linguist standard aliases:
@@ -59,18 +52,14 @@ function inferApiScope(filePath) {
 * 5. Renders to ApiExample component with pre-rendered Shiki HAST
 */
 const remarkWithApi = (options) => {
-	const { shikiCrossLinker, getTransformer, theme } = options;
+	const { getTransformer, theme } = options;
 	const resolvedTheme = theme ?? DEFAULT_SHIKI_THEMES;
 	return async function remarkTransformer(tree, file) {
 		const promises = [];
 		let needsApiExampleImport = false;
 		const isSsgMd = import.meta.env?.SSG_MD || process.env.RSBUILD_ENVIRONMENT === "node_md" || process.env.BUILD_TARGET === "node_md";
 		const currentFilePath = file.path;
-		if (currentFilePath) {
-			const apiScope = inferApiScope(currentFilePath);
-			if (apiScope) shikiCrossLinker.setApiScope(apiScope);
-			TwoslashManager.getInstance().setCurrentFile(currentFilePath);
-		}
+		if (currentFilePath) setTwoslashFile(currentFilePath);
 		visit(tree, "code", (node, index, parent) => {
 			const hasWithApi = node.meta?.includes("with-api");
 			const lang = node.lang || "typescript";
@@ -99,12 +88,13 @@ const remarkWithApi = (options) => {
 					transformers
 				});
 				const renderMs = performance.now() - shikiStart;
-				if (apiScope) hast = shikiCrossLinker.transformHast(hast, apiScope);
+				const scopeLinker = apiScope ? VfsRegistry.get(apiScope)?.crossLinker : void 0;
+				if (scopeLinker) hast = scopeLinker.transformHast(hast);
 				const totalBlockTime = performance.now() - blockStart;
-				const isSlow = totalBlockTime > currentSlowCodeBlockMs;
-				emitEvent(PluginEvent.CodeBlockProcessed({
+				const isSlow = totalBlockTime > syncSlowCodeBlockMs();
+				emitSync(PluginEvent.CodeBlockProcessed({
 					ctx: {
-						buildId: currentBuildId,
+						buildId: syncBuildId(),
 						...apiScope != null ? { apiScope } : {},
 						...currentFilePath != null ? { file: currentFilePath } : {}
 					},
@@ -191,4 +181,4 @@ const remarkWithApi = (options) => {
 };
 
 //#endregion
-export { remarkWithApi, setRemarkWithApiEventEmitter };
+export { remarkWithApi };

package/schemas/config.js

@@ -304,8 +304,6 @@ const PluginOptions = Schema.Struct({
 	api: Schema.optional(Schema.NullOr(SingleApiConfig)),
 	/** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
 	apis: Schema.optional(Schema.NullOr(Schema.mutable(Schema.Array(MultiApiConfig)))),
-	/** Canonical site URL used for Open Graph absolute URLs. */
-	siteUrl: Schema.optional(Schema.String),
 	/** Global Open Graph image configuration (overridden per-API). */
 	ogImage: Schema.optional(OpenGraphImageConfig),
 	/** Override the default category definitions for all APIs. */

package/services/ConfigService.js

@@ -1,7 +1,42 @@
-import { Context } from "effect";
+import { makeConfigService } from "../layers/config-resolution.js";
+import { Context, Effect, Layer } from "effect";
 
 //#region src/services/ConfigService.ts
-var ConfigService = class extends Context.Service()("rspress-plugin-api-extractor/ConfigService") {};
+var ConfigService = class ConfigService extends Context.Service()("rspress-plugin-api-extractor/ConfigService") {
+	/**
+	* Config resolution over the plugin options and the RSPress config.
+	*
+	* @remarks
+	* A plain `const`, not a factory. It used to take the plugin options as an
+	* argument, 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 "call it twice" is a type error
+	* rather than a test case.
+	*
+	* `Effect.suspend` because {@link makeConfigService} is imported from a
+	* module this one is also imported BY: a static initializer runs while the
+	* module body is still evaluating, so reading the binding eagerly can throw
+	* at import time with a completely clean typecheck.
+	*/
+	static layer = Layer.effect(this, Effect.suspend(() => makeConfigService));
+	/**
+	* An in-memory double whose unstubbed member dies naming itself.
+	*
+	* @remarks
+	* **No default `resolve`.** Returning an empty array by default would be a
+	* silent "this site documents nothing" — the exact state an inert plugin
+	* produces — so a test that forgot to stub it would assert against a build
+	* that generated no pages and pass. Stub it explicitly, or provide
+	* {@link ConfigService.layer} over real inputs.
+	*/
+	static makeTest = (overrides = {}) => ({ resolve: overrides.resolve ?? (() => unstubbed("resolve")) });
+	/** {@link ConfigService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ConfigService, ConfigService.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`ConfigService.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
 
 //#endregion
 export { ConfigService };

package/services/HighlighterService.js

@@ -0,0 +1,75 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { SHIKI_LANGS } from "../markdown/shiki-utils.js";
+import { Context, Effect, Layer } from "effect";
+import { createHighlighter } from "shiki";
+
+//#region src/services/HighlighterService.ts
+/**
+* The build's single Shiki highlighter.
+*
+* @remarks
+* A highlighter owns a WASM oniguruma instance and every loaded grammar and
+* theme, and it has a `dispose()` nobody was calling: `ConfigService.layer`
+* created one per `resolve()`, so a dev-mode HMR session leaked one per
+* rebuild. The test run reported it as
+* `[Shiki] 10 instances have been created` — a console leak, not a failure.
+*
+* The fix is NOT to scope it to `resolve()`. `VfsRegistry` hands this
+* highlighter to the remark plugins, which RSPress invokes during its render
+* pass — after `config()` has returned and after any `resolve()`-scoped scope
+* would have closed. The lifetime that matches is the `ManagedRuntime`'s:
+* acquired when the layer builds, released by `effectRuntime.dispose()` in
+* `afterBuild` on production builds, and deliberately kept alive in dev so HMR
+* rebuilds reuse it.
+*
+* Getting that wrong is silent — a disposed highlighter does not throw, the
+* code blocks just render as unhighlighted `<pre>`.
+*
+* @packageDocumentation
+*/
+var HighlighterService = class extends Context.Service()("rspress-plugin-api-extractor/HighlighterService") {
+	/**
+	* Acquire the build's highlighter, and release it when the runtime is
+	* disposed.
+	*
+	* @remarks
+	* `Layer.effect` over `Effect.acquireRelease` is the v4 scoped-constructor
+	* idiom (`Layer.scoped` is gone; `Layer.effect` strips `Scope` from `R`).
+	* Because the layer sits in the `ManagedRuntime`'s stack, the highlighter is
+	* created on the runtime's first use and `dispose()`d by
+	* `effectRuntime.dispose()` — which `plugin.ts` calls on production builds
+	* only, so a dev HMR session keeps one highlighter across rebuilds instead of
+	* leaking one per rebuild.
+	*
+	* **Bind the result to a `const`.** This is a layer FACTORY: each call mints a
+	* fresh layer reference, and layers memoize by reference, so calling it twice
+	* in one graph acquires two highlighters — the exact leak this layer exists to
+	* fix.
+	*
+	* The themes are passed in rather than read from a resolved build context
+	* because the layer builds before `ConfigService.resolve()` runs. Passing them
+	* as an argument rather than through a `Context.Reference` is deliberate: a
+	* Reference carries a default, so forgetting to wire it would silently load
+	* only the default themes and render every custom-themed block wrong. A
+	* missing argument is a type error.
+	*/
+	static layer = (themes) => Layer.effect(this, make(themes));
+};
+const make = (themes) => Effect.gen(function* () {
+	const startedMs = performance.now();
+	const highlighter = yield* Effect.acquireRelease(Effect.promise(() => createHighlighter({
+		themes: [...themes],
+		langs: [...SHIKI_LANGS]
+	})), (instance) => Effect.sync(() => instance.dispose()));
+	yield* emit(PluginEvent.PhaseCompleted({
+		ctx: {},
+		level: "debug",
+		phase: "shikiInit",
+		durationMs: Math.round(performance.now() - startedMs)
+	}));
+	return { highlighter };
+});
+
+//#endregion
+export { HighlighterService };