rspress-plugin-api-extractor 0.10.0 → 0.11.0

package/remark-api-codeblocks.js

@@ -1,20 +1,12 @@
 import { PluginEvent } from "./observability/events.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateShikiHast } from "./markdown/shiki-utils.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 { VfsRegistry } from "./vfs-registry.js";
 import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.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/services/HighlighterService.js

@@ -0,0 +1,30 @@
+import { Context } from "effect";
+
+//#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: `ConfigServiceLive`
+* 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") {};
+
+//#endregion
+export { HighlighterService };

package/services/OgService.js

@@ -0,0 +1,23 @@
+import { Context, Data } from "effect";
+
+//#region src/services/OgService.ts
+const OgImageErrorBase = Data.TaggedError("OgImageError");
+/**
+* A configured OG image that could not be resolved.
+*
+* @remarks
+* `cause` carries the original failure (an `image-size` parse error, a
+* filesystem error) rather than a stringified copy of it.
+*/
+var OgImageError = class extends OgImageErrorBase {
+	get message() {
+		if (this.code === "invalid-url") return `Invalid Open Graph image URL in '${this.field}': ${this.value} — expected an absolute http(s) URL or a path starting with '/'`;
+		if (this.code === "invalid-secure-url") return `Invalid Open Graph secure URL in '${this.field}': ${this.value} — secureUrl must be an absolute https URL`;
+		const cause = this.cause instanceof Error ? this.cause.message : String(this.cause);
+		return `Could not read Open Graph image '${this.value}': ${cause}`;
+	}
+};
+var OgService = class extends Context.Service()("rspress-plugin-api-extractor/OgService") {};
+
+//#endregion
+export { OgImageError, OgService };

package/services/PluginConfig.js

@@ -0,0 +1,26 @@
+import { Context } from "effect";
+
+//#region src/services/PluginConfig.ts
+/**
+* The decoded plugin options, as a service.
+*
+* @remarks
+* `ConfigServiceLive` used to be a factory taking these as an argument, which
+* made it a layer-returning function — the shape the house rules warn about,
+* since layers memoize by reference and a second call mints a second layer.
+* It was only ever called once, but "only ever called once" is a property of
+* the current call sites, not of the design.
+*
+* A `Context.Service` rather than a `Context.Reference`, deliberately, and for
+* the same reason the Shiki themes are a layer argument: a Reference carries a
+* default, so a wiring mistake would silently resolve to empty options and the
+* build would document nothing while reporting success. There is no sensible
+* default for "which APIs is this site documenting", so forgetting to provide
+* it should be a loud "service not provided", which is what this gives.
+*
+* @packageDocumentation
+*/
+var PluginConfig = class extends Context.Service()("rspress-plugin-api-extractor/PluginConfig") {};
+
+//#endregion
+export { PluginConfig };

package/services/TwoslashEnvironments.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/TwoslashEnvironments.ts
+var TwoslashEnvironments = class extends Context.Service()("rspress-plugin-api-extractor/TwoslashEnvironments") {};
+
+//#endregion
+export { TwoslashEnvironments };

package/shiki-transformer.js

@@ -43,100 +43,53 @@
 * @see the `@tsdoctor/model` CrossLinker for the markdown equivalent
 * @see {@link TwoslashManager} for type-aware documentation features
 */
