rspress-plugin-api-extractor 0.9.2 → 0.10.0

package/observability/sinks/metrics-sink.js

@@ -1,17 +1,22 @@
 import { BuildMetrics } from "../../layers/build-metrics.js";
-import { Effect, Metric } from "effect";
+import { Metric } from "effect";
 
 //#region src/observability/sinks/metrics-sink.ts
 /**
 * Event-driven metrics sink.
 *
 * Translates each `PluginEvent` to the corresponding `BuildMetrics` counter or
-* histogram update via `Effect.runSync`. The fan-out from `EventBus.emit` is
+* histogram update against the build's metric registry. The fan-out from `EventBus.emit` is
 * synchronous, so by the time the emitting fiber resumes the metrics are already
 * recorded — counts are exact when `logBuildSummary` reads them in `afterBuild`.
 *
 * Unmapped event tags hit the `default` branch and are silently ignored.
 *
+* Events whose breakdown is worth querying are recorded twice — undimensioned
+* for the build-wide totals, and tagged for `metric-report.ts`. The attributes
+* are deliberately bounded (scope, status, phase, TS code); anything unbounded,
+* such as a file path, belongs in a sample-shaped sink instead.
+*
 * Intentionally NOT derived here: `externalPackagesTotal` and `apiVersionsLoaded`
 * remain inline increments in `ConfigServiceLive`. `externalPackagesTotal` counts
 * CONFIGURED packages via `incrementBy(length)`; the only candidate event,
@@ -19,46 +24,84 @@ import { Effect, Metric } from "effect";
 * a `loaded` (SUCCEEDED) count — different semantics, so deriving it here would
 * change what the metric means. `apiVersionsLoaded` has no corresponding event.
 */
