@tsdoctor/model 0.4.0 → 0.5.0

package/ApiExtractedPackage.js

@@ -0,0 +1,477 @@
+import { ApiItemKind, ApiModel, ExcerptTokenKind } from "@microsoft/api-extractor-model";
+import { VirtualPackage } from "@tsdoctor/vfs";
+
+//#region src/ApiExtractedPackage.ts
+/**
+* Reconstructs TypeScript declaration files from an API Extractor model.
+*
+* Extends `VirtualPackage` with the ability to generate high-fidelity
+* `.d.ts` output from API Extractor's `ApiPackage` — including enum values,
+* full JSDoc, namespace members, and all interface member kinds.
+*
+* Use the factory methods `fromApiModel` or `fromPackage` to create instances.
+*
+* @public
+*/
+var ApiExtractedPackage = class ApiExtractedPackage extends VirtualPackage {
+	apiPackage;
+	constructor(apiPackage, packageName, entries) {
+		super({
+			name: packageName,
+			version: "1.0.0",
+			entries
+		});
+		this.apiPackage = apiPackage;
+	}
+	/**
+	* Create an ApiExtractedPackage from an API model JSON file path.
+	*/
+	static fromApiModel(modelPath) {
+		const apiPackage = new ApiModel().loadPackage(modelPath);
+		return ApiExtractedPackage.fromPackage(apiPackage, apiPackage.name);
+	}
+	/**
+	* Create an ApiExtractedPackage from an existing ApiPackage instance.
+	*/
+	static fromPackage(apiPackage, packageName) {
+		const scratch = new ApiExtractedPackage(apiPackage, packageName, /* @__PURE__ */ new Map([["index.d.ts", ""]]));
+		const entries = /* @__PURE__ */ new Map();
+		for (const ep of apiPackage.entryPoints) {
+			const entryName = scratch.getEntryPointName(ep);
+			const fileName = entryName ? `${entryName}.d.ts` : "index.d.ts";
+			entries.set(fileName, scratch.generateDeclarations(ep));
+		}
+		return new ApiExtractedPackage(apiPackage, packageName, entries);
+	}
+	/**
+	* Generate the .d.ts content for a specific entry point.
+	*/
+	generateDeclarations(entryPoint) {
+		const ep = entryPoint ?? this.apiPackage.entryPoints[0];
+		if (!ep) return "";
+		const parts = [];
+		const packageDoc = this.extractPackageDocumentation();
+		if (packageDoc) {
+			parts.push(packageDoc);
+			parts.push("");
+		}
+		for (const member of ep.members) {
+			const decl = this.generateDeclaration(member);
+			if (decl) {
+				parts.push(decl);
+				parts.push("");
+			}
+		}
+		parts.push("export { }");
+		parts.push("");
+		return parts.join("\n");
+	}
+	/**
+	* Generate a TypeScript declaration for a single API item.
+	*/
+	generateDeclaration(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Class: return this.generateClassDeclaration(apiItem);
+			case ApiItemKind.Interface: return this.generateInterfaceDeclaration(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateTypeAliasDeclaration(apiItem);
+			case ApiItemKind.Function: return this.generateFunctionDeclaration(apiItem);
+			case ApiItemKind.Enum: return this.generateEnumDeclaration(apiItem);
+			case ApiItemKind.Variable: return this.generateVariableDeclaration(apiItem);
+			case ApiItemKind.Namespace: return this.generateNamespaceDeclaration(apiItem);
+			default: return null;
+		}
+	}
+	generateClassDeclaration(apiClass) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiClass);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiClass.displayName;
+		if (apiClass.typeParameters?.length) name += this.formatTypeParameters(apiClass.typeParameters);
+		const headerParts = apiClass.isAbstract ? ["export declare abstract class", name] : ["export declare class", name];
+		if (apiClass.extendsType) headerParts.push(`extends ${this.renderExcerpt(apiClass.extendsType.excerpt)}`);
+		if (apiClass.implementsTypes?.length) {
+			const impl = apiClass.implementsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`implements ${impl}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiClass.members) {
+			const memberDecl = this.generateClassMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateInterfaceDeclaration(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export declare interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateTypeAliasDeclaration(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias);
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`export declare type ${name} = ${this.renderExcerpt(typeAlias.typeExcerpt)};`);
+		return lines.join("\n");
+	}
+	generateFunctionDeclaration(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(apiFunction.excerpt));
+		const decl = cleaned.startsWith("function ") ? cleaned : `const ${cleaned}`;
+		lines.push(`export declare ${decl};`);
+		return lines.join("\n");
+	}
+	generateEnumDeclaration(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "    ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`    ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`    ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateVariableDeclaration(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable);
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(this.renderExcerpt(apiVariable.excerpt));
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`export declare ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceDeclaration(apiNamespace) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiNamespace);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare namespace ${apiNamespace.displayName} {`);
+		for (const member of apiNamespace.members) {
+			const memberDecl = this.generateNamespaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateNamespaceMember(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Function: return this.generateNamespaceFunction(apiItem);
+			case ApiItemKind.Interface: return this.generateNamespaceInterface(apiItem);
+			case ApiItemKind.Enum: return this.generateNamespaceEnum(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateNamespaceTypeAlias(apiItem);
+			case ApiItemKind.Variable: return this.generateNamespaceVariable(apiItem);
+			case ApiItemKind.Class: return this.generateNamespaceClass(apiItem);
+			default: return null;
+		}
+	}
+	generateNamespaceFunction(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(apiFunction.excerpt));
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceInterface(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`    ${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member, "        ");
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceEnum(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`    export enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "        ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`        ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`        ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceTypeAlias(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`    export type ${name} = ${this.renderExcerpt(typeAlias.typeExcerpt)};`);
+		return lines.join("\n");
+	}
+	generateNamespaceVariable(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(this.renderExcerpt(apiVariable.excerpt));
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceClass(apiClass) {
+		const decl = this.generateClassDeclaration(apiClass);
+		if (!decl) return "";
+		return decl.replace(/\bexport declare (abstract )?class\b/, "export $1class").split("\n").map((line) => line.trim() ? `    ${line}` : line).join("\n");
+	}
+	generateClassMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.Constructor: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Method: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Property: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateInterfaceMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.MethodSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.PropertySignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.CallSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.ConstructSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.IndexSignature: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateMemberFromExcerpt(member, indent) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(member, indent);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(member.excerpt));
+		lines.push(`${indent}${cleaned};`);
+		return lines.join("\n");
+	}
+	/**
+	* Render an excerpt to source text, normalizing dts-rollup disambiguation
+	* aliases. The dts rollup renames a re-imported symbol as `Name$1`, but its
+	* canonical reference is the un-suffixed `Name` (the same symbol). The import
+	* prepender ({@link TypeReferenceExtractor}) imports the canonical name, so
+	* emitting the suffixed text would leave `Name$1` undefined (TS2304). Emit the
+	* canonical name so the body and the prepended import agree.
+	*
+	* Equivalent to `excerpt.text` for excerpts without rollup aliases (the text
+	* is the concatenation of the spanned tokens), so unaliased output is unchanged.
+	*/
+	renderExcerpt(excerpt) {
+		return excerpt.spannedTokens.map((token) => this.normalizeTokenText(token)).join("");
+	}
+	/**
+	* Strip a dts-rollup `$N` suffix from a reference token when the de-suffixed
+	* text matches the token's canonical symbol. Never touches a non-reference
+	* token or a legitimate identifier that genuinely ends in `$N` (its canonical
+	* name would carry the suffix too).
+	*/
+	normalizeTokenText(token) {
+		if (token.kind !== ExcerptTokenKind.Reference) return token.text;
+		const match = /^(.+)\$\d+$/.exec(token.text);
+		if (!match) return token.text;
+		const canonical = token.canonicalReference?.toString();
+		if (!canonical) return token.text;
+		const afterBang = canonical.slice(canonical.indexOf("!") + 1);
+		const colon = afterBang.indexOf(":");
+		const symbol = colon === -1 ? afterBang : afterBang.slice(0, colon);
+		const leaf = symbol.includes(".") ? symbol.slice(symbol.lastIndexOf(".") + 1) : symbol;
+		return match[1] === symbol || match[1] === leaf ? match[1] : token.text;
+	}
+	/**
+	* Clean an excerpt text: strip export/declare keywords and trailing semicolons/whitespace.
+	*/
+	cleanExcerpt(text) {
+		return text.replace(/^export\s+/, "").replace(/^declare\s+/, "").replace(/;+\s*$/, "").trim();
+	}
+	formatTypeParameters(typeParameters) {
+		if (!typeParameters.length) return "";
+		return `<${typeParameters.map((tp) => {
+			const parts = [tp.name];
+			if (tp.constraintExcerpt && this.renderExcerpt(tp.constraintExcerpt).trim()) parts.push(`extends ${this.renderExcerpt(tp.constraintExcerpt).trim()}`);
+			if (tp.defaultTypeExcerpt && this.renderExcerpt(tp.defaultTypeExcerpt).trim()) parts.push(`= ${this.renderExcerpt(tp.defaultTypeExcerpt).trim()}`);
+			return parts.join(" ");
+		}).join(", ")}>`;
+	}
+	extractPackageDocumentation() {
+		const pkg = this.apiPackage;
+		if (!pkg.tsdocComment?.summarySection) return null;
+		const summary = this.extractPlainText(pkg.tsdocComment.summarySection).trim();
+		if (!summary) return null;
+		const lines = [];
+		for (const line of summary.split("\n")) lines.push(line);
+		lines.push("");
+		lines.push("@packageDocumentation");
+		return `/**\n${lines.map((line) => line ? ` * ${line}` : " *").join("\n")}\n */`;
+	}
+	/**
+	* Format JSDoc comment from an API item's TSDoc.
+	* Produces output matching the TypeScript compiler's JSDoc style.
+	*/
+	formatJSDoc(apiItem, indent = "") {
+		const item = apiItem;
+		if (!item.tsdocComment) return null;
+		const tsdoc = item.tsdocComment;
+		const lines = [];
+		if (tsdoc.summarySection) {
+			const summary = this.extractPlainText(tsdoc.summarySection).trim();
+			if (summary) for (const line of summary.split("\n")) lines.push(line);
+		}
+		const typeParamLines = [];
+		if (tsdoc.typeParams?.blocks) for (const block of tsdoc.typeParams.blocks) {
+			const blockAny = block;
+			const name = blockAny.parameterName || "";
+			const desc = this.extractPlainText(blockAny.content).replace(/\s+/g, " ").trim();
+			if (name && desc) typeParamLines.push(`@typeParam ${name} - ${desc}`);
+		}
+		const paramLines = [];
+		if (tsdoc.params?.blocks) for (const paramBlock of tsdoc.params.blocks) {
+			const param = paramBlock;
+			const name = param.parameterName || "";
+			const desc = this.extractPlainText(param.content).replace(/\s+/g, " ").trim();
+			if (name && desc) paramLines.push(`@param ${name} - ${desc}`);
+		}
+		let returnsLine = null;
+		if (tsdoc.returnsBlock) {
+			const desc = this.extractPlainText(tsdoc.returnsBlock.content).replace(/\s+/g, " ").trim();
+			if (desc) returnsLine = `@returns ${desc}`;
+		}
+		if (typeParamLines.length || paramLines.length || returnsLine) {
+			if (lines.length > 0) lines.push("");
+			lines.push(...typeParamLines);
+			lines.push(...paramLines);
+			if (returnsLine) lines.push(returnsLine);
+		}
+		if (tsdoc.deprecatedBlock) {
+			const msg = this.extractPlainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim();
+			if (msg) {
+				if (lines.length > 0) lines.push("");
+				lines.push(`@deprecated ${msg}`);
+			}
+		}
+		if (tsdoc.remarksBlock) {
+			const remarks = this.extractPlainText(tsdoc.remarksBlock.content).trim();
+			if (remarks) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@remarks");
+				for (const line of remarks.split("\n")) lines.push(line);
+			}
+		}
+		if (tsdoc.customBlocks) for (const block of tsdoc.customBlocks) {
+			const blockAny = block;
+			if (blockAny.blockTag?.tagName === "@example") {
+				const exampleText = this.extractPlainText(blockAny.content).trim();
+				if (exampleText) {
+					if (lines.length > 0) lines.push("");
+					lines.push("@example");
+					for (const line of exampleText.split("\n")) lines.push(line);
+				}
+			}
+		}
+		try {
+			if (tsdoc.modifierTagSet?.isPublic?.()) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@public");
+			}
+		} catch {}
+		if (lines.length === 0) return null;
+		if (lines.length === 1 && !lines[0].includes("\n")) return `${indent}/** ${lines[0]} */`;
+		return `${indent}/**\n${lines.map((line) => line ? `${indent} * ${line}` : `${indent} *`).join("\n")}\n${indent} */`;
+	}
+	/**
+	* Recursively extract plain text from a TSDoc DocNode tree.
+	*
+	* @remarks
+	* NOT interchangeable with this package's `Tsdoc` prose extraction, despite
+	* the overlapping name and shape. This one **preserves** `{@link X.Y}` TSDoc
+	* syntax and reconstructs fenced code blocks, because its output is a
+	* `.d.ts` file whose JSDoc must survive round-tripping into a virtual
+	* TypeScript environment. `Tsdoc`'s flattens `{@link}` to its display text
+	* and drops code fences, because its output is rendered prose.
+	*
+	* They looked like duplicates from two packages away and now sit in one, so
+	* this is the note that should stop the merge: collapsing them would either
+	* put display text where a declaration reference belongs, or leak link
+	* syntax into rendered documentation.
+	*/
+	extractPlainText(node) {
+		const n = node;
+		if (n.kind === "PlainText") return n.text || "";
+		if (n.kind === "SoftBreak") return "\n";
+		if (n.kind === "CodeSpan") return `\`${n.code || ""}\``;
+		if (n.kind === "EscapedText") return n.encodedText || n.decodedText || "";
+		if (n.kind === "ErrorText") return n.text || "";
+		if (n.kind === "FencedCode") return `\`\`\`${n.language || ""}\n${(n.code || "").replace(/\n+$/, "")}\n\`\`\``;
+		if (n.kind === "LinkTag") {
+			let target = "";
+			if (n.codeDestination?.memberReferences) {
+				const identifiers = [];
+				for (const ref of n.codeDestination.memberReferences) if (ref.memberIdentifier?.identifier) identifiers.push(ref.memberIdentifier.identifier);
+				target = identifiers.join(".");
+			}
+			const displayText = typeof n.linkText === "string" ? n.linkText : "";
+			if (target && displayText) return `{@link ${target} | ${displayText}}`;
+			if (target) return `{@link ${target}}`;
+			if (displayText) return displayText;
+			return "";
+		}
+		if (n.kind === "Section") {
+			const children = n.getChildNodes?.() || [];
+			const paragraphs = [];
+			for (const child of children) {
+				const trimmed = this.extractPlainText(child).trim();
+				if (trimmed) paragraphs.push(trimmed);
+			}
+			return paragraphs.join("\n\n");
+		}
+		const parts = [];
+		if (n.getChildNodes && typeof n.getChildNodes === "function") for (const child of n.getChildNodes()) {
+			const text = this.extractPlainText(child);
+			if (text) parts.push(text);
+		}
+		return parts.join("");
+	}
+	getEntryPointName(entryPoint) {
+		if (entryPoint.displayName === "") return void 0;
+		return entryPoint.displayName;
+	}
+};
+
+//#endregion
+export { ApiExtractedPackage };

