rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/layers/xdg.js

@@ -0,0 +1,44 @@
+import { NodeFileSystem } from "@effect/platform-node";
+import { Layer, Path } from "effect";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/layers/xdg.ts
+/**
+* The plugin's shared platform and XDG layers.
+*
+* @remarks
+* Both cache-backed services — the type registry and the Twoslash result cache
+* — need a Node platform and an XDG app-directory root, and both used to
+* declare their own. Two consequences, both fixed by having one home:
+*
+* 1. **Two distinct layer references build twice.** Layer memoization is by
+*    reference, so a second `Layer.mergeAll(NodeFileSystem.layer, Path.layer)`
+*    is a different layer as far as the memo map is concerned, and the XDG
+*    resolution ran once per consumer.
+* 2. **The namespace literal was copy-pasted.** The house style bans exactly
+*    this: when two sibling layers must agree on an identity string, the
+*    agreement has to be structural rather than textual. A drift here is
+*    silent and permanent — the caches move to a different directory, every
+*    lookup misses, and a build that should hit a warm Twoslash cache goes
+*    cold forever with no error and nothing in the output to notice.
+*
+* @packageDocumentation
+*/
+/**
+* The XDG namespace every cache this plugin keeps lives under.
+*
+* @remarks
+* One definition, deliberately. Changing it invalidates every on-disk cache —
+* the type registry's `metadata.sqlite` and the Twoslash result cache's
+* `twoslash.sqlite` — which is a cold refetch and a full re-type-check, not an
+* error. That was accepted once, at the phase-2 rename from
+* `type-registry-effect`; do not do it casually.
+*/
+const TSDOCTOR_NAMESPACE = "tsdoctor";
+/** Node platform services: the filesystem and path implementations. */
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
+/** XDG application directories rooted at {@link TSDOCTOR_NAMESPACE}. */
+const AppDirsLive = AppDirs.layer({ namespace: TSDOCTOR_NAMESPACE }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
+
+//#endregion
+export { AppDirsLive, PlatformLive, TSDOCTOR_NAMESPACE };

package/markdown/helpers.js

@@ -4,7 +4,6 @@ import { formatCode } from "../prettier-formatter.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 
 //#region src/markdown/helpers.ts
-/* v8 ignore start -- markdown generation helpers, tested via page generator integration tests */
 /**
 * Helper utilities for generating markdown API documentation.
 *
@@ -50,63 +49,18 @@ function prepareExampleCode(example, apiItemName, packageName, suppressErrors =
 	};
 }
 /**
-* Sanitize a display name to create a URL-safe HTML ID.
-*
-* Converts a display name (e.g., method or property name) into a valid
-* HTML ID suitable for anchor links. Handles special characters, quotes,
-* and optionally adds a prefix for disambiguation.
-*
-* @param displayName - The original display name
-* @param prefix - Optional prefix to add (e.g., "static-property")
-* @returns URL-safe ID string
-*
-* @example
-* ```ts
-* sanitizeId("myMethod");        // "mymethod"
-* sanitizeId("get value");       // "get-value"
-* sanitizeId("run", "static");   // "static-run"
-* ```
-*/
-function sanitizeId(displayName, prefix = "") {
-	const baseName = displayName.replace(/["']/g, "").replace(/[^\w-]/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
-	return prefix ? `${prefix}-${baseName}` : baseName;
-}
-/**
-* Escape a YAML string value by handling special characters.
-*
-* Normalizes whitespace and wraps strings in double quotes if they contain
-* characters that could break YAML parsing (colons, quotes, hashes, pipes,
-* brackets, braces, Unicode characters, etc.).
-*
-* @param value - The string value to escape
-* @returns YAML-safe string
-*
-* @example
-* ```ts
-* escapeYamlString("Hello World");           // "Hello World"
-* escapeYamlString("Type: string");          // "\"Type: string\""
-* escapeYamlString("He said \"hello\"");     // "\"He said \\\"hello\\\"\""
-* escapeYamlString("@pkg/name。:");          // "\"@pkg/name。:\""
-* ```
-*/
-/**
-* Normalize a string for use as a YAML frontmatter value: collapse newlines
-* and repeated whitespace to single spaces and trim.
-*
-* This is the cleaning half of the former hand-rolled YAML escaping. It is
-* applied to every frontmatter value BEFORE serialization so the parsed data
-* (and therefore the snapshot frontmatter hash — see `@tsdoctor/snapshot`)
-* is byte-identical to what the previous emitter produced; the quoting half
-* is now owned by the real YAML emitter in `../frontmatter.ts`.
+* Collapse newlines and runs of whitespace to single spaces, and trim.
+*
+* @remarks
+* Applied to every frontmatter scalar before emission. This is NOT quoting —
+* `@effected/yaml` owns that — it is whitespace normalization, and it is
+* load-bearing: the snapshot system hashes the PARSED frontmatter, so a value
+* that folds differently between builds would churn the hash. Survives the
+* removal of `escapeYamlString`, which was its other caller.
 */
 function cleanYamlValue(value) {
 	return value.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
 }
-function escapeYamlString(value) {
-	const cleaned = cleanYamlValue(value);
-	if (/["':#|>&*!%@`[\]{},?-]/.test(cleaned) || /[\u0080-\uFFFF]/.test(cleaned) || /^(true|false|null|~|yes|no|on|off)$/i.test(cleaned) || /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(cleaned)) return `"${cleaned.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
-	return cleaned;
-}
 /**
 * Escape generic type parameters in MDX by wrapping them in backticks.
 *
@@ -334,4 +288,4 @@ async function formatExampleCode(code, language, _context) {
 }
 
 //#endregion
-export { escapeMdxGenerics, escapeYamlString, formatExampleCode, formatImportsWithCut, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };
+export { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives };

package/markdown/page-generators/class-page.js

@@ -1,7 +1,7 @@
 import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives } from "../helpers.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
 import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc } from "@tsdoctor/model";
+import { ApiItems, Routes, Signature, Tsdoc } from "@tsdoctor/model";
 
 //#region src/markdown/page-generators/class-page.ts
 /**
@@ -60,7 +60,7 @@ var ClassPageGenerator = class {
 	*
 	* @param apiScope - API scope identifier for VFS lookup
 	*/
-	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom, syntheticBase) {
+	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom, syntheticBase, memberAnchors) {
 		const shouldSuppressErrors = suppressExampleErrors ?? true;
 		const name = apiClass.displayName;
 		const summary = Tsdoc.summary(apiClass) || "No description available.";
@@ -99,7 +99,7 @@ var ClassPageGenerator = class {
 			content += `## Constructors\n\n`;
 			for (const ctor of constructors) {
 				const ctorSummary = Tsdoc.summary(ctor);
-				const ctorId = sanitizeId("constructor");
+				const ctorId = Routes.memberAnchor("constructor");
 				const ctorItem = ctor;
 				const params = Tsdoc.params(ctor);
 				const hasParameters = params.length > 0;
@@ -131,15 +131,14 @@ var ClassPageGenerator = class {
 			const isGetter = m.displayName.startsWith("get ") || m.displayName.startsWith("set ");
 			return !isStatic && !isGetter;
 		});
-		const prefixMap = this.detectMemberConflicts(staticProperties, grouped.staticMethods, instanceProperties, grouped.instanceMethods, grouped.getters);
+		const anchors = memberAnchors ?? ApiItems.memberAnchors(apiClass);
+		const anchorFor = (member) => anchors.get(member.canonicalReference?.toString() ?? member.displayName) ?? Routes.memberAnchor(member.displayName);
 		const renderProperties = async (title, propList) => {
 			if (propList.length === 0) return;
 			content += `## ${title}\n\n`;
 			for (const prop of propList) {
 				const propSummary = Tsdoc.summary(prop);
-				const baseName = sanitizeId(prop.displayName);
-				const prefix = prefixMap.get(baseName) || "";
-				const propId = sanitizeId(prop.displayName, prefix);
+				const propId = anchorFor(prop);
 				const propItem = prop;
 				if (propItem.excerpt?.text) {
 					const memberSignature = Signature.format(propItem.excerpt).trim();
@@ -154,9 +153,7 @@ var ClassPageGenerator = class {
 			content += `## ${title}\n\n`;
 			for (const method of methodList) {
 				const methodSummary = Tsdoc.summary(method);
-				const baseName = sanitizeId(method.displayName);
-				const prefix = prefixMap.get(baseName) || "";
-				const methodId = sanitizeId(method.displayName, prefix);
+				const methodId = anchorFor(method);
 				const methodItem = method;
 				const params = Tsdoc.params(method);
 				const hasParameters = params.length > 0;
@@ -258,26 +255,6 @@ var ClassPageGenerator = class {
 		};
 	}
 	/**
-	* Detect naming conflicts between class members and return prefixes to apply.
-	* Returns a Map of sanitized name to prefix (empty string if no conflict).
-	*/
-	detectMemberConflicts(staticProps, staticMethods, instanceProps, instanceMethods, getters) {
-		const prefixMap = /* @__PURE__ */ new Map();
-		const staticPropNames = new Set(staticProps.map((p) => sanitizeId(p.displayName)));
-		const staticMethodNames = new Set(staticMethods.map((m) => sanitizeId(m.displayName)));
-		const instancePropNames = new Set(instanceProps.map((p) => sanitizeId(p.displayName)));
-		const instanceMethodNames = new Set(instanceMethods.map((m) => sanitizeId(m.displayName)));
-		const getterNames = new Set(getters.map((g) => sanitizeId(g.displayName)));
-		for (const name of staticPropNames) if (staticMethodNames.has(name) || instancePropNames.has(name) || instanceMethodNames.has(name) || getterNames.has(name)) prefixMap.set(name, "static-property");
-		for (const name of staticMethodNames) if (instanceMethodNames.has(name) || instancePropNames.has(name) || getterNames.has(name)) prefixMap.set(name, "static");
-		else if (staticPropNames.has(name)) prefixMap.set(name, "");
-		for (const name of instancePropNames) if (instanceMethodNames.has(name) || getterNames.has(name)) prefixMap.set(name, "property");
-		else if (staticMethodNames.has(name)) prefixMap.set(name, "");
-		for (const name of instanceMethodNames) if (!prefixMap.has(name)) prefixMap.set(name, "");
-		for (const name of getterNames) if (!prefixMap.has(name)) prefixMap.set(name, "");
-		return prefixMap;
-	}
-	/**
 	* Generate a class member signature with full class context
 	* Includes hidden imports with cut directive for external type resolution
 	* Uses the simplified approach: 3 lines (class opening, member, closing)

package/markdown/page-generators/index-pages.js

@@ -1,4 +1,4 @@
-import { escapeYamlString } from "../helpers.js";
+import { emitFrontmatterBlock } from "../../frontmatter.js";
 
 //#region src/markdown/page-generators/index-pages.ts
 /**
@@ -9,13 +9,11 @@ var MainIndexPageGenerator = class {
 	* Generate the main API index page
 	*/
 	generate(packageName, baseRoute, _categoryCounts) {
-		const content = `---
-title: API Reference
-description: Auto-generated API documentation for ${escapeYamlString(packageName)}
-overview: true
----
-
-`;
+		const content = emitFrontmatterBlock({
+			title: "API Reference",
+			description: `Auto-generated API documentation for ${packageName}`,
+			overview: true
+		});
 		return {
 			routePath: `${baseRoute}/index`,
 			content

package/markdown/page-generators/interface-page.js

@@ -1,7 +1,7 @@
 import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives } from "../helpers.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
 import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc } from "@tsdoctor/model";
+import { ApiItems, Routes, Signature, Tsdoc } from "@tsdoctor/model";
 
 //#region src/markdown/page-generators/interface-page.ts
 /**
@@ -98,7 +98,7 @@ var InterfacePageGenerator = class {
 			content += `## Call Signatures\n\n`;
 			for (const callSig of callSignatures) {
 				const callSigSummary = Tsdoc.summary(callSig);
-				const callSigId = sanitizeId("call-signature");
+				const callSigId = Routes.memberAnchor("call-signature");
 				const callSigItem = callSig;
 				if (callSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(callSigItem.excerpt).trim();
@@ -113,7 +113,7 @@ var InterfacePageGenerator = class {
 			content += `## Construct Signatures\n\n`;
 			for (const constructSig of constructSignatures) {
 				const constructSigSummary = Tsdoc.summary(constructSig);
-				const constructSigId = sanitizeId("construct-signature");
+				const constructSigId = Routes.memberAnchor("construct-signature");
 				const constructSigItem = constructSig;
 				if (constructSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(constructSigItem.excerpt).trim();
@@ -128,7 +128,7 @@ var InterfacePageGenerator = class {
 			content += `## Index Signature\n\n`;
 			for (const indexSig of indexSignatures) {
 				const indexSigSummary = Tsdoc.summary(indexSig);
-				const indexSigId = sanitizeId("index-signature");
+				const indexSigId = Routes.memberAnchor("index-signature");
 				const indexSigItem = indexSig;
 				if (indexSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(indexSigItem.excerpt).trim();
@@ -143,7 +143,7 @@ var InterfacePageGenerator = class {
 			content += `## Properties\n\n`;
 			for (const prop of properties) {
 				const propSummary = Tsdoc.summary(prop);
-				const propId = sanitizeId(prop.displayName);
+				const propId = Routes.memberAnchor(prop.displayName);
 				const propItem = prop;
 				if (propItem.excerpt?.text) {
 					const memberSignature = Signature.format(propItem.excerpt).trim();
@@ -158,7 +158,7 @@ var InterfacePageGenerator = class {
 			content += `## Methods\n\n`;
 			for (const method of methods) {
 				const methodSummary = Tsdoc.summary(method);
-				const methodId = sanitizeId(method.displayName);
+				const methodId = Routes.memberAnchor(method.displayName);
 				const methodItem = method;
 				if (methodItem.excerpt?.text) {
 					const memberSignature = Signature.format(methodItem.excerpt).trim();

package/markdown/shiki-utils.js

@@ -1,13 +1,7 @@
 import { PluginEvent } from "../observability/events.js";
+import { emitSync, syncBuildId } from "../observability/sync-emitter.js";
 
 //#region src/markdown/shiki-utils.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setShikiUtilsEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
 * Default Shiki theme configuration
 */
@@ -48,8 +42,8 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 		if (enableTwoslash) options.meta = { __raw: "twoslash" };
 		return await highlighter.codeToHast(code, options);
 	} catch (error) {
-		emitEvent(PluginEvent.ShikiError({
-			ctx: { buildId: currentBuildId },
+		emitSync(PluginEvent.ShikiError({
+			ctx: { buildId: syncBuildId() },
 			file: "unknown",
 			reason: String(error),
 			level: "warn"
@@ -57,6 +51,67 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 		return null;
 	}
 }
+/* v8 ignore stop -- everything below is pure and covered by __test__/markdown/shiki-themes.test.ts */
+/**
+* Normalize a theme option into the `{ light, dark }` pair the highlighter and
+* the remark plugins both expect.
+*
+* @remarks
+* Accepts a single theme name applied to both modes, an explicit pair, or a
+* raw theme object. Lives beside {@link DEFAULT_SHIKI_THEMES} because it falls
+* back to it; it was previously duplicated byte-for-byte in `plugin.ts` and
+* `ConfigServiceLive.ts`.
+*/
+function normalizeThemeConfig(theme) {
+	if (!theme) return { ...DEFAULT_SHIKI_THEMES };
+	if (typeof theme === "string") return {
+		light: theme,
+		dark: theme
+	};
+	if ("light" in theme && "dark" in theme && typeof theme.light === "string" && typeof theme.dark === "string") return {
+		light: theme.light,
+		dark: theme.dark
+	};
+	return {
+		light: theme,
+		dark: theme
+	};
+}
+/**
+* Every theme the build's single highlighter must load: one normalized pair
+* per documented API, plus the two defaults.
+*
+* @remarks
+* Takes the RAW option configs rather than resolved ones, because the
+* highlighter is now acquired when its layer builds — before `resolve()` has
+* run. That is sound: a resolved config's `theme` is exactly
+* `normalizeThemeConfig(api.theme)` and no version-level override exists, so
+* the two inputs cannot disagree.
+*
+* Named theme strings are deduplicated; object themes are not (they have no
+* identity to compare), which matches the previous behaviour and is harmless —
+* Shiki keys a loaded theme by its `name`.
+*/
+function collectShikiThemes(apis) {
+	const named = /* @__PURE__ */ new Set();
+	const objects = [];
+	for (const api of apis) {
+		const theme = normalizeThemeConfig(api.theme);
+		for (const input of [theme.light, theme.dark]) if (typeof input === "string") named.add(input);
+		else objects.push(input);
+	}
+	if (typeof DEFAULT_SHIKI_THEMES.light === "string") named.add(DEFAULT_SHIKI_THEMES.light);
+	if (typeof DEFAULT_SHIKI_THEMES.dark === "string") named.add(DEFAULT_SHIKI_THEMES.dark);
+	return [...named, ...objects];
+}
+/** Languages the highlighter loads. Every code block the plugin renders is one of these. */
+const SHIKI_LANGS = [
+	"typescript",
+	"javascript",
+	"json",
+	"bash",
+	"sh"
+];
 
 //#endregion
-export { DEFAULT_SHIKI_THEMES, generateShikiHast, setShikiUtilsEventEmitter };
+export { DEFAULT_SHIKI_THEMES, SHIKI_LANGS, collectShikiThemes, generateShikiHast, normalizeThemeConfig };

package/observability/EventBus.js

@@ -1,3 +1,4 @@
+import { BuildId } from "../BuildEnv.js";
 import { LEVEL_RANK, levelOf } from "./events.js";
 import { Context, Effect, Layer, Option } from "effect";
 
@@ -16,11 +17,34 @@ function makeShape(sinks) {
 function makeEventBusLayer(sinks) {
 	return Layer.succeed(EventBus, makeShape(sinks));
 }
-/** No sinks: every emit is a no-op, wantsLevel always false. */
-const EventBusNoop = makeEventBusLayer([]);
-/** Emit when a bus is in context; silently no-op otherwise. */
+/**
+* Emit when a bus is in context; silently no-op otherwise.
+*
+* @remarks
+* Fills `ctx.buildId` from the {@link BuildId} Reference when the caller left
+* it empty, which is why no emit site passes one. Before this, 24 sites wrote
+* `ctx: { buildId: "" }` — 22 in `ConfigServiceLive`, where the real value sat
+* three scopes up and was simply not reached, and every site in
+* `TypeRegistryServiceLive`, where the layer is module-level and there is no
+* build to name. The second group is why a Reference is the fix and a
+* find-and-replace is not: a Reference reaches code that no parameter can.
+*
+* A caller that sets a non-empty `buildId` keeps it, so a test can still emit
+* with an explicit id.
+*/
 function emit(event) {
-	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.emit(event) : Effect.void));
+	return Effect.gen(function* () {
+		const maybe = yield* Effect.serviceOption(EventBus);
+		if (Option.isNone(maybe)) return;
+		const filled = (event.ctx.buildId ?? "") === "" ? {
+			...event,
+			ctx: {
+				...event.ctx,
+				buildId: yield* BuildId
+			}
+		} : event;
+		yield* maybe.value.emit(filled);
+	});
 }
 /**
 * Returns true when a bus is in context and has at least one sink admitted at
@@ -29,10 +53,6 @@ function emit(event) {
 function wantsLevel(level) {
 	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.wantsLevel(level) : Effect.succeed(false)));
 }
-/** Bind a runtime so non-Effect (sync island) callbacks can emit. */
-function makeRuntimeEmitter(runtime) {
-	return (event) => runtime.runSync(emit(event));
-}
 
 //#endregion
-export { EventBus, emit, makeEventBusLayer, makeRuntimeEmitter, wantsLevel };
+export { EventBus, emit, makeEventBusLayer, wantsLevel };

package/observability/heartbeat.js

@@ -70,4 +70,4 @@ function runHeartbeat(opts) {
 }
 
 //#endregion
-export { formatProgress, makeProgressEvent, readCounts, runHeartbeat };
+export { formatProgress, makeProgressEvent, runHeartbeat };

package/observability/metric-report.js

@@ -0,0 +1,124 @@
+import { Effect, Metric } from "effect";
+
+//#region src/observability/metric-report.ts
+/**
+* Break any counter down by its attributes, largest first.
+*
+* This is the generic form of what the code-block report does: because Effect
+* keys a registry entry by metric name plus attribute set, a breakdown is a
+* filter over `Metric.snapshot`, not something a sink has to accumulate. Adding
+* a dimension to an existing metric therefore costs a tag at the emit site and
+* nothing here.
+*/
+function seriesFor(snapshots, id) {
+	return snapshots.filter((snap) => snap.id === id && snap.attributes !== void 0).map((snap) => ({
+		attributes: snap.attributes ?? {},
+		value: counterValue(snap.state)
+	})).filter((series) => series.value > 0).sort((a, b) => b.value - a.value);
+}
+const ID_TO_FIELD = new Map(Object.entries({
+	blocks: "codeblock.total",
+	twoslashBlocks: "codeblock.twoslash.total",
+	slowBlocks: "codeblock.slow",
+	totalMs: "codeblock.time.ms",
+	twoslashMs: "codeblock.twoslash.ms",
+	shikiMs: "codeblock.shiki.ms"
+}).map(([field, id]) => [id, field]));
+function emptyBucket() {
+	return {
+		blocks: 0,
+		twoslashBlocks: 0,
+		slowBlocks: 0,
+		totalMs: 0,
+		twoslashMs: 0,
+		shikiMs: 0,
+		otherMs: 0
+	};
+}
+function withOther(bucket) {
+	return {
+		...bucket,
+		otherMs: Math.max(0, bucket.totalMs - bucket.twoslashMs - bucket.shikiMs)
+	};
+}
+function add(a, b) {
+	return withOther({
+		blocks: a.blocks + b.blocks,
+		twoslashBlocks: a.twoslashBlocks + b.twoslashBlocks,
+		slowBlocks: a.slowBlocks + b.slowBlocks,
+		totalMs: a.totalMs + b.totalMs,
+		twoslashMs: a.twoslashMs + b.twoslashMs,
+		shikiMs: a.shikiMs + b.shikiMs,
+		otherMs: 0
+	});
+}
+/** Counter states carry `count`; anything else contributes nothing. */
+function counterValue(state) {
+	if (typeof state !== "object" || state === null || !("count" in state)) return 0;
+	const count = state.count;
+	return typeof count === "number" ? count : Number(count);
+}
+/**
+* Build the code-block report from an explicit set of metric snapshots.
+*
+* Split from {@link codeBlockReport} so it can be exercised without a live
+* metric registry.
+*/
+function codeBlockReportFrom(snapshots) {
+	const bySeries = /* @__PURE__ */ new Map();
+	for (const snap of snapshots) {
+		const field = ID_TO_FIELD.get(snap.id);
+		if (!field || !snap.attributes) continue;
+		const { scope, component, twoslash } = snap.attributes;
+		if (scope === void 0 || component === void 0 || twoslash === void 0) continue;
+		const key = `${scope} ${component} ${twoslash}`;
+		const current = bySeries.get(key) ?? {
+			scope,
+			component,
+			twoslash: twoslash === "true",
+			...emptyBucket()
+		};
+		bySeries.set(key, {
+			...current,
+			[field]: current[field] + counterValue(snap.state)
+		});
+	}
+	const series = [...bySeries.values()].map((s) => ({
+		...s,
+		...withOther(s)
+	})).sort((a, b) => b.totalMs - a.totalMs);
+	let overall = emptyBucket();
+	const byScope = /* @__PURE__ */ new Map();
+	const byComponent = /* @__PURE__ */ new Map();
+	for (const s of series) {
+		overall = add(overall, s);
+		byScope.set(s.scope, add(byScope.get(s.scope) ?? emptyBucket(), s));
+		byComponent.set(s.component, add(byComponent.get(s.component) ?? emptyBucket(), s));
+	}
+	return {
+		overall,
+		series,
+		byScope: Object.fromEntries(byScope),
+		byComponent: Object.fromEntries(byComponent)
+	};
+}
+/** Read the code-block report from the current context's metric registry. */
+const codeBlockReport = Effect.map(Metric.snapshot, codeBlockReportFrom);
+/**
+* Render the report as the console summary lines logged at the end of a build.
+* Returns an empty array when no code block was processed.
+*/
+function formatCodeBlockReport(report) {
+	const { overall } = report;
+	if (overall.blocks === 0) return [];
+	const s = (ms) => `${(ms / 1e3).toFixed(1)}s`;
+	const pct = (ms) => overall.totalMs > 0 ? `${Math.round(ms / overall.totalMs * 100)}%` : "0%";
+	const lines = [`render phase: ${overall.blocks} code blocks in ${s(overall.totalMs)} (twoslash ${s(overall.twoslashMs)} ${pct(overall.twoslashMs)}, shiki ${s(overall.shikiMs)} ${pct(overall.shikiMs)}, other ${s(overall.otherMs)} ${pct(overall.otherMs)})`];
+	const scopes = Object.entries(report.byScope).sort((a, b) => b[1].totalMs - a[1].totalMs);
+	for (const [scope, bucket] of scopes.slice(0, 10)) lines.push(`  ${scope}: ${bucket.blocks} blocks, ${s(bucket.totalMs)} (twoslash ${s(bucket.twoslashMs)}, ${bucket.twoslashBlocks} typechecked)`);
+	if (scopes.length > 10) lines.push(`  and ${scopes.length - 10} more scopes`);
+	return lines;
+}
+
+//#endregion
+export { codeBlockReport, codeBlockReportFrom, formatCodeBlockReport, seriesFor };

package/observability/sinks/console-sink.js

@@ -27,6 +27,12 @@ function render(event) {
 		case "ConfigResolved": return `resolved ${event.baseRoute}: ${event.categoryCount} categories, ${event.externalCount} external`;
 		case "TwoslashDiagnostic": return `Twoslash TS${event.code} in ${event.file}:${event.line}:${event.col}: ${event.message}`;
 		case "TwoslashCheckFailed": return `Twoslash check failed (TS${event.code}) in ${event.file}; ${event.fsMapKeys.length} VFS files`;
+		case "TwoslashCacheLoaded": return event.entries > 0 ? `Twoslash cache: restored ${event.entries} cached result(s)` : "Twoslash cache: cold (no cached results for this type environment)";
+		case "TwoslashCacheSaved": {
+			const total = event.hits + event.misses;
+			const pct = total > 0 ? Math.round(event.hits / total * 100) : 0;
+			return `Twoslash cache: ${event.hits}/${total} hits (${pct}%), ${event.entries} entries${event.persisted ? " (saved)" : ""}`;
+		}
 		case "PageGenerated": return `page ${event.category}/${event.item} (${event.durationMs}ms)`;
 		case "FileDecision": return `${event.status}: ${event.file}`;
 		case "ItemSkipped": return `skipped ${event.kind} "${event.item}": ${event.reason}`;