rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/BuildEnv.js

@@ -0,0 +1,58 @@
+import { Context } from "effect";
+
+//#region src/BuildEnv.ts
+/**
+* Per-build configuration, as `Context.Reference` values rather than threaded
+* parameters.
+*
+* @remarks
+* Each of these used to travel by hand. `thresholds` made a four-hop journey —
+* `plugin.ts` → `ConfigService.layer`'s fourth constructor argument →
+* a `ResolvedBuildContext` field → destructured in `build-program.ts` → every
+* `withPhase` call — while `obs.thresholds` already held the same value one
+* scope away. `buildId` was worse: 24 event emit sites wrote
+* `ctx: { buildId: "" }` because the value was not reachable from where they
+* stood, and in `TypeRegistryService.layer` it genuinely was not — that layer is
+* module-level and has no build to name. A Reference is the fix precisely
+* because it reaches module-level code that no parameter can.
+*
+* A `Context.Reference` carries a default, so nothing has to provide these for
+* a program to run. That is convenient and it is also the hazard: a wiring
+* mistake does not fail, it silently substitutes the default. The tests for
+* this module provide NON-default values and assert the provided value is the
+* one observed, which is the only way to tell the two apart.
+*
+* @packageDocumentation
+*/
+/**
+* Identifier correlating every event emitted by one build.
+*
+* @remarks
+* The empty-string default is deliberate: an event emitted outside a build —
+* a test, a stray sync callback — is better tagged empty than crashing. Every
+* production path provides a real id.
+*/
+const BuildId = Context.Reference("rspress-plugin-api-extractor/BuildId", { defaultValue: () => "" });
+/** Duration thresholds above which an operation is reported as slow. */
+const Thresholds = Context.Reference("rspress-plugin-api-extractor/Thresholds", { defaultValue: () => ({
+	slowCodeBlock: 100,
+	slowPageGeneration: 500,
+	slowApiLoad: 1e3,
+	slowFileOperation: 50,
+	slowHttpRequest: 2e3,
+	slowDbOperation: 100
+}) });
+/**
+* How many pages the build pipeline generates concurrently.
+*
+* @remarks
+* Defaults to the CPU count, which is what `ConfigService.layer` computed
+* inline. Kept a Reference rather than a constant so a consumer with a
+* constrained CI runner can lower it without a code change.
+*/
+const PageConcurrency = Context.Reference("rspress-plugin-api-extractor/PageConcurrency", { defaultValue: () => 1 });
+/** Whether Twoslash diagnostics inside `@example` blocks are suppressed. */
+const SuppressExampleErrors = Context.Reference("rspress-plugin-api-extractor/SuppressExampleErrors", { defaultValue: () => true });
+
+//#endregion
+export { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds };

package/build-program.js

@@ -1,12 +1,16 @@
+import { BuildId, PageConcurrency, SuppressExampleErrors } from "./BuildEnv.js";
 import { setProseLinker } from "./markdown/prose-linker.js";
-import "./markdown/index.js";
 import { buildPipelineForApi, cleanupAndCommit, prepareWorkItems, writeMetadata } from "./build-stages.js";
+import { HideCutLinesTransformer, MemberFormatTransformer } from "./hide-cut-transformer.js";
 import { withPhase } from "./observability/spans.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { HighlighterService } from "./services/HighlighterService.js";
+import { addTypeRoutes } from "./twoslash-transformer.js";
+import { TwoslashEnvironments } from "./services/TwoslashEnvironments.js";
+import { ShikiCrossLinker } from "./shiki-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import path from "node:path";
-import { SnapshotService } from "@tsdoctor/snapshot";
 import { Effect, FileSystem } from "effect";
+import { SnapshotService } from "@tsdoctor/snapshot";
 
 //#region src/build-program.ts
 /**
@@ -22,17 +26,17 @@ import { Effect, FileSystem } from "effect";
 * Returns build result metadata including CrossLinkData for cross-link merging
 * and generated file paths for LLMs post-processing.
 */
