rspress-plugin-api-extractor 0.11.0 → 0.12.0

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/og-resolver.js

@@ -30,6 +30,37 @@ function resolveOgUrl(siteUrl, url) {
 	if (url.startsWith("http://") || url.startsWith("https://")) return url;
 	if (url.startsWith("/")) return `${siteUrl}${url}`;
 }
+/**
+* Derive the site URL prefix from RSPress's own config.
+*
+* @remarks
+* Replaces the plugin's former `siteUrl` option. RSPress already knows where a
+* site is deployed — {@link https://rspress.rs/api/config/config-basic#siteorigin | `siteOrigin`}
+* plus `base` — so asking for it a second time invited the two to disagree, and
+* a plugin-level answer that contradicted the site's own would silently emit
+* canonical and `og:url` tags pointing at a host the site is not served from.
+*
+* RSPress concatenates as `siteOrigin + base + routePath`, and **this follows
+* its documented fallback exactly**: with no `siteOrigin`, RSPress uses
+* `base + routePath`. So an unset origin yields a ROOT-RELATIVE prefix rather
+* than nothing.
+*
+* That fallback is what makes the tags inspectable in `rspress dev`, where the
+* site is served from `localhost` and no configured origin could be correct
+* anyway. A root-relative `/images/og.png` resolves against the page's own
+* origin in the browser; it is a *relative* path (`images/og.png`, no leading
+* slash) that has no base to resolve against, and this never emits one.
+*
+* @returns The prefix to put in front of a route that already begins with `/`.
+* `""` when the site declares neither `siteOrigin` nor a non-root `base`, which
+* leaves every URL root-relative. Never has a trailing slash, since every
+* caller appends a route starting with `/`.
+*/
+function deriveSiteUrl(siteOrigin, base) {
+	const origin = (siteOrigin ?? "").trim().replace(/\/+$/, "");
+	const path = (base ?? "/").trim();
+	return `${origin}${path === "" || path === "/" ? "" : `/${path.replace(/^\/+/, "").replace(/\/+$/, "")}`}`;
+}
 /** Descriptive alt text for a package's (or one API's) OG image. */
 function ogAltText(packageName, apiName) {
 	return apiName ? `${apiName} - ${packageName} API Documentation` : `${packageName} API Documentation`;
@@ -61,4 +92,4 @@ function createPageMetadata(options) {
 }
 
 //#endregion
-export { createPageMetadata, imageMimeType, ogAltText, resolveOgUrl };
+export { createPageMetadata, deriveSiteUrl, imageMimeType, ogAltText, resolveOgUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -55,7 +55,7 @@
 		"@tsdoctor/bundle": "0.2.0",
 		"@tsdoctor/model": "0.3.0",
 		"@tsdoctor/registry": "0.2.1",
-		"@tsdoctor/snapshot": "0.1.1",
+		"@tsdoctor/snapshot": "0.2.0",
 		"@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

@@ -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,6 +1,25 @@
-import { Context, Data } from "effect";
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { imageMimeType, ogAltText, resolveOgUrl } from "../og-resolver.js";
+import { Context, Data, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageSize } from "image-size";
 
 //#region src/services/OgService.ts
+/**
+* Resolving an API's configured Open Graph image into page metadata.
+*
+* @remarks
+* Replaces the `OpenGraphResolver` class, which did synchronous `node:fs` from
+* inside `Effect.promise`, carried its own sync-island event emitter, and
+* returned `undefined` for all three of its failure modes — indistinguishable
+* from "no image was configured".
+*
+* This is also where phase 4's SEO work lands, which is why the contract is
+* wider than today's single caller needs: it names its failures instead of
+* erasing them.
+*
+* @packageDocumentation
+*/
 const OgImageErrorBase = Data.TaggedError("OgImageError");
 /**
 * A configured OG image that could not be resolved.
@@ -17,7 +36,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 = resolveOgUrl(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 = resolveOgUrl(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