-var ShikiCrossLinker = class {
-	/** Map of API scopes to their route maps (API item name to route) */
-	apiItemRoutesByScope = /* @__PURE__ */ new Map();
-	/** Map of API scopes to their kind maps (API item name to kind) */
-	apiItemKindsByScope = /* @__PURE__ */ new Map();
-	/** Map of API scopes to their class members maps (class name to member names) */
-	classMembersMapByScope = /* @__PURE__ */ new Map();
-	/**
-	* Current API scope being processed (e.g., "claude-binary-plugin")
-	*/
-	currentApiScope = null;
-	/**
-	* Creates a new ShikiCrossLinker instance. Call reinitialize() with routes, kinds,
-	* and API scope before using the transformer.
-	*/
-	constructor(routes, kinds, apiScope) {
-		if (routes && kinds && apiScope) this.reinitialize(routes, kinds, apiScope);
+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) {
+		this.apiScope = apiScope;
+		this.apiItemRoutes = apiItemRoutes;
+		this.apiItemKinds = apiItemKinds;
+		this.classMembersMap = classMembersMap;
 	}
 	/**
-	* Initialize or reinitialize the cross-link maps with new data for a specific API scope.
-	* This allows the same transformer instance to be used across multiple API packages,
-	* with each API's routes stored separately and scoped to prevent cross-API linking.
+	* One linker for one API's routes.
+	*
+	* @remarks
+	* Mirrors `@tsdoctor/model`'s `CrossLinker.fromRoutes`, deliberately: the
+	* two halves of cross-linking — prose and code blocks — are built the same
+	* way and both are immutable per build.
 	*
-	* @param routes - Map of API item names to their documentation routes
-	* @param kinds - Map of API item names to their kinds (Class, Interface, etc.)
-	* @param apiScope - The API scope identifier (e.g., "claude-binary-plugin", "rslib-builder")
+	* This replaces a single long-lived instance created at plugin-factory time,
+	* threaded through `ConfigServiceLive`'s constructor and the build context,
+	* and mutated per API by `reinitialize()`. Scope isolation used to be a
+	* property of internal `…ByScope` maps plus a mutable `currentApiScope` that
+	* any caller could reassign between a lookup and a render; it is now a
+	* property of the instance, which cannot be pointed at another package's
+	* routes at all.
 	*/
-	reinitialize(routes, kinds, apiScope) {
-		this.apiItemRoutesByScope.set(apiScope, new Map(routes));
-		this.apiItemKindsByScope.set(apiScope, new Map(kinds));
+	static fromRoutes(routes, kinds, apiScope) {
 		const classMembersMap = /* @__PURE__ */ new Map();
-		for (const [name] of routes.entries()) if (name.includes(".")) {
+		for (const [name] of routes.entries()) {
 			const dotIndex = name.indexOf(".");
+			if (dotIndex === -1) continue;
 			const className = name.substring(0, dotIndex);
 			const memberName = name.substring(dotIndex + 1);
-			if (!classMembersMap.has(className)) classMembersMap.set(className, []);
 			const members = classMembersMap.get(className);
-			if (members && !members.includes(memberName)) members.push(memberName);
+			if (members === void 0) classMembersMap.set(className, [memberName]);
+			else if (!members.includes(memberName)) members.push(memberName);
 		}
 		for (const members of classMembersMap.values()) members.sort((a, b) => b.length - a.length);
-		this.classMembersMapByScope.set(apiScope, classMembersMap);
-		this.currentApiScope = apiScope;
-	}
-	/**
-	* Set the current API scope for cross-linking.
-	* This should be called before rendering each file to ensure links are scoped correctly.
-	*
-	* @param apiScope - The API scope identifier (e.g., "claude-binary-plugin")
-	*/
-	setApiScope(apiScope) {
-		this.currentApiScope = apiScope;
-	}
-	/**
-	* Get the routes map for the current API scope
-	*/
-	getRoutesForCurrentScope() {
-		if (!this.currentApiScope) return /* @__PURE__ */ new Map();
-		return this.apiItemRoutesByScope.get(this.currentApiScope) || /* @__PURE__ */ new Map();
-	}
-	/**
-	* Get the kinds map for the current API scope
-	*/
-	getKindsForCurrentScope() {
-		if (!this.currentApiScope) return /* @__PURE__ */ new Map();
-		return this.apiItemKindsByScope.get(this.currentApiScope) || /* @__PURE__ */ new Map();
-	}
-	/**
-	* Get the class members map for the current API scope
-	*/
-	getClassMembersForCurrentScope() {
-		if (!this.currentApiScope) return /* @__PURE__ */ new Map();
-		return this.classMembersMapByScope.get(this.currentApiScope) || /* @__PURE__ */ new Map();
-	}
-	/**
-	* Get the routes map for a specific API scope
-	*/
-	getRoutesForScope(scope) {
-		if (!scope) return /* @__PURE__ */ new Map();
-		return this.apiItemRoutesByScope.get(scope) || /* @__PURE__ */ new Map();
-	}
-	/**
-	* Get the kinds map for a specific API scope
-	*/
-	getKindsForScope(scope) {
-		if (!scope) return /* @__PURE__ */ new Map();
-		return this.apiItemKindsByScope.get(scope) || /* @__PURE__ */ new Map();
-	}
-	/**
-	* Get the class members map for a specific API scope
-	*/
-	getClassMembersForScope(scope) {
-		if (!scope) return /* @__PURE__ */ new Map();
-		return this.classMembersMapByScope.get(scope) || /* @__PURE__ */ new Map();
+		return new ShikiCrossLinker(apiScope, new Map(routes), new Map(kinds), 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());
 	/**
 	* Transform a finalized HAST tree to add cross-links to type references.
 	*
@@ -145,162 +98,28 @@ var ShikiCrossLinker = class {
 	* positions before we add anchor links.
 	*
 	* @param hast - The finalized HAST root node from Shiki
-	* @param apiScope - Optional API scope to use for lookups. If not provided, uses currentApiScope.
 	* @returns The transformed HAST with cross-links added
 	*
+	* @remarks
+	* There is no scope parameter. A linker IS a scope — the caller picks the
+	* right instance (from the `VfsRegistry` entry for the page's scope) rather
+	* than picking the right argument. The parameter it replaces was optional
+	* and fell back to a mutable `currentApiScope`, so omitting it linked
+	* against whichever package happened to render last.
+	*
 	* @example
 	* ```ts
 	* const hast = await highlighter.codeToHast(code, { transformers: [twoslashTransformer] });
-	* const linkedHast = crossLinker.transformHast(hast, "my-api");
+	* const linkedHast = crossLinker.transformHast(hast);
 	* ```
 	*/
-	transformHast(hast, apiScope) {
-		const effectiveScope = apiScope ?? this.currentApiScope;
-		return this.transformRootWithScope(hast, effectiveScope);
+	transformHast(hast) {
+		return this.transformRoot(hast);
 	}
-	/**
-	* Transform the root node of the syntax tree with explicit scope
-	*/
-	transformRootWithScope(node, scope) {
-		const apiItemRoutes = this.getRoutesForScope(scope);
-		const apiItemKinds = this.getKindsForScope(scope);
-		const classMembersMap = this.getClassMembersForScope(scope);
-		const scopeStack = [];
-		const preElement = node.children.find((child) => child.type === "element" && child.tagName === "pre");
-		if (preElement?.type !== "element") return node;
-		const codeElement = preElement.children.find((child) => child.type === "element" && child.tagName === "code");
-		if (codeElement?.type !== "element") return node;
-		for (const lineElement of codeElement.children) {
-			if (lineElement.type !== "element" || lineElement.tagName !== "span") continue;
-			const getText = (node) => {
-				if (node.type === "text") return node.value;
-				if (node.type === "element") return node.children.map(getText).join("");
-				return "";
-			};
-			const lineText = lineElement.children.map(getText).join("");
-			const currentScope = scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
-			if (currentScope) {
-				const members = classMembersMap.get(currentScope);
-				if (members) for (const spanElement of lineElement.children) {
-					if (spanElement.type !== "element" || spanElement.tagName !== "span") continue;
-					if (spanElement.children?.length !== 1) continue;
-					const textNode = spanElement.children[0];
-					if (textNode.type !== "text") continue;
-					const rawContent = textNode.value;
-					const content = rawContent.trim();
-					if (!content) continue;
-					if (members.includes(content)) {
-						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",
-								value: leadingSpace
-							});
-							newChildren.push({
-								type: "element",
-								tagName: "a",
-								properties: {
-									href: memberRoute,
-									class: classNames.join(" ")
-								},
-								children: [{
-									type: "text",
-									value: content
-								}]
-							});
-							if (trailingSpace) newChildren.push({
-								type: "text",
-								value: trailingSpace
-							});
-							spanElement.children = newChildren;
-							spanElement.properties = {
-								...spanElement.properties,
-								"data-api-processed": "true"
-							};
-						}
-					}
-				}
-			}
-			const classMatch = lineText.match(/(?:class|interface|namespace)\s+(\w+)\s*(?:<[^>]*>)?\s*(?:extends|implements)?[^{]*\{/);
-			if (classMatch) {
-				if ((lineText.match(/\{/g) || []).length > (lineText.match(/\}/g) || []).length) scopeStack.push(classMatch[1]);
-			}
-			const openBraces = (lineText.match(/\{/g) || []).length;
-			const excessCloses = (lineText.match(/\}/g) || []).length - openBraces;
-			for (let i = 0; i < excessCloses && scopeStack.length > 0; i++) scopeStack.pop();
-		}
-		const findTwoslashSpans = (element) => {
-			const results = [];
-			if (element.properties?.class && String(element.properties.class).includes("twoslash-hover")) results.push(element);
-			if (element.children) {
-				for (const child of element.children) if (child.type === "element") results.push(...findTwoslashSpans(child));
-			}
-			return results;
-		};
-		const twoslashSpans = findTwoslashSpans(codeElement);
-		for (const twoslashSpan of twoslashSpans) {
-			if (twoslashSpan.properties?.["data-api-processed"] === "true") continue;
-			const methodInfo = this.extractMethodInfoFromTwoslashTooltip(twoslashSpan);
-			if (!methodInfo) continue;
-			const { className, methodName } = methodInfo;
-			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);
-			twoslashSpan.properties = {
-				...twoslashSpan.properties,
-				"data-api-processed": "true"
-			};
-		}
-		const typeNames = Array.from(apiItemRoutes.keys()).filter((name) => !name.includes(".")).sort((a, b) => b.length - a.length);
-		if (typeNames.length > 0) {
-			for (const twoslashSpan of twoslashSpans) {
-				if (twoslashSpan.properties?.["data-api-processed"] === "true") continue;
-				const text = this.extractTextFromTwoslash(twoslashSpan);
-				if (!text) continue;
-				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);
-				twoslashSpan.properties = {
-					...twoslashSpan.properties,
-					"data-api-processed": "true"
-				};
-			}
-			const escapedNames = typeNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-			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);
-			}
-		}
-		return node;
-	}
-	/**
-	* Transform the root node of the syntax tree
-	*/
 	transformRoot(node) {
-		const apiItemRoutes = this.getRoutesForCurrentScope();
-		const apiItemKinds = this.getKindsForCurrentScope();
-		const classMembersMap = this.getClassMembersForCurrentScope();
+		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");
 		if (preElement?.type !== "element") return node;
@@ -434,9 +253,9 @@ var ShikiCrossLinker = class {
 	* Transform a line element
 	*/
 	transformLine(node) {
-		const apiItemRoutes = this.getRoutesForCurrentScope();
-		const apiItemKinds = this.getKindsForCurrentScope();
-		const classMembersMap = this.getClassMembersForCurrentScope();
+		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++) {
 			const child = node.children[i];
@@ -521,8 +340,8 @@ var ShikiCrossLinker = class {
 	* Transform a span element
 	*/
 	transformSpan(node, _line, _col) {
-		const apiItemRoutes = this.getRoutesForCurrentScope();
-		const apiItemKinds = this.getKindsForCurrentScope();
+		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;

package/twoslash-access.js

@@ -0,0 +1,48 @@
+//#region src/twoslash-access.ts
+/** The uninstalled state: no environments, so nothing to hand out. */
+const NOT_INSTALLED = {
+	transformerFor: () => null,
+	setCurrentFile: () => {}
+};
+let current = NOT_INSTALLED;
+/**
+* Bind the render pass to this build's environments.
+*
+* @remarks
+* Called from `plugin.ts`'s Effect program, beside the other seam wiring, and
+* NOT from `ConfigServiceLive` — config resolution should compute a value, not
+* also mutate module state on the side.
+*/
+function installTwoslashAccess(environments) {
+	current = environments;
+}
+/**
+* Reset to the uninstalled state.
+*
+* @remarks
+* Called at the start of every build, next to `VfsRegistry.clear()`, for the
+* same reason that call exists: a dev HMR session reuses the process, so a
+* holder from the previous build would otherwise outlive it and hand the
+* render pass transformers built against declarations that have since changed.
+*/
+function clearTwoslashAccess() {
+	current = NOT_INSTALLED;
+}
+/**
+* The transformer for a scope, for the remark plugins.
+*
+* @returns `null` when nothing is installed — an inert build, which registers
+* no environments at all. A `with-api` fence still renders; it just renders
+* without type information, which is the honest answer when the build
+* documents no API.
+*/
+function twoslashTransformerFor(apiScope) {
+	return current.transformerFor(apiScope);
+}
+/** Attribute subsequent Twoslash diagnostics to a source file. */
+function setTwoslashFile(path) {
+	current.setCurrentFile(path);
+}
+
+//#endregion
+export { clearTwoslashAccess, installTwoslashAccess, setTwoslashFile, twoslashTransformerFor };