@tsdoctor/model 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @tsdoctor/model
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor/model?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/model)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178c6.svg)](https://www.typescriptlang.org/)
+
+Turn a Microsoft API Extractor `.api.json` model into plain markdown that reads cleanly for both people and language models. You get one markdown document per top-level export — an H1, the summary, a fenced `ts` signature, parameters, returns, container members and examples — with no site chrome, no HTML and no framework coupling.
+
+## Why @tsdoctor/model
+
+API Extractor already understands your `.d.ts` surface. What it will not do is hand you docs you can drop into a prompt, a wiki or a static site. That is the gap this package closes. The body of every rendered doc stays the same no matter where it ends up. Two things change between consumers: the frontmatter block at the top and the URL scheme for cross-links. You inject both, so one renderer feeds an RSPress site, an MCP server or a folder of bare `.md` files.
+
+## Install
+
+```bash
+npm install @tsdoctor/model
+# or
+pnpm add @tsdoctor/model
+```
+
+The package is also published to GitHub Packages as `@spencerbeggs/@tsdoctor/model` if you prefer the scoped name; point your registry at `https://npm.pkg.github.com` for that scope and install it the same way.
+
+This is an ESM-only package. Import it from a module context (`"type": "module"` or `.mjs`).
+
+## Quick start
+
+Load a model, render it, then write each doc wherever you want. The library does no I/O of its own. File writing is yours.
+
+```ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { loadApiModel, renderPackage } from "@tsdoctor/model";
+
+const pkg = await loadApiModel("./temp/my-pkg.api.json");
+
+const docs = renderPackage(pkg, {
+  packageName: "my-pkg",
+  routeFor: (ref) => `/api/${ref.slug}`,
+});
+
+await mkdir("./out", { recursive: true });
+for (const doc of docs) {
+  await writeFile(`./out/${doc.slug}.md`, doc.markdown);
+}
+
+console.log(docs.map((d) => `${d.kind}: ${d.name}`));
+// e.g. [ 'function: loadApiModel', 'class: CrossLinker', 'type: RenderedDoc' ]
+// (the actual list depends on your model's exports)
+```
+
+Each entry in the returned array is a `RenderedDoc` with `name`, `kind`, `slug`, `summary`, `packageName` and the assembled `markdown`.
+
+### Inject frontmatter
+
+Pass a `frontmatter` function to prepend a block — YAML, TOML or whatever your target expects. Omit it for bare bodies.
+
+```ts
+const docs = renderPackage(pkg, {
+  packageName: "my-pkg",
+  frontmatter: (meta) => `---\ntitle: ${meta.name}\nkind: ${meta.kind}\n---\n\n`,
+});
+
+console.log(docs[0].markdown.startsWith("---"));
+// true
+```
+
+`routeFor` and `frontmatter` are independent. Supply either, both or neither.
+
+### Filter exports
+
+By default `renderPackage` drops compiler-synthetic forgotten exports — the `*_base` classes TypeScript hoists for Effect class mixins, which API Extractor keeps in the model when it runs with `includeForgottenExports: true`. They stay in the `.api.json` (downstream `.d.ts` reconstruction needs them) but never reach the rendered markdown. That default lives in the exported `isEmittable` predicate.
+
+Pass your own `filter` to change which top-level items are emitted. A filter that returns `true` keeps the item, both as a rendered doc and as a crosslink target. Supplying a `filter` fully replaces the default, so compose it with `isEmittable` when you want to keep the forgotten-export drop alongside your own rule.
+
+```ts
+import { isEmittable, renderPackage } from "@tsdoctor/model";
+
+const docs = renderPackage(pkg, {
+  packageName: "my-pkg",
+  filter: (item) => isEmittable(item) && !item.displayName.startsWith("Internal"),
+});
+
+console.log(docs.every((d) => !d.name.startsWith("Internal")));
+// true
+```
+
+## Features
+
+- `loadApiModel(path)` reads a `.api.json` file from disk and returns its `ApiPackage`.
+- `renderPackage(pkg, opts)` walks the first entry point and returns one `RenderedDoc` per top-level member, dropping compiler-synthetic forgotten exports unless you pass your own `filter`.
+- `renderItem(item, opts)` renders a single API item to a markdown body, with an optional `CrossLinker`.
+- `isEmittable(item)` is the default emit rule — it drops forgotten exports (`isExported === false`) and keeps everything else; compose it into a custom `filter` to keep that behaviour.
+- `CrossLinker` wraps known item names in prose with links, skipping code spans and existing links, using your injected route scheme.
+- `TypeSignatureFormatter` formats an API Extractor `Excerpt` into a clean type signature, wrapping long unions across lines.
+- TSDoc helpers — `getSummary`, `getParams`, `getReturns`, `getExamples`, `getDeprecation`, `getReleaseTag`, `hasModifierTag` and `extractPlainText` — pull plain data off an `ApiItem` with no rendering.
+
+## Generating a model
+
+This package consumes the JSON that [Microsoft API Extractor](https://api-extractor.com/) produces. Run API Extractor against your project first with `docModel.enabled` set in your `api-extractor.json`, then feed the resulting `.api.json` to `loadApiModel`.
+
+## License
+
+[MIT](LICENSE)

package/cross-linker.js

@@ -0,0 +1,37 @@
+//#region src/cross-linker.ts
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* Links known API item names in prose to their docs, using an injected
+* {@link RouteFormatter} so each consumer supplies its own URL scheme.
+*
+* @public
+*/
+var CrossLinker = class {
+	byName;
+	routeFor;
+	constructor(refs, routeFor) {
+		this.byName = new Map(refs.map((r) => [r.name, r]));
+		this.routeFor = routeFor;
+	}
+	/** Wrap known item names in markdown links, skipping code spans + existing links. */
+	addLinks(text) {
+		let result = text;
+		const names = [...this.byName.keys()].sort((a, b) => b.length - a.length);
+		for (const name of names) {
+			const ref = this.byName.get(name);
+			if (!ref) continue;
+			const route = this.routeFor(ref);
+			const regex = new RegExp(`\\b${escapeRegExp(name)}\\b`, "g");
+			result = result.replace(regex, (match, offset) => {
+				const before = result.slice(0, offset);
+				if (before.endsWith("](") || before.endsWith("[")) return match;
+				if ((before.match(/`/g) || []).length % 2 === 1) return match;
+				return `[${match}](${route})`;
+			});
+		}
+		return result;
+	}
+};
+
+//#endregion
+export { CrossLinker };

package/formatter.js

@@ -0,0 +1,70 @@
+//#region src/formatter.ts
+/**
+* Formats an API Extractor `Excerpt` into a clean, line-wrapped type signature string.
+*
+* @public
+*/
+var TypeSignatureFormatter = class {
+	maxLineLength;
+	indent;
+	constructor(opts = {}) {
+		this.maxLineLength = opts.maxLineLength ?? 80;
+		this.indent = opts.indent ?? "  ";
+	}
+	format(excerpt) {
+		if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return this.stripExportDeclare(excerpt.text);
+		const tokens = excerpt.spannedTokens;
+		let currentLine = "";
+		const lines = [];
+		let bracketDepth = 0;
+		let lastTokenText = "";
+		for (let i = 0; i < tokens.length; i++) {
+			let tokenText = tokens[i].text;
+			if (i === 0) tokenText = this.stripExportDeclare(tokenText);
+			if (tokenText.trim() === "") continue;
+			if (tokenText === "{" || tokenText === "[" || tokenText === "(") bracketDepth++;
+			else if (tokenText === "}" || tokenText === "]" || tokenText === ")") bracketDepth--;
+			const isOperator = tokenText.trim() === "|" || tokenText.trim() === "&";
+			if (lastTokenText && this.needsSpaceBefore(lastTokenText, tokenText)) currentLine += " ";
+			currentLine += tokenText;
+			lastTokenText = tokenText;
+			if (isOperator && bracketDepth === 0 && currentLine.length > this.maxLineLength && i < tokens.length - 1) {
+				lines.push(currentLine.trimEnd());
+				currentLine = this.indent;
+			}
+		}
+		if (currentLine.trim()) lines.push(currentLine.trimEnd());
+		if (lines.length <= 1) return lines.length === 1 ? lines[0].trimStart() : "";
+		return this.stripExportDeclare(lines.join("\n"));
+	}
+	stripExportDeclare(text) {
+		let result = text.trim().replace(/^export\s+declare\s+/i, "").replace(/^export\s+/i, "").replace(/^declare\s+/i, "");
+		result = result.replace(/\bexport\s+declare\s+/gi, "").replace(/\bexport\s+/gi, "").replace(/\bdeclare\s+/gi, "");
+		return result;
+	}
+	needsSpaceBefore(prevText, currentText) {
+		if (/\s$/.test(prevText)) return false;
+		if (/^\s/.test(currentText)) return false;
+		if (currentText.trim().startsWith("<")) return false;
+		if (currentText.trim().match(/^[,;]/)) return false;
+		if (prevText.trim().endsWith(",")) return true;
+		if (currentText.trim() === "=" || currentText.trim().startsWith("=")) return true;
+		if (prevText.trim().endsWith("=")) return true;
+		if (currentText.trim() === "|" || currentText.trim() === "&") return true;
+		if (prevText.trim() === "|" || prevText.trim() === "&") return true;
+		if (prevText.trim() === "{" && currentText.trim() !== "}") return true;
+		if (currentText.trim() === "}" && prevText.trim() !== "{") return true;
+		if (prevText.trim().match(/^[[(]$/)) return false;
+		if (currentText.trim().match(/^[\])]$/)) return false;
+		if (prevText.trim().endsWith(":")) return true;
+		if (prevText.trim().endsWith("?:")) return true;
+		if (currentText.trim().startsWith(":") && !prevText.trim().match(/[,;:?]$/)) return false;
+		if (currentText.trim().startsWith("{") && /[a-zA-Z0-9_>]$/.test(prevText.trim())) return true;
+		const prevEndsAlnum = /[a-zA-Z0-9_>]$/.test(prevText.trim());
+		const currStartsAlnum = /^[a-zA-Z0-9_<]/.test(currentText.trim());
+		return prevEndsAlnum && currStartsAlnum;
+	}
+};
+
+//#endregion
+export { TypeSignatureFormatter };

package/index.d.ts

@@ -0,0 +1,211 @@
+import { ApiItem, ApiPackage, Excerpt } from "@microsoft/api-extractor-model";
+import { DocNode } from "@microsoft/tsdoc";
+//#region src/types.d.ts
+/**
+ * URL-stable slug for an item kind, used in routes and generated doc paths.
+ *
+ * @public
+ */
+type ItemKindSlug = "class" | "interface" | "function" | "type" | "variable" | "enum" | "namespace";
+/**
+ * A reference to a renderable top-level API item.
+ *
+ * @public
+ */
+interface ApiItemRef {
+  readonly name: string;
+  readonly kind: ItemKindSlug;
+  /** Lowercased name for the file/url, e.g. "managedsection". */
+  readonly slug: string;
+}
+/**
+ * Metadata handed to the injected frontmatter renderer for one doc.
+ *
+ * @public
+ */
+interface DocMeta extends ApiItemRef {
+  readonly summary: string;
+  readonly packageName: string;
+}
+/**
+ * Injected: turn an item reference into a crosslink URL (the only scheme difference).
+ *
+ * @public
+ */
+type RouteFormatter = (ref: ApiItemRef) => string;
+/**
+ * Injected: produce the frontmatter block (incl. trailing blank line) for a doc, or "".
+ *
+ * @public
+ */
+type FrontmatterRenderer = (meta: DocMeta) => string;
+/**
+ * One rendered API doc = its metadata plus the assembled markdown (frontmatter + body).
+ *
+ * @public
+ */
+interface RenderedDoc extends DocMeta {
+  readonly markdown: string;
+}
+/**
+ * Options for {@link renderPackage}: the package name plus the optional injected
+ * route, frontmatter, and filter services.
+ *
+ * @public
+ */
+interface RenderPackageOptions {
+  /** Package display name (used in fallbacks + handed to the frontmatter renderer). */
+  readonly packageName: string;
+  /** Injected crosslink scheme. Omit → no cross-linking. */
+  readonly routeFor?: RouteFormatter;
+  /** Injected frontmatter. Omit → bodies only. */
+  readonly frontmatter?: FrontmatterRenderer;
+  /**
+   * Predicate deciding whether a top-level item is emitted (and registered as a
+   * crosslink target). Returns `true` to keep the item. Omit → the default rule
+   * {@link isEmittable} drops compiler-synthetic forgotten exports
+   * (`isExported === false`). Providing a filter fully replaces the default; compose
+   * with {@link isEmittable} to retain the forgotten-export drop.
+   */
+  readonly filter?: (item: ApiItem) => boolean;
+}
+//#endregion
+//#region src/cross-linker.d.ts
+/**
+ * Links known API item names in prose to their docs, using an injected
+ * {@link RouteFormatter} so each consumer supplies its own URL scheme.
+ *
+ * @public
+ */
+declare class CrossLinker {
+  private readonly byName;
+  private readonly routeFor;
+  constructor(refs: ReadonlyArray<ApiItemRef>, routeFor: RouteFormatter);
+  /** Wrap known item names in markdown links, skipping code spans + existing links. */
+  addLinks(text: string): string;
+}
+//#endregion
+//#region src/formatter.d.ts
+/**
+ * Formats an API Extractor `Excerpt` into a clean, line-wrapped type signature string.
+ *
+ * @public
+ */
+declare class TypeSignatureFormatter {
+  private readonly maxLineLength;
+  private readonly indent;
+  constructor(opts?: {
+    maxLineLength?: number;
+    indent?: string;
+  });
+  format(excerpt: Excerpt): string;
+  private stripExportDeclare;
+  private needsSpaceBefore;
+}
+//#endregion
+//#region src/model-loader.d.ts
+/**
+ * Load a `.api.json` model file and return its first (only) package.
+ *
+ * @public
+ */
+declare function loadApiModel(modelPath: string): Promise<ApiPackage>;
+//#endregion
+//#region src/render.d.ts
+/**
+ * The default emit rule for {@link renderPackage}: drop compiler-synthetic
+ * forgotten exports — items the model retains only because API Extractor ran with
+ * `includeForgottenExports: true` (e.g. the `*_base` classes TypeScript hoists for
+ * Effect class mixins). Those carry `isExported === false` on `ApiExportedMixin`.
+ * Every other item, including any lacking the flag, is kept.
+ *
+ * @public
+ */
+declare const isEmittable: (item: ApiItem) => boolean;
+/**
+ * Options for {@link renderItem}: the package name used in fallbacks and an
+ * optional crosslinker applied to the rendered prose.
+ *
+ * @public
+ */
+interface RenderItemOptions {
+  readonly packageName: string;
+  /** Optional crosslinker applied to prose (summaries, params, returns, deprecation). */
+  readonly crossLinker?: CrossLinker;
+}
+/**
+ * Render one API item to a markdown body (no frontmatter).
+ *
+ * @public
+ */
+declare function renderItem(item: ApiItem, opts: RenderItemOptions): string;
+/**
+ * Walk a package's first entry point and assemble one RenderedDoc per top-level member.
+ *
+ * @public
+ */
+declare function renderPackage(apiPackage: ApiPackage, opts: RenderPackageOptions): RenderedDoc[];
+//#endregion
+//#region src/tsdoc.d.ts
+/**
+ * Recursively flatten a TSDoc DocNode tree to plain text (code spans → backticks).
+ *
+ * @public
+ */
+declare function extractPlainText(node: DocNode): string;
+/**
+ * The TSDoc `@summary` section as a single cleaned line.
+ *
+ * @public
+ */
+declare function getSummary(item: ApiItem): string;
+/**
+ * `@param` blocks merged with parameter types from the declaration excerpt.
+ *
+ * @public
+ */
+declare function getParams(item: ApiItem): Array<{
+  name: string;
+  type?: string;
+  description: string;
+}>;
+/**
+ * The `@returns` block description, if present.
+ *
+ * @public
+ */
+declare function getReturns(item: ApiItem): {
+  description: string;
+} | null;
+/**
+ * All `@example` fenced-code blocks (falls back to plain text).
+ *
+ * @public
+ */
+declare function getExamples(item: ApiItem): Array<{
+  language: string;
+  code: string;
+}>;
+/**
+ * Reads the deprecation-block message from an ApiItem, if one is present.
+ *
+ * @public
+ */
+declare function getDeprecation(item: ApiItem): {
+  message: string;
+} | null;
+/**
+ * The release tag (Public/Beta/Alpha/Internal) or "Public" when absent.
+ *
+ * @public
+ */
+declare function getReleaseTag(item: ApiItem): string;
+/**
+ * True when the item carries the given TSDoc modifier tag (without the `@`).
+ *
+ * @public
+ */
+declare function hasModifierTag(item: ApiItem, tagName: string): boolean;
+//#endregion
+export { type ApiItemRef, CrossLinker, type DocMeta, type FrontmatterRenderer, type ItemKindSlug, type RenderItemOptions, type RenderPackageOptions, type RenderedDoc, type RouteFormatter, TypeSignatureFormatter, extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag, isEmittable, loadApiModel, renderItem, renderPackage };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,7 @@
+import { CrossLinker } from "./cross-linker.js";
+import { TypeSignatureFormatter } from "./formatter.js";
+import { loadApiModel } from "./model-loader.js";
+import { extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag } from "./tsdoc.js";
+import { isEmittable, renderItem, renderPackage } from "./render.js";
+
+export { CrossLinker, TypeSignatureFormatter, extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag, isEmittable, loadApiModel, renderItem, renderPackage };

package/model-loader.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ApiModel } from "@microsoft/api-extractor-model";
+
+//#region src/model-loader.ts
+/**
+* Load a Microsoft API Extractor `.api.json` model from disk and return its
+* single `ApiPackage`. Ported from rspress-plugin-api-extractor's ApiModelLoader.
+*
+* @packageDocumentation
+*/
+/**
+* Load a `.api.json` model file and return its first (only) package.
+*
+* @public
+*/
+async function loadApiModel(modelPath) {
+	const resolved = resolve(modelPath);
+	if (!existsSync(resolved)) throw new Error(`API model file not found: ${resolved}`);
+	return new ApiModel().loadPackage(resolved);
+}
+
+//#endregion
+export { loadApiModel };

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@tsdoctor/model",
+	"version": "0.1.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": [
+		"api-extractor",
+		"tsdoc",
+		"llms",
+		"documentation",
+		"markdown",
+		"typescript",
+		"esm"
+	],
+	"homepage": "https://github.com/spencerbeggs/tsdoctor#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/tsdoctor/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/tsdoctor.git",
+		"directory": "packages/model"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@microsoft/api-extractor-model": "^7.33.10",
+		"@microsoft/tsdoc": "^0.16.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/render.js

@@ -0,0 +1,118 @@
+import { CrossLinker } from "./cross-linker.js";
+import { TypeSignatureFormatter } from "./formatter.js";
+import { getDeprecation, getExamples, getParams, getReturns, getSummary } from "./tsdoc.js";
+import { ApiItemContainerMixin } from "@microsoft/api-extractor-model";
+
+//#region src/render.ts
+const KIND_SLUG = {
+	Class: "class",
+	Interface: "interface",
+	Function: "function",
+	TypeAlias: "type",
+	Variable: "variable",
+	Enum: "enum",
+	Namespace: "namespace"
+};
+/**
+* The default emit rule for {@link renderPackage}: drop compiler-synthetic
+* forgotten exports — items the model retains only because API Extractor ran with
+* `includeForgottenExports: true` (e.g. the `*_base` classes TypeScript hoists for
+* Effect class mixins). Those carry `isExported === false` on `ApiExportedMixin`.
+* Every other item, including any lacking the flag, is kept.
+*
+* @public
+*/
+const isEmittable = (item) => item.isExported !== false;
+const formatter = new TypeSignatureFormatter();
+const signatureOf = (item) => {
+	const declared = item;
+	return declared.excerpt?.text ? formatter.format(declared.excerpt).trim() : "";
+};
+/**
+* Render one API item to a markdown body (no frontmatter).
+*
+* @public
+*/
+function renderItem(item, opts) {
+	const link = (text) => opts.crossLinker ? opts.crossLinker.addLinks(text) : text;
+	const lines = [`# ${item.displayName}`, ""];
+	const deprecation = getDeprecation(item);
+	if (deprecation) lines.push(`> **Deprecated:** ${link(deprecation.message)}`, "");
+	const summary = getSummary(item);
+	if (summary) lines.push(link(summary), "");
+	const signature = signatureOf(item);
+	if (signature) lines.push("```ts", signature, "```", "");
+	const params = getParams(item);
+	if (params.length > 0) {
+		lines.push("## Parameters", "");
+		for (const p of params) {
+			const type = p.type ? ` \`${p.type}\`` : "";
+			const desc = p.description ? ` — ${link(p.description)}` : "";
+			lines.push(`- \`${p.name}\`${type}${desc}`);
+		}
+		lines.push("");
+	}
+	const returns = getReturns(item);
+	if (returns) lines.push("## Returns", "", link(returns.description), "");
+	const members = item.members;
+	if (Array.isArray(members) && members.length > 0 && ApiItemContainerMixin.isBaseClassOf(item)) {
+		lines.push("## Members", "");
+		for (const m of members) {
+			const sig = signatureOf(m);
+			const mSummary = getSummary(m);
+			lines.push(`### ${m.displayName}`, "");
+			if (sig) lines.push("```ts", sig, "```", "");
+			if (mSummary) lines.push(link(mSummary), "");
+		}
+	}
+	const examples = getExamples(item);
+	if (examples.length > 0) {
+		lines.push("## Examples", "");
+		for (const ex of examples) lines.push(`\`\`\`${ex.language}`, ex.code, "```", "");
+	}
+	return `${lines.join("\n").trim()}\n`;
+}
+/**
+* Walk a package's first entry point and assemble one RenderedDoc per top-level member.
+*
+* @public
+*/
+function renderPackage(apiPackage, opts) {
+	const entryPoint = apiPackage.entryPoints[0];
+	if (!entryPoint) return [];
+	const keep = opts.filter ?? isEmittable;
+	const pairs = [];
+	for (const member of entryPoint.members) {
+		const kind = KIND_SLUG[member.kind];
+		if (kind === void 0) continue;
+		if (!keep(member)) continue;
+		pairs.push({
+			item: member,
+			ref: {
+				name: member.displayName,
+				kind,
+				slug: member.displayName.toLowerCase()
+			}
+		});
+	}
+	const crossLinker = opts.routeFor ? new CrossLinker(pairs.map((p) => p.ref), opts.routeFor) : void 0;
+	return pairs.map(({ item, ref }) => {
+		const body = renderItem(item, {
+			packageName: opts.packageName,
+			...crossLinker ? { crossLinker } : {}
+		});
+		const meta = {
+			...ref,
+			summary: getSummary(item),
+			packageName: opts.packageName
+		};
+		const frontmatter = opts.frontmatter ? opts.frontmatter(meta) : "";
+		return {
+			...meta,
+			markdown: frontmatter + body
+		};
+	});
+}
+
+//#endregion
+export { isEmittable, renderItem, renderPackage };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.0"
+    }
+  ]
+}

package/tsdoc.js

@@ -0,0 +1,158 @@
+import { ApiDocumentedItem, ApiReleaseTagMixin, ReleaseTag } from "@microsoft/api-extractor-model";
+
+//#region src/tsdoc.ts
+/**
+* Recursively flatten a TSDoc DocNode tree to plain text (code spans → backticks).
+*
+* @public
+*/
+function extractPlainText(node) {
+	const nodeAny = node;
+	if (node.kind === "PlainText") return nodeAny.text || "";
+	if (node.kind === "SoftBreak") return " ";
+	if (node.kind === "CodeSpan") return `\`${nodeAny.code || ""}\``;
+	if (node.kind === "LinkTag") {
+		if (nodeAny.linkText) return extractPlainText(nodeAny.linkText);
+		return (nodeAny.codeDestination?.memberReferences?.[0]?.memberIdentifier)?.identifier || "";
+	}
+	const parts = [];
+	if (typeof nodeAny.getChildNodes === "function") for (const child of nodeAny.getChildNodes()) {
+		const childText = extractPlainText(child);
+		if (childText) parts.push(childText);
+	}
+	return parts.join("");
+}
+/**
+* The TSDoc `@summary` section as a single cleaned line.
+*
+* @public
+*/
+function getSummary(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.summarySection) return extractPlainText(tsdoc.summarySection).replace(/\s+/g, " ").trim();
+	}
+	return "";
+}
+/**
+* `@param` blocks merged with parameter types from the declaration excerpt.
+*
+* @public
+*/
+function getParams(item) {
+	const out = [];
+	const paramTypes = /* @__PURE__ */ new Map();
+	const parameters = item.parameters;
+	if (Array.isArray(parameters)) for (const param of parameters) {
+		const excerpt = param.parameterTypeExcerpt;
+		const name = param.name || "";
+		if (excerpt?.text) paramTypes.set(name, String(excerpt.text).trim());
+	}
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.params) {
+			for (const block of tsdoc.params.blocks) {
+				const blockAny = block;
+				const name = blockAny.parameterName || "";
+				const description = extractPlainText(blockAny.content).replace(/\s+/g, " ").trim();
+				const type = paramTypes.get(name);
+				out.push({
+					name,
+					...type != null ? { type } : {},
+					description
+				});
+			}
+			return out;
+		}
+	}
+	for (const [name, type] of paramTypes.entries()) out.push({
+		name,
+		type,
+		description: ""
+	});
+	return out;
+}
+/**
+* The `@returns` block description, if present.
+*
+* @public
+*/
+function getReturns(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.returnsBlock) {
+			const description = extractPlainText(tsdoc.returnsBlock.content).replace(/\s+/g, " ").trim();
+			return description.length > 0 ? { description } : null;
+		}
+	}
+	return null;
+}
+/**
+* All `@example` fenced-code blocks (falls back to plain text).
+*
+* @public
+*/
+function getExamples(item) {
+	const examples = [];
+	if (!(item instanceof ApiDocumentedItem)) return examples;
+	const tsdoc = item.tsdocComment;
+	for (const block of tsdoc?.customBlocks || []) {
+		if (block.blockTag?.tagNameWithUpperCase !== "@EXAMPLE") continue;
+		const content = block.content;
+		let found = false;
+		for (const node of content?.nodes || []) if (node.kind === "FencedCode") {
+			examples.push({
+				language: node.language || "typescript",
+				code: node.code || ""
+			});
+			found = true;
+		}
+		if (!found) {
+			const text = extractPlainText(content).trim();
+			if (text) examples.push({
+				language: "typescript",
+				code: text
+			});
+		}
+	}
+	return examples;
+}
+/**
+* Reads the deprecation-block message from an ApiItem, if one is present.
+*
+* @public
+*/
+function getDeprecation(item) {
+	if (item instanceof ApiDocumentedItem) {
+		const tsdoc = item.tsdocComment;
+		if (tsdoc?.deprecatedBlock) return { message: extractPlainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim() };
+	}
+	return null;
+}
+/**
+* The release tag (Public/Beta/Alpha/Internal) or "Public" when absent.
+*
+* @public
+*/
+function getReleaseTag(item) {
+	if (ApiReleaseTagMixin.isBaseClassOf(item)) switch (item.releaseTag) {
+		case ReleaseTag.Public: return "Public";
+		case ReleaseTag.Beta: return "Beta";
+		case ReleaseTag.Alpha: return "Alpha";
+		case ReleaseTag.Internal: return "Internal";
+		default: return "Public";
+	}
+	return "Public";
+}
+/**
+* True when the item carries the given TSDoc modifier tag (without the `@`).
+*
+* @public
+*/
+function hasModifierTag(item, tagName) {
+	if (item instanceof ApiDocumentedItem) return ((item.tsdocComment?.modifierTagSet)?.nodes || []).some((t) => t.tagName === `@${tagName}`);
+	return false;
+}
+
+//#endregion
+export { extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag };