rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/shiki-transformer.js

@@ -35,128 +35,61 @@
 * 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
 * @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();
-	}
-	/**
-	* 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" };
+		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.
 	*
@@ -165,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);
-	}
-	/**
-	* 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;
+	transformHast(hast) {
+		return this.transformRoot(hast);
 	}
-	/**
-	* 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;
@@ -454,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];
@@ -541,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 };

package/twoslash-cache.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { gunzipSync, gzipSync } from "node:zlib";
+
+//#region src/twoslash-cache.ts
+/**
+* Persisted Twoslash result cache.
+*
+* Type-checking code blocks is by far the dominant cost of the render phase —
+* measured at ~97% of it, concentrated in the minority of blocks that carry an
+* `@example` (see `render-phase-instrumentation.md`). `@shikijs/twoslash`
+* exposes a first-class `typesCache` seam for exactly this, so the work here is
+* a keying scheme and a store rather than a new interception point.
+*
+* ## Soundness
+*
+* A Twoslash result depends on the code, the compiler options, the declarations
+* it is checked against, and the compiler doing the checking. The keys cover
+* all four: the per-entry key carries the code, its language and the compiler
+* options; {@link twoslashEnvHash} carries the declarations and the TypeScript
+* version.
+*
+* The TypeScript version is load-bearing and easy to overlook — `lib.d.ts`
+* ships with the compiler and inference changes between releases, so an upgrade
+* against unchanged declarations yields different hovers. Omitting it would let
+* a warm cache serve results from the previous compiler and stay wrong until
+* the API's own declarations happened to change.
+*
+* NOT covered, and covered instead by {@link TWOSLASH_CACHE_FORMAT}: the
+* `@shikijs/twoslash` / `twoslash` renderer version, which determines the shape
+* of the stored `nodes`. Bump the format constant when upgrading those, since
+* nothing derives it automatically.
+*
+* ## Invalidation granularity
+*
+* The consequence of that soundness is coarse invalidation: any VFS change
+* discards the whole generation, because a declaration change anywhere can
+* legitimately change any block's inferred types. So this cache makes repeat
+* builds over an UNCHANGED API nearly free — CI re-runs, prose-only edits,
+* theme and config changes, rebuilding a site without touching the library —
+* and does nothing for the build right after an API item changes.
+*
+* Sharpening that would need per-scope type environments, so one package's
+* change stops invalidating every other package's blocks. That is fix (b) in
+* `render-phase-instrumentation.md`, tracked as a correctness fix; it would
+* make this cache substantially more effective on a multi-API site as a side
+* effect.
+*
+* ## Synchronous by necessity
+*
+* `TwoslashTypesCache.read`/`write` are synchronous — they are called from
+* inside Shiki's `preprocess` hook. Persistence is therefore load-once at
+* startup and save-once at the end, against an in-memory map; there is no
+* per-entry I/O. See `TwoslashCacheService`.
+*/
+/**
+* Bumped when the stored shape changes, so an older blob is treated as absent
+* rather than deserialized into the wrong shape.
+*
+* Also the manual lever for renderer changes: bump this when upgrading
+* `@shikijs/twoslash` or `twoslash`, whose versions determine the shape of the
+* stored `nodes` and are not derived into any key.
+*/
+const TWOSLASH_CACHE_FORMAT = 1;
+function sha256(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/**
+* Fingerprint the type environment a generation is checked against.
+*
+* Covers the declarations (`vfs`) and the compiler that interprets them
+* (`toolchain`). The VFS is hashed over sorted `path\0content` pairs so the
+* digest is stable against map iteration order.
+*
+* `toolchain` must carry the TypeScript version. The declarations alone do not
+* determine the answer: `lib.d.ts` ships with the compiler and inference
+* behaviour changes between releases, so upgrading TypeScript against unchanged
+* declarations produces different hovers. Without the version in the key the
+* warm cache would serve results computed by the previous compiler, and stay
+* wrong until the API's own declarations happened to change.
+*
+* Compiler OPTIONS are deliberately not folded in here — they belong on the
+* per-entry key, so one generation can hold results from the several
+* configurations a multi-API site may declare.
+*/
+function twoslashEnvHash(vfs, toolchain) {
+	const hash = createHash("sha256");
+	hash.update(`format:${1}\0toolchain:${toolchain}\0`);
+	for (const key of [...vfs.keys()].sort()) hash.update(`${key}\0${vfs.get(key) ?? ""}\0`);
+	return hash.digest("hex");
+}
+/** JSON with object keys sorted, so equivalent options hash identically. */
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/**
+* Per-entry key: the code, its language, and the compiler configuration it is
+* checked under.
+*
+* The configuration matters because two APIs on one site may be documented
+* under different `tsconfig`s — the same source checked under different options
+* can produce different types, so it must not share a cache entry.
+*/
+function twoslashEntryKey(code, lang, compilerOptions) {
+	return sha256(`${lang ?? "ts"}\0${stableStringify(compilerOptions ?? {})}\0${code}`);
+}
+/**
+* The cache key a whole generation is stored under. One blob per environment,
+* so a changed environment reads as a miss rather than serving stale results.
+*/
+function twoslashBlobKey(envHash) {
+	return `twoslash/v${1}/${envHash}`;
+}
+/**
+* Build a synchronous Twoslash cache over an in-memory map, optionally seeded
+* with entries loaded from a previous build.
+*/
+function makeTwoslashCache(initial) {
+	const map = new Map(initial);
+	let hits = 0;
+	let misses = 0;
+	let dirty = false;
+	return {
+		read: (code, lang, options) => {
+			const found = map.get(twoslashEntryKey(code, lang, options?.compilerOptions));
+			if (found === void 0) {
+				misses += 1;
+				return null;
+			}
+			hits += 1;
+			return found;
+		},
+		write: (code, data, lang, options) => {
+			const value = {
+				nodes: data.nodes,
+				code: data.code,
+				...data.meta?.extension != null ? { meta: { extension: data.meta.extension } } : {}
+			};
+			map.set(twoslashEntryKey(code, lang, options?.compilerOptions), value);
+			dirty = true;
+		},
+		stats: () => ({
+			hits,
+			misses,
+			entries: map.size,
+			dirty
+		}),
+		entries: () => map
+	};
+}
+/** Serialize a generation for storage. Gzipped JSON — hover text compresses well. */
+function encodeTwoslashCache(entries) {
+	return gzipSync(Buffer.from(JSON.stringify(Object.fromEntries(entries)), "utf-8"));
+}
+/**
+* Deserialize a stored generation.
+*
+* Returns an empty map for anything unreadable — a truncated blob, a format
+* change, a corrupted file. A cache that cannot be read is a cache miss, never
+* a build failure.
+*/
+function decodeTwoslashCache(blob) {
+	try {
+		const parsed = JSON.parse(gunzipSync(blob).toString("utf-8"));
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return /* @__PURE__ */ new Map();
+		return new Map(Object.entries(parsed));
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+
+//#endregion
+export { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey, twoslashEntryKey, twoslashEnvHash };

package/twoslash-patterns.js

@@ -84,4 +84,4 @@ function classifyCutDirective(trimmedLine) {
 }
 
 //#endregion
-export { RE_ANNOTATION, RE_CONFIG, RE_CUT, classifyCutDirective, isTwoslashDirective };
+export { classifyCutDirective, isTwoslashDirective };

package/twoslash-timing-wrapper.js

@@ -0,0 +1,23 @@
+//#region src/twoslash-timing-wrapper.ts
+/**
+* Wraps a Twoslash transformer to measure execution time
+*/
+function createTwoslashTimingWrapper(twoslashTransformer, onTiming) {
+	const wrapper = {
+		...twoslashTransformer,
+		name: `${twoslashTransformer.name}-timing-wrapper`
+	};
+	if (twoslashTransformer.preprocess) {
+		const originalPreprocess = twoslashTransformer.preprocess;
+		wrapper.preprocess = function(code, options) {
+			const start = performance.now();
+			const result = originalPreprocess.call(this, code, options);
+			onTiming(performance.now() - start);
+			return result ?? void 0;
+		};
+	}
+	return wrapper;
+}
+
+//#endregion
+export { createTwoslashTimingWrapper };