package/Frontmatter.js

@@ -0,0 +1,152 @@
+import { Effect } from "effect";
+import { FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit } from "@effected/markdown";
+import { Yaml, YamlStringifyOptions } from "@effected/yaml";
+
+//#region src/Frontmatter.ts
+/**
+* Stringify options shared by both emit sites.
+*
+* `lineWidth: 0` disables wrapping so long titles/descriptions/URLs stay on
+* one line. The quoting matters for downstream consumers: RSPress parses the
+* emitted frontmatter with js-yaml (YAML 1.1-flavored), where an unquoted
+* ISO timestamp such as `2024-01-15T12:00:00.000Z` decodes to a `Date`
+* object instead of a string. `quoteCompat: "yaml-1.1"` quotes exactly the
+* plain scalars a YAML 1.1 resolver would coerce (timestamps, `yes`/`no`/
+* `on`/`off` booleans, legacy octal/sexagesimal numbers), keeping the
+* decoded representation identical across YAML 1.1 and 1.2 parsers without
+* quoting every value; `quoteStyle: "double"` makes the quotes that do
+* appear double quotes.
+*/
+const STRINGIFY_OPTIONS = YamlStringifyOptions.make({
+	lineWidth: 0,
+	quoteCompat: "yaml-1.1",
+	quoteStyle: "double"
+});
+/**
+* Split markdown source into frontmatter data and body content, preserving
+* gray-matter's exact boundary semantics.
+*
+* @remarks
+* This is a byte-for-byte port of the `gray-matter` split contract the
+* snapshot system's hashes depend on (see `@tsdoctor/snapshot`
+* `hashContent`/`hashFrontmatter` and the disk-fallback comparison in
+* `build-stages.ts`), with `@effected/yaml` (`Yaml.parse`, YAML 1.2) as the
+* YAML engine instead of js-yaml:
+*
+* - No opening `---` line at offset 0 → `data: {}` and the whole input as
+*   `content` (a leading BOM is stripped first, as gray-matter does).
+* - The closing delimiter is the first `\n---` after the opening line
+*   (gray-matter uses a plain `indexOf`, so `\n----` also closes and the
+*   leftover `-` stays in the body — preserved deliberately).
+* - Exactly one newline (`\n` or `\r\n`) immediately after the closing `---`
+*   is consumed; everything else is the body verbatim. A build's generated
+*   page (`---\n…\n---\n\n# Title`) therefore yields a body starting with a
+*   single `\n`, exactly as gray-matter returned it.
+* - A block with no closing delimiter is all frontmatter and yields an empty
+*   body; an empty/blank block yields `data: {}`.
+* - Invalid YAML throws (a defect), matching gray-matter's js-yaml throw.
+*
+* One deliberate delta: gray-matter treats text on the opening line
+* (`---toml`) as an engine name and throws for unregistered engines; this
+* split treats such input as "no frontmatter" instead. The plugin never emits
+* or consumes language-tagged frontmatter.
+*
+* `@effected/markdown`'s `FrontmatterSource.split` was evaluated for this
+* path and deliberately NOT adopted: its grammar is strict by design (a
+* fence line is exactly `---`, an unterminated block is not frontmatter),
+* while this contract pins gray-matter's `indexOf`-based quirks (`\n----`
+* closes, trailing-space close lines close, a missing close means
+* all-frontmatter). The emission half (`stringifyFrontmatter` /
+* `emitFrontmatterBlock`) does use `FrontmatterSource.join`.
+*
+* Representation parity with js-yaml is verified by characterization tests
+* (`__test__/frontmatter.test.ts`) pinning hashes captured under gray-matter.
+* The one input where the engines disagree — an *unquoted* ISO timestamp
+* (js-yaml: `Date`, YAML 1.2: string) — is unreachable from this plugin's
+* emitters, which always quote timestamp values, and hashes identically
+* anyway because `hashFrontmatter` JSON-serializes (a `Date` serializes to
+* the same ISO string).
+*
+* @param source - The markdown source, with or without a frontmatter block
+* @returns The decoded frontmatter data and the body content
+*
+* @public
+*/
+function parseFrontmatter(source) {
+	const text = source.charCodeAt(0) === 65279 ? source.slice(1) : source;
+	const split = FrontmatterSource.split(text);
+	if (split.frontmatter === void 0 || split.frontmatter.format !== "yaml") return {
+		data: {},
+		content: split.body
+	};
+	if (split.frontmatter.value.trim() === "") return {
+		data: {},
+		content: split.body
+	};
+	const value = Effect.runSync(Yaml.parse(split.frontmatter.value));
+	return {
+		data: value == null ? {} : value,
+		content: split.body
+	};
+}
+/**
+* Serialize frontmatter data and body content back into a markdown document,
+* preserving gray-matter's `matter.stringify` contract.
+*
+* @remarks
+* Emits `---\n<yaml>---\n<content>` with the body's trailing newline ensured,
+* and returns the body unchanged (no fences) when `data` has no keys — both
+* gray-matter behaviors the write path relied on. The YAML is emitted by
+* `@effected/yaml` with every string value double-quoted (see
+* `STRINGIFY_OPTIONS` for why); byte output differs from js-yaml's dump, but
+* the decoded representation is identical, which is the invariant the
+* snapshot hashes depend on. Unchanged pages are never rewritten, so the byte
+* difference only ever lands in files that were being rewritten anyway.
+*
+* @param content - The body content
+* @param data - The frontmatter data to serialize
+* @returns The combined markdown document
+*
+* @public
+*/
+function stringifyFrontmatter(content, data) {
+	const body = content.endsWith("\n") ? content : `${content}\n`;
+	if (Object.keys(data).length === 0) return body;
+	const yaml = Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS));
+	return FrontmatterSource.join(FrontmatterSourceSplit.make({
+		frontmatter: FrontmatterSourceBlock.make({
+			format: "yaml",
+			value: yaml
+		}),
+		body
+	}));
+}
+/**
+* Serialize a data object to a YAML frontmatter block (fences included, plus
+* the trailing blank line the page generators emit before the body).
+*
+* @remarks
+* Used by `generateFrontmatter` (`markdown/helpers.ts`) as the emission half
+* of the page generators' frontmatter. Every string value is double-quoted
+* (see `STRINGIFY_OPTIONS`), so values that a YAML 1.1 consumer would
+* otherwise coerce (timestamps, `yes`/`no`, numeric-looking strings) stay
+* strings for RSPress's js-yaml parse.
+*
+* @param data - The frontmatter data to serialize
+* @returns A `---`-fenced YAML block ending with a blank line
+*
+* @public
+*/
+function emitFrontmatterBlock(data) {
+	const yaml = Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS));
+	return FrontmatterSource.join(FrontmatterSourceSplit.make({
+		frontmatter: FrontmatterSourceBlock.make({
+			format: "yaml",
+			value: yaml
+		}),
+		body: "\n"
+	}));
+}
+
+//#endregion
+export { emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Framework-neutral analysis and rendering for Microsoft API Extractor `.api.json` models: Effect-typed loading, pure TSDoc extraction, categorization, multi-entry-point resolution, route/collision computation, synthetic-base detection, type-signature formatting, prose cross-linking and markdown rendering.
+Framework-neutral analysis and rendering for Microsoft API Extractor `.api.json` models: Effect-typed loading, pure TSDoc extraction, categorization, multi-entry-point resolution, route/collision computation, synthetic-base detection, type-signature formatting, prose cross-linking, declaration reconstruction and markdown rendering.
 
 ## Why @tsdoctor/model
 
@@ -23,7 +23,7 @@ pnpm add @tsdoctor/model
 
 Requires Node.js >=24.11.0. This is an ESM-only package.
 
-`@effected/markdown` and `effect` are required peers (`Render` builds its output as `@effected/markdown` node trees). `@effected/package-json` is an optional peer, needed only by the `StructuredData` seam.
+`@effected/markdown`, `@effected/yaml` and `effect` are required peers — `Render` builds its output as `@effected/markdown` node trees, and the frontmatter helpers parse and emit through `@effected/yaml`. [`@tsdoctor/vfs`](https://www.npmjs.com/package/@tsdoctor/vfs) is an ordinary dependency, resolved for you: `ApiExtractedPackage` extends its `VirtualPackage`.
 
 ## Quick start
 
@@ -100,7 +100,9 @@ Supplying `filter` fully replaces the default, so compose it with `Render.isEmit
 - **`Signature`** — `format(excerpt)` turns an API Extractor `Excerpt` into a clean, line-wrapped type signature string; `stripExportDeclare` strips `export`/`declare` modifiers from declaration text.
 - **`CrossLinker`** — an immutable class that wraps known item names in prose with links, skipping code spans and existing links. Build one per build from a precomputed route map (`CrossLinker.fromRoutes`) or from item refs plus an injected URL scheme (`CrossLinker.fromRefs`); `link` returns markdown links, `linkHtml` returns `<a>` anchors.
 - **`Render`** — the markdown output system. `Render.docs(pkg, opts)` renders a whole package; `Render.item(apiItem, opts)` renders one item; `Render.isEmittable` is the default emit rule. `Render.tree` (`@alpha`) exposes the pre-serialization `@effected/markdown` node tree for a future page-IR consumer.
-- **`StructuredData`** (`@alpha`) — a reserved seam for schema.org JSON-LD derivation. `StructuredData.derive` is not implemented yet and throws if called.
+- **`ApiExtractedPackage`** — reconstructs `.d.ts` text from a model and renders it to a `Vfs`, one declaration file per entry point behind a synthetic `package.json`, so a type-checker can resolve the documented package the way a consumer would. Built on `VirtualPackage` from `@tsdoctor/vfs`; `fromApiModel(path)` loads a model file, `fromPackage(apiPackage, name)` takes one already in memory.
+- **`TypeReferenceExtractor`** — finds the types a package's declarations reference but do not own, and emits the `import type` statements those declarations need. `extractImports` covers a package, `extractImportsForEntryPoint` one entry point, and the static `formatImports` renders an `ImportStatement[]` to source lines. Built-in and self-referencing types are filtered out, and a namespaced reference imports its namespace root rather than the leaf member.
+- **Frontmatter** — `parseFrontmatter(text)` splits a document into `{ data, content }`, `stringifyFrontmatter(data)` emits the YAML block, and `emitFrontmatterBlock(data, body)` assembles a whole document. Quoting is chosen so a YAML 1.1 consumer decodes the same values a YAML 1.2 one does — an unquoted ISO timestamp would otherwise arrive as a `Date` in one and a string in the other.
 
 ## License
 

package/TypeReferenceExtractor.js

@@ -0,0 +1,201 @@
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/TypeReferenceExtractor.ts
+/**
+* Extracts type references from API Extractor models to generate import statements.
+*
+* This class analyzes API items and their excerpt tokens to identify external type
+* references that need to be imported in the generated TypeScript declaration files.
+*
+* **How it works:**
+* 1. Walks through all API items (classes, interfaces, functions, etc.)
+* 2. Extracts type references from excerpt tokens
+* 3. Filters out built-in types and internal references
+* 4. Groups external references by package
+* 5. Generates `import type` statements
+*
+* **Reference Types:**
+* - **Built-in:** TypeScript types like `Promise`, `Record`, `NonNullable` (skipped)
+* - **Internal:** References to types in the same package (skipped)
+* - **External:** References to types from npm packages (imported)
+*
+* **Canonical Reference Format:**
+* API Extractor uses canonical references like:
+* - `"zod!ZodType:interface"` → External reference to `zod` package
+* - `"mypackage!MyType:type"` → Internal reference (same package)
+* - `"!Promise:interface"` → Built-in TypeScript type
+* - `"!\"node:buffer\".__global.Buffer:interface"` → Node.js built-in (treated as built-in)
+*
+* @example
+* ```ts
+* const extractor = new TypeReferenceExtractor(apiPackage, "my-package");
+* const imports = extractor.extractImports();
+*
+* for (const stmt of imports) {
+*   console.log(`import type { ${[...stmt.symbols].join(", ")} } from "${stmt.packageName}";`);
+* }
+* // Output:
+* // import type { ZodType } from "zod";
+* // import type { Effect } from "@effect/schema";
+* ```
+*
+* @public
+*/
+var TypeReferenceExtractor = class {
+	apiPackage;
+	currentPackageName;
+	/**
+	* All type references found in the API package
+	*/
+	references = /* @__PURE__ */ new Map();
+	constructor(apiPackage, currentPackageName) {
+		this.apiPackage = apiPackage;
+		this.currentPackageName = currentPackageName;
+	}
+	/**
+	* Extract all type references from the API package and generate import statements.
+	* Returns an array of import statements grouped by package.
+	*/
+	extractImports() {
+		this.walkApiPackage();
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a specific entry point only.
+	* This enables per-entry-point import optimization for multi-entry packages.
+	*
+	* @param entryPoint - The specific entry point to extract imports for
+	* @returns Import statements containing only types used in this entry point
+	*/
+	extractImportsForEntryPoint(entryPoint) {
+		this.references.clear();
+		for (const member of entryPoint.members) this.walkApiItem(member);
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a single API item.
+	* This enables generating imports for individual signatures.
+	*
+	* @param apiItem - The specific API item to extract imports for
+	* @returns Import statements containing only types used in this item
+	*/
+	extractImportsForApiItem(apiItem) {
+		this.references.clear();
+		this.walkApiItem(apiItem);
+		return this.generateImportStatements();
+	}
+	/**
+	* Generate import statements from collected references.
+	* Used by both extractImports() and extractImportsForEntryPoint().
+	*/
+	generateImportStatements() {
+		const packageMap = /* @__PURE__ */ new Map();
+		for (const ref of this.references.values()) {
+			if (ref.isBuiltIn || ref.isInternal) continue;
+			if (!packageMap.has(ref.packageName)) packageMap.set(ref.packageName, /* @__PURE__ */ new Set());
+			packageMap.get(ref.packageName)?.add(ref.symbolName);
+		}
+		const imports = [];
+		for (const [packageName, symbols] of packageMap.entries()) imports.push({
+			packageName,
+			symbols,
+			typeOnly: true
+		});
+		imports.sort((a, b) => a.packageName.localeCompare(b.packageName));
+		return imports;
+	}
+	/**
+	* Generate import statement strings from ImportStatement objects.
+	* Returns an array of formatted import statements.
+	*/
+	static formatImports(imports) {
+		const statements = [];
+		for (const stmt of imports) {
+			const sortedSymbols = Array.from(stmt.symbols).sort();
+			const statement = `${stmt.typeOnly ? "import type" : "import"} { ${sortedSymbols.join(", ")} } from "${stmt.packageName}";`;
+			statements.push(statement);
+		}
+		return statements;
+	}
+	/**
+	* Walk through the entire API package and extract all type references
+	*/
+	walkApiPackage() {
+		for (const entryPoint of this.apiPackage.entryPoints) for (const member of entryPoint.members) this.walkApiItem(member);
+	}
+	/**
+	* Recursively walk through an API item and its children to extract type references
+	*/
+	walkApiItem(apiItem) {
+		this.extractFromExcerpt(apiItem);
+		if ("members" in apiItem) {
+			const members = apiItem.members;
+			if (Array.isArray(members)) for (const member of members) this.walkApiItem(member);
+		}
+	}
+	/**
+	* Extract type references from an API item using its excerpt
+	*/
+	extractFromExcerpt(apiItem) {
+		const excerpt = this.getExcerpt(apiItem);
+		if (!excerpt) return;
+		this.extractFromExcerptTokens(excerpt);
+	}
+	/**
+	* Get the appropriate excerpt from an API item based on its kind
+	*/
+	getExcerpt(apiItem) {
+		const item = apiItem;
+		if (item.excerpt) return item.excerpt;
+		if (apiItem.kind === ApiItemKind.TypeAlias && item.typeExcerpt) return item.typeExcerpt;
+		if ((apiItem.kind === ApiItemKind.Property || apiItem.kind === ApiItemKind.PropertySignature) && item.propertyTypeExcerpt) return item.propertyTypeExcerpt;
+		if (item.returnTypeExcerpt) return item.returnTypeExcerpt;
+		return null;
+	}
+	/**
+	* Extract type references from excerpt tokens
+	*/
+	extractFromExcerptTokens(excerpt) {
+		if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return;
+		for (const token of excerpt.spannedTokens) {
+			if (token.kind !== "Reference") continue;
+			const canonicalRef = token.canonicalReference?.toString();
+			if (!canonicalRef || typeof canonicalRef !== "string") continue;
+			const ref = this.parseCanonicalReference(canonicalRef, token.text);
+			if (ref) this.references.set(ref.canonicalReference, ref);
+		}
+	}
+	/**
+	* Parse a canonical reference string to extract type reference information.
+	*
+	* Canonical reference format: "packageName!symbolName:kind"
+	* Examples:
+	* - "zod!ZodType:interface" → External reference
+	* - "mypackage!MyType:type" → Internal reference
+	* - "!Promise:interface" → Built-in type
+	* - "!\"node:buffer\".__global.Buffer:interface" → Node.js built-in
+	*/
+	parseCanonicalReference(canonicalRef, symbolText) {
+		const exclamationIndex = canonicalRef.indexOf("!");
+		if (exclamationIndex === -1) return null;
+		const packagePart = canonicalRef.substring(0, exclamationIndex);
+		const rest = canonicalRef.substring(exclamationIndex + 1);
+		const colonIndex = rest.indexOf(":");
+		const symbolFromCanonical = colonIndex !== -1 ? rest.substring(0, colonIndex) : rest;
+		const isBuiltIn = packagePart === "" || packagePart.startsWith("\"");
+		const isInternal = packagePart === this.currentPackageName;
+		let symbolName;
+		if (symbolText.includes(".")) symbolName = symbolText.split(".")[0].trim();
+		else symbolName = symbolFromCanonical.trim();
+		return {
+			symbolName,
+			packageName: packagePart,
+			canonicalReference: canonicalRef,
+			isBuiltIn,
+			isInternal
+		};
+	}
+};
+
+//#endregion
+export { TypeReferenceExtractor };

package/index.d.ts

@@ -1,7 +1,106 @@
-import { ApiClass, ApiInterface, ApiItem, ApiModel, ApiNamespace, ApiPackage, Excerpt } from "@microsoft/api-extractor-model";
+import { ApiClass, ApiEntryPoint, ApiInterface, ApiItem, ApiModel, ApiNamespace, ApiPackage, Excerpt } from "@microsoft/api-extractor-model";
+import { VirtualPackage } from "@tsdoctor/vfs";
 import { Effect, Schema } from "effect";
 import { FlowContent, MarkdownNode } from "@effected/markdown";
 import { DocNode } from "@microsoft/tsdoc";
+//#endregion
+//#region src/ApiExtractedPackage.d.ts
+/**
+ * Reconstructs TypeScript declaration files from an API Extractor model.
+ *
+ * Extends `VirtualPackage` with the ability to generate high-fidelity
+ * `.d.ts` output from API Extractor's `ApiPackage` — including enum values,
+ * full JSDoc, namespace members, and all interface member kinds.
+ *
+ * Use the factory methods `fromApiModel` or `fromPackage` to create instances.
+ *
+ * @public
+ */
+declare class ApiExtractedPackage extends VirtualPackage {
+  readonly apiPackage: ApiPackage;
+  private constructor();
+  /**
+   * Create an ApiExtractedPackage from an API model JSON file path.
+   */
+  static fromApiModel(modelPath: string): ApiExtractedPackage;
+  /**
+   * Create an ApiExtractedPackage from an existing ApiPackage instance.
+   */
+  static fromPackage(apiPackage: ApiPackage, packageName: string): ApiExtractedPackage;
+  /**
+   * Generate the .d.ts content for a specific entry point.
+   */
+  generateDeclarations(entryPoint?: ApiEntryPoint): string;
+  /**
+   * Generate a TypeScript declaration for a single API item.
+   */
+  private generateDeclaration;
+  private generateClassDeclaration;
+  private generateInterfaceDeclaration;
+  private generateTypeAliasDeclaration;
+  private generateFunctionDeclaration;
+  private generateEnumDeclaration;
+  private generateVariableDeclaration;
+  private generateNamespaceDeclaration;
+  private generateNamespaceMember;
+  private generateNamespaceFunction;
+  private generateNamespaceInterface;
+  private generateNamespaceEnum;
+  private generateNamespaceTypeAlias;
+  private generateNamespaceVariable;
+  private generateNamespaceClass;
+  private generateClassMember;
+  private generateInterfaceMember;
+  private generateMemberFromExcerpt;
+  /**
+   * Render an excerpt to source text, normalizing dts-rollup disambiguation
+   * aliases. The dts rollup renames a re-imported symbol as `Name$1`, but its
+   * canonical reference is the un-suffixed `Name` (the same symbol). The import
+   * prepender ({@link TypeReferenceExtractor}) imports the canonical name, so
+   * emitting the suffixed text would leave `Name$1` undefined (TS2304). Emit the
+   * canonical name so the body and the prepended import agree.
+   *
+   * Equivalent to `excerpt.text` for excerpts without rollup aliases (the text
+   * is the concatenation of the spanned tokens), so unaliased output is unchanged.
+   */
+  private renderExcerpt;
+  /**
+   * Strip a dts-rollup `$N` suffix from a reference token when the de-suffixed
+   * text matches the token's canonical symbol. Never touches a non-reference
+   * token or a legitimate identifier that genuinely ends in `$N` (its canonical
+   * name would carry the suffix too).
+   */
+  private normalizeTokenText;
+  /**
+   * Clean an excerpt text: strip export/declare keywords and trailing semicolons/whitespace.
+   */
+  private cleanExcerpt;
+  private formatTypeParameters;
+  private extractPackageDocumentation;
+  /**
+   * Format JSDoc comment from an API item's TSDoc.
+   * Produces output matching the TypeScript compiler's JSDoc style.
+   */
+  private formatJSDoc;
+  /**
+   * Recursively extract plain text from a TSDoc DocNode tree.
+   *
+   * @remarks
+   * NOT interchangeable with this package's `Tsdoc` prose extraction, despite
+   * the overlapping name and shape. This one **preserves** `{@link X.Y}` TSDoc
+   * syntax and reconstructs fenced code blocks, because its output is a
+   * `.d.ts` file whose JSDoc must survive round-tripping into a virtual
+   * TypeScript environment. `Tsdoc`'s flattens `{@link}` to its display text
+   * and drops code fences, because its output is rendered prose.
+   *
+   * They looked like duplicates from two packages away and now sit in one, so
+   * this is the note that should stop the merge: collapsing them would either
+   * put display text where a declaration reference belongs, or leak link
+   * syntax into rendered documentation.
+   */
+  private extractPlainText;
+  private getEntryPointName;
+}
 declare namespace EntryPoints_d_exports {
   export { ResolvedEntryItem, entryPointName, resolve };
 }
@@ -265,6 +364,109 @@ declare class CrossLinker {
    */
   linkHtml(text: string): string;
 }
+//#endregion
+//#region src/Frontmatter.d.ts
+/**
+ * A parsed frontmatter document: the decoded frontmatter data and the body
+ * content that followed the closing delimiter.
+ *
+ * @public
+ */
+interface ParsedFrontmatter {
+  /** Decoded frontmatter data (`{}` when there is no frontmatter block). */
+  readonly data: Record<string, unknown>;
+  /** Body content after the closing delimiter (whole input when no block). */
+  readonly content: string;
+}
+/**
+ * Split markdown source into frontmatter data and body content, preserving
+ * gray-matter's exact boundary semantics.
+ *
+ * @remarks
+ * This is a byte-for-byte port of the `gray-matter` split contract the
+ * snapshot system's hashes depend on (see `@tsdoctor/snapshot`
+ * `hashContent`/`hashFrontmatter` and the disk-fallback comparison in
+ * `build-stages.ts`), with `@effected/yaml` (`Yaml.parse`, YAML 1.2) as the
+ * YAML engine instead of js-yaml:
+ *
+ * - No opening `---` line at offset 0 → `data: {}` and the whole input as
+ *   `content` (a leading BOM is stripped first, as gray-matter does).
+ * - The closing delimiter is the first `\n---` after the opening line
+ *   (gray-matter uses a plain `indexOf`, so `\n----` also closes and the
+ *   leftover `-` stays in the body — preserved deliberately).
+ * - Exactly one newline (`\n` or `\r\n`) immediately after the closing `---`
+ *   is consumed; everything else is the body verbatim. A build's generated
+ *   page (`---\n…\n---\n\n# Title`) therefore yields a body starting with a
+ *   single `\n`, exactly as gray-matter returned it.
+ * - A block with no closing delimiter is all frontmatter and yields an empty
+ *   body; an empty/blank block yields `data: {}`.
+ * - Invalid YAML throws (a defect), matching gray-matter's js-yaml throw.
+ *
+ * One deliberate delta: gray-matter treats text on the opening line
+ * (`---toml`) as an engine name and throws for unregistered engines; this
+ * split treats such input as "no frontmatter" instead. The plugin never emits
+ * or consumes language-tagged frontmatter.
+ *
+ * `@effected/markdown`'s `FrontmatterSource.split` was evaluated for this
+ * path and deliberately NOT adopted: its grammar is strict by design (a
+ * fence line is exactly `---`, an unterminated block is not frontmatter),
+ * while this contract pins gray-matter's `indexOf`-based quirks (`\n----`
+ * closes, trailing-space close lines close, a missing close means
+ * all-frontmatter). The emission half (`stringifyFrontmatter` /
+ * `emitFrontmatterBlock`) does use `FrontmatterSource.join`.
+ *
+ * Representation parity with js-yaml is verified by characterization tests
+ * (`__test__/frontmatter.test.ts`) pinning hashes captured under gray-matter.
+ * The one input where the engines disagree — an *unquoted* ISO timestamp
+ * (js-yaml: `Date`, YAML 1.2: string) — is unreachable from this plugin's
+ * emitters, which always quote timestamp values, and hashes identically
+ * anyway because `hashFrontmatter` JSON-serializes (a `Date` serializes to
+ * the same ISO string).
+ *
+ * @param source - The markdown source, with or without a frontmatter block
+ * @returns The decoded frontmatter data and the body content
+ *
+ * @public
+ */
+declare function parseFrontmatter(source: string): ParsedFrontmatter;
+/**
+ * Serialize frontmatter data and body content back into a markdown document,
+ * preserving gray-matter's `matter.stringify` contract.
+ *
+ * @remarks
+ * Emits `---\n<yaml>---\n<content>` with the body's trailing newline ensured,
+ * and returns the body unchanged (no fences) when `data` has no keys — both
+ * gray-matter behaviors the write path relied on. The YAML is emitted by
+ * `@effected/yaml` with every string value double-quoted (see
+ * `STRINGIFY_OPTIONS` for why); byte output differs from js-yaml's dump, but
+ * the decoded representation is identical, which is the invariant the
+ * snapshot hashes depend on. Unchanged pages are never rewritten, so the byte
+ * difference only ever lands in files that were being rewritten anyway.
+ *
+ * @param content - The body content
+ * @param data - The frontmatter data to serialize
+ * @returns The combined markdown document
+ *
+ * @public
+ */
+declare function stringifyFrontmatter(content: string, data: Record<string, unknown>): string;
+/**
+ * Serialize a data object to a YAML frontmatter block (fences included, plus
+ * the trailing blank line the page generators emit before the body).
+ *
+ * @remarks
+ * Used by `generateFrontmatter` (`markdown/helpers.ts`) as the emission half
+ * of the page generators' frontmatter. Every string value is double-quoted
+ * (see `STRINGIFY_OPTIONS`), so values that a YAML 1.1 consumer would
+ * otherwise coerce (timestamps, `yes`/`no`, numeric-looking strings) stay
+ * strings for RSPress's js-yaml parse.
+ *
+ * @param data - The frontmatter data to serialize
+ * @returns A `---`-fenced YAML block ending with a blank line
+ *
+ * @public
+ */
+declare function emitFrontmatterBlock(data: Record<string, unknown>): string;
 declare namespace Model_d_exports {
   export { EmptyModelError, ModelNotFoundError, ModelParseError, firstPackage, load };
 }
@@ -724,5 +926,167 @@ declare function seeReferences(item: ApiItem): ReadonlyArray<{
   readonly text: string;
 }>;
 //#endregion
-export { type ApiItemRef, ApiItems_d_exports as ApiItems, CrossLinker, type DocMeta, EntryPoints_d_exports as EntryPoints, type FrontmatterRenderer, type ItemKindSlug, Model_d_exports as Model, Render_d_exports as Render, type RenderPackageOptions, type RenderedDoc, type RouteFormatter, Routes_d_exports as Routes, Signature_d_exports as Signature, SyntheticBases_d_exports as SyntheticBases, Tsdoc_d_exports as Tsdoc };
+//#region src/TypeReferenceExtractor.d.ts
+/**
+ * Represents a type reference extracted from an API item.
+ * Contains information about where the type comes from and how to import it.
+ *
+ * @public
+ */
+interface TypeReference {
+  /**
+   * The symbol name to import (e.g., "ZodType", "Effect")
+   */
+  symbolName: string;
+  /**
+   * The package name (e.g., "zod", "\@effect/schema").
+   * Empty string for built-in TypeScript types.
+   */
+  packageName: string;
+  /**
+   * The canonical reference from API Extractor
+   * Format: "packageName!symbolName:kind"
+   */
+  canonicalReference: string;
+  /**
+   * Whether this is a built-in TypeScript type (Promise, Record, etc.)
+   */
+  isBuiltIn: boolean;
+  /**
+   * Whether this reference is from the current package being documented
+   */
+  isInternal: boolean;
+}
+/**
+ * Import statement to be generated for a package
+ *
+ * @public
+ */
+interface ImportStatement {
+  /**
+   * Package name to import from
+   */
+  packageName: string;
+  /**
+   * Named imports from this package
+   */
+  symbols: Set<string>;
+  /**
+   * Whether to use type-only import
+   */
+  typeOnly: boolean;
+}
+/**
+ * Extracts type references from API Extractor models to generate import statements.
+ *
+ * This class analyzes API items and their excerpt tokens to identify external type
+ * references that need to be imported in the generated TypeScript declaration files.
+ *
+ * **How it works:**
+ * 1. Walks through all API items (classes, interfaces, functions, etc.)
+ * 2. Extracts type references from excerpt tokens
+ * 3. Filters out built-in types and internal references
+ * 4. Groups external references by package
+ * 5. Generates `import type` statements
+ *
+ * **Reference Types:**
+ * - **Built-in:** TypeScript types like `Promise`, `Record`, `NonNullable` (skipped)
+ * - **Internal:** References to types in the same package (skipped)
+ * - **External:** References to types from npm packages (imported)
+ *
+ * **Canonical Reference Format:**
+ * API Extractor uses canonical references like:
+ * - `"zod!ZodType:interface"` → External reference to `zod` package
+ * - `"mypackage!MyType:type"` → Internal reference (same package)
+ * - `"!Promise:interface"` → Built-in TypeScript type
+ * - `"!\"node:buffer\".__global.Buffer:interface"` → Node.js built-in (treated as built-in)
+ *
+ * @example
+ * ```ts
+ * const extractor = new TypeReferenceExtractor(apiPackage, "my-package");
+ * const imports = extractor.extractImports();
+ *
+ * for (const stmt of imports) {
+ *   console.log(`import type { ${[...stmt.symbols].join(", ")} } from "${stmt.packageName}";`);
+ * }
+ * // Output:
+ * // import type { ZodType } from "zod";
+ * // import type { Effect } from "@effect/schema";
+ * ```
+ *
+ * @public
+ */
+declare class TypeReferenceExtractor {
+  private readonly apiPackage;
+  private readonly currentPackageName;
+  /**
+   * All type references found in the API package
+   */
+  private readonly references;
+  constructor(apiPackage: ApiPackage, currentPackageName: string);
+  /**
+   * Extract all type references from the API package and generate import statements.
+   * Returns an array of import statements grouped by package.
+   */
+  extractImports(): ImportStatement[];
+  /**
+   * Extract type references for a specific entry point only.
+   * This enables per-entry-point import optimization for multi-entry packages.
+   *
+   * @param entryPoint - The specific entry point to extract imports for
+   * @returns Import statements containing only types used in this entry point
+   */
+  extractImportsForEntryPoint(entryPoint: ApiEntryPoint): ImportStatement[];
+  /**
+   * Extract type references for a single API item.
+   * This enables generating imports for individual signatures.
+   *
+   * @param apiItem - The specific API item to extract imports for
+   * @returns Import statements containing only types used in this item
+   */
+  extractImportsForApiItem(apiItem: ApiItem): ImportStatement[];
+  /**
+   * Generate import statements from collected references.
+   * Used by both extractImports() and extractImportsForEntryPoint().
+   */
+  private generateImportStatements;
+  /**
+   * Generate import statement strings from ImportStatement objects.
+   * Returns an array of formatted import statements.
+   */
+  static formatImports(imports: ImportStatement[]): string[];
+  /**
+   * Walk through the entire API package and extract all type references
+   */
+  private walkApiPackage;
+  /**
+   * Recursively walk through an API item and its children to extract type references
+   */
+  private walkApiItem;
+  /**
+   * Extract type references from an API item using its excerpt
+   */
+  private extractFromExcerpt;
+  /**
+   * Get the appropriate excerpt from an API item based on its kind
+   */
+  private getExcerpt;
+  /**
+   * Extract type references from excerpt tokens
+   */
+  private extractFromExcerptTokens;
+  /**
+   * Parse a canonical reference string to extract type reference information.
+   *
+   * Canonical reference format: "packageName!symbolName:kind"
+   * Examples:
+   * - "zod!ZodType:interface" → External reference
+   * - "mypackage!MyType:type" → Internal reference
+   * - "!Promise:interface" → Built-in type
+   * - "!\"node:buffer\".__global.Buffer:interface" → Node.js built-in
+   */
+  private parseCanonicalReference;
+}
+//#endregion
+export { ApiExtractedPackage, type ApiItemRef, ApiItems_d_exports as ApiItems, CrossLinker, type DocMeta, EntryPoints_d_exports as EntryPoints, type FrontmatterRenderer, type ImportStatement, type ItemKindSlug, Model_d_exports as Model, type ParsedFrontmatter, Render_d_exports as Render, type RenderPackageOptions, type RenderedDoc, type RouteFormatter, Routes_d_exports as Routes, Signature_d_exports as Signature, SyntheticBases_d_exports as SyntheticBases, Tsdoc_d_exports as Tsdoc, type TypeReference, TypeReferenceExtractor, emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,11 +1,14 @@
+import { ApiExtractedPackage } from "./ApiExtractedPackage.js";
 import { Routes_exports } from "./Routes.js";
 import { Tsdoc_exports } from "./Tsdoc.js";
 import { ApiItems_exports } from "./ApiItems.js";
 import { CrossLinker } from "./CrossLinker.js";
 import { EntryPoints_exports } from "./EntryPoints.js";
+import { emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter } from "./Frontmatter.js";
 import { Model_exports } from "./Model.js";
 import { Signature_exports } from "./Signature.js";
 import { Render_exports } from "./Render.js";
 import { SyntheticBases_exports } from "./SyntheticBases.js";
+import { TypeReferenceExtractor } from "./TypeReferenceExtractor.js";
 
-export { ApiItems_exports as ApiItems, CrossLinker, EntryPoints_exports as EntryPoints, Model_exports as Model, Render_exports as Render, Routes_exports as Routes, Signature_exports as Signature, SyntheticBases_exports as SyntheticBases, Tsdoc_exports as Tsdoc };
+export { ApiExtractedPackage, ApiItems_exports as ApiItems, CrossLinker, EntryPoints_exports as EntryPoints, Model_exports as Model, Render_exports as Render, Routes_exports as Routes, Signature_exports as Signature, SyntheticBases_exports as SyntheticBases, Tsdoc_exports as Tsdoc, TypeReferenceExtractor, emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/model",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"private": false,
 	"description": "Render Microsoft API Extractor models into LLM-lean markdown. Pure model loading, TSDoc extraction, type-signature formatting, and per-item markdown rendering.",
 	"keywords": [
@@ -39,18 +39,14 @@
 	},
 	"dependencies": {
 		"@microsoft/api-extractor-model": "^7.33.11",
-		"@microsoft/tsdoc": "^0.16.0"
+		"@microsoft/tsdoc": "^0.16.0",
+		"@tsdoctor/vfs": "0.1.0"
 	},
 	"peerDependencies": {
 		"@effected/markdown": "^0.7.0",
-		"@effected/package-json": "^0.13.0",
+		"@effected/yaml": "^0.12.0",
 		"effect": "4.0.0-rc.109"
 	},
-	"peerDependenciesMeta": {
-		"@effected/package-json": {
-			"optional": true
-		}
-	},
 	"engines": {
 		"node": ">=24.11.0"
 	}