rspress-plugin-api-extractor 0.13.3 → 0.15.0

package/schemas/config.js

@@ -1,4 +1,3 @@
-import { PerformanceConfig } from "./performance.js";
 import { ObservabilityConfig } from "./observability.js";
 import { Effect, Schema } from "effect";
 import { OpenGraphImageConfig } from "@tsdoctor/seo";
@@ -10,24 +9,9 @@ import { ApiItemKind } from "@microsoft/api-extractor-model";
 * an async loader function, or a URL.
 */
 const ModelInput = Schema.declare((input) => typeof input === "string" || typeof input === "function" || input instanceof URL);
-/**
-* Verbosity level for plugin build output.
-*
-* @public
-*/
-const LogLevel = Schema.Literals([
-	"none",
-	"info",
-	"verbose",
-	"debug",
-	"warn",
-	"error"
-]);
 const ExternalPackageSpec = Schema.Struct({
 	name: Schema.String,
-	version: Schema.String,
-	tsconfig: Schema.optional(ModelInput),
-	compilerOptions: Schema.optional(Schema.Unknown)
+	version: Schema.String
 });
 const AutoDetectDependencies = Schema.Struct({
 	dependencies: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
@@ -68,8 +52,6 @@ const CategoryConfig = Schema.Struct({
 	folderName: Schema.String,
 	/** API item kinds included in this category. */
 	itemKinds: Schema.optional(Schema.mutable(Schema.Array(ApiItemKindSchema))),
-	/** TSDoc modifier tag that marks items for this category. */
-	tsdocModifier: Schema.optional(Schema.String),
 	/** Whether the sidebar section is collapsible. Defaults to `true`. */
 	collapsible: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
 	/** Whether the sidebar section starts collapsed. Defaults to `true`. */
@@ -190,11 +172,7 @@ const VersionConfig = Schema.Struct({
 	/** Open Graph image configuration for this version. */
 	ogImage: Schema.optional(OpenGraphImageConfig),
 	/** LLMs integration options for this version. */
-	llmsPlugin: Schema.optional(LlmsPlugin),
-	/** Path to a `tsconfig.json` for this version. */
-	tsconfig: Schema.optional(ModelInput),
-	/** TypeScript compiler options for Twoslash. */
-	compilerOptions: Schema.optional(Schema.Unknown)
+	llmsPlugin: Schema.optional(LlmsPlugin)
 });
 /** Union for the versions record value: can be a path/function OR a full VersionConfig */
 const VersionValue = Schema.Union([ModelInput, VersionConfig]);
@@ -312,13 +290,9 @@ const PluginOptions = Schema.Struct({
 	errors: Schema.optional(ErrorConfig),
 	/** LLMs integration options, or `false` to disable. */
 	llmsPlugin: Schema.optional(Schema.Union([Schema.Boolean, LlmsPlugin])),
-	/** Verbosity level for plugin build output. @deprecated Use `observability.logLevel`. */
-	logLevel: Schema.optional(LogLevel),
-	/** Performance tuning options. @deprecated Use `observability.thresholds`. */
-	performance: Schema.optional(PerformanceConfig),
 	/** Unified observability configuration (logLevel, trace artifact, thresholds). */
 	observability: Schema.optional(ObservabilityConfig)
 });
 
 //#endregion
-export { AutoDetectDependencies, CategoryConfig, DEFAULT_CATEGORIES, ErrorConfig, ExternalPackageSpec, LlmsPlugin, LogLevel, ModelInput, MultiApiConfig, PluginOptions, SingleApiConfig, SourceConfig, ThemeConfig, VersionConfig };
+export { AutoDetectDependencies, CategoryConfig, DEFAULT_CATEGORIES, ErrorConfig, ExternalPackageSpec, LlmsPlugin, ModelInput, MultiApiConfig, PluginOptions, SingleApiConfig, SourceConfig, ThemeConfig, VersionConfig };

package/schemas/observability.js

@@ -22,7 +22,6 @@ const DEFAULT_THRESHOLDS = {
 	slowPageGeneration: 500,
 	slowApiLoad: 1e3,
 	slowFileOperation: 50,
-	slowHttpRequest: 2e3,
 	slowDbOperation: 100
 };
 function normalizeLevel(value) {
@@ -31,21 +30,11 @@ function normalizeLevel(value) {
 	return value;
 }
 function resolveObservability(input) {
-	const deprecations = [];
-	if (input.logLevel !== void 0) deprecations.push({
-		key: "logLevel",
-		replacement: "observability.logLevel"
-	});
-	if (input.performance !== void 0) deprecations.push({
-		key: "performance",
-		replacement: "observability.thresholds"
-	});
-	const level = normalizeLevel(input.envLogLevel) ?? normalizeLevel(input.observability?.logLevel) ?? normalizeLevel(input.logLevel) ?? "info";
+	const level = normalizeLevel(input.envLogLevel) ?? normalizeLevel(input.observability?.logLevel) ?? "info";
 	const traceOpt = input.observability?.trace;
 	const tracePath = typeof traceOpt === "string" ? traceOpt : traceOpt === true ? `${input.cwd}/.api-docs/build/trace-${input.buildId}.jsonl` : null;
 	const merged = {
 		...DEFAULT_THRESHOLDS,
-		...input.performance?.thresholds ?? {},
 		...input.observability?.thresholds ?? {}
 	};
 	const thresholds = {
@@ -53,22 +42,18 @@ function resolveObservability(input) {
 		slowPageGeneration: merged.slowPageGeneration ?? DEFAULT_THRESHOLDS.slowPageGeneration,
 		slowApiLoad: merged.slowApiLoad ?? DEFAULT_THRESHOLDS.slowApiLoad,
 		slowFileOperation: merged.slowFileOperation ?? DEFAULT_THRESHOLDS.slowFileOperation,
-		slowHttpRequest: merged.slowHttpRequest ?? DEFAULT_THRESHOLDS.slowHttpRequest,
 		slowDbOperation: merged.slowDbOperation ?? DEFAULT_THRESHOLDS.slowDbOperation
 	};
 	const pi = input.observability?.progressInterval;
 	const seconds = pi === false ? null : typeof pi === "number" ? pi : 10;
 	const progressIntervalMs = seconds !== null && Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : null;
-	return {
-		resolved: {
-			logLevel: level,
-			json: level === "debug",
-			tracePath,
-			progressIntervalMs,
-			thresholds
-		},
-		deprecations
-	};
+	return { resolved: {
+		logLevel: level,
+		json: level === "debug",
+		tracePath,
+		progressIntervalMs,
+		thresholds
+	} };
 }
 
 //#endregion

package/schemas/performance.js

@@ -6,14 +6,8 @@ const PerformanceThresholds = Schema.Struct({
 	slowPageGeneration: Schema.Number.pipe(Schema.withDecodingDefault(Effect.succeed(500))),
 	slowApiLoad: Schema.Number.pipe(Schema.withDecodingDefault(Effect.succeed(1e3))),
 	slowFileOperation: Schema.Number.pipe(Schema.withDecodingDefault(Effect.succeed(50))),
-	slowHttpRequest: Schema.Number.pipe(Schema.withDecodingDefault(Effect.succeed(2e3))),
 	slowDbOperation: Schema.Number.pipe(Schema.withDecodingDefault(Effect.succeed(100)))
 });
-const PerformanceConfig = Schema.Struct({
-	thresholds: Schema.optional(PerformanceThresholds),
-	showInsights: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
-	trackDetailedMetrics: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false)))
-});
 
 //#endregion
-export { PerformanceConfig, PerformanceThresholds };
+export { PerformanceThresholds };

package/services/TwoslashCacheService.js

@@ -1,6 +1,6 @@
 import { AppDirsLive, PlatformLive } from "../layers/xdg.js";
-import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
 import { Context, Effect, Layer, Option, Path } from "effect";
+import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "@tsdoctor/vfs";
 import { Cache } from "@effected/store";
 import { AppDirs } from "@effected/xdg";
 
@@ -20,23 +20,29 @@ var TwoslashCacheService = class TwoslashCacheService extends Context.Service()(
 	* @remarks
 	* Failure is absorbed at TWO levels, and both are load-bearing. Inside the
 	* service, a failed read or write degrades that one operation. Around the
-	* layer, a failed CONSTRUCTION — no HOME for XDG, an unwritable cache
-	* directory, a corrupt database — degrades to {@link DegradedLive}.
+	* cache layer, a failed CONSTRUCTION — no HOME for XDG, an unwritable cache
+	* directory, a corrupt database — degrades to a cache that always misses,
+	* via `Cache.degrading` (see {@link CacheLive}).
 	*
-	* The second is why `Layer.catchCause` wraps this at all. While the sqlite
-	* layer was provided inside each method, a construction failure surfaced as
-	* that method's failure and the in-method handler swallowed it. Hoisting
+	* The second is why anything wraps this at all. While the sqlite layer was
+	* provided inside each method, a construction failure surfaced as that
+	* method's failure and the in-method handler swallowed it. Hoisting
 	* acquisition to layer construction moved the failure to `ManagedRuntime`
 	* build time, where it would abort the entire build — breaking the contract
 	* this service documents, that an unreachable cache must never fail a build
-	* that would otherwise succeed. `catchCause` rather than a failure-only catch
-	* because a defect thrown by the sqlite driver must degrade too.
+	* that would otherwise succeed.
+	*
+	* There is no separate degraded implementation of this service any more.
+	* Degrading one level down, at the `Cache`, means the ordinary
+	* implementation running over an always-missing cache IS the degraded
+	* behaviour, so a second implementation would only be a way for the two to
+	* disagree.
 	*
 	* `Layer.suspend` because the composition below is declared after this class:
 	* a static initializer runs while the module body is still evaluating, so
 	* naming those consts directly throws at import time with a clean typecheck.
 	*/
-	static layer = Layer.suspend(() => CacheBackedLive.pipe(Layer.catchCause(() => DegradedLive)));
+	static layer = Layer.suspend(() => CacheBackedLive);
 	/**
 	* An always-cold in-memory double.
 	*
@@ -50,6 +56,7 @@ var TwoslashCacheService = class TwoslashCacheService extends Context.Service()(
 	* the render path's SHAPE rather than merely dropping its persistence.
 	*/
 	static makeTest = (overrides = {}) => ({
+		degraded: overrides.degraded ?? false,
 		load: overrides.load ?? (() => Effect.succeed(/* @__PURE__ */ new Map())),
 		save: overrides.save ?? (() => Effect.void),
 		open: overrides.open ?? (() => Effect.succeed(makeTwoslashCache())),
@@ -117,6 +124,7 @@ function withGeneration(base) {
 const CacheBackedLive = Layer.effect(TwoslashCacheService, Effect.gen(function* () {
 	const cache = yield* Cache;
 	return withGeneration({
+		degraded: cache.degraded,
 		load: (envHash) => cache.get(twoslashBlobKey(envHash)).pipe(Effect.map((entry) => Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map()), Effect.catch(() => Effect.succeed(/* @__PURE__ */ new Map()))),
 		save: (envHash, entries) => cache.set({
 			key: twoslashBlobKey(envHash),
@@ -124,7 +132,7 @@ const CacheBackedLive = Layer.effect(TwoslashCacheService, Effect.gen(function*
 			tags: ["twoslash"]
 		}).pipe(Effect.catch(() => Effect.void))
 	});
-})).pipe(Layer.provide(CacheLive));
+})).pipe(Layer.provide(Cache.degrading(CacheLive)));
 /**
 * A cache that holds nothing, for when the real one cannot be opened.
 *
@@ -132,10 +140,6 @@ const CacheBackedLive = Layer.effect(TwoslashCacheService, Effect.gen(function*
 * `load` returns empty and `save` discards, which is precisely the behaviour
 * before this cache existed: type-check everything, persist nothing.
 */
-const DegradedLive = Layer.succeed(TwoslashCacheService, withGeneration({
-	load: () => Effect.succeed(/* @__PURE__ */ new Map()),
-	save: () => Effect.void
-}));
 
 //#endregion
 export { TwoslashCacheService };

package/services/TypeRegistryService.js

@@ -3,11 +3,11 @@ import { emit } from "../observability/EventBus.js";
 import { resolveExternalPackageVersions } from "../config-utils.js";
 import { TypeRegistryError } from "../errors.js";
 import { AppDirsLive, PlatformLive } from "../layers/xdg.js";
-import { Context, Duration, Effect, Layer, Path } from "effect";
+import { Cause, Context, Duration, Effect, Layer, Path } from "effect";
 import { NodeHttpClient } from "@effect/platform-node";
-import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
 import { Cache } from "@effected/store";
 import { AppDirs } from "@effected/xdg";
+import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
 
 //#region src/services/TypeRegistryService.ts
 var TypeRegistryService = class TypeRegistryService extends Context.Service()("rspress-plugin-api-extractor/TypeRegistryService") {
@@ -27,7 +27,7 @@ var TypeRegistryService = class TypeRegistryService extends Context.Service()("r
 	* static initializer runs while the module body is still evaluating, so naming
 	* those consts directly throws at import time with a clean typecheck.
 	*/
-	static layer = Layer.suspend(() => RegistryBackedLive.pipe(Layer.catchCause(() => DegradedLive)));
+	static layer = Layer.suspend(() => RegistryBackedLive.pipe(Layer.catchCause((cause) => Cause.hasInterrupts(cause) ? Layer.effectContext(Effect.failCause(Cause.interrupt([...Cause.interruptors(cause)][0]))) : DegradedLive)));
 	/**
 	* An in-memory double: no network, no XDG cache, no sqlite.
 	*
@@ -132,7 +132,7 @@ const MetadataCacheLive = Layer.unwrap(Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const cacheDir = yield* appDirs.ensureCache;
 	return Cache.layerSqlite({ filename: path.join(cacheDir, "metadata.sqlite") });
-})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)));
+})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)), Cache.degrading);
 /**
 * The full registry runtime: TypeRegistry over an XDG-rooted TypeCache and the
 * jsDelivr PackageFetcher, with the observer that forwards registry events to

package/shiki-transformer.js

@@ -33,7 +33,7 @@
 * @example Basic usage
 * ```ts
 * const crossLinker = new ShikiCrossLinker();
-* crossLinker.reinitialize(routes, kinds, "my-api");
+* const crossLinker = ShikiCrossLinker.fromRoutes(routes, "my-api");
 * crossLinker.setApiScope("my-api");
 *
 * // Cross-link the finalized HAST, after Shiki and Twoslash have run
@@ -46,16 +46,13 @@
 var ShikiCrossLinker = class ShikiCrossLinker {
 	/** API item name to route, for THIS scope. */
 	apiItemRoutes;
-	/** API item name to kind (Class, Interface, …), for THIS scope. */
-	apiItemKinds;
 	/** Parent name to its member names, longest first, for THIS scope. */
 	classMembersMap;
 	/** The scope this linker links for. Read-only after construction. */
 	apiScope;
-	constructor(apiScope, apiItemRoutes, apiItemKinds, classMembersMap) {
+	constructor(apiScope, apiItemRoutes, classMembersMap) {
 		this.apiScope = apiScope;
 		this.apiItemRoutes = apiItemRoutes;
-		this.apiItemKinds = apiItemKinds;
 		this.classMembersMap = classMembersMap;
 	}
 	/**
@@ -74,7 +71,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	* property of the instance, which cannot be pointed at another package's
 	* routes at all.
 	*/
-	static fromRoutes(routes, kinds, apiScope) {
+	static fromRoutes(routes, apiScope) {
 		const classMembersMap = /* @__PURE__ */ new Map();
 		for (const [name] of routes.entries()) {
 			const dotIndex = name.indexOf(".");
@@ -86,10 +83,10 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 			else if (!members.includes(memberName)) members.push(memberName);
 		}
 		for (const members of classMembersMap.values()) members.sort((a, b) => b.length - a.length);
-		return new ShikiCrossLinker(apiScope, new Map(routes), new Map(kinds), classMembersMap);
+		return new ShikiCrossLinker(apiScope, new Map(routes), classMembersMap);
 	}
 	/** A linker that links nothing — for a scope with no documented routes. */
-	static empty = new ShikiCrossLinker("", /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
+	static empty = new ShikiCrossLinker("", /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
 	/**
 	* Transform a finalized HAST tree to add cross-links to type references.
 	*
@@ -118,7 +115,6 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	}
 	transformRoot(node) {
 		const apiItemRoutes = this.apiItemRoutes;
-		const apiItemKinds = this.apiItemKinds;
 		const classMembersMap = this.classMembersMap;
 		const scopeStack = [];
 		const preElement = node.children.find((child) => child.type === "element" && child.tagName === "pre");
@@ -148,12 +144,9 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 						const fullMemberName = `${currentScope}.${content}`;
 						const memberRoute = apiItemRoutes.get(fullMemberName);
 						if (memberRoute) {
-							const memberKind = apiItemKinds.get(fullMemberName);
-							const memberSemanticClass = memberKind ? this.getSemanticClass(memberKind) : null;
 							const leadingSpace = rawContent.match(/^\s*/)?.[0] || "";
 							const trailingSpace = rawContent.match(/\s*$/)?.[0] || "";
 							const classNames = ["api-type-link"];
-							if (memberSemanticClass) classNames.push(memberSemanticClass);
 							const newChildren = [];
 							if (leadingSpace) newChildren.push({
 								type: "text",
@@ -209,10 +202,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 			const fullMemberName = `${className}.${methodName}`;
 			const memberRoute = apiItemRoutes.get(fullMemberName);
 			if (!memberRoute) continue;
-			const memberKind = apiItemKinds.get(fullMemberName);
-			const memberSemanticClass = memberKind ? this.getSemanticClass(memberKind) : null;
 			const memberClassNames = ["api-type-link"];
-			if (memberSemanticClass) memberClassNames.push(memberSemanticClass);
 			const textContent = this.extractTextFromTwoslash(twoslashSpan);
 			if (!textContent) continue;
 			this.wrapTwoslashTextInAnchor(twoslashSpan, textContent.trim(), memberRoute, memberClassNames);
@@ -230,11 +220,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 				const content = text.trim();
 				const route = apiItemRoutes.get(content);
 				if (!route) continue;
-				const kind = apiItemKinds.get(content);
-				const semanticClass = kind ? this.getSemanticClass(kind) : null;
-				const classNames = ["api-type-link"];
-				if (semanticClass) classNames.push(semanticClass);
-				this.wrapTwoslashTextInAnchor(twoslashSpan, content, route, classNames);
+				this.wrapTwoslashTextInAnchor(twoslashSpan, content, route, ["api-type-link"]);
 				twoslashSpan.properties = {
 					...twoslashSpan.properties,
 					"data-api-processed": "true"
@@ -244,7 +230,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 			const typePattern = new RegExp(`\\b(${escapedNames.join("|")})\\b`, "g");
 			for (const lineElement of codeElement.children) {
 				if (lineElement.type !== "element" || lineElement.tagName !== "span") continue;
-				this.linkTypeReferencesInLine(lineElement, typePattern, apiItemRoutes, apiItemKinds);
+				this.linkTypeReferencesInLine(lineElement, typePattern, apiItemRoutes);
 			}
 		}
 		return node;
@@ -254,7 +240,6 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	*/
 	transformLine(node) {
 		const apiItemRoutes = this.apiItemRoutes;
-		const apiItemKinds = this.apiItemKinds;
 		const classMembersMap = this.classMembersMap;
 		if (!node.children) return;
 		for (let i = 0; i < node.children.length; i++) {
@@ -290,10 +275,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 			const fullMemberName = `${trimmedContent}.${matchedMember}`;
 			const memberRoute = apiItemRoutes.get(fullMemberName);
 			if (!memberRoute) continue;
-			const memberKind = apiItemKinds.get(fullMemberName);
-			const memberSemanticClass = memberKind ? this.getSemanticClass(memberKind) : null;
 			const memberClassNames = ["api-type-link"];
-			if (memberSemanticClass) memberClassNames.push(memberSemanticClass);
 			if (methodSpan.properties?.class && String(methodSpan.properties.class).includes("twoslash-hover")) this.wrapTwoslashTextInAnchor(methodSpan, methodText.trim(), memberRoute, memberClassNames);
 			else {
 				const textNode = methodSpan.children.find((c) => c.type === "text");
@@ -341,7 +323,6 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	*/
 	transformSpan(node, _line, _col) {
 		const apiItemRoutes = this.apiItemRoutes;
-		const apiItemKinds = this.apiItemKinds;
 		if (node.properties?.["data-api-processed"] === "true") return;
 		const firstChild = node.children?.[0];
 		if (firstChild && firstChild.type === "element" && firstChild.tagName === "a") return;
@@ -352,11 +333,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 			if (!content) return;
 			const route = apiItemRoutes.get(content);
 			if (route) {
-				const kind = apiItemKinds.get(content);
-				const semanticClass = kind ? this.getSemanticClass(kind) : null;
-				const classNames = ["api-type-link", "rp-link"];
-				if (semanticClass) classNames.push(semanticClass);
-				this.wrapTwoslashTextInAnchor(firstChild, content, route, classNames);
+				this.wrapTwoslashTextInAnchor(firstChild, content, route, ["api-type-link", "rp-link"]);
 				node.properties = {
 					...node.properties,
 					"data-api-processed": "true"
@@ -371,12 +348,9 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 		if (!content) return;
 		const route = apiItemRoutes.get(content);
 		if (route) {
-			const kind = apiItemKinds.get(content);
-			const semanticClass = kind ? this.getSemanticClass(kind) : null;
 			const leadingSpace = rawContent.match(/^\s*/)?.[0] || "";
 			const trailingSpace = rawContent.match(/\s*$/)?.[0] || "";
 			const classNames = ["api-type-link", "rp-link"];
-			if (semanticClass) classNames.push(semanticClass);
 			const newChildren = [];
 			if (leadingSpace) newChildren.push({
 				type: "text",
@@ -470,7 +444,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	* Iterates child spans, skipping already-processed and Twoslash-containing spans,
 	* and splits text nodes at type name boundaries.
 	*/
-	linkTypeReferencesInLine(lineElement, typePattern, apiItemRoutes, apiItemKinds) {
+	linkTypeReferencesInLine(lineElement, typePattern, apiItemRoutes) {
 		for (const child of lineElement.children) {
 			if (child.type !== "element" || child.tagName !== "span") continue;
 			if (child.properties?.["data-api-processed"] === "true") continue;
@@ -482,7 +456,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 					newChildren.push(textChild);
 					continue;
 				}
-				const fragments = this.splitTextAtTypeReferences(textChild.value, typePattern, apiItemRoutes, apiItemKinds);
+				const fragments = this.splitTextAtTypeReferences(textChild.value, typePattern, apiItemRoutes);
 				if (fragments.length === 1 && fragments[0].type === "text") newChildren.push(textChild);
 				else {
 					newChildren.push(...fragments);
@@ -502,7 +476,7 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 	* Split a text string at type reference boundaries, returning an array of
 	* text nodes and anchor elements for matched type names.
 	*/
-	splitTextAtTypeReferences(text, typePattern, apiItemRoutes, apiItemKinds) {
+	splitTextAtTypeReferences(text, typePattern, apiItemRoutes) {
 		typePattern.lastIndex = 0;
 		const result = [];
 		let lastIndex = 0;
@@ -514,16 +488,12 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 				type: "text",
 				value: text.slice(lastIndex, match.index)
 			});
-			const kind = apiItemKinds.get(matchedName);
-			const semanticClass = kind ? this.getSemanticClass(kind) : null;
-			const classNames = ["api-type-link"];
-			if (semanticClass) classNames.push(semanticClass);
 			result.push({
 				type: "element",
 				tagName: "a",
 				properties: {
 					href: route,
-					class: classNames.join(" ")
+					class: ["api-type-link"].join(" ")
 				},
 				children: [{
 					type: "text",
@@ -542,15 +512,6 @@ var ShikiCrossLinker = class ShikiCrossLinker {
 		});
 		return result;
 	}
-	/**
-	* Get the semantic CSS class name for an API item kind.
-	*
-	* @deprecated Semantic token colors are now handled by Shiki's theme CSS variables.
-	* This method always returns null - only api-type-link is used for underline styling.
-	*/
-	getSemanticClass(_kind) {
-		return null;
-	}
 };
 
 //#endregion

package/twoslash-transformer.js

@@ -1,19 +1,18 @@
 import { PluginEvent } from "./observability/events.js";
 import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
-import { DEFAULT_COMPILER_OPTIONS } from "./typescript-config.js";
 import { Result } from "effect";
 import { Markdown, Mdast } from "@effected/markdown";
-import { TsEnumCodec } from "@effected/tsconfig-json";
 import { rendererRich, transformerTwoslash } from "@shikijs/twoslash";
+import { DEFAULT_COMPILER_OPTIONS, toProgrammaticCompilerOptions } from "@tsdoctor/vfs";
 import { toHast } from "mdast-util-to-hast";
 
 //#region src/twoslash-transformer.ts
 /* v8 ignore start -- Shiki/Twoslash integration, requires full highlighter setup for testing */
 /**
 * Module-level type routes map for resolving link references.
-* This is set by TwoslashManager.setTypeRoutes() before initialization.
+* Populated per build by `addTypeRoutes` and reset by `clearTypeRoutes`.
 */
-let typeRoutes = /* @__PURE__ */ new Map();
+const typeRoutes = /* @__PURE__ */ new Map();
 /**
 * Transform TSDoc link tag syntax to markdown links or plain text.
 *
@@ -181,47 +180,6 @@ function renderMarkdownInline(markdown, context) {
 	}];
 }
 /**
-* Singleton manager for the Twoslash transformer, enabling type-aware documentation.
-*
-* The TwoslashManager initializes and manages a Shiki transformer that provides
-* TypeScript IntelliSense features (hover types, error highlighting, completions)
-* in documentation code blocks. It uses a virtual file system (VFS) to provide
-* type definitions without requiring actual file system access.
-*
-* **How it works:**
-* 1. Plugin initializes the manager with a VFS containing all package type definitions
-* 2. Code blocks marked with `twoslash` are processed by the transformer
-* 3. TypeScript language services provide hover information and error checking
-* 4. Results are rendered as HTML with interactive hover popups
-*
-* **VFS Integration:**
-* The VFS is populated by {@link TypeRegistryService} with:
-* - The documented package's own type definitions (from API Extractor)
-* - External package types (fetched via @tsdoctor/registry)
-*
-* **Error Handling:**
-* TypeScript errors in code blocks are captured (not thrown) and:
-* - Counted via Effect Metric (BuildMetrics.twoslashErrors)
-* - Logged inline via console.error
-* - Displayed in the rendered output as error annotations
-*
-* **Relationships:**
-* - Initialized by {@link ApiExtractorPlugin} in the beforeBuild hook
-* - Receives VFS from {@link TypeRegistryService}
-* - The transformer is used by page generators for rendering code blocks
-*
-* @example
-* ```ts
-* const manager = TwoslashManager.getInstance();
-* manager.initialize(vfs, undefined, logger);
-*
-* const transformer = manager.getTransformer();
-* // Use transformer with Shiki highlighter
-* ```
-*
-* @see {@link TypeRegistryService} for VFS generation
-*/
-/**
 * Fingerprint a compiler configuration so environments can be deduped and code
 * blocks routed to the right one. Keys are sorted, so two configurations that
 * differ only in property order share an environment.
@@ -244,9 +202,6 @@ function renderMarkdownInline(markdown, context) {
 * environment, not the raw default), so a synthetic test compiling each
 * resolution path through the real compiler is the only verification there is.
 */
-function toProgrammaticCompilerOptions(options) {
-	return TsEnumCodec.encodeCompilerOptions(options);
-}
 /**
 * Fingerprint a compiler configuration, for keying the environment map.
 *
@@ -441,6 +396,18 @@ var TwoslashEnvironmentRegistry = class {
 		this.handleTwoslashError(error, code, file);
 	}
 };
+/**
+* Cross-link routes used to turn type names in hover docs into links.
+*
+* @remarks
+* These were `static` members of the old singleton, but they are cross-link
+* DATA, not type-checking state — they only ever read and wrote the
+* module-level `typeRoutes` map above, and they share their concern with
+* the prose cross-linker rather than with the environment registry. They
+* are deliberately NOT part of {@link TwoslashEnvironments}: folding them in
+* would widen the service's surface with state that has nothing to do with
+* compiler configurations.
+*/
 /** Merge routes in, so a multi-API build accumulates every scope's names. */
 function addTypeRoutes(routes) {
 	for (const [name, route] of routes) typeRoutes.set(name, route);
@@ -463,4 +430,4 @@ function clearTypeRoutes() {
 }
 
 //#endregion
-export { TwoslashEnvironmentRegistry, addTypeRoutes, clearTypeRoutes, toProgrammaticCompilerOptions };
+export { TwoslashEnvironmentRegistry, addTypeRoutes, clearTypeRoutes };