-function generateApiDocs(apiConfig, buildContext, fileContextMap) {
+function generateApiDocs(apiConfig, fileContextMap) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
+		const { highlighter } = yield* HighlighterService;
+		const environments = yield* TwoslashEnvironments;
+		const buildId = yield* BuildId;
+		const pageConcurrency = yield* PageConcurrency;
+		const suppressExampleErrors = yield* SuppressExampleErrors;
 		const snapshotSvc = yield* SnapshotService;
 		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage } = apiConfig;
-		const suppressExampleErrors = apiConfig.suppressExampleErrors ?? true;
-		const { shikiCrossLinker, highlighter, hideCutTransformer, hideCutLinesTransformer, twoslashTransformer, ogResolver, pageConcurrency, thresholds, buildId } = buildContext;
-		const phaseCtx = {
-			buildId,
-			packageName
-		};
+		const phaseCtx = { packageName };
 		const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
 		const buildTime = (/* @__PURE__ */ new Date()).toISOString();
 		const allSnapshots = yield* snapshotSvc.getAllForDirectory(resolvedOutputDir).pipe(Effect.orDie);
@@ -43,29 +47,27 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			categories,
 			baseRoute,
 			packageName
-		})), thresholds);
+		})));
 		setProseLinker(crossLinkData.routes);
 		const apiScope = baseRoute.replace(/^\//, "").split("/")[0] || packageName;
-		shikiCrossLinker.reinitialize(crossLinkData.routes, crossLinkData.kinds, apiScope);
-		TwoslashManager.addTypeRoutes(crossLinkData.routes);
-		if (highlighter) {
-			const vfsConfig = {
-				vfs: /* @__PURE__ */ new Map(),
-				highlighter,
-				crossLinker: shikiCrossLinker,
-				packageName,
-				apiScope
-			};
-			const scopeTransformer = TwoslashManager.getInstance().getTransformer(apiScope) ?? twoslashTransformer;
-			if (scopeTransformer != null) vfsConfig.twoslashTransformer = scopeTransformer;
-			if (hideCutTransformer != null) vfsConfig.hideCutTransformer = hideCutTransformer;
-			if (hideCutLinesTransformer != null) vfsConfig.hideCutLinesTransformer = hideCutLinesTransformer;
-			if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
-			VfsRegistry.register(apiScope, vfsConfig);
-		}
+		const shikiCrossLinker = ShikiCrossLinker.fromRoutes(crossLinkData.routes, crossLinkData.kinds, apiScope);
+		addTypeRoutes(crossLinkData.routes);
+		const vfsConfig = {
+			highlighter,
+			crossLinker: shikiCrossLinker,
+			packageName,
+			apiScope
+		};
+		const scopeTransformer = environments.transformerFor(apiScope);
+		if (scopeTransformer != null) vfsConfig.twoslashTransformer = scopeTransformer;
+		vfsConfig.hideCutTransformer = MemberFormatTransformer;
+		vfsConfig.hideCutLinesTransformer = HideCutLinesTransformer;
+		if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
+		VfsRegistry.register(apiScope, vfsConfig);
 		yield* Effect.logDebug(`Generating ${workItems.length} pages across ${Object.keys(categories).length} categories in parallel`);
 		const fileResults = yield* withPhase("generate", phaseCtx, buildPipelineForApi({
 			buildId,
+			pageConcurrency,
 			workItems,
 			baseRoute,
 			packageName,
@@ -74,14 +76,13 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			...source != null ? { source } : {},
 			buildTime,
 			resolvedOutputDir,
-			pageConcurrency,
 			existingSnapshots,
 			...suppressExampleErrors != null ? { suppressExampleErrors } : {},
 			...llmsPlugin != null ? { llmsPlugin } : {},
-			...ogResolver !== void 0 ? { ogResolver } : {},
+			...apiConfig.docsRoot != null ? { docsRoot: apiConfig.docsRoot } : {},
 			...siteUrl != null ? { siteUrl } : {},
 			...ogImage != null ? { ogImage } : {}
-		}), thresholds);
+		}));
 		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
 		yield* Effect.logDebug(`Generated ${changedCount} pages`);
 		const generatedFiles = /* @__PURE__ */ new Set();
@@ -103,13 +104,13 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			packageName,
 			...apiName != null ? { apiName } : {},
 			generatedFiles
-		}), thresholds);
+		}));
 		yield* withPhase("cleanup", phaseCtx, cleanupAndCommit({
 			buildId,
 			fileResults,
 			resolvedOutputDir,
 			generatedFiles
-		}), thresholds);
+		}));
 		yield* Effect.logDebug(`Generated ${changedCount} API documentation files for ${packageName}`);
 		return {
 			crossLinkData,

package/build-stages.js

@@ -1,8 +1,8 @@
 import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.js";
+import { BuildMetrics } from "./layers/build-metrics.js";
 import { PluginEvent } from "./observability/events.js";
 import { emit } from "./observability/EventBus.js";
-import { BuildMetrics } from "./layers/build-metrics.js";
-import "./layers/ObservabilityLive.js";
+import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
 import { generateFrontmatter } from "./markdown/helpers.js";
 import { ClassPageGenerator } from "./markdown/page-generators/class-page.js";
 import { EnumPageGenerator } from "./markdown/page-generators/enum-page.js";
@@ -12,11 +12,11 @@ import { InterfacePageGenerator } from "./markdown/page-generators/interface-pag
 import { NamespacePageGenerator } from "./markdown/page-generators/namespace-page.js";
 import { TypeAliasPageGenerator } from "./markdown/page-generators/type-alias-page.js";
 import { VariablePageGenerator } from "./markdown/page-generators/variable-page.js";
-import "./markdown/index.js";
-import { OpenGraphResolver } from "./og-resolver.js";
+import { createPageMetadata } from "./og-resolver.js";
+import { OgService } from "./services/OgService.js";
 import path from "node:path";
+import { Effect, FileSystem, Metric, Option, Stream } from "effect";
 import { SnapshotService, hashContent, hashFrontmatter } from "@tsdoctor/snapshot";
-import { Effect, FileSystem, Metric, Stream } from "effect";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
 
@@ -41,24 +41,6 @@ function crossLinkKindPriority(kind) {
 	return CROSS_LINK_KIND_PRIORITY[kind] ?? 100;
 }
 /**
-* Module-level emitter seam. `prepareWorkItems` runs synchronously outside any
-* Effect fiber, so a route collision cannot `yield* emit(...)` — it mirrors the
-* sync-island pattern used by `twoslash-transformer.ts` (`setEventEmitter`) and
-* `loader.ts` (`setLoaderEventEmitter`). Default is a no-op; wired in plugin.ts
-* via `setBuildStagesEventEmitter(emitSync, buildId)` right after the runtime
-* emitter is created.
-*/
-let emitEvent = () => {};
-let currentBuildId = "";
-/**
-* Inject the runtime-bound emitter into the build-stages module.
-* Call this right after `makeRuntimeEmitter` in plugin.ts.
-*/
-function setBuildStagesEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
-/**
 * Prepare the flat list of WorkItems to process and the cross-link data maps.
 *
 * This function:
@@ -82,8 +64,8 @@ function prepareWorkItems(input) {
 		resolvedLookup.set(key, resolved);
 	}
 	const { items, uncategorized } = ApiItems.categorize(docItems, categories);
-	for (const skipped of uncategorized) emitEvent(PluginEvent.ItemSkipped({
-		ctx: { buildId: currentBuildId },
+	for (const skipped of uncategorized) emitSync(PluginEvent.ItemSkipped({
+		ctx: { buildId: syncBuildId() },
 		item: skipped.displayName,
 		kind: String(skipped.kind),
 		reason: "uncategorized",
@@ -115,9 +97,9 @@ function prepareWorkItems(input) {
 	const collisions = Routes.detectCollisions(candidates);
 	if (collisions.length > 0) {
 		try {
-			for (const collision of collisions) emitEvent(PluginEvent.RouteCollisionDetected({
+			for (const collision of collisions) emitSync(PluginEvent.RouteCollisionDetected({
 				ctx: {
-					buildId: currentBuildId,
+					buildId: syncBuildId(),
 					route: collision.route
 				},
 				level: "error",
@@ -145,13 +127,14 @@ function prepareWorkItems(input) {
 			}
 			if (item.kind === "Class" || item.kind === "Interface") {
 				const itemWithMembers = item;
-				for (const member of itemWithMembers.members) {
-					const memberName = member.displayName;
-					const memberId = Routes.sanitizeId(memberName);
-					const fullMemberName = `${item.displayName}.${memberName}`;
-					const memberRoute = `${itemRoute}#${memberId}`;
-					routes.set(fullMemberName, memberRoute);
-					kinds.set(fullMemberName, member.kind);
+				const anchors = ApiItems.memberAnchors(itemWithMembers);
+				const byCanonicalRef = new Map(itemWithMembers.members.map((member) => [member.canonicalReference?.toString() ?? member.displayName, member]));
+				for (const [routeKey, memberId] of ApiItems.memberRouteKeys(itemWithMembers)) {
+					const member = byCanonicalRef.get(memberId);
+					if (!member) continue;
+					const anchor = anchors.get(memberId) ?? Routes.memberAnchor(member.displayName);
+					routes.set(routeKey, `${itemRoute}#${anchor}`);
+					kinds.set(routeKey, member.kind);
 				}
 			}
 		}
@@ -190,12 +173,14 @@ function prepareWorkItems(input) {
 			const lookupKey = `${item.displayName}::${item.kind}`;
 			const resolved = resolvedLookup.get(lookupKey);
 			const syntheticBase = syntheticBases.baseByOwner.get(item);
+			const memberAnchors = item.kind === "Class" || item.kind === "Interface" ? ApiItems.memberAnchors(item) : void 0;
 			workItems.push({
 				item,
 				categoryKey,
 				categoryConfig,
 				...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {},
-				...syntheticBase != null ? { syntheticBase } : {}
+				...syntheticBase != null ? { syntheticBase } : {},
+				...memberAnchors != null ? { memberAnchors } : {}
 			});
 		}
 	}
@@ -240,7 +225,7 @@ function generateSinglePage(workItem, ctx) {
 		switch (item.kind) {
 			case ApiItemKind.Class: {
 				const generator = new ClassPageGenerator();
-				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom, workItem.syntheticBase));
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom, workItem.syntheticBase, workItem.memberAnchors));
 				page = {
 					routePath: page.routePath.replace("/class/", `/${categoryConfig.folderName}/`),
 					content: page.content
@@ -402,7 +387,7 @@ function generateSinglePage(workItem, ctx) {
 function writeSingleFile(result, ctx) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
-		const { buildId, resolvedOutputDir, buildTime, ogResolver, siteUrl, ogImage, packageName, apiName } = ctx;
+		const { buildId, resolvedOutputDir, buildTime, siteUrl, docsRoot, ogImage, packageName, apiName } = ctx;
 		const { workItem, bodyContent, frontmatter, contentHash, frontmatterHash, publishedTime, modifiedTime, isUnchanged, routePath, relativePathWithExt } = result;
 		const { item, categoryKey, categoryConfig, namespaceMember } = workItem;
 		const absolutePath = path.join(resolvedOutputDir, relativePathWithExt);
@@ -440,8 +425,29 @@ function writeSingleFile(result, ctx) {
 			};
 		}
 		let finalContent = stringifyFrontmatter(bodyContent, frontmatter);
-		if (ogResolver && siteUrl && packageName) {
-			const ogImageMetadata = yield* Effect.promise(() => ogResolver.resolve(ogImage, packageName, apiName));
+		if (siteUrl != null && packageName) {
+			const ogSvc = yield* OgService;
+			const ogImageResult = yield* Effect.result(ogSvc.resolveImage({
+				config: ogImage,
+				siteUrl,
+				docsRoot,
+				packageName,
+				...apiName != null ? { apiName } : {}
+			}));
+			if (ogImageResult._tag === "Failure") {
+				const failure = ogImageResult.failure;
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {
+						buildId,
+						packageName
+					},
+					field: failure.field,
+					value: failure.value,
+					reason: failure.message,
+					level: "warn"
+				}));
+			}
+			const ogImageMetadata = ogImageResult._tag === "Success" && Option.isSome(ogImageResult.success) ? ogImageResult.success.value : void 0;
 			const ogMetadataOptions = {
 				siteUrl,
 				pageRoute: routePath,
@@ -452,7 +458,7 @@ function writeSingleFile(result, ctx) {
 				packageName
 			};
 			if (ogImageMetadata) ogMetadataOptions.ogImage = ogImageMetadata;
-			const ogMetadata = OpenGraphResolver.createPageMetadata(ogMetadataOptions);
+			const ogMetadata = createPageMetadata(ogMetadataOptions);
 			finalContent = generateFrontmatter(item.displayName, frontmatter.description, categoryConfig.singularName, apiName, ogMetadata) + bodyContent;
 		}
 		const fileExisted = yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false));
@@ -793,7 +799,7 @@ function buildPipelineForApi(input) {
 		buildId: input.buildId,
 		resolvedOutputDir: input.resolvedOutputDir,
 		buildTime: input.buildTime,
-		...input.ogResolver !== void 0 ? { ogResolver: input.ogResolver } : {},
+		...input.docsRoot !== void 0 ? { docsRoot: input.docsRoot } : {},
 		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
 		...input.ogImage != null ? { ogImage: input.ogImage } : {},
 		...input.packageName != null ? { packageName: input.packageName } : {},
@@ -803,4 +809,4 @@ function buildPipelineForApi(input) {
 }
 
 //#endregion
-export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, prepareWorkItems, setBuildStagesEventEmitter, writeMetadata, writeSingleFile };
+export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, prepareWorkItems, writeMetadata, writeSingleFile };

package/config-helpers.js

@@ -1,6 +1,6 @@
 import { normalizeBaseRoute } from "./path-derivation.js";
 import { SyncDiscoveryLayer } from "./sync-node-fs.js";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 import { Effect, Result } from "effect";
 import { discoverBundle } from "@tsdoctor/bundle";
@@ -18,14 +18,14 @@ const PREFIX = "[rspress-plugin-api-extractor]";
 function requirePackageJson(dir) {
 	let stat;
 	try {
-		stat = fs.statSync(dir);
+		stat = fsSync.statSync(dir);
 	} catch {
 		throw new Error(`${PREFIX} api.fromDir: directory not found: ${dir}`);
 	}
 	if (!stat.isDirectory()) throw new Error(`${PREFIX} api.fromDir: not a directory: ${dir}`);
 	let pkg;
 	try {
-		pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+		pkg = JSON.parse(fsSync.readFileSync(path.join(dir, "package.json"), "utf8"));
 	} catch {
 		throw new Error(`${PREFIX} api.fromDir: missing or unreadable package.json in ${dir}`);
 	}
@@ -103,9 +103,9 @@ function fromDir(dir, overrides = {}) {
 	};
 }
 function isModelFolder(dir) {
-	if (!fs.existsSync(path.join(dir, "package.json"))) return false;
+	if (!fsSync.existsSync(path.join(dir, "package.json"))) return false;
 	try {
-		return fs.readdirSync(dir).some((f) => f.endsWith(".api.json"));
+		return fsSync.readdirSync(dir).some((f) => f.endsWith(".api.json"));
 	} catch {
 		return false;
 	}
@@ -124,12 +124,12 @@ function fromParentDir(parentDir, options = {}) {
 	const absParent = path.resolve(cwd ?? process.cwd(), parentDir);
 	let stat;
 	try {
-		stat = fs.statSync(absParent);
+		stat = fsSync.statSync(absParent);
 	} catch {
 		throw new Error(`${PREFIX} apis.fromDir: directory not found: ${absParent}`);
 	}
 	if (!stat.isDirectory()) throw new Error(`${PREFIX} apis.fromDir: not a directory: ${absParent}`);
-	const subdirs = fs.readdirSync(absParent, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name).sort();
+	const subdirs = fsSync.readdirSync(absParent, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name).sort();
 	const configs = [];
 	for (const name of subdirs) {
 		const subdir = path.join(absParent, name);

package/errors.js

@@ -7,17 +7,12 @@ var ConfigValidationError = class extends ConfigValidationErrorBase {
 		return `Config validation failed for '${this.field}': ${this.reason}`;
 	}
 };
-const ApiModelLoadErrorBase = Data.TaggedError("ApiModelLoadError");
-const PathDerivationErrorBase = Data.TaggedError("PathDerivationError");
 const TypeRegistryErrorBase = Data.TaggedError("TypeRegistryError");
 var TypeRegistryError = class extends TypeRegistryErrorBase {
 	get message() {
 		return `Type registry error for '${this.packageName}@${this.version}': ${this.reason}`;
 	}
 };
-const PageGenerationErrorBase = Data.TaggedError("PageGenerationError");
-const TwoslashProcessingErrorBase = Data.TaggedError("TwoslashProcessingError");
-const PrettierFormatErrorBase = Data.TaggedError("PrettierFormatError");
 
 //#endregion
-export { ConfigValidationError, ConfigValidationErrorBase, TypeRegistryError, TypeRegistryErrorBase };
+export { ConfigValidationError, TypeRegistryError };

package/index.d.ts

@@ -669,8 +669,6 @@ declare const PluginOptions: Schema.Struct<{
      */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
   }>>>>>;