-function makeMetricsSink() {
+function makeMetricsSink(context) {
+	const update = (metric, input) => metric.updateUnsafe(input, context);
+	/** Record `metric` twice: undimensioned, and tagged for breakdown queries. */
+	const both = (metric, input, attributes) => {
+		update(metric, input);
+		update(Metric.withAttributes(metric, attributes), input);
+	};
+	const scopeOf = (event) => event.ctx.apiScope ?? "(unscoped)";
 	return {
 		minLevel: "trace",
 		handle(event) {
 			switch (event._tag) {
 				case "FileDecision":
-					Effect.runSync(Metric.update(BuildMetrics.filesTotal, 1));
-					if (event.status === "new") Effect.runSync(Metric.update(BuildMetrics.filesNew, 1));
-					else if (event.status === "modified") Effect.runSync(Metric.update(BuildMetrics.filesModified, 1));
-					else Effect.runSync(Metric.update(BuildMetrics.filesUnchanged, 1));
+					both(BuildMetrics.filesTotal, 1, {
+						scope: scopeOf(event),
+						status: event.status
+					});
+					if (event.status === "new") update(BuildMetrics.filesNew, 1);
+					else if (event.status === "modified") update(BuildMetrics.filesModified, 1);
+					else update(BuildMetrics.filesUnchanged, 1);
 					break;
 				case "PageGenerated":
-					Effect.runSync(Metric.update(BuildMetrics.pagesGenerated, 1));
+					update(BuildMetrics.pagesGenerated, 1);
 					break;
 				case "ApiDocsCompleted":
-					Effect.runSync(Metric.update(BuildMetrics.apisCompleted, 1));
+					update(BuildMetrics.apisCompleted, 1);
 					break;
 				case "TwoslashDiagnostic":
-					Effect.runSync(Metric.update(BuildMetrics.twoslashDiagnostics, 1));
-					Effect.runSync(Metric.update(BuildMetrics.twoslashErrors, 1));
+					both(BuildMetrics.twoslashDiagnostics, 1, {
+						code: `TS${event.code}`,
+						scope: scopeOf(event)
+					});
+					update(BuildMetrics.twoslashErrors, 1);
 					break;
 				case "PrettierError":
-					Effect.runSync(Metric.update(BuildMetrics.prettierErrors, 1));
+					both(BuildMetrics.prettierErrors, 1, { scope: scopeOf(event) });
+					break;
+				case "ShikiError":
+					both(BuildMetrics.shikiErrors, 1, { scope: scopeOf(event) });
 					break;
-				case "CodeBlockProcessed":
-					Effect.runSync(Metric.update(BuildMetrics.codeblockTotal, 1));
-					Effect.runSync(Metric.update(BuildMetrics.codeblockDuration, event.totalMs));
-					if (event.shikiMs > 0) Effect.runSync(Metric.update(BuildMetrics.codeblockShikiDuration, event.shikiMs));
-					if (event.slow) Effect.runSync(Metric.update(BuildMetrics.codeblockSlow, 1));
+				case "CodeBlockProcessed": {
+					const attrs = {
+						scope: event.ctx.apiScope ?? "(unscoped)",
+						component: event.component,
+						twoslash: String(event.twoslash)
+					};
+					const tagged = (metric) => Metric.withAttributes(metric, attrs);
+					update(BuildMetrics.codeblockTotal, 1);
+					update(tagged(BuildMetrics.codeblockTotal), 1);
+					update(BuildMetrics.codeblockDuration, event.totalMs);
+					update(BuildMetrics.codeblockTimeMs, event.totalMs);
+					update(tagged(BuildMetrics.codeblockTimeMs), event.totalMs);
+					update(BuildMetrics.codeblockTwoslashMs, event.twoslashMs);
+					update(tagged(BuildMetrics.codeblockTwoslashMs), event.twoslashMs);
+					update(BuildMetrics.codeblockShikiMs, event.shikiMs);
+					update(tagged(BuildMetrics.codeblockShikiMs), event.shikiMs);
+					if (event.twoslash) {
+						update(BuildMetrics.codeblockTwoslashTotal, 1);
+						update(tagged(BuildMetrics.codeblockTwoslashTotal), 1);
+					}
+					if (event.shikiMs > 0) update(BuildMetrics.codeblockShikiDuration, event.shikiMs);
+					if (event.slow) {
+						update(BuildMetrics.codeblockSlow, 1);
+						update(tagged(BuildMetrics.codeblockSlow), 1);
+					}
 					break;
+				}
 				case "VfsGenerated":
-					Effect.runSync(Metric.update(BuildMetrics.vfsFiles, 1));
+					update(BuildMetrics.vfsFiles, 1);
 					break;
 				case "ImportsPrepended":
-					Effect.runSync(Metric.update(BuildMetrics.importsPrepended, 1));
+					update(BuildMetrics.importsPrepended, 1);
 					break;
 				case "PhaseCompleted":
-					Effect.runSync(Metric.update(BuildMetrics.phaseDuration, event.durationMs));
+					update(BuildMetrics.phaseDuration, event.durationMs);
+					both(BuildMetrics.phaseTimeMs, event.durationMs, { phase: event.phase });
 					break;
-				case "DefaultApplied": Effect.runSync(Metric.update(BuildMetrics.configDefaultsApplied, 1));
+				case "DefaultApplied": update(BuildMetrics.configDefaultsApplied, 1);
 			}
 		}
 	};

package/observability/sinks/render-sink.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { Effect, FileSystem } from "effect";
+
+//#region src/observability/sinks/render-sink.ts
+const UNSCOPED = "(unscoped)";
+/** How many of the slowest blocks the artifact retains. */
+const SLOWEST_LIMIT = 25;
+function makeRenderSink() {
+	let firstAt = 0;
+	let lastAt = 0;
+	const byFile = /* @__PURE__ */ new Map();
+	const slowest = [];
+	return {
+		minLevel: "trace",
+		handle(event) {
+			if (event._tag !== "CodeBlockProcessed") return;
+			const now = performance.now();
+			if (firstAt === 0) firstAt = now;
+			lastAt = now;
+			const sample = {
+				apiScope: event.ctx.apiScope ?? UNSCOPED,
+				file: event.ctx.file ?? "unknown",
+				component: event.component,
+				totalMs: event.totalMs,
+				twoslashMs: event.twoslashMs,
+				shikiMs: event.shikiMs
+			};
+			const current = byFile.get(sample.file) ?? {
+				blocks: 0,
+				twoslashBlocks: 0,
+				totalMs: 0,
+				twoslashMs: 0
+			};
+			byFile.set(sample.file, {
+				blocks: current.blocks + 1,
+				twoslashBlocks: current.twoslashBlocks + (event.twoslash ? 1 : 0),
+				totalMs: current.totalMs + sample.totalMs,
+				twoslashMs: current.twoslashMs + sample.twoslashMs
+			});
+			if (slowest.length < SLOWEST_LIMIT || sample.totalMs > (slowest.at(-1)?.totalMs ?? 0)) {
+				const at = slowest.findIndex((s) => s.totalMs < sample.totalMs);
+				slowest.splice(at === -1 ? slowest.length : at, 0, sample);
+				if (slowest.length > SLOWEST_LIMIT) slowest.length = SLOWEST_LIMIT;
+			}
+		},
+		snapshot() {
+			return {
+				wallMs: firstAt === 0 ? 0 : lastAt - firstAt,
+				byFile: Object.fromEntries(byFile),
+				slowest: [...slowest]
+			};
+		}
+	};
+}
+/**
+* Write the render-phase attribution artifact to
+* `<cwd>/.api-docs/build/render-phase.json`, combining the metric-derived
+* rollups with the sample-shaped per-file and slowest-block data.
+*
+* Writes nothing when no code block was processed, so a build that never
+* reached the render phase does not leave an empty artifact behind.
+*/
+function writeRenderPhaseJson(report, samples, opts) {
+	return Effect.gen(function* () {
+		if (report.overall.blocks === 0) return;
+		const fs = yield* FileSystem.FileSystem;
+		const dir = path.join(opts.cwd, ".api-docs", "build");
+		yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.ignore);
+		const doc = {
+			generatedAt: opts.generatedAt,
+			package: opts.packageName,
+			target: "prod",
+			overall: report.overall,
+			wallMs: samples.wallMs,
+			byScope: report.byScope,
+			byComponent: report.byComponent,
+			series: report.series,
+			byFile: samples.byFile,
+			slowest: samples.slowest
+		};
+		yield* fs.writeFileString(path.join(dir, "render-phase.json"), `${JSON.stringify(doc, null, 2)}\n`).pipe(Effect.ignore);
+	});
+}
+
+//#endregion
+export { makeRenderSink, writeRenderPhaseJson };

package/observability/sinks/trace-sink.js

@@ -7,30 +7,23 @@ function openTracePath(p) {
 	fs.writeFileSync(p, "");
 }
 /**
-* Create a JSONL trace sink.
+* Create a JSONL trace sink, opening the file eagerly at construction.
 *
-* When `initialPath` is provided the file is opened eagerly at construction
-* (existing behaviour for an explicit `trace: "/some/path"` config).
-* When omitted the sink starts in deferred mode — events are silently dropped
-* until `setPath` is called.  This lets `plugin.ts` create the sink before
-* the RSPress `outDir` is known and then bind the real path in the `config()`
-* hook once `_config.outDir` is available.
+* The path is always known up front: `resolveObservability` derives it from
+* `cwd`, which (unlike the RSPress `outDir`) is available at plugin-factory
+* time. The sink previously supported a deferred mode — construct with no path,
+* bind one later via `setPath` — for the era when the path depended on
+* `outDir`; nothing has called it since, so it is gone.
 */
-function makeTraceSink(initialPath) {
-	let currentPath = initialPath ?? null;
-	if (currentPath) openTracePath(currentPath);
+function makeTraceSink(tracePath) {
+	openTracePath(tracePath);
 	return {
 		minLevel: "trace",
 		capturesPayload: true,
 		handle: (event) => {
-			if (!currentPath) return;
-			fs.appendFileSync(currentPath, `${JSON.stringify(event)}\n`);
+			fs.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
 		},
-		flush: () => {},
-		setPath: (p) => {
-			currentPath = p;
-			openTracePath(p);
-		}
+		flush: () => {}
 	};
 }
 

package/observability/spans.js

@@ -54,4 +54,4 @@ function withPhase(phase, ctx, effect, thresholds) {
 }
 
 //#endregion
-export { PHASE_THRESHOLD_KEY, withPhase };
+export { withPhase };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.9.2",
+	"version": "0.10.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -42,7 +42,7 @@
 		"@effected/glob": "^0.4.0",
 		"@effected/jsonc": "^0.8.0",
 		"@effected/markdown": "^0.7.0",
-		"@effected/npm": "^0.12.0",
+		"@effected/npm": "^0.12.1",
 		"@effected/package-json": "^0.12.0",
 		"@effected/semver": "^0.5.0",
 		"@effected/store": "^0.5.0",
@@ -54,7 +54,7 @@
 		"@shikijs/twoslash": "^4.4.3",
 		"@tsdoctor/bundle": "0.2.0",
 		"@tsdoctor/model": "0.2.2",
-		"@tsdoctor/registry": "0.2.0",
+		"@tsdoctor/registry": "0.2.1",
 		"@tsdoctor/snapshot": "0.1.1",
 		"@typescript/vfs": "^1.6.4",
 		"clsx": "^2.1.1",

package/plugin.js

@@ -1,7 +1,9 @@
 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";
@@ -17,8 +19,10 @@ 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";
@@ -83,10 +87,10 @@ function ApiExtractorPluginImpl(rawOptions) {
 		cwd: process.cwd(),
 		buildId
 	});
-	const { layer: eventBusLayer, trace: traceSink, issues: issuesSink } = buildEventBus(obs);
+	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, TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath), makeSummaryLoggerLayer(obs.logLevel));
+	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);
@@ -95,8 +99,13 @@ function ApiExtractorPluginImpl(rawOptions) {
 	setPrettierEventEmitter(emitSync, buildId);
 	setOgResolverEventEmitter(emitSync, buildId);
 	setRemarkWithApiEventEmitter(emitSync, buildId, obs.thresholds.slowCodeBlock);
-	setRemarkApiCodeblocksEventEmitter(emitSync, buildId);
+	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 fileContextMap = /* @__PURE__ */ new Map();
 	let docsRoot;
 	let isFirstBuild = true;
@@ -110,13 +119,37 @@ function ApiExtractorPluginImpl(rawOptions) {
 		async beforeBuild(_config, _isProd) {},
 		async afterBuild(_config, isProd) {
 			if (isFirstBuild && !isInert) {
-				await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock));
+				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(logBuildSummary(obs.thresholds.slowCodeBlock, report));
 				if (isProd) await effectRuntime.runPromise(Effect.gen(function* () {
 					const packageName = yield* readSitePackageName;
+					const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
 					yield* writeIssuesJson(issuesSink.snapshot(), {
 						cwd: process.cwd(),
 						packageName,
-						generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+						generatedAt
+					});
+					yield* writeRenderPhaseJson(report, renderSamples, {
+						cwd: process.cwd(),
+						packageName,
+						generatedAt
 					});
 				}));
 				if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled) {
@@ -205,6 +238,10 @@ function ApiExtractorPluginImpl(rawOptions) {
 						buildId
 					}));
 					const buildContext = yield* (yield* ConfigService).resolve(rspressConfigSubset);
