rspress-plugin-api-extractor 0.11.0 → 0.13.0

package/markdown/helpers.js

@@ -5,15 +5,6 @@ import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 
 //#region src/markdown/helpers.ts
 /**
-* Helper utilities for generating markdown API documentation.
-*
-* This module provides shared utility functions used by the page generators
-* for common tasks like preparing Twoslash examples, generating frontmatter,
-* escaping special characters, and sanitizing IDs.
-*
-* @packageDocumentation
-*/
-/**
 * Generate an "Available from" line for items exported from multiple entry points.
 * Returns empty string if only one entry point or none provided.
 */
@@ -118,7 +109,7 @@ function buildPageTitle(entityName, singularName, apiName) {
 * @param description - Page description for SEO
 * @param singularName - The category singular name (e.g., "Class")
 * @param apiName - Optional API/package display name
-* @param ogMetadata - Optional Open Graph metadata for social sharing
+* @param tags - Optional neutral head tags to render into the `head` array
 * @returns YAML frontmatter string
 *
 * @example
@@ -136,30 +127,14 @@ function buildPageTitle(entityName, singularName, apiName) {
 * // ---
 * ```
 */
-function generateFrontmatter(entityName, description, singularName, apiName, ogMetadata) {
+function generateFrontmatter(entityName, description, singularName, apiName, tags) {
 	const title = buildPageTitle(entityName, singularName, apiName);
-	const meta = (property, content) => ["meta", {
-		property,
-		content: cleanYamlValue(content)
-	}];
-	const headEntries = [];
-	if (ogMetadata) {
-		headEntries.push(meta("og:url", `${ogMetadata.siteUrl}${ogMetadata.pageRoute}`));
-		headEntries.push(meta("og:type", ogMetadata.ogType));
-		headEntries.push(meta("og:description", ogMetadata.description));
-		if (ogMetadata.ogImage) {
-			headEntries.push(meta("og:image", ogMetadata.ogImage.url));
-			if (ogMetadata.ogImage.secureUrl) headEntries.push(meta("og:image:secure_url", ogMetadata.ogImage.secureUrl));
-			if (ogMetadata.ogImage.type) headEntries.push(meta("og:image:type", ogMetadata.ogImage.type));
-			if (ogMetadata.ogImage.width) headEntries.push(meta("og:image:width", String(ogMetadata.ogImage.width)));
-			if (ogMetadata.ogImage.height) headEntries.push(meta("og:image:height", String(ogMetadata.ogImage.height)));
-			if (ogMetadata.ogImage.alt) headEntries.push(meta("og:image:alt", ogMetadata.ogImage.alt));
-		}
-		headEntries.push(meta("article:published_time", ogMetadata.publishedTime));
-		headEntries.push(meta("article:modified_time", ogMetadata.modifiedTime));
-		headEntries.push(meta("article:section", ogMetadata.section));
-		for (const tag of ogMetadata.tags) headEntries.push(meta("article:tag", tag));
-	}
+	const headEntries = (tags ?? []).map((tag) => {
+		const attrs = {};
+		for (const [key, value] of Object.entries(tag.attrs)) attrs[key] = cleanYamlValue(value);
+		if (tag.body != null) attrs.children = cleanYamlValue(tag.body);
+		return [tag.tag, attrs];
+	});
 	const data = {
 		title: cleanYamlValue(title),
 		description: cleanYamlValue(description)

package/markdown/shiki-utils.js

@@ -60,7 +60,7 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 * 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`.
+* `ConfigService.layer.ts`.
 */
 function normalizeThemeConfig(theme) {
 	if (!theme) return { ...DEFAULT_SHIKI_THEMES };

package/model-loader.js

@@ -1,5 +1,5 @@
 import { isLoadedModel, isVersionConfig } from "./config-utils.js";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 import { Effect } from "effect";
 import { Model } from "@tsdoctor/model";
@@ -10,8 +10,8 @@ import { Model } from "@tsdoctor/model";
 */
 async function loadPackageJsonFromPath(pkgPath) {
 	const resolvedPath = path.resolve(pkgPath.toString());
-	if (!fs.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
-	const content = fs.readFileSync(resolvedPath, "utf-8");
+	if (!fsSync.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
+	const content = fsSync.readFileSync(resolvedPath, "utf-8");
 	try {
 		return JSON.parse(content);
 	} catch (error) {

package/observability/EventBus.js

@@ -23,9 +23,9 @@ function makeEventBusLayer(sinks) {
 * @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
+* `ctx: { buildId: "" }` — 22 in `ConfigService.layer`, 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
+* `TypeRegistryService.layer`, 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.
 *

package/observability/heartbeat.js

@@ -1,6 +1,6 @@
+import { BuildMetrics } from "../layers/build-metrics.js";
 import { PluginEvent } from "./events.js";
 import { emit } from "./EventBus.js";
-import { BuildMetrics } from "../layers/build-metrics.js";
 import { Duration, Effect, Metric, Ref } from "effect";
 
 //#region src/observability/heartbeat.ts

package/observability/sinks/metrics-sink.js

@@ -18,7 +18,7 @@ import { Metric } from "effect";
 * such as a file path, belongs in a sample-shaped sink instead.
 *
 * Intentionally NOT derived here: `externalPackagesTotal` and `apiVersionsLoaded`
-* remain inline increments in `ConfigServiceLive`. `externalPackagesTotal` counts
+* remain inline increments in `ConfigService.layer`. `externalPackagesTotal` counts
 * CONFIGURED packages via `incrementBy(length)`; the only candidate event,
 * `TypeRegistryEvent{BatchComplete}`, carries an unstructured `detail` string and
 * a `loaded` (SUCCEEDED) count — different semantics, so deriving it here would

package/observability/sinks/trace-sink.js

@@ -1,10 +1,10 @@
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 
 //#region src/observability/sinks/trace-sink.ts
 function openTracePath(p) {
-	fs.mkdirSync(path.dirname(p), { recursive: true });
-	fs.writeFileSync(p, "");
+	fsSync.mkdirSync(path.dirname(p), { recursive: true });
+	fsSync.writeFileSync(p, "");
 }
 /**
 * Create a JSONL trace sink, opening the file eagerly at construction.
@@ -21,7 +21,7 @@ function makeTraceSink(tracePath) {
 		minLevel: "trace",
 		capturesPayload: true,
 		handle: (event) => {
-			fs.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
+			fsSync.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
 		},
 		flush: () => {}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -43,7 +43,7 @@
 		"@effected/jsonc": "^0.8.0",
 		"@effected/markdown": "^0.7.0",
 		"@effected/npm": "^0.12.1",
-		"@effected/package-json": "^0.12.0",
+		"@effected/package-json": "^0.13.0",
 		"@effected/semver": "^0.5.0",
 		"@effected/store": "^0.5.0",
 		"@effected/tsconfig-json": "^0.6.1",
@@ -53,9 +53,10 @@
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
 		"@tsdoctor/bundle": "0.2.0",
-		"@tsdoctor/model": "0.3.0",
+		"@tsdoctor/model": "0.4.0",
 		"@tsdoctor/registry": "0.2.1",
-		"@tsdoctor/snapshot": "0.1.1",
+		"@tsdoctor/seo": "0.1.0",
+		"@tsdoctor/snapshot": "0.2.1",
 		"@typescript/vfs": "^1.6.4",
 		"clsx": "^2.1.1",
 		"effect": "4.0.0-rc.109",

package/plugin.js

@@ -1,44 +1,33 @@
-import { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds } from "./BuildEnv.js";
 import { PluginEvent } from "./observability/events.js";
 import { emit } from "./observability/EventBus.js";
-import { codeBlockReport } from "./observability/metric-report.js";
-import { runHeartbeat } from "./observability/heartbeat.js";
-import { writeIssuesJson } from "./observability/sinks/issues-sink.js";
-import { writeRenderPhaseJson } from "./observability/sinks/render-sink.js";
-import { buildEventBus, logBuildSummary, makeSummaryLoggerLayer } from "./layers/ObservabilityLive.js";
 import { emitSync, installSyncEmitter } from "./observability/sync-emitter.js";
-import { TwoslashEnvironments } from "./services/TwoslashEnvironments.js";
+import { normalizeThemeConfig } from "./markdown/shiki-utils.js";
 import { clearTypeRoutes } from "./twoslash-transformer.js";
+import { TwoslashEnvironments } from "./services/TwoslashEnvironments.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateApiDocs } from "./build-program.js";
 import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
 import { fromDir, fromParentDir } from "./config-helpers.js";
 import { classifyApiConfig, mergeLlmsPluginConfig } from "./config-utils.js";
-import { collectShikiThemes, normalizeThemeConfig } from "./markdown/shiki-utils.js";
 import { resolveObservability } from "./schemas/observability.js";
 import { PluginOptions } from "./schemas/config.js";
-import "./schemas/index.js";
-import { ConfigService } from "./services/ConfigService.js";
-import { PluginConfig } from "./services/PluginConfig.js";
 import { TwoslashCacheService } from "./services/TwoslashCacheService.js";
-import { ConfigServiceLive } from "./layers/ConfigServiceLive.js";
-import { HighlighterServiceLive } from "./layers/HighlighterServiceLive.js";
-import { OgServiceLive } from "./layers/OgServiceLive.js";
-import { PlatformLive } from "./layers/xdg.js";
-import { TwoslashCacheServiceLive } from "./layers/TwoslashCacheServiceLive.js";
-import { TwoslashEnvironmentsLive } from "./layers/TwoslashEnvironmentsLive.js";
-import { TypeRegistryServiceLive } from "./layers/TypeRegistryServiceLive.js";
+import { ConfigService } from "./services/ConfigService.js";
+import { codeBlockReport } from "./observability/metric-report.js";
+import { runHeartbeat } from "./observability/heartbeat.js";
+import { writeIssuesJson } from "./observability/sinks/issues-sink.js";
+import { writeRenderPhaseJson } from "./observability/sinks/render-sink.js";
+import { buildEventBus, logBuildSummary } from "./layers/observability.js";
+import { makeAppLayers } from "./layers/AppLayer.js";
 import { clearTwoslashAccess, installTwoslashAccess, twoslashTransformerFor } from "./twoslash-access.js";
 import { remarkApiCodeblocks } from "./remark-api-codeblocks.js";
 import { remarkWithApi } from "./remark-with-api.js";
 import { createRequire } from "node:module";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { NodeFileSystem } from "@effect/platform-node";
-import { SnapshotServiceLive } from "@tsdoctor/snapshot";
-import { Effect, FileSystem, Layer, ManagedRuntime, Option, Ref, Schema } from "effect";
+import { Effect, FileSystem, ManagedRuntime, Option, Ref, Schema } from "effect";
 
 //#region src/plugin.ts
 /* v8 ignore start -- RSPress plugin adapter, requires RSPress runtime */
@@ -75,14 +64,18 @@ function ApiExtractorPluginImpl(rawOptions) {
 	});
 	const { layer: eventBusLayer, trace: traceSink, issues: issuesSink, render: renderSink, metrics: metricStore } = buildEventBus(obs);
 	const dbPath = path.resolve(process.cwd(), ".api-docs", "snapshot", "api-docs.db");
-	fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-	const BuildEnvLayer = Layer.mergeAll(Layer.succeed(BuildId, buildId), Layer.succeed(Thresholds, obs.thresholds), Layer.succeed(PageConcurrency, os.cpus().length), Layer.succeed(SuppressExampleErrors, options.errors?.example !== "show"));
-	const PluginConfigLive = Layer.succeed(PluginConfig, options);
-	const HighlighterLive = HighlighterServiceLive(collectShikiThemes(options.api ? [options.api] : options.apis ?? []));
-	const BaseLayer = Layer.mergeAll(eventBusLayer, PluginConfigLive, HighlighterLive, TwoslashEnvironmentsLive, Layer.provide(OgServiceLive, PlatformLive), BuildEnvLayer, metricStore.layer, TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath), TwoslashCacheServiceLive, makeSummaryLoggerLayer(obs.logLevel));
-	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive, BaseLayer);
-	const effectRuntime = ManagedRuntime.make(EffectAppLayer);
-	const emitterRuntime = ManagedRuntime.make(Layer.mergeAll(eventBusLayer, metricStore.layer, makeSummaryLoggerLayer(obs.logLevel), BuildEnvLayer));
+	fsSync.mkdirSync(path.dirname(dbPath), { recursive: true });
+	const appLayers = makeAppLayers({
+		options,
+		obs,
+		buildId,
+		dbPath,
+		pageConcurrency: os.cpus().length,
+		eventBus: eventBusLayer,
+		metrics: metricStore
+	});
+	const effectRuntime = ManagedRuntime.make(appLayers.app);
+	const emitterRuntime = ManagedRuntime.make(appLayers.emitter);
 	installSyncEmitter(emitterRuntime);
 	const fileContextMap = /* @__PURE__ */ new Map();
 	let docsRoot;
@@ -153,6 +146,8 @@ function ApiExtractorPluginImpl(rawOptions) {
 			const rspressLocales = _config.locales?.map((l) => l.lang) ?? [];
 			const rspressLang = _config.lang;
 			const rspressMultiVersion = _config.multiVersion;
+			const rspressSiteOrigin = _config.siteOrigin;
+			const rspressBase = _config.base;
 			rspressLlmsEnabled = Boolean(_config.llms);
 			rspressOutDir = _config.outDir ?? "dist";
 			if (options.api) {
@@ -169,7 +164,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 					versions,
 					defaultVersion: rspressMultiVersion?.default
 				});
-				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+				for (const dp of derivedPaths) fsSync.mkdirSync(dp.outputDir, { recursive: true });
 			} else if (options.apis) for (const api of options.apis) {
 				const baseRoute = normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
 				const derivedPaths = deriveOutputPaths({
@@ -182,7 +177,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 					versions: [],
 					defaultVersion: void 0
 				});
-				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+				for (const dp of derivedPaths) fsSync.mkdirSync(dp.outputDir, { recursive: true });
 			}
 			VfsRegistry.clear();
 			clearTwoslashAccess();
@@ -200,7 +195,9 @@ function ApiExtractorPluginImpl(rawOptions) {
 					...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
 					...rspressLocales.length > 0 ? { locales: rspressLocales.map((lang) => ({ lang })) } : {},
 					...rspressLang != null ? { lang: rspressLang } : {},
-					...docsRoot != null ? { root: docsRoot } : {}
+					...docsRoot != null ? { root: docsRoot } : {},
+					...rspressSiteOrigin != null ? { siteOrigin: rspressSiteOrigin } : {},
+					...rspressBase != null ? { base: rspressBase } : {}
 				};
 				await effectRuntime.runPromise(Effect.gen(function* () {
 					const apiCount = options.api ? 1 : options.apis?.length ?? 0;

package/prettier-formatter.js

@@ -1,5 +1,5 @@
-import { PluginEvent } from "./observability/events.js";
 import { addLogicalBlankLines } from "./code-post-processor.js";
+import { PluginEvent } from "./observability/events.js";
 import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
 import { format } from "prettier";
 

package/remark-api-codeblocks.js

@@ -1,7 +1,7 @@
 import { PluginEvent } from "./observability/events.js";
 import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
-import { VfsRegistry } from "./vfs-registry.js";
 import { generateShikiHast } from "./markdown/shiki-utils.js";
+import { VfsRegistry } from "./vfs-registry.js";
 import { setTwoslashFile } from "./twoslash-access.js";
 import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { visit } from "unist-util-visit";

package/remark-with-api.js

@@ -2,8 +2,8 @@ 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 { VfsRegistry } from "./vfs-registry.js";
 import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { VfsRegistry } from "./vfs-registry.js";
 import { setTwoslashFile } from "./twoslash-access.js";
 import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { codeToHast, hastToHtml } from "shiki";

package/schemas/config.js

@@ -1,7 +1,7 @@
 import { PerformanceConfig } from "./performance.js";
 import { ObservabilityConfig } from "./observability.js";
-import { OpenGraphImageConfig } from "./opengraph.js";
 import { Effect, Schema } from "effect";
+import { OpenGraphImageConfig } from "@tsdoctor/seo";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 
 //#region src/schemas/config.ts
@@ -304,8 +304,6 @@ const PluginOptions = Schema.Struct({
 	api: Schema.optional(Schema.NullOr(SingleApiConfig)),
 	/** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
 	apis: Schema.optional(Schema.NullOr(Schema.mutable(Schema.Array(MultiApiConfig)))),
-	/** Canonical site URL used for Open Graph absolute URLs. */
-	siteUrl: Schema.optional(Schema.String),
 	/** Global Open Graph image configuration (overridden per-API). */
 	ogImage: Schema.optional(OpenGraphImageConfig),
 	/** Override the default category definitions for all APIs. */

package/services/ConfigService.js

@@ -1,7 +1,42 @@
-import { Context } from "effect";
+import { makeConfigService } from "../layers/config-resolution.js";
+import { Context, Effect, Layer } from "effect";
 
 //#region src/services/ConfigService.ts
-var ConfigService = class extends Context.Service()("rspress-plugin-api-extractor/ConfigService") {};
+var ConfigService = class ConfigService extends Context.Service()("rspress-plugin-api-extractor/ConfigService") {
+	/**
+	* Config resolution over the plugin options and the RSPress config.
+	*
+	* @remarks
+	* A plain `const`, not a factory. It used to take the plugin options as an
+	* argument, which made it a layer-RETURNING function: layers memoize by
+	* reference, so a second call would build a second `ConfigService` with its
+	* own captured `TypeRegistry`. The options come from {@link PluginConfig}
+	* now, so there is nothing to pass and "call it twice" is a type error
+	* rather than a test case.
+	*
+	* `Effect.suspend` because {@link makeConfigService} is imported from a
+	* module this one is also imported BY: a static initializer runs while the
+	* module body is still evaluating, so reading the binding eagerly can throw
+	* at import time with a completely clean typecheck.
+	*/
+	static layer = Layer.effect(this, Effect.suspend(() => makeConfigService));
+	/**
+	* An in-memory double whose unstubbed member dies naming itself.
+	*
+	* @remarks
+	* **No default `resolve`.** Returning an empty array by default would be a
+	* silent "this site documents nothing" — the exact state an inert plugin
+	* produces — so a test that forgot to stub it would assert against a build
+	* that generated no pages and pass. Stub it explicitly, or provide
+	* {@link ConfigService.layer} over real inputs.
+	*/
+	static makeTest = (overrides = {}) => ({ resolve: overrides.resolve ?? (() => unstubbed("resolve")) });
+	/** {@link ConfigService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ConfigService, ConfigService.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`ConfigService.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
 
 //#endregion
 export { ConfigService };

package/services/HighlighterService.js

@@ -1,4 +1,8 @@
-import { Context } from "effect";
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { SHIKI_LANGS } from "../markdown/shiki-utils.js";
+import { Context, Effect, Layer } from "effect";
+import { createHighlighter } from "shiki";
 
 //#region src/services/HighlighterService.ts
 /**
@@ -6,7 +10,7 @@ import { Context } from "effect";
 *
 * @remarks
 * A highlighter owns a WASM oniguruma instance and every loaded grammar and
-* theme, and it has a `dispose()` nobody was calling: `ConfigServiceLive`
+* theme, and it has a `dispose()` nobody was calling: `ConfigService.layer`
 * 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.
@@ -24,7 +28,48 @@ import { Context } from "effect";
 *
 * @packageDocumentation
 */
-var HighlighterService = class extends Context.Service()("rspress-plugin-api-extractor/HighlighterService") {};
+var HighlighterService = class extends Context.Service()("rspress-plugin-api-extractor/HighlighterService") {
+	/**
+	* Acquire the build's highlighter, and release it when the runtime is
+	* disposed.
+	*
+	* @remarks
+	* `Layer.effect` over `Effect.acquireRelease` is the v4 scoped-constructor
+	* idiom (`Layer.scoped` is gone; `Layer.effect` strips `Scope` from `R`).
+	* Because the layer sits in the `ManagedRuntime`'s stack, the highlighter is
+	* created on the runtime's first use and `dispose()`d by
+	* `effectRuntime.dispose()` — which `plugin.ts` calls on production builds
+	* only, so a dev HMR session keeps one highlighter across rebuilds instead of
+	* leaking one per rebuild.
+	*
+	* **Bind the result to a `const`.** This is a layer FACTORY: each call mints a
+	* fresh layer reference, and layers memoize by reference, so calling it twice
+	* in one graph acquires two highlighters — the exact leak this layer exists to
+	* fix.
+	*
+	* The themes are passed in rather than read from a resolved build context
+	* because the layer builds before `ConfigService.resolve()` runs. Passing them
+	* as an argument rather than through a `Context.Reference` is deliberate: a
+	* Reference carries a default, so forgetting to wire it would silently load
+	* only the default themes and render every custom-themed block wrong. A
+	* missing argument is a type error.
+	*/
+	static layer = (themes) => Layer.effect(this, make(themes));
+};
+const make = (themes) => Effect.gen(function* () {
+	const startedMs = performance.now();
+	const highlighter = yield* Effect.acquireRelease(Effect.promise(() => createHighlighter({
+		themes: [...themes],
+		langs: [...SHIKI_LANGS]
+	})), (instance) => Effect.sync(() => instance.dispose()));
+	yield* emit(PluginEvent.PhaseCompleted({
+		ctx: {},
+		level: "debug",
+		phase: "shikiInit",
+		durationMs: Math.round(performance.now() - startedMs)
+	}));
+	return { highlighter };
+});
 
 //#endregion
 export { HighlighterService };

package/services/OgService.js

@@ -1,4 +1,8 @@
-import { Context, Data } from "effect";
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { Context, Data, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageMimeType, ogAltText, resolveUrl } from "@tsdoctor/seo";
+import { imageSize } from "image-size";
 
 //#region src/services/OgService.ts
 const OgImageErrorBase = Data.TaggedError("OgImageError");
@@ -17,7 +21,155 @@ var OgImageError = class extends OgImageErrorBase {
 		return `Could not read Open Graph image '${this.value}': ${cause}`;
 	}
 };
-var OgService = class extends Context.Service()("rspress-plugin-api-extractor/OgService") {};
+var OgService = class OgService extends Context.Service()("rspress-plugin-api-extractor/OgService") {
+	/**
+	* Resolve OG images through the core `FileSystem`, with one read per file per
+	* build.
+	*
+	* @remarks
+	* The `node:fs` `existsSync` + `imageSizeFromFile` pair this replaces ran once
+	* per PAGE, so a 400-page API re-read the same image 400 times. The memo below
+	* keys on the absolute path and removes that entirely.
+	*
+	* The memo is per build, not persisted. A cross-build cache in the shared XDG
+	* store was considered and deliberately deferred: it would need mtime/size
+	* invalidation to stay sound, and a stale image dimension is a silent wrong
+	* answer. There is nothing expensive enough here to justify that yet — when
+	* phase 4 starts GENERATING images, which are expensive and content-addressed,
+	* the XDG cache is the right home for them.
+	*
+	* `imageSize` over the read bytes replaces `imageSizeFromFile`, which took a
+	* path and therefore required real `node:fs`. Same parser, same output.
+	*
+	* `Effect.suspend(() => make())` rather than a bare `make`: a static
+	* initializer runs while the module body is still evaluating, so naming a
+	* `const` declared further down throws at import time with a clean typecheck.
+	*/
+	static layer = Layer.effect(this, Effect.suspend(() => make()));
+	/**
+	* An in-memory double whose unstubbed member dies naming itself.
+	*
+	* @remarks
+	* **There is deliberately no default `resolveImage`.** A default returning
+	* `Option.none` would be indistinguishable from "this API declares no
+	* image", which is precisely the ambiguity {@link OgImageError} exists to
+	* remove — and a test asserting that a page rendered without an `og:image`
+	* would then pass whether or not the service was ever consulted.
+	*
+	* Where the wiring is what matters, prefer the real layer over a platform
+	* filesystem instead of this double; see `__test__/utils/layers.ts`.
+	*/
+	static makeTest = (overrides = {}) => ({ resolveImage: overrides.resolveImage ?? (() => unstubbed("resolveImage")) });
+	/** {@link OgService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(OgService, OgService.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`OgService.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const make = () => Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	/** Absolute path → facts, or `null` for "looked, could not use it". */
+	const factsByPath = /* @__PURE__ */ new Map();
+	/** Locate a root-relative image under the docs `public/` directory. */
+	const findLocalImage = (imagePath, docsRoot) => {
+		if (docsRoot == null || !imagePath.startsWith("/")) return Effect.succeed(Option.none());
+		const candidate = path.join(docsRoot, "public", imagePath);
+		return fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false), Effect.map((found) => found ? Option.some(candidate) : Option.none()));
+	};
+	/**
+	* Read dimensions and MIME type. A file that cannot be parsed warns and
+	* yields nothing — the page still gets its `og:image`, just without
+	* dimensions, which is what the class this replaced did.
+	*/
+	const readImageFacts = (filePath) => Effect.gen(function* () {
+		const memoed = factsByPath.get(filePath);
+		if (memoed !== void 0) return memoed;
+		const result = yield* Effect.result(fileSystem.readFile(filePath).pipe(Effect.flatMap((bytes) => Effect.try(() => imageSize(bytes)))));
+		if (result._tag === "Failure") {
+			const error = new OgImageError({
+				code: "unreadable-image",
+				field: "ogImage",
+				value: filePath,
+				cause: result.failure
+			});
+			yield* emit(PluginEvent.ConfigValidationWarning({
+				ctx: {},
+				field: "ogImage",
+				value: filePath,
+				reason: error.message,
+				level: "warn"
+			}));
+			factsByPath.set(filePath, null);
+			return null;
+		}
+		const size = result.success;
+		const mimeType = imageMimeType(size.type);
+		const facts = {
+			...size.width != null ? { width: size.width } : {},
+			...size.height != null ? { height: size.height } : {},
+			...mimeType != null ? { type: mimeType } : {}
+		};
+		factsByPath.set(filePath, facts);
+		return facts;
+	});
+	const resolveFromString = (imageUrl, request) => Effect.gen(function* () {
+		const resolvedUrl = resolveUrl(request.siteUrl, imageUrl);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage",
+			value: imageUrl
+		}));
+		const localPath = yield* findLocalImage(imageUrl, request.docsRoot);
+		const facts = Option.isSome(localPath) ? yield* readImageFacts(localPath.value) : null;
+		return Option.some({
+			url: resolvedUrl,
+			type: facts?.type,
+			width: facts?.width,
+			height: facts?.height,
+			alt: ogAltText(request.packageName, request.apiName)
+		});
+	});
+	const resolveFromMetadata = (metadata, request) => Effect.gen(function* () {
+		const { url, secureUrl, type, width, height, alt } = metadata;
+		const resolvedUrl = resolveUrl(request.siteUrl, url);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage.url",
+			value: url
+		}));
+		let resolvedSecureUrl;
+		if (secureUrl != null) {
+			if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
+			else {
+				const error = new OgImageError({
+					code: "invalid-secure-url",
+					field: "ogImage.secureUrl",
+					value: secureUrl
+				});
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {},
+					field: "ogImage.secureUrl",
+					value: secureUrl,
+					reason: error.message,
+					level: "warn"
+				}));
+			}
+		}
+		return Option.some({
+			url: resolvedUrl,
+			secureUrl: resolvedSecureUrl,
+			type,
+			width,
+			height,
+			alt: alt ?? ogAltText(request.packageName, request.apiName)
+		});
+	});
+	return { resolveImage: (request) => {
+		if (request.config == null) return Effect.succeed(Option.none());
+		return typeof request.config === "object" ? resolveFromMetadata(request.config, request) : resolveFromString(request.config, request);
+	} };
+});
 
 //#endregion
 export { OgImageError, OgService };

package/services/PluginConfig.js

@@ -5,7 +5,7 @@ import { Context } from "effect";
 * The decoded plugin options, as a service.
 *
 * @remarks
-* `ConfigServiceLive` used to be a factory taking these as an argument, which
+* `ConfigService.layer` 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