rspress-plugin-api-extractor 0.1.2 → 0.2.1

package/shiki-transformer.js

@@ -0,0 +1,758 @@
+//#region src/shiki-transformer.ts
+/**
+* A Shiki transformer that adds cross-links to type references in code blocks.
+*
+* This class creates a Shiki transformer that identifies TypeScript type names
+* in syntax-highlighted code blocks and wraps them in anchor tags linking to
+* their API documentation pages. It handles both standalone type references and
+* class member references (e.g., `ClassName.methodName`).
+*
+* **How it works:**
+* 1. The transformer is initialized with route and kind maps from {@link MarkdownCrossLinker}
+* 2. During Shiki rendering, it walks the HAST tree looking for type names
+* 3. When a match is found, it wraps the text node in an anchor tag with the route
+* 4. Semantic CSS classes are added based on the API item kind (class, interface, etc.)
+*
+* **API Scoping:**
+* - Routes are stored per API scope (e.g., "claude-binary-plugin", "rslib-builder")
+* - Each API only links to types within its own scope
+* - The current API scope is set via `setApiScope()` before rendering each file
+*
+* **Relationships:**
+* - Initialized by {@link ApiExtractorPlugin} during the beforeBuild hook
+* - Receives route data from {@link MarkdownCrossLinker.initialize}
+* - Used alongside {@link TwoslashManager} for type-aware code blocks
+* - Works with the hide-cut transformer for member signatures
+*
+* **Features:**
+* - Matches class/interface members within their declaration context
+* - Handles Twoslash-wrapped spans with popup containers
+* - Preserves whitespace and formatting around linked text
+* - Adds semantic CSS classes for styling (api-token-class, api-token-interface, etc.)
+*
+* @example Basic usage
+* ```ts
+* 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]
+* });
+* ```
+*
+* @see {@link MarkdownCrossLinker} 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);
+	}
+	/**
+	* 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.
+	*
+	* @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")
+	*/
+	reinitialize(routes, kinds, apiScope) {
+		this.apiItemRoutesByScope.set(apiScope, new Map(routes));
+		this.apiItemKindsByScope.set(apiScope, new Map(kinds));
+		const classMembersMap = /* @__PURE__ */ new Map();
+		for (const [name] of routes.entries()) if (name.includes(".")) {
+			const dotIndex = name.indexOf(".");
+			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);
+		}
+		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();
+	}
+	/**
+	* 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
+	* the code block. This ensures Twoslash popup containers are already in their correct
+	* 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
+	*
+	* @example
+	* ```ts
+	* const hast = await highlighter.codeToHast(code, { transformers: [twoslashTransformer] });
+	* const linkedHast = crossLinker.transformHast(hast, "my-api");
+	* ```
+	*/
+	transformHast(hast, apiScope) {
+		const effectiveScope = apiScope ?? this.currentApiScope;
+		return this.transformRootWithScope(hast, effectiveScope);
+	}
+	/**
+	* 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 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 a line element
+	*/
+	transformLine(node) {
+		const apiItemRoutes = this.getRoutesForCurrentScope();
+		const apiItemKinds = this.getKindsForCurrentScope();
+		const classMembersMap = this.getClassMembersForCurrentScope();
+		if (!node.children) return;
+		for (let i = 0; i < node.children.length; i++) {
+			const child = node.children[i];
+			if (child.type !== "element" || child.tagName !== "span") continue;
+			if (child.properties?.["data-api-processed"] === "true") continue;
+			const content = this.extractTextFromTwoslash(child);
+			if (!content) continue;
+			const trimmedContent = content.trim();
+			if (!apiItemRoutes.get(trimmedContent) || !classMembersMap.has(trimmedContent)) continue;
+			const nextChild = node.children[i + 1];
+			if (nextChild?.type !== "element" || nextChild.tagName !== "span") continue;
+			const nextContent = this.extractTextFromTwoslash(nextChild);
+			if (!nextContent) continue;
+			const nextValue = nextContent.trim();
+			if (!nextValue.startsWith(".")) continue;
+			const methodSpanIndex = nextValue === "." ? i + 2 : i + 1;
+			let methodSpan = null;
+			let methodText = null;
+			if (nextValue === ".") {
+				const possibleMethodSpan = node.children[i + 2];
+				if (possibleMethodSpan && possibleMethodSpan.type === "element") {
+					methodSpan = possibleMethodSpan;
+					methodText = this.extractTextFromTwoslash(methodSpan);
+				}
+			} else if (nextValue.startsWith(".")) {
+				methodSpan = nextChild;
+				methodText = nextValue.substring(1);
+			}
+			if (!methodText || !methodSpan) continue;
+			const matchedMember = classMembersMap.get(trimmedContent)?.find((member) => methodText.startsWith(member));
+			if (!matchedMember) continue;
+			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");
+				if (textNode && textNode.type === "text") {
+					const leadingSpace = textNode.value.match(/^\s*/)?.[0] || "";
+					const trailingSpace = textNode.value.match(/\s*$/)?.[0] || "";
+					const newChildren = [];
+					if (leadingSpace) newChildren.push({
+						type: "text",
+						value: leadingSpace
+					});
+					newChildren.push({
+						type: "element",
+						tagName: "a",
+						properties: {
+							href: memberRoute,
+							class: memberClassNames.join(" ")
+						},
+						children: [{
+							type: "text",
+							value: methodText.trim()
+						}]
+					});
+					if (trailingSpace) newChildren.push({
+						type: "text",
+						value: trailingSpace
+					});
+					methodSpan.children = newChildren;
+				}
+			}
+			child.properties = {
+				...child.properties,
+				"data-api-processed": "true"
+			};
+			methodSpan.properties = {
+				...methodSpan.properties,
+				"data-api-processed": "true"
+			};
+			if (methodSpanIndex > i + 1) i = methodSpanIndex;
+			else i++;
+		}
+	}
+	/**
+	* Transform a span element
+	*/
+	transformSpan(node, _line, _col) {
+		const apiItemRoutes = this.getRoutesForCurrentScope();
+		const apiItemKinds = this.getKindsForCurrentScope();
+		if (node.properties?.["data-api-processed"] === "true") return;
+		const firstChild = node.children?.[0];
+		if (firstChild && firstChild.type === "element" && firstChild.tagName === "a") return;
+		if (firstChild && firstChild.type === "element" && firstChild.properties?.class && String(firstChild.properties.class).includes("twoslash-hover") && firstChild.type === "element") {
+			const text = this.extractTextFromTwoslash(firstChild);
+			if (!text) return;
+			const content = text.trim();
+			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);
+				node.properties = {
+					...node.properties,
+					"data-api-processed": "true"
+				};
+			}
+			return;
+		}
+		const textChild = node.children[0];
+		if (textChild?.type !== "text") return;
+		const rawContent = textChild.value;
+		const content = rawContent.trim();
+		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",
+				value: leadingSpace
+			});
+			newChildren.push({
+				type: "element",
+				tagName: "a",
+				properties: {
+					href: route,
+					class: classNames.join(" ")
+				},
+				children: [{
+					type: "text",
+					value: content
+				}]
+			});
+			if (trailingSpace) newChildren.push({
+				type: "text",
+				value: trailingSpace
+			});
+			node.children = newChildren;
+		}
+	}
+	/**
+	* Helper to extract text content from potentially Twoslash-wrapped elements
+	* Twoslash wraps identifiers in: `<span class="twoslash-hover"><span class="twoslash-popup-container">...</span>text</span>`
+	*/
+	extractTextFromTwoslash(element) {
+		if (element.type !== "element") return null;
+		if (element.tagName === "span" && element.properties?.class && String(element.properties.class).includes("twoslash-hover")) {
+			for (const child of element.children) if (child.type === "text") return child.value;
+			return null;
+		}
+		if (element.children && element.children.length === 1 && element.children[0].type === "text") return element.children[0].value;
+		const anchor = element.children.find((c) => c.type === "element" && c.tagName === "a");
+		if (anchor && anchor.type === "element") {
+			const text = anchor.children.find((c) => c.type === "text");
+			if (text && text.type === "text") return text.value;
+		}
+		return null;
+	}
+	/**
+	* Helper to wrap text in Twoslash hover span with an anchor
+	*/
+	wrapTwoslashTextInAnchor(element, text, href, classNames) {
+		for (let i = 0; i < element.children.length; i++) {
+			const child = element.children[i];
+			if (child.type === "text" && child.value.trim() === text.trim()) {
+				element.children[i] = {
+					type: "element",
+					tagName: "a",
+					properties: {
+						href,
+						class: classNames.join(" ")
+					},
+					children: [{
+						type: "text",
+						value: text
+					}]
+				};
+				return;
+			}
+		}
+	}
+	/**
+	* Helper to extract class and method information from Twoslash tooltip.
+	* Returns an object with className and methodName if found, null otherwise.
+	*/
+	extractMethodInfoFromTwoslashTooltip(element) {
+		if (element.tagName !== "span") return null;
+		if (!(element.properties?.class && String(element.properties.class).includes("twoslash-hover"))) return null;
+		const popupContainer = element.children.find((c) => c.type === "element" && c.properties?.class?.toString().includes("twoslash-popup-container"));
+		if (popupContainer?.type !== "element") return null;
+		const codeElement = popupContainer.children.find((c) => c.type === "element" && c.tagName === "code");
+		if (codeElement?.type !== "element") return null;
+		const getText = (node) => {
+			if (node.type === "text") return node.value;
+			if (node.type === "element") return node.children.map(getText).join("");
+			return "";
+		};
+		const match = codeElement.children.map(getText).join("").match(/^(?:\([^)]+\)\s+)?(?:(?:function|interface|class|enum|type|namespace|const|let|var)\s+)?([A-Z]\w+)\.(\w+)[(:]/);
+		if (match) return {
+			className: match[1],
+			methodName: match[2]
+		};
+		return null;
+	}
+	/**
+	* Link type references in regular text nodes within a line element.
+	* Iterates child spans, skipping already-processed and Twoslash-containing spans,
+	* and splits text nodes at type name boundaries.
+	*/
+	linkTypeReferencesInLine(lineElement, typePattern, apiItemRoutes, apiItemKinds) {
+		for (const child of lineElement.children) {
+			if (child.type !== "element" || child.tagName !== "span") continue;
+			if (child.properties?.["data-api-processed"] === "true") continue;
+			if (child.children.some((c) => c.type === "element" && c.properties?.class && String(c.properties.class).includes("twoslash"))) continue;
+			let modified = false;
+			const newChildren = [];
+			for (const textChild of child.children) {
+				if (textChild.type !== "text") {
+					newChildren.push(textChild);
+					continue;
+				}
+				const fragments = this.splitTextAtTypeReferences(textChild.value, typePattern, apiItemRoutes, apiItemKinds);
+				if (fragments.length === 1 && fragments[0].type === "text") newChildren.push(textChild);
+				else {
+					newChildren.push(...fragments);
+					modified = true;
+				}
+			}
+			if (modified) {
+				child.children = newChildren;
+				child.properties = {
+					...child.properties,
+					"data-api-processed": "true"
+				};
+			}
+		}
+	}
+	/**
+	* 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) {
+		typePattern.lastIndex = 0;
+		const result = [];
+		let lastIndex = 0;
+		for (let match = typePattern.exec(text); match !== null; match = typePattern.exec(text)) {
+			const matchedName = match[1];
+			const route = apiItemRoutes.get(matchedName);
+			if (!route) continue;
+			if (match.index > lastIndex) result.push({
+				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(" ")
+				},
+				children: [{
+					type: "text",
+					value: matchedName
+				}]
+			});
+			lastIndex = match.index + match[0].length;
+		}
+		if (result.length === 0) return [{
+			type: "text",
+			value: text
+		}];
+		if (lastIndex < text.length) result.push({
+			type: "text",
+			value: text.slice(lastIndex)
+		});
+		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
+export { ShikiCrossLinker };