rspress-plugin-api-extractor 0.1.2 → 0.2.0

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

@@ -0,0 +1,307 @@
+import { ApiParser } from "../../loader.js";
+import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives } from "../helpers.js";
+import { markdownCrossLinker } from "../cross-linker.js";
+import { TypeSignatureFormatter } from "../../formatter.js";
+
+//#region src/markdown/page-generators/interface-page.ts
+/**
+* Generates MDX documentation pages for TypeScript interfaces.
+*
+* This class transforms API Extractor interface models into rich MDX documentation
+* pages with syntax-highlighted signatures, cross-linked type references, and
+* interactive features.
+*
+* **Page Structure:**
+* 1. Frontmatter with title, description, and Open Graph metadata
+* 2. Component imports (SourceCode, ParametersTable, ApiSignature, etc.)
+* 3. Page title (H1) and summary
+* 4. Optional deprecation warning and release tag badge
+* 5. Source code link toolbar
+* 6. Full interface signature block showing all members
+* 7. Member sections: Call Signatures, Construct Signatures, Index Signatures, Properties, Methods
+* 8. Examples section with Twoslash-enabled code blocks
+* 9. See Also references
+*
+* **Interface-Specific Features:**
+* - Handles type parameters (generics) in interface declarations
+* - Supports call signatures for callable interfaces
+* - Supports construct signatures for constructable interfaces
+* - Supports index signatures for dictionary-like interfaces
+* - Handles extends clauses for interface inheritance
+*
+* **Relationships:**
+* - Created and invoked by {@link ApiExtractorPlugin} during page generation
+* - Uses {@link TypeSignatureFormatter} for formatting type signatures
+* - Uses {@link ApiParser} for extracting documentation from API models
+* - Uses {@link MarkdownCrossLinker} for adding type reference links
+*
+* @example
+* ```ts
+* const generator = new InterfacePageGenerator();
+* const { routePath, content } = await generator.generate(
+*   apiInterface,
+*   "/api/my-package",
+*   "my-package",
+*   "Interface",
+*   "My Package",
+*   sourceConfig,
+*   true, // suppressExampleErrors
+*   undefined, // llmsPlugin
+*   "claude-binary-plugin", // apiScope
+* );
+* ```
+*
+* @see {@link ClassPageGenerator} for class documentation
+* @see {@link TypeAliasPageGenerator} for type alias documentation
+*/
+var InterfacePageGenerator = class {
+	typeFormatter = new TypeSignatureFormatter();
+	/**
+	* Generate a markdown page for an interface
+	*
+	* @param apiScope - API scope identifier for VFS lookup
+	*/
+	async generate(apiInterface, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
+		const shouldSuppressErrors = suppressExampleErrors ?? true;
+		const name = apiInterface.displayName;
+		const summary = ApiParser.getSummary(apiInterface) || "No description available.";
+		const releaseTag = ApiParser.getReleaseTag(apiInterface);
+		let content = generateFrontmatter(name, summary, singularName, apiName);
+		content += `import { SourceCode } from "@rspress/core/theme";\n`;
+		content += `import { ParametersTable } from "rspress-plugin-api-extractor/runtime";\n`;
+		content += `import { ApiSignature, ApiMember, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
+		content += `# ${name}\n\n`;
+		const deprecation = ApiParser.getDeprecation(apiInterface);
+		if (deprecation) {
+			const message = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(deprecation.message));
+			content += `> ⚠️ **Deprecated:** ${message}\n\n`;
+		}
+		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
+		content += `${summary}\n\n`;
+		content += generateAvailableFrom(packageName, availableFrom);
+		const sourceLink = ApiParser.getSourceLink(apiInterface, sourceConfig);
+		if (sourceLink) {
+			content += `<div className="api-docs-toolbar">\n`;
+			content += `  <div className="api-docs-toolbar-left">\n`;
+			content += `    <SourceCode href="${sourceLink}" />\n`;
+			content += `  </div>\n`;
+			if (llmsPlugin?.enabled) {
+				content += `  <div className="api-docs-toolbar-right">\n`;
+				content += `  </div>\n`;
+			}
+			content += `</div>\n\n`;
+		}
+		const skeleton = this.generateInterfaceSkeletonWithTwoslash(apiInterface, packageName);
+		const displayCode = stripTwoslashDirectives(skeleton);
+		content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(skeleton)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		const callSignatures = apiInterface.members.filter((m) => m.kind === "CallSignature");
+		if (callSignatures.length > 0) {
+			content += `## Call Signatures\n\n`;
+			for (const callSig of callSignatures) {
+				const callSigSummary = ApiParser.getSummary(callSig);
+				const callSigId = sanitizeId("call-signature");
+				const callSigItem = callSig;
+				if (callSigItem.excerpt?.text) {
+					const memberSignature = this.typeFormatter.format(callSigItem.excerpt).trim();
+					const skeletonWithContext = this.generateInterfaceMemberWithContext(apiInterface, callSig, packageName);
+					const summaryMd = callSigSummary ? escapeMdxGenerics(markdownCrossLinker.addCrossLinks(callSigSummary)) : void 0;
+					content += `<ApiMember code={${JSON.stringify(memberSignature)}} source={${JSON.stringify(skeletonWithContext)}} apiScope={${JSON.stringify(apiScope)}} memberName="Call Signature"${summaryMd ? ` summary={${JSON.stringify(summaryMd)}}` : ""} id={${JSON.stringify(callSigId)}} />\n\n`;
+				}
+			}
+		}
+		const constructSignatures = apiInterface.members.filter((m) => m.kind === "ConstructSignature");
+		if (constructSignatures.length > 0) {
+			content += `## Construct Signatures\n\n`;
+			for (const constructSig of constructSignatures) {
+				const constructSigSummary = ApiParser.getSummary(constructSig);
+				const constructSigId = sanitizeId("construct-signature");
+				const constructSigItem = constructSig;
+				if (constructSigItem.excerpt?.text) {
+					const memberSignature = this.typeFormatter.format(constructSigItem.excerpt).trim();
+					const skeletonWithContext = this.generateInterfaceMemberWithContext(apiInterface, constructSig, packageName);
+					const summaryMd = constructSigSummary ? escapeMdxGenerics(markdownCrossLinker.addCrossLinks(constructSigSummary)) : void 0;
+					content += `<ApiMember code={${JSON.stringify(memberSignature)}} source={${JSON.stringify(skeletonWithContext)}} apiScope={${JSON.stringify(apiScope)}} memberName="Construct Signature"${summaryMd ? ` summary={${JSON.stringify(summaryMd)}}` : ""} id={${JSON.stringify(constructSigId)}} />\n\n`;
+				}
+			}
+		}
+		const indexSignatures = apiInterface.members.filter((m) => m.kind === "IndexSignature");
+		if (indexSignatures.length > 0) {
+			content += `## Index Signature\n\n`;
+			for (const indexSig of indexSignatures) {
+				const indexSigSummary = ApiParser.getSummary(indexSig);
+				const indexSigId = sanitizeId("index-signature");
+				const indexSigItem = indexSig;
+				if (indexSigItem.excerpt?.text) {
+					const memberSignature = this.typeFormatter.format(indexSigItem.excerpt).trim();
+					const skeletonWithContext = this.generateInterfaceMemberWithContext(apiInterface, indexSig, packageName);
+					const summaryMd = indexSigSummary ? escapeMdxGenerics(markdownCrossLinker.addCrossLinks(indexSigSummary)) : void 0;
+					content += `<ApiMember code={${JSON.stringify(memberSignature)}} source={${JSON.stringify(skeletonWithContext)}} apiScope={${JSON.stringify(apiScope)}} memberName="Index Signature"${summaryMd ? ` summary={${JSON.stringify(summaryMd)}}` : ""} id={${JSON.stringify(indexSigId)}} />\n\n`;
+				}
+			}
+		}
+		const properties = apiInterface.members.filter((m) => m.kind === "PropertySignature");
+		if (properties.length > 0) {
+			content += `## Properties\n\n`;
+			for (const prop of properties) {
+				const propSummary = ApiParser.getSummary(prop);
+				const propId = sanitizeId(prop.displayName);
+				const propItem = prop;
+				if (propItem.excerpt?.text) {
+					const memberSignature = this.typeFormatter.format(propItem.excerpt).trim();
+					const skeletonWithContext = this.generateInterfaceMemberWithContext(apiInterface, prop, packageName);
+					const summaryMd = propSummary ? escapeMdxGenerics(markdownCrossLinker.addCrossLinks(propSummary)) : void 0;
+					content += `<ApiMember code={${JSON.stringify(memberSignature)}} source={${JSON.stringify(skeletonWithContext)}} apiScope={${JSON.stringify(apiScope)}} memberName={${JSON.stringify(prop.displayName)}}${summaryMd ? ` summary={${JSON.stringify(summaryMd)}}` : ""} id={${JSON.stringify(propId)}} />\n\n`;
+				}
+			}
+		}
+		const methods = apiInterface.members.filter((m) => m.kind === "MethodSignature");
+		if (methods.length > 0) {
+			content += `## Methods\n\n`;
+			for (const method of methods) {
+				const methodSummary = ApiParser.getSummary(method);
+				const methodId = sanitizeId(method.displayName);
+				const methodItem = method;
+				if (methodItem.excerpt?.text) {
+					const memberSignature = this.typeFormatter.format(methodItem.excerpt).trim();
+					const skeletonWithContext = this.generateInterfaceMemberWithContext(apiInterface, method, packageName);
+					const hasParameters = ApiParser.getParams(method).length > 0;
+					const summaryMd = methodSummary ? escapeMdxGenerics(markdownCrossLinker.addCrossLinks(methodSummary)) : void 0;
+					content += `<ApiMember code={${JSON.stringify(memberSignature)}} source={${JSON.stringify(skeletonWithContext)}} apiScope={${JSON.stringify(apiScope)}} memberName={${JSON.stringify(method.displayName)}}${summaryMd ? ` summary={${JSON.stringify(summaryMd)}}` : ""} id={${JSON.stringify(methodId)}} hasParameters={${hasParameters}} />\n\n`;
+				}
+				const params = ApiParser.getParams(method);
+				if (params.length > 0) content += `<ParametersTable parameters={${JSON.stringify(params.map((p) => ({
+					name: p.name,
+					type: p.type,
+					description: markdownCrossLinker.addCrossLinks(p.description)
+				})))}} />\n\n`;
+				const returns = ApiParser.getReturns(method);
+				if (returns) {
+					const description = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(returns.description));
+					content += `**Returns:** ${description}\n\n`;
+				}
+			}
+		}
+		const examples = ApiParser.getExamples(apiInterface);
+		if (examples.length > 0) {
+			content += `## Examples\n\n`;
+			for (const example of examples) {
+				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
+				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
+					api: packageName,
+					blockType: "example"
+				});
+				if (prepared.isTypeScript) {
+					const displayCode = stripTwoslashDirectives(formattedCode);
+					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
+			}
+		}
+		const seeReferences = ApiParser.getSeeReferences(apiInterface);
+		if (seeReferences.length > 0) {
+			content += `## See Also\n\n`;
+			for (const reference of seeReferences) {
+				const refText = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(reference.text));
+				content += `- ${refText}\n`;
+			}
+			content += `\n`;
+		}
+		return {
+			routePath: `${baseRoute}/interface/${name.toLowerCase()}`,
+			content
+		};
+	}
+	/**
+	* Generate an interface member signature with full interface context
+	* Includes hidden imports with cut directive for external type resolution
+	* Uses the simplified approach: 3 lines (interface opening, member, closing)
+	*/
+	generateInterfaceMemberWithContext(apiInterface, targetMember, packageName) {
+		const interfaceName = apiInterface.displayName;
+		const inheritance = ApiParser.getInheritance(apiInterface);
+		let declaration = `interface ${interfaceName}`;
+		if (apiInterface.typeParameters && apiInterface.typeParameters.length > 0) {
+			const typeParams = apiInterface.typeParameters.map((tp) => tp.name).join(", ");
+			declaration += `<${typeParams}>`;
+		}
+		if (inheritance.extends && inheritance.extends.length > 0) declaration += ` extends ${inheritance.extends.join(", ")}`;
+		declaration += " {";
+		const memberItem = targetMember;
+		const memberSignature = memberItem.excerpt?.text ? this.typeFormatter.format(memberItem.excerpt).trim() : "";
+		const skeleton = `${declaration}\n${memberSignature}\n}`;
+		const apiPackage = apiInterface.getAssociatedPackage?.();
+		if (apiPackage) return prependHiddenImports(skeleton, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(targetMember));
+		return skeleton;
+	}
+	/**
+	* Generate an interface skeleton for signature blocks
+	* Includes hidden imports with cut directive for external type resolution
+	*/
+	generateInterfaceSkeletonWithTwoslash(apiInterface, packageName) {
+		const skeleton = this.generateInterfaceSkeleton(apiInterface);
+		const apiPackage = apiInterface.getAssociatedPackage?.();
+		if (apiPackage) return prependHiddenImports(skeleton, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiInterface));
+		return skeleton;
+	}
+	/**
+	* Generate a complete interface skeleton showing all members
+	*/
+	generateInterfaceSkeleton(apiInterface) {
+		const lines = [];
+		const interfaceName = apiInterface.displayName;
+		const inheritance = ApiParser.getInheritance(apiInterface);
+		let declaration = `interface ${interfaceName}`;
+		if (apiInterface.typeParameters && apiInterface.typeParameters.length > 0) {
+			const typeParams = apiInterface.typeParameters.map((tp) => tp.name).join(", ");
+			declaration += `<${typeParams}>`;
+		}
+		if (inheritance.extends && inheritance.extends.length > 0) declaration += ` extends ${inheritance.extends.join(", ")}`;
+		declaration += " {";
+		lines.push(declaration);
+		const callSignatures = apiInterface.members.filter((m) => m.kind === "CallSignature");
+		if (callSignatures.length > 0) for (const callSig of callSignatures) {
+			const callSigItem = callSig;
+			if (callSigItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(callSigItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		const constructSignatures = apiInterface.members.filter((m) => m.kind === "ConstructSignature");
+		if (constructSignatures.length > 0) for (const constructSig of constructSignatures) {
+			const constructSigItem = constructSig;
+			if (constructSigItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(constructSigItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		const indexSignatures = apiInterface.members.filter((m) => m.kind === "IndexSignature");
+		if (indexSignatures.length > 0) for (const indexSig of indexSignatures) {
+			const indexSigItem = indexSig;
+			if (indexSigItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(indexSigItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		const properties = apiInterface.members.filter((m) => m.kind === "PropertySignature");
+		if (properties.length > 0) for (const prop of properties) {
+			const propItem = prop;
+			if (propItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(propItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		const methods = apiInterface.members.filter((m) => m.kind === "MethodSignature");
+		if (methods.length > 0) for (const method of methods) {
+			const methodItem = method;
+			if (methodItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(methodItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+};
+
+//#endregion
+export { InterfacePageGenerator };

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

@@ -0,0 +1,280 @@
+import { ApiParser } from "../../loader.js";
+import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
+import { markdownCrossLinker } from "../cross-linker.js";
+import { TypeSignatureFormatter } from "../../formatter.js";
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/markdown/page-generators/namespace-page.ts
+/**
+* Generates MDX documentation pages for TypeScript namespaces.
+*
+* This class transforms API Extractor namespace models into rich MDX documentation pages
+* with syntax-highlighted signatures, cross-linked type references, and member listings.
+*
+* **Page Structure:**
+* 1. Frontmatter with title, description, and Open Graph metadata
+* 2. Component imports (SourceCode, ApiSignature, etc.)
+* 3. Page title (H1) and summary
+* 4. Optional deprecation warning and release tag badge
+* 5. Source code link toolbar
+* 6. Full namespace signature block showing all members
+* 7. Member sections: Classes, Interfaces, Functions, Variables, Types, Enums, Namespaces
+* 8. Examples section with Twoslash-enabled code blocks
+* 9. See Also references
+*
+* **Member Rendering:**
+* Each member section lists members with links to their individual documentation pages.
+*
+* **Relationships:**
+* - Created and invoked by {@link ApiExtractorPlugin} during page generation
+* - Uses {@link TypeSignatureFormatter} for formatting type signatures
+* - Uses {@link ApiParser} for extracting documentation from API models
+* - Uses {@link MarkdownCrossLinker} for adding type reference links
+*
+* @example
+* ```ts
+* const generator = new NamespacePageGenerator();
+* const { routePath, content } = await generator.generate(
+*   apiNamespace,
+*   "/api/my-package",
+*   "my-package",
+*   "Namespace",
+*   "My Package",
+*   sourceConfig,
+*   true, // suppressExampleErrors
+*   undefined, // llmsPlugin
+*   "my-scope"
+* );
+* ```
+*
+* @see {@link ClassPageGenerator} for class documentation
+* @see {@link InterfacePageGenerator} for interface documentation
+*/
+var NamespacePageGenerator = class {
+	typeFormatter = new TypeSignatureFormatter();
+	/**
+	* Generate a markdown page for a namespace
+	*
+	* @param apiScope - API scope identifier for VFS lookup
+	*/
+	async generate(apiNamespace, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
+		const shouldSuppressErrors = suppressExampleErrors ?? true;
+		const name = apiNamespace.displayName;
+		const summary = ApiParser.getSummary(apiNamespace) || "No description available.";
+		const releaseTag = ApiParser.getReleaseTag(apiNamespace);
+		let content = generateFrontmatter(name, summary, singularName, apiName);
+		content += `import { SourceCode } from "@rspress/core/theme";\n`;
+		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
+		content += `# ${name}\n\n`;
+		const deprecation = ApiParser.getDeprecation(apiNamespace);
+		if (deprecation) {
+			const message = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(deprecation.message));
+			content += `> **Deprecated:** ${message}\n\n`;
+		}
+		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
+		content += `${summary}\n\n`;
+		content += generateAvailableFrom(packageName, availableFrom);
+		const sourceLink = ApiParser.getSourceLink(apiNamespace, sourceConfig);
+		if (sourceLink) {
+			content += `<div className="api-docs-toolbar">\n`;
+			content += `  <div className="api-docs-toolbar-left">\n`;
+			content += `    <SourceCode href="${sourceLink}" />\n`;
+			content += `  </div>\n`;
+			if (llmsPlugin?.enabled) {
+				content += `  <div className="api-docs-toolbar-right">\n`;
+				content += `  </div>\n`;
+			}
+			content += `</div>\n\n`;
+		}
+		const skeleton = this.generateNamespaceSkeletonWithTwoslash(apiNamespace, packageName);
+		const displayCode = stripTwoslashDirectives(skeleton);
+		content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(skeleton)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		const grouped = this.groupNamespaceMembers(apiNamespace.members);
+		content += this.renderMemberSection("Classes", grouped.classes, baseRoute, "class", name);
+		content += this.renderMemberSection("Interfaces", grouped.interfaces, baseRoute, "interface", name);
+		content += this.renderMemberSection("Functions", grouped.functions, baseRoute, "function", name);
+		content += this.renderMemberSection("Variables", grouped.variables, baseRoute, "variable", name);
+		content += this.renderMemberSection("Types", grouped.typeAliases, baseRoute, "type", name);
+		content += this.renderMemberSection("Enums", grouped.enums, baseRoute, "enum", name);
+		content += this.renderMemberSection("Namespaces", grouped.namespaces, baseRoute, "namespace", name);
+		const examples = ApiParser.getExamples(apiNamespace);
+		if (examples.length > 0) {
+			content += `## Examples\n\n`;
+			for (const example of examples) {
+				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
+				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
+					api: packageName,
+					blockType: "example"
+				});
+				if (prepared.isTypeScript) {
+					const displayCode = stripTwoslashDirectives(formattedCode);
+					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
+			}
+		}
+		const seeReferences = ApiParser.getSeeReferences(apiNamespace);
+		if (seeReferences.length > 0) {
+			content += `## See Also\n\n`;
+			for (const reference of seeReferences) {
+				const refText = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(reference.text));
+				content += `- ${refText}\n`;
+			}
+			content += `\n`;
+		}
+		return {
+			routePath: `${baseRoute}/namespace/${name.toLowerCase()}`,
+			content
+		};
+	}
+	/**
+	* Group namespace members by their type
+	*/
+	groupNamespaceMembers(members) {
+		const classes = [];
+		const interfaces = [];
+		const functions = [];
+		const variables = [];
+		const typeAliases = [];
+		const enums = [];
+		const namespaces = [];
+		for (const member of members) switch (member.kind) {
+			case ApiItemKind.Class:
+				classes.push(member);
+				break;
+			case ApiItemKind.Interface:
+				interfaces.push(member);
+				break;
+			case ApiItemKind.Function:
+				functions.push(member);
+				break;
+			case ApiItemKind.Variable:
+				variables.push(member);
+				break;
+			case ApiItemKind.TypeAlias:
+				typeAliases.push(member);
+				break;
+			case ApiItemKind.Enum:
+				enums.push(member);
+				break;
+			case ApiItemKind.Namespace:
+				namespaces.push(member);
+				break;
+			default: break;
+		}
+		return {
+			classes,
+			interfaces,
+			functions,
+			variables,
+			typeAliases,
+			enums,
+			namespaces
+		};
+	}
+	/**
+	* Render a section of members with links to their pages
+	* @param title - Section heading
+	* @param members - Array of API items to list
+	* @param baseRoute - Base API route (e.g., /api/package)
+	* @param categoryFolder - Category folder name (e.g., "class", "function")
+	* @param namespaceName - Parent namespace name for qualified routes
+	*/
+	renderMemberSection(title, members, baseRoute, categoryFolder, namespaceName) {
+		if (members.length === 0) return "";
+		let section = `## ${title}\n\n`;
+		for (const member of members) {
+			const memberName = member.displayName;
+			const memberSummary = ApiParser.getSummary(member);
+			const memberRoute = `${baseRoute}/${categoryFolder}/${`${namespaceName}.${memberName}`.toLowerCase()}`;
+			if (memberSummary) {
+				const escapedSummary = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(memberSummary));
+				section += `- [${memberName}](${memberRoute}) - ${escapedSummary}\n`;
+			} else section += `- [${memberName}](${memberRoute})\n`;
+		}
+		section += `\n`;
+		return section;
+	}
+	/**
+	* Generate a namespace skeleton for signature blocks
+	* Includes hidden imports with cut directive for external type resolution
+	*/
+	generateNamespaceSkeletonWithTwoslash(apiNamespace, packageName) {
+		const skeleton = this.generateNamespaceSkeleton(apiNamespace);
+		const apiPackage = apiNamespace.getAssociatedPackage?.();
+		if (apiPackage) return prependHiddenImports(skeleton, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiNamespace));
+		return skeleton;
+	}
+	/**
+	* Generate a complete namespace skeleton showing all members
+	*/
+	generateNamespaceSkeleton(apiNamespace) {
+		const lines = [];
+		const namespaceName = apiNamespace.displayName;
+		lines.push(`namespace ${namespaceName} {`);
+		const grouped = this.groupNamespaceMembers(apiNamespace.members);
+		for (const cls of grouped.classes) {
+			const clsItem = cls;
+			if (clsItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(clsItem.excerpt).trim();
+				lines.push(`    ${this.abbreviateDeclaration(signature, "class")} { }`);
+			}
+		}
+		for (const iface of grouped.interfaces) {
+			const ifaceItem = iface;
+			if (ifaceItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(ifaceItem.excerpt).trim();
+				lines.push(`    ${this.abbreviateDeclaration(signature, "interface")} { }`);
+			}
+		}
+		for (const func of grouped.functions) {
+			const funcItem = func;
+			if (funcItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(funcItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		for (const variable of grouped.variables) {
+			const varItem = variable;
+			if (varItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(varItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		for (const typeAlias of grouped.typeAliases) {
+			const typeItem = typeAlias;
+			if (typeItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(typeItem.excerpt).trim();
+				lines.push(`    ${signature}`);
+			}
+		}
+		for (const enumItem of grouped.enums) {
+			const enumDeclItem = enumItem;
+			if (enumDeclItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(enumDeclItem.excerpt).trim();
+				lines.push(`    ${this.abbreviateDeclaration(signature, "enum")} { }`);
+			}
+		}
+		for (const ns of grouped.namespaces) {
+			const nsItem = ns;
+			if (nsItem.excerpt?.text) {
+				const signature = this.typeFormatter.format(nsItem.excerpt).trim();
+				lines.push(`    ${this.abbreviateDeclaration(signature, "namespace")} { }`);
+			}
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	/**
+	* Abbreviate a full declaration to just its header
+	* For example, `class Foo extends Bar implements Baz \{ ... \}` becomes `class Foo extends Bar implements Baz`
+	*/
+	abbreviateDeclaration(signature, _keyword) {
+		const braceIndex = signature.indexOf("{");
+		if (braceIndex === -1) return signature;
+		return signature.substring(0, braceIndex).trim();
+	}
+};
+
+//#endregion
+export { NamespacePageGenerator };