+					twoslashCacheHandle = {
+						cache: buildContext.twoslashCache,
+						envHash: buildContext.twoslashEnvHash
+					};
 					buildResults.length = 0;
 					yield* Ref.set(phaseRef, "generate");
 					yield* Effect.forEach(buildContext.apiConfigs, (apiConfig) => generateApiDocs({
@@ -271,7 +308,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 			const remarkTheme = normalizeThemeConfig(options.api?.theme ?? options.apis?.[0]?.theme);
 			updatedConfig.markdown.remarkPlugins.push([remarkWithApi, {
 				shikiCrossLinker,
-				getTransformer: () => TwoslashManager.getInstance().getTransformer(),
+				getTransformer: (apiScope) => TwoslashManager.getInstance().getTransformer(apiScope),
 				theme: remarkTheme
 			}]);
 			updatedConfig.markdown.remarkPlugins.push([remarkApiCodeblocks]);

package/remark-api-codeblocks.js

@@ -2,15 +2,18 @@ import { PluginEvent } from "./observability/events.js";
 import { TwoslashManager } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateShikiHast } from "./markdown/shiki-utils.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 = "";
-function setRemarkApiCodeblocksEventEmitter(fn, buildId = "") {
+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.
@@ -123,14 +126,37 @@ const remarkApiCodeblocks = () => {
 					return;
 				}
 				const transformers = [];
-				if (node.name === "ApiExample" && vfsConfig.twoslashTransformer) transformers.push(vfsConfig.twoslashTransformer);
+				let twoslashMs = 0;
+				if (node.name === "ApiExample" && vfsConfig.twoslashTransformer) transformers.push(createTwoslashTimingWrapper(vfsConfig.twoslashTransformer, (duration) => {
+					twoslashMs += duration;
+				}));
 				else if (node.name === "ApiMember" && vfsConfig.hideCutTransformer) transformers.push(vfsConfig.hideCutTransformer);
 				else if (node.name === "ApiSignature") {
 					if (vfsConfig.hideCutLinesTransformer) transformers.push(vfsConfig.hideCutLinesTransformer);
 				}
 				const isExample = node.name === "ApiExample" && !!vfsConfig.twoslashTransformer;
-				let hast = await generateShikiHast(source, vfsConfig.highlighter, transformers.length > 0 ? transformers : void 0, isExample, vfsConfig.theme);
+				const shikiStart = performance.now();
+				const hastPromise = generateShikiHast(source, vfsConfig.highlighter, transformers.length > 0 ? transformers : void 0, isExample, vfsConfig.theme);
+				const renderMs = performance.now() - shikiStart;
+				let hast = await hastPromise;
+				const postStart = performance.now();
 				if (hast && vfsConfig.crossLinker) hast = vfsConfig.crossLinker.transformHast(hast, apiScopeValue);
+				const totalBlockTime = renderMs + (performance.now() - postStart);
+				emitEvent(PluginEvent.CodeBlockProcessed({
+					ctx: {
+						buildId: currentBuildId,
+						apiScope: apiScopeValue,
+						file: currentFilePath
+					},
+					lang: "typescript",
+					component: node.name,
+					twoslash: isExample,
+					twoslashMs,
+					shikiMs: Math.max(0, renderMs - twoslashMs),
+					totalMs: totalBlockTime,
+					slow: totalBlockTime > currentSlowCodeBlockMs,
+					level: "debug"
+				}));
 				const hastBase64 = hast ? Buffer.from(JSON.stringify(hast), "utf-8").toString("base64") : "";
 				node.attributes.push({
 					type: "mdxJsxAttribute",

package/remark-with-api.js

@@ -3,6 +3,7 @@ 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 { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { codeToHast, hastToHtml } from "shiki";
 import { visit } from "unist-util-visit";
 
@@ -78,9 +79,13 @@ const remarkWithApi = (options) => {
 			const promise = (async () => {
 				const blockStart = performance.now();
 				const rawCode = node.value;
+				const apiScope = currentFilePath ? inferApiScope(currentFilePath) : void 0;
 				const code = (await formatCode(rawCode, lang)).code;
-				const twoslashTransformer = getTransformer();
-				const transformers = twoslashTransformer ? [twoslashTransformer] : [];
+				let twoslashMs = 0;
+				const twoslashTransformer = getTransformer(apiScope);
+				const transformers = twoslashTransformer ? [createTwoslashTimingWrapper(twoslashTransformer, (duration) => {
+					twoslashMs += duration;
+				})] : [];
 				const shikiStart = performance.now();
 				let hast = await codeToHast(code, {
 					lang,
@@ -93,19 +98,21 @@ const remarkWithApi = (options) => {
 					cssVariablePrefix: "--api-shiki-",
 					transformers
 				});
-				const apiScope = currentFilePath ? inferApiScope(currentFilePath) : void 0;
+				const renderMs = performance.now() - shikiStart;
 				if (apiScope) hast = shikiCrossLinker.transformHast(hast, apiScope);
-				const shikiTime = performance.now() - shikiStart;
 				const totalBlockTime = performance.now() - blockStart;
 				const isSlow = totalBlockTime > currentSlowCodeBlockMs;
 				emitEvent(PluginEvent.CodeBlockProcessed({
 					ctx: {
 						buildId: currentBuildId,
+						...apiScope != null ? { apiScope } : {},
 						...currentFilePath != null ? { file: currentFilePath } : {}
 					},
 					lang,
-					shikiMs: shikiTime,
-					twoslashMs: totalBlockTime - shikiTime,
+					component: "with-api",
+					twoslash: twoslashTransformer != null,
+					twoslashMs,
+					shikiMs: Math.max(0, renderMs - twoslashMs),
 					totalMs: totalBlockTime,
 					slow: isSlow,
 					level: "debug"

package/schemas/config.js

@@ -273,15 +273,19 @@ const MultiApiConfig = Schema.Struct({
 	* Path to a `tsconfig.json` for Twoslash.
 	*
 	* @remarks
-	* Twoslash runs against a single shared TypeScript environment for the
-	* whole build, so per-API tsconfigs are not honored in multi-API mode:
-	* the first API that provides one wins and the rest are ignored (a
-	* `ConfigCascadeWarning` is emitted when they differ). Ensure the
-	* configured tsconfigs are equivalent, or set the intended one on the
-	* first API only.
+	* This API's code blocks are type-checked under this config. APIs that
+	* declare the same config share one TypeScript environment; the file set
+	* is shared across all documented APIs either way, so a type owned by
+	* another documented package still resolves.
 	*/
 	tsconfig: Schema.optional(ModelInput),
-	/** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+	/**
+	* TypeScript compiler options for Twoslash, applying to this API only.
+	*
+	* @remarks
+	* Merged on top of the defaults and of this API's `tsconfig`, so declaring
+	* a single option overrides just that one.
+	*/
 	compilerOptions: Schema.optional(Schema.Unknown)
 });
 /**

package/services/TwoslashCacheService.js

@@ -0,0 +1,15 @@
+import { Context } from "effect";
+
+//#region src/services/TwoslashCacheService.ts
+/**
+* Persistence for the Twoslash result cache.
+*
+* Split from the synchronous cache object (`twoslash-cache.ts`) because
+* `TwoslashTypesCache.read`/`write` are called from inside Shiki's `preprocess`
+* hook and cannot await: the service loads once before the render phase and
+* saves once after it, while every lookup in between is a synchronous map hit.
+*/
+var TwoslashCacheService = class extends Context.Service()("rspress-plugin-api-extractor/TwoslashCacheService") {};
+
+//#endregion
+export { TwoslashCacheService };

package/shiki-transformer.js

@@ -35,13 +35,9 @@
 * const crossLinker = new ShikiCrossLinker();
 * crossLinker.reinitialize(routes, kinds, "my-api");
 * crossLinker.setApiScope("my-api");
-* const transformer = crossLinker.createTransformer();
 *
-* // Use with Shiki
-* const html = await codeToHtml(code, {
-*   lang: "typescript",
-*   transformers: [transformer]
-* });
+* // Cross-link the finalized HAST, after Shiki and Twoslash have run
+* const linked = crossLinker.transformHast(hast, "my-api");
 * ```
 *
 * @see the `@tsdoctor/model` CrossLinker for the markdown equivalent
@@ -142,22 +138,6 @@ var ShikiCrossLinker = class {
 		return this.classMembersMapByScope.get(scope) || /* @__PURE__ */ new Map();
 	}
 	/**
-	* Create a Shiki transformer that adds cross-links to type references in code blocks.
-	*
-	* **DEPRECATED:** This method now returns a no-op transformer. Cross-linking has been
-	* moved to post-processing via {@link transformHast} to avoid interfering with Twoslash
-	* popup positioning. The Twoslash transformer calculates popup positions based on the
-	* original span structure, and modifying spans during the Shiki pipeline caused popups
-	* to appear offset from their intended positions.
-	*
-	* @param _apiScope - Unused, kept for API compatibility
-	* @returns A no-op Shiki transformer
-	* @deprecated Use {@link transformHast} after Shiki processing completes instead
-	*/
-	createTransformer(_apiScope) {
-		return { name: "api-docs-cross-linker" };
-	}
-	/**
 	* Transform a finalized HAST tree to add cross-links to type references.
 	*
 	* This method should be called AFTER Shiki (including Twoslash) has fully processed