-  /** Canonical site URL used for Open Graph absolute URLs. */
-  readonly siteUrl: Schema.optional<Schema.String>;
   /** Global Open Graph image configuration (overridden per-API). */
   readonly ogImage: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
     readonly url: Schema.String;
@@ -746,90 +744,6 @@ declare const PluginOptions: Schema.Struct<{
 /** @public */
 type PluginOptions = typeof PluginOptions.Encoded;
 //#endregion
-//#region src/schemas/opengraph.d.ts
-/**
- * Structured Open Graph image metadata (alternative to a plain URL string).
- *
- * @public
- */
-declare const OpenGraphImageMetadata: Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>;
-/** @public */
-type OpenGraphImageMetadata = typeof OpenGraphImageMetadata.Type;
-/**
- * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
- *
- * @public
- */
-declare const OpenGraphImageConfig: Schema.Union<readonly [Schema.String, Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>]>;
-/** @public */
-type OpenGraphImageConfig = typeof OpenGraphImageConfig.Type;
-/**
- * Resolved Open Graph metadata emitted into each generated page's frontmatter.
- *
- * @public
- */
-declare const OpenGraphMetadata: Schema.Struct<{
-  /** Canonical site base URL. */
-  readonly siteUrl: Schema.String;
-  /** Page route path (e.g. `/api/classes/myclass`). */
-  readonly pageRoute: Schema.String;
-  /** Page description for the `og:description` tag. */
-  readonly description: Schema.String;
-  /** ISO 8601 date string for `article:published_time`. */
-  readonly publishedTime: Schema.String;
-  /** ISO 8601 date string for `article:modified_time`. */
-  readonly modifiedTime: Schema.String;
-  /** Article section label (e.g. `"API"`). */
-  readonly section: Schema.String;
-  /** Article tag keywords. */
-  readonly tags: Schema.mutable<Schema.$Array<Schema.String>>;
-  /** Optional structured image metadata. */
-  readonly ogImage: Schema.optional<Schema.Struct<{
-    /** Absolute URL of the image. */
-    readonly url: Schema.String;
-    /** HTTPS URL of the image (for secure contexts). */
-    readonly secureUrl: Schema.optional<Schema.String>;
-    /** MIME type of the image (e.g. `"image/png"`). */
-    readonly type: Schema.optional<Schema.String>;
-    /** Image width in pixels. */
-    readonly width: Schema.optional<Schema.Number>;
-    /** Image height in pixels. */
-    readonly height: Schema.optional<Schema.Number>;
-    /** Alt text for the image. */
-    readonly alt: Schema.optional<Schema.String>;
-  }>>;
-  /** Open Graph object type (e.g. `"article"`). */
-  readonly ogType: Schema.String;
-}>;
-/** @public */
-type OpenGraphMetadata = typeof OpenGraphMetadata.Type;
-//#endregion
 //#region src/config-helpers.d.ts
 /**
  * Metadata discovered from a single rslib-builder localPaths package folder.
@@ -940,6 +854,90 @@ declare const ApiExtractorPlugin: typeof ApiExtractorPluginImpl & {
   };
 };
 //#endregion
+//#region src/schemas/opengraph.d.ts
+/**
+ * Structured Open Graph image metadata (alternative to a plain URL string).
+ *
+ * @public
+ */
+declare const OpenGraphImageMetadata: Schema.Struct<{
+  /** Absolute URL of the image. */
+  readonly url: Schema.String;
+  /** HTTPS URL of the image (for secure contexts). */
+  readonly secureUrl: Schema.optional<Schema.String>;
+  /** MIME type of the image (e.g. `"image/png"`). */
+  readonly type: Schema.optional<Schema.String>;
+  /** Image width in pixels. */
+  readonly width: Schema.optional<Schema.Number>;
+  /** Image height in pixels. */
+  readonly height: Schema.optional<Schema.Number>;
+  /** Alt text for the image. */
+  readonly alt: Schema.optional<Schema.String>;
+}>;
+/** @public */
+type OpenGraphImageMetadata = typeof OpenGraphImageMetadata.Type;
+/**
+ * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
+ *
+ * @public
+ */
+declare const OpenGraphImageConfig: Schema.Union<readonly [Schema.String, Schema.Struct<{
+  /** Absolute URL of the image. */
+  readonly url: Schema.String;
+  /** HTTPS URL of the image (for secure contexts). */
+  readonly secureUrl: Schema.optional<Schema.String>;
+  /** MIME type of the image (e.g. `"image/png"`). */
+  readonly type: Schema.optional<Schema.String>;
+  /** Image width in pixels. */
+  readonly width: Schema.optional<Schema.Number>;
+  /** Image height in pixels. */
+  readonly height: Schema.optional<Schema.Number>;
+  /** Alt text for the image. */
+  readonly alt: Schema.optional<Schema.String>;
+}>]>;
+/** @public */
+type OpenGraphImageConfig = typeof OpenGraphImageConfig.Type;
+/**
+ * Resolved Open Graph metadata emitted into each generated page's frontmatter.
+ *
+ * @public
+ */
+declare const OpenGraphMetadata: Schema.Struct<{
+  /** Canonical site base URL. */
+  readonly siteUrl: Schema.String;
+  /** Page route path (e.g. `/api/classes/myclass`). */
+  readonly pageRoute: Schema.String;
+  /** Page description for the `og:description` tag. */
+  readonly description: Schema.String;
+  /** ISO 8601 date string for `article:published_time`. */
+  readonly publishedTime: Schema.String;
+  /** ISO 8601 date string for `article:modified_time`. */
+  readonly modifiedTime: Schema.String;
+  /** Article section label (e.g. `"API"`). */
+  readonly section: Schema.String;
+  /** Article tag keywords. */
+  readonly tags: Schema.mutable<Schema.$Array<Schema.String>>;
+  /** Optional structured image metadata. */
+  readonly ogImage: Schema.optional<Schema.Struct<{
+    /** Absolute URL of the image. */
+    readonly url: Schema.String;
+    /** HTTPS URL of the image (for secure contexts). */
+    readonly secureUrl: Schema.optional<Schema.String>;
+    /** MIME type of the image (e.g. `"image/png"`). */
+    readonly type: Schema.optional<Schema.String>;
+    /** Image width in pixels. */
+    readonly width: Schema.optional<Schema.Number>;
+    /** Image height in pixels. */
+    readonly height: Schema.optional<Schema.Number>;
+    /** Alt text for the image. */
+    readonly alt: Schema.optional<Schema.String>;
+  }>>;
+  /** Open Graph object type (e.g. `"article"`). */
+  readonly ogType: Schema.String;
+}>;
+/** @public */
+type OpenGraphMetadata = typeof OpenGraphMetadata.Type;
+//#endregion
 //#region src/serve.d.ts
 /**
  * Which RSPress server {@link serve} runs.