@openpkg-ts/sdk 0.30.0 → 0.30.1

package/dist/index.d.ts

@@ -1,404 +1,323 @@
-interface ListExportsOptions {
-	/** Entry point file path */
-	entryFile: string;
-	/** Base directory for resolution */
-	baseDir?: string;
-	/** Optional in-memory content (for testing) */
-	content?: string;
-}
-interface ExportItem {
-	/** Export name */
-	name: string;
-	/** Export kind */
-	kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace";
-	/** Source file path */
-	file: string;
-	/** Line number (1-indexed) */
-	line: number;
-	/** JSDoc description (first line, max 80 chars) */
-	description?: string;
-	/** Whether is deprecated */
-	deprecated?: boolean;
-	/** Whether this is a re-from another module */
-	reexport?: boolean;
-}
-interface ListExportsResult {
-	exports: ExportItem[];
-	errors: string[];
-}
+import { BreakingSeverity, CategorizedBreaking, calculateNextVersion, categorizeBreakingChanges, diffSpec, diffSpec as diffSpec2, MemberChangeInfo, recommendSemverBump, SemverBump, SemverRecommendation, SpecDiff } from "@openpkg-ts/spec";
+import { SpecMember } from "@openpkg-ts/spec";
 /**
-* List all exports from a TypeScript entry point
+* Extract badge strings from a member's visibility and flags.
+* Handles: visibility (if not public), static, readonly, async, abstract
 */
-declare function listExports(options: ListExportsOptions): Promise<ListExportsResult>;
-import { SpecExport, SpecType } from "@openpkg-ts/spec";
-interface GetExportOptions {
-	/** Entry point file path */
-	entryFile: string;
-	/** Export name to get */
-	exportName: string;
-	/** Base directory for resolution */
-	baseDir?: string;
-	/** Optional in-memory content (for testing) */
-	content?: string;
-	/** Max depth for type resolution */
-	maxTypeDepth?: number;
-}
-interface GetExportResult {
-	/** The spec, or null if not found */
-	export: SpecExport | null;
-	/** Related types referenced by the */
-	types: SpecType[];
-	/** Errors encountered */
-	errors: string[];
-}
-/**
-* Get detailed spec for a single */
-declare function getExport2(options: GetExportOptions): Promise<GetExportResult>;
-import { OpenPkg } from "@openpkg-ts/spec";
-interface ExtractOptions {
-	entryFile: string;
-	baseDir?: string;
-	content?: string;
-	maxTypeDepth?: number;
-	maxExternalTypeDepth?: number;
-	resolveExternalTypes?: boolean;
-	schemaExtraction?: "static" | "hybrid";
-	/** Target JSON Schema dialect for runtime schema extraction */
-	schemaTarget?: "draft-2020-12" | "draft-07" | "openapi-3.0";
-	/** Include $schema URL in output */
-	includeSchema?: boolean;
-	/** Only extract these exports (supports * wildcards) */
-	only?: string[];
-	/** Ignore these exports (supports * wildcards) */
-	ignore?: string[];
-	/** Progress callback for tracking extraction progress */
-	onProgress?: (current: number, total: number, item: string) => void;
-	/** Whether source is a .d.ts file (degraded mode - TSDoc may be missing) */
-	isDtsSource?: boolean;
-}
-interface ExtractResult {
-	spec: OpenPkg;
-	diagnostics: Diagnostic[];
-	forgottenExports?: ForgottenExport[];
-	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
-	runtimeSchemas?: {
-		/** Number of schema exports found */
-		extracted: number;
-		/** Number of schemas successfully merged with static types */
-		merged: number;
-		/** Schema vendors detected (e.g., 'zod', 'arktype', 'valibot', 'typebox') */
-		vendors: string[];
-		/** Any errors encountered during runtime extraction */
-		errors: string[];
-		/** Extraction method used: 'compiled' or 'direct-ts (runtime)' */
-		method?: string;
-	};
-	/** Degraded mode info when extracting from .d.ts files */
-	degradedMode?: {
-		reason: "dts-source";
-		stats: {
-			exportsWithoutDescription: number;
-			paramsWithoutDocs: number;
-			missingExamples: number;
-		};
-	};
-	/** Export verification comparing discovered vs extracted */
-	verification?: ExportVerification;
-}
-interface Diagnostic {
-	message: string;
-	severity: "error" | "warning" | "info";
-	code?: string;
-	suggestion?: string;
-	location?: {
-		file?: string;
-		line?: number;
-		column?: number;
-	};
-}
-/** Context tracking for type references in public API */
-interface TypeReference2 {
-	typeName: string;
-	exportName: string;
-	location: "return" | "parameter" | "property" | "extends" | "type-parameter";
-	path?: string;
-}
-/** Structured data for forgotten exports */
-interface ForgottenExport {
-	name: string;
-	definedIn?: string;
-	referencedBy: TypeReference2[];
-	isExternal: boolean;
-	fix?: string;
-}
-/** Tracks status of each discovered through serialization pipeline */
-interface ExportTracker {
-	name: string;
-	discovered: boolean;
-	status: "pending" | "success" | "skipped" | "failed";
-	skipReason?: "filtered" | "no-declaration" | "internal";
-	error?: string;
-	kind?: string;
-}
-/** Verification result comparing discovered vs extracted exports */
-interface ExportVerification {
-	/** Total exports discovered by TypeScript */
-	discovered: number;
-	/** Exports successfully extracted */
-	extracted: number;
-	/** Exports skipped (filtered, no-declaration, internal) */
-	skipped: number;
-	/** Exports that failed during serialization */
-	failed: number;
-	/** Delta: discovered - extracted */
-	delta: number;
-	details: {
-		skipped: Array<{
-			name: string;
-			reason: "filtered" | "no-declaration" | "internal";
-		}>;
-		failed: Array<{
-			name: string;
-			error: string;
-		}>;
-	};
-}
+declare function getMemberBadges(member: SpecMember): string[];
 /**
-* Extract full OpenPkg spec from a TypeScript entry point
-*
-* @example
-* ```typescript
-* import { extractSpec } from '@openpkg-ts/sdk';
-*
-* const result = await extractSpec({
-*   entryFile: './src/index.ts'
-* });
-*
-* console.log(result.spec.exports.length);
-* ```
+* Format badges array into a display string (space-separated).
 */
-declare const extractSpec: (options: ExtractOptions) => Promise<ExtractResult>;
-import { diffSpec, categorizeBreakingChanges, recommendSemverBump, calculateNextVersion, SpecDiff, BreakingSeverity, CategorizedBreaking, MemberChangeInfo, SemverBump, SemverRecommendation } from "@openpkg-ts/spec";
-import { diffSpec as diffSpec2 } from "@openpkg-ts/spec";
-import { OpenPkg as OpenPkg2, SpecExport as SpecExport2, SpecMember, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";
-interface FormatSchemaOptions {
-	/** Include package attribution for external types */
-	includePackage?: boolean;
+declare function formatBadges(badges: string[]): string;
+import { OpenPkg as OpenPkg6, SpecExport as SpecExport2, SpecExportKind as SpecExportKind4, SpecType } from "@openpkg-ts/spec";
+import { OpenPkg } from "@openpkg-ts/spec";
+interface HTMLOptions {
+	/** Page title override */
+	title?: string;
+	/** Include inline styles */
+	includeStyles?: boolean;
+	/** Custom CSS to inject */
+	customCSS?: string;
+	/** Custom head content */
+	headContent?: string;
+	/** Wrap in full HTML document */
+	fullDocument?: boolean;
+	/** Export to render (single mode) */
+	export?: string;
 }
 /**
-* Format a schema to a human-readable type string.
+* Render spec to standalone HTML page.
 *
-* @param schema - The schema to format
-* @param options - Formatting options
-* @returns Formatted type string
+* @param spec - The OpenPkg spec to render
+* @param options - HTML rendering options
+* @returns Complete HTML document or fragment
 *
 * @example
 * ```ts
-* formatSchema({ type: 'string' }) // 'string'
-* formatSchema({ $ref: '#/types/User' }) // 'User'
-* formatSchema({ anyOf: [{ type: 'string' }, { type: 'number' }] }) // 'string | number'
-* formatSchema({ type: 'integer', 'x-ts-type': 'bigint' }) // 'bigint'
-* formatSchema({ 'x-ts-type': 'Response', 'x-ts-package': 'express' }, { includePackage: true }) // 'Response (from express)'
-* ```
-*/
-declare function formatSchema(schema: SpecSchema | undefined, options?: FormatSchemaOptions): string;
-/**
-* Format type parameters to a string like `<T, U extends string>`.
+* import { createDocs } from '@openpkg-ts/sdk'
 *
-* @param typeParams - Array of type parameters
-* @returns Formatted type parameters string or empty string
+* const docs = createDocs('./openpkg.json')
 *
-* @example
-* ```ts
-* formatTypeParameters([{ name: 'T' }]) // '<T>'
-* formatTypeParameters([{ name: 'T', constraint: 'object' }]) // '<T extends object>'
-* formatTypeParameters([{ name: 'T', default: 'unknown' }]) // '<T = unknown>'
-* formatTypeParameters([{ name: 'T', variance: 'in' }]) // '<in T>'
+* // Full HTML page
+* const html = docs.toHTML({ includeStyles: true })
+* fs.writeFileSync('api.html', html)
+*
+* // Single export, no document wrapper
+* const fragment = docs.toHTML({ export: 'greet', fullDocument: false })
 * ```
 */
-declare function formatTypeParameters(typeParams?: SpecTypeParameter[]): string;
+declare function toHTML2(spec: OpenPkg, options?: HTMLOptions): string;
+import { OpenPkg as OpenPkg2, SpecExportKind } from "@openpkg-ts/spec";
+interface JSONOptions {
+	/** Include raw spec data alongside simplified data */
+	includeRaw?: boolean;
+	/** Export to render (single mode) */
+	export?: string;
+	/** Include computed fields (signatures, formatted types) */
+	computed?: boolean;
+	/** Flatten nested structures */
+	flatten?: boolean;
+}
+interface SimplifiedParameter {
+	name: string;
+	type: string;
+	required: boolean;
+	description?: string;
+	default?: unknown;
+	rest?: boolean;
+}
+interface SimplifiedReturn {
+	type: string;
+	description?: string;
+}
+interface SimplifiedSignature {
+	parameters: SimplifiedParameter[];
+	returns?: SimplifiedReturn;
+	description?: string;
+	typeParameters?: string[];
+}
+interface SimplifiedMember {
+	name: string;
+	kind: "property" | "method";
+	type?: string;
+	description?: string;
+	visibility?: "public" | "protected" | "private";
+	signature?: SimplifiedSignature;
+}
+interface SimplifiedExample {
+	code: string;
+	title?: string;
+	description?: string;
+	language?: string;
+}
+interface SimplifiedExport {
+	id: string;
+	name: string;
+	kind: SpecExportKind;
+	signature: string;
+	description?: string;
+	deprecated: boolean;
+	tags: Array<{
+		name: string;
+		text: string;
+	}>;
+	parameters?: SimplifiedParameter[];
+	returns?: SimplifiedReturn;
+	members?: SimplifiedMember[];
+	examples?: SimplifiedExample[];
+	extends?: string;
+	implements?: string[];
+	sourceFile?: string;
+	sourceLine?: number;
+}
+interface SimplifiedSpec {
+	name: string;
+	version?: string;
+	description?: string;
+	exports: SimplifiedExport[];
+	byKind: Record<SpecExportKind, SimplifiedExport[]>;
+	totalExports: number;
+}
 /**
-* Format function parameters to a string like `(a: string, b?: number)`.
+* Render spec to simplified JSON structure.
 *
-* @param sig - The signature containing parameters
-* @returns Formatted parameters string
+* @param spec - The OpenPkg spec to simplify
+* @param options - JSON rendering options
+* @returns Simplified spec or single structure
 *
 * @example
 * ```ts
-* formatParameters({ parameters: [{ name: 'id', schema: { type: 'string' } }] })
-* // '(id: string)'
-* ```
-*/
-declare function formatParameters(sig?: SpecSignature): string;
-/**
-* Format return type from signature.
+* import { createDocs } from '@openpkg-ts/sdk'
 *
-* @param sig - The signature containing return type
-* @returns Formatted return type string
+* const docs = createDocs('./openpkg.json')
 *
-* @example
-* ```ts
-* formatReturnType({ returns: { schema: { type: 'Promise', items: { type: 'string' } } } })
-* // 'Promise<string>'
+* // Full spec as simplified JSON
+* const json = docs.toJSON()
+* // { name, version, exports: [...], byKind: {...} }
+*
+* // Single * const fnJson = docs.toJSON({ export: 'greet' })
+* // { id, name, kind, signature, parameters, returns, ... }
 * ```
 */
-declare function formatReturnType(sig?: SpecSignature): string;
+declare function toJSON2(spec: OpenPkg2, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
 /**
-* Build a full signature string for an export.
-*
-* @param exp - The to build a signature for
-* @param sigIndex - Index of signature to use for overloaded functions
-* @returns Complete signature string
-*
-* @example
-* ```ts
-* buildSignatureString({ kind: 'function', name: 'greet', signatures: [...] })
-* // 'function greet(name: string): string'
+* Serialize to JSON string with formatting.
 *
-* buildSignatureString({ kind: 'class', name: 'Logger', extends: 'EventEmitter' })
-* // 'class Logger extends EventEmitter'
-* ```
+* @param spec - The OpenPkg spec to serialize
+* @param options - JSON options plus pretty formatting option
+* @returns JSON string
 */
-declare function buildSignatureString(exp: SpecExport2, sigIndex?: number): string;
+declare function toJSONString(spec: OpenPkg2, options?: JSONOptions & {
+	pretty?: boolean;
+}): string;
+import { OpenPkg as OpenPkg3, SpecExport } from "@openpkg-ts/spec";
+interface MarkdownOptions {
+	/** Include frontmatter in output */
+	frontmatter?: boolean;
+	/** Sections to include */
+	sections?: {
+		signature?: boolean;
+		description?: boolean;
+		parameters?: boolean;
+		returns?: boolean;
+		examples?: boolean;
+		members?: boolean;
+		properties?: boolean;
+		methods?: boolean;
+	};
+	/** Custom frontmatter fields */
+	customFrontmatter?: Record<string, unknown>;
+	/** Use code fences for signatures */
+	codeSignatures?: boolean;
+	/** Heading level offset (0 = starts at h1, 1 = starts at h2) */
+	headingOffset?: number;
+}
+interface ExportMarkdownOptions extends MarkdownOptions {
+	/** Export to render */
+	export?: string;
+}
 /**
-* Resolve a type reference to its definition.
+* Render a single to MDX.
 *
-* @param ref - Type reference string (e.g., '#/types/User')
-* @param spec - The OpenPkg spec containing type definitions
-* @returns The resolved type definition or undefined
+* @param exp - The to render
+* @param options - Markdown rendering options
+* @returns MDX string with frontmatter
 *
 * @example
 * ```ts
-* resolveTypeRef('#/types/User', spec)
-* // { id: 'User', name: 'User', kind: 'interface', ... }
+* const mdx = exportToMarkdown(fn, {
+*   frontmatter: true,
+*   codeSignatures: true,
+*   sections: { examples: true }
+* })
 * ```
 */
-declare function resolveTypeRef(ref: string, spec: OpenPkg2): SpecType2 | undefined;
+declare function exportToMarkdown(exp: SpecExport, options?: MarkdownOptions): string;
 /**
-* Check if a member is a method (has signatures).
+* Render entire spec to MDX.
 *
-* @param member - The member to check
-* @returns True if the member is a method
+* @param spec - The OpenPkg spec to render
+* @param options - Markdown options, optionally with name for single mode
+* @returns MDX string
 *
 * @example
 * ```ts
-* isMethod({ name: 'foo', signatures: [{ parameters: [] }] }) // true
-* isMethod({ name: 'bar', schema: { type: 'string' } }) // false
-* ```
-*/
-declare function isMethod(member: SpecMember): boolean;
-/**
-* Check if a member is a property (no signatures).
+* import { createDocs } from '@openpkg-ts/sdk'
 *
-* @param member - The member to check
-* @returns True if the member is a property
-*/
-declare function isProperty(member: SpecMember): boolean;
-/**
-* Get methods from members list.
+* const docs = createDocs('./openpkg.json')
 *
-* @param members - Array of members to filter
-* @returns Array of method members
-*/
-declare function getMethods(members?: SpecMember[]): SpecMember[];
-/**
-* Get properties from members list.
+* // Full spec
+* const fullMdx = docs.toMarkdown()
 *
-* @param members - Array of members to filter
-* @returns Array of property members
+* // Single * const fnMdx = docs.toMarkdown({ export: 'greet' })
+* ```
 */
-declare function getProperties(members?: SpecMember[]): SpecMember[];
+declare function toMarkdown2(spec: OpenPkg3, options?: ExportMarkdownOptions): string;
+import { OpenPkg as OpenPkg4, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
+type NavFormat = "fumadocs" | "docusaurus" | "generic";
+type GroupBy = "kind" | "module" | "tag" | "none";
+interface NavOptions {
+	/** Output format */
+	format?: NavFormat;
+	/** How to group exports */
+	groupBy?: GroupBy;
+	/** Base path for links */
+	basePath?: string;
+	/** Custom slug generator */
+	slugify?: (name: string) => string;
+	/** Include index pages for groups */
+	includeGroupIndex?: boolean;
+	/** Custom kind labels */
+	kindLabels?: Partial<Record<SpecExportKind2, string>>;
+	/** Sort exports alphabetically */
+	sortAlphabetically?: boolean;
+}
+interface NavItem {
+	title: string;
+	href?: string;
+	items?: NavItem[];
+}
+interface NavGroup {
+	title: string;
+	items: NavItem[];
+	index?: string;
+}
+interface GenericNav {
+	title: string;
+	groups: NavGroup[];
+	items: NavItem[];
+}
+interface FumadocsMetaItem {
+	title: string;
+	pages?: string[];
+	defaultOpen?: boolean;
+}
+interface FumadocsMeta {
+	root?: boolean;
+	title?: string;
+	pages?: (string | FumadocsMetaItem)[];
+}
+interface DocusaurusSidebarItem {
+	type: "category" | "doc" | "link";
+	label: string;
+	items?: DocusaurusSidebarItem[];
+	id?: string;
+	href?: string;
+}
+type DocusaurusSidebar = DocusaurusSidebarItem[];
 /**
-* Group members by visibility (public, protected, private).
+* Generate navigation structure for doc frameworks.
 *
-* @param members - Array of members to group
-* @returns Object with public, protected, and private arrays
+* @param spec - The OpenPkg spec
+* @param options - Navigation options including format and grouping
+* @returns Navigation structure in requested format
 *
 * @example
 * ```ts
-* const groups = groupByVisibility(classExport.members)
-* groups.public  // [{ name: 'foo', visibility: 'public' }]
-* groups.private // [{ name: 'bar', visibility: 'private' }]
-* ```
-*/
-declare function groupByVisibility(members?: SpecMember[]): {
-	public: SpecMember[];
-	protected: SpecMember[];
-	private: SpecMember[];
-};
-/**
-* Sort exports alphabetically by name.
+* import { createDocs } from '@openpkg-ts/sdk'
 *
-* @param items - Array of items with a name property
-* @returns New sorted array
-*/
-declare function sortByName<T extends {
-	name: string;
-}>(items: T[]): T[];
-/**
-* Conditional type structure from the spec.
-*/
-interface SpecConditionalType {
-	checkType: SpecSchema;
-	extendsType: SpecSchema;
-	trueType: SpecSchema;
-	falseType: SpecSchema;
-}
-/**
-* Mapped type structure from the spec.
+* const docs = createDocs('./openpkg.json')
+*
+* // Generic nav
+* const nav = docs.toNavigation({ format: 'generic', groupBy: 'kind' })
+*
+* // Fumadocs meta.json
+* const meta = docs.toNavigation({ format: 'fumadocs' })
+*
+* // Docusaurus sidebar
+* const sidebar = docs.toNavigation({ format: 'docusaurus' })
+* ```
 */
-interface SpecMappedType {
-	keyType: SpecSchema;
-	valueType: SpecSchema;
-	readonly?: boolean | "add" | "remove";
-	optional?: boolean | "add" | "remove";
-}
+declare function toNavigation2(spec: OpenPkg4, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
 /**
-* Format a conditional type to a human-readable string.
+* Generate Fumadocs meta.json file content.
 *
-* @param condType - The conditional type structure
-* @returns Formatted conditional type string
+* @param spec - The OpenPkg spec
+* @param options - Navigation options (format is forced to fumadocs)
+* @returns JSON string for meta.json file
 *
 * @example
 * ```ts
-* formatConditionalType({
-*   checkType: { 'x-ts-type': 'T' },
-*   extendsType: { type: 'string' },
-*   trueType: { type: 'boolean', const: true },
-*   falseType: { type: 'boolean', const: false }
-* })
-* // 'T extends string ? true : false'
+* const meta = toFumadocsMetaJSON(spec, { groupBy: 'kind' })
+* fs.writeFileSync('docs/api/meta.json', meta)
 * ```
 */
-declare function formatConditionalType(condType: SpecConditionalType): string;
+declare function toFumadocsMetaJSON(spec: OpenPkg4, options?: Omit<NavOptions, "format">): string;
 /**
-* Format a mapped type to a human-readable string.
+* Generate Docusaurus sidebar config.
 *
-* @param mappedType - The mapped type structure
-* @returns Formatted mapped type string
+* @param spec - The OpenPkg spec
+* @param options - Navigation options (format is forced to docusaurus)
+* @returns JavaScript module.exports string for sidebars.js
 *
 * @example
 * ```ts
-* formatMappedType({
-*   keyType: { 'x-ts-type': 'K in keyof T' },
-*   valueType: { 'x-ts-type': 'T[K]' },
-*   readonly: true
-* })
-* // '{ readonly [K in keyof T]: T[K] }'
+* const sidebar = toDocusaurusSidebarJS(spec, { basePath: 'api' })
+* fs.writeFileSync('sidebars.js', sidebar)
 * ```
 */
-declare function formatMappedType(mappedType: SpecMappedType): string;
-import { SpecMember as SpecMember2 } from "@openpkg-ts/spec";
-/**
-* Extract badge strings from a member's visibility and flags.
-* Handles: visibility (if not public), static, readonly, async, abstract
-*/
-declare function getMemberBadges(member: SpecMember2): string[];
-/**
-* Format badges array into a display string (space-separated).
-*/
-declare function formatBadges(badges: string[]): string;
-import { OpenPkg as OpenPkg3, SpecExportKind } from "@openpkg-ts/spec";
+declare function toDocusaurusSidebarJS(spec: OpenPkg4, options?: Omit<NavOptions, "format">): string;
+import { OpenPkg as OpenPkg5, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
 interface SearchOptions {
 	/** Base URL for search result links */
 	baseUrl?: string;
@@ -442,7 +361,7 @@ interface PagefindRecord {
 interface AlgoliaRecord {
 	objectID: string;
 	name: string;
-	kind: SpecExportKind;
+	kind: SpecExportKind3;
 	description?: string;
 	signature: string;
 	content: string;
@@ -462,7 +381,7 @@ interface AlgoliaRecord {
 interface SearchRecord {
 	id: string;
 	name: string;
-	kind: SpecExportKind;
+	kind: SpecExportKind3;
 	signature: string;
 	description?: string;
 	content: string;
@@ -470,459 +389,539 @@ interface SearchRecord {
 	url: string;
 	deprecated: boolean;
 }
-interface SearchIndex {
-	records: SearchRecord[];
-	version: string;
-	generatedAt: string;
-	packageName: string;
-}
-/**
-* Generate search index from spec.
-*
-* @param spec - The OpenPkg spec to index
-* @param options - Search index configuration
-* @returns Search index with records for each *
-* @example
-* ```ts
-* import { createDocs } from '@openpkg-ts/sdk'
-*
-* const docs = createDocs('./openpkg.json')
-* const index = docs.toSearchIndex({ baseUrl: '/api' })
-* // { records: [...], version: '1.0.0', packageName: 'my-lib' }
-* ```
-*/
-declare function toSearchIndex2(spec: OpenPkg3, options?: SearchOptions): SearchIndex;
-/**
-* Generate Pagefind-compatible records.
-*
-* @param spec - The OpenPkg spec to index
-* @param options - Search configuration including weights
-* @returns Array of Pagefind-compatible search records
-*
-* @example
-* ```ts
-* const records = toPagefindRecords(spec, {
-*   baseUrl: '/docs/api',
-*   weights: { name: 10, description: 5 }
-* })
-* ```
-*/
-declare function toPagefindRecords2(spec: OpenPkg3, options?: SearchOptions): PagefindRecord[];
-/**
-* Generate Algolia-compatible records.
-*
-* @param spec - The OpenPkg spec to index
-* @param options - Search configuration
-* @returns Array of Algolia-compatible search records with hierarchy
-*
-* @example
-* ```ts
-* const records = toAlgoliaRecords(spec, { baseUrl: '/api' })
-* // Upload to Algolia index
-* ```
-*/
-declare function toAlgoliaRecords2(spec: OpenPkg3, options?: SearchOptions): AlgoliaRecord[];
-/**
-* Serialize search index to JSON string.
-*
-* @param spec - The OpenPkg spec to index
-* @param options - Search options plus pretty formatting option
-* @returns JSON string of search index
-*
-* @example
-* ```ts
-* const json = toSearchIndexJSON(spec, { pretty: true })
-* fs.writeFileSync('search-index.json', json)
-* ```
-*/
-declare function toSearchIndexJSON(spec: OpenPkg3, options?: SearchOptions & {
-	pretty?: boolean;
-}): string;
-import { OpenPkg as OpenPkg8, SpecExport as SpecExport4, SpecExportKind as SpecExportKind4, SpecType as SpecType3 } from "@openpkg-ts/spec";
-import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
-interface HTMLOptions {
-	/** Page title override */
-	title?: string;
-	/** Include inline styles */
-	includeStyles?: boolean;
-	/** Custom CSS to inject */
-	customCSS?: string;
-	/** Custom head content */
-	headContent?: string;
-	/** Wrap in full HTML document */
-	fullDocument?: boolean;
-	/** Export to render (single mode) */
-	export?: string;
-}
-/**
-* Render spec to standalone HTML page.
-*
-* @param spec - The OpenPkg spec to render
-* @param options - HTML rendering options
-* @returns Complete HTML document or fragment
-*
-* @example
-* ```ts
-* import { createDocs } from '@openpkg-ts/sdk'
-*
-* const docs = createDocs('./openpkg.json')
-*
-* // Full HTML page
-* const html = docs.toHTML({ includeStyles: true })
-* fs.writeFileSync('api.html', html)
-*
-* // Single export, no document wrapper
-* const fragment = docs.toHTML({ export: 'greet', fullDocument: false })
-* ```
-*/
-declare function toHTML2(spec: OpenPkg4, options?: HTMLOptions): string;
-import { OpenPkg as OpenPkg5, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
-interface JSONOptions {
-	/** Include raw spec data alongside simplified data */
-	includeRaw?: boolean;
-	/** Export to render (single mode) */
-	export?: string;
-	/** Include computed fields (signatures, formatted types) */
-	computed?: boolean;
-	/** Flatten nested structures */
-	flatten?: boolean;
-}
-interface SimplifiedParameter {
-	name: string;
-	type: string;
-	required: boolean;
-	description?: string;
-	default?: unknown;
-	rest?: boolean;
-}
-interface SimplifiedReturn {
-	type: string;
-	description?: string;
-}
-interface SimplifiedSignature {
-	parameters: SimplifiedParameter[];
-	returns?: SimplifiedReturn;
-	description?: string;
-	typeParameters?: string[];
-}
-interface SimplifiedMember {
-	name: string;
-	kind: "property" | "method";
-	type?: string;
-	description?: string;
-	visibility?: "public" | "protected" | "private";
-	signature?: SimplifiedSignature;
-}
-interface SimplifiedExample {
-	code: string;
-	title?: string;
-	description?: string;
-	language?: string;
-}
-interface SimplifiedExport {
-	id: string;
-	name: string;
-	kind: SpecExportKind2;
-	signature: string;
-	description?: string;
-	deprecated: boolean;
-	tags: Array<{
-		name: string;
-		text: string;
-	}>;
-	parameters?: SimplifiedParameter[];
-	returns?: SimplifiedReturn;
-	members?: SimplifiedMember[];
-	examples?: SimplifiedExample[];
-	extends?: string;
-	implements?: string[];
-	sourceFile?: string;
-	sourceLine?: number;
-}
-interface SimplifiedSpec {
-	name: string;
-	version?: string;
-	description?: string;
-	exports: SimplifiedExport[];
-	byKind: Record<SpecExportKind2, SimplifiedExport[]>;
-	totalExports: number;
+interface SearchIndex {
+	records: SearchRecord[];
+	version: string;
+	generatedAt: string;
+	packageName: string;
 }
 /**
-* Render spec to simplified JSON structure.
-*
-* @param spec - The OpenPkg spec to simplify
-* @param options - JSON rendering options
-* @returns Simplified spec or single structure
+* Generate search index from spec.
 *
+* @param spec - The OpenPkg spec to index
+* @param options - Search index configuration
+* @returns Search index with records for each *
 * @example
 * ```ts
 * import { createDocs } from '@openpkg-ts/sdk'
 *
 * const docs = createDocs('./openpkg.json')
+* const index = docs.toSearchIndex({ baseUrl: '/api' })
+* // { records: [...], version: '1.0.0', packageName: 'my-lib' }
+* ```
+*/
+declare function toSearchIndex2(spec: OpenPkg5, options?: SearchOptions): SearchIndex;
+/**
+* Generate Pagefind-compatible records.
 *
-* // Full spec as simplified JSON
-* const json = docs.toJSON()
-* // { name, version, exports: [...], byKind: {...} }
+* @param spec - The OpenPkg spec to index
+* @param options - Search configuration including weights
+* @returns Array of Pagefind-compatible search records
 *
-* // Single * const fnJson = docs.toJSON({ export: 'greet' })
-* // { id, name, kind, signature, parameters, returns, ... }
+* @example
+* ```ts
+* const records = toPagefindRecords(spec, {
+*   baseUrl: '/docs/api',
+*   weights: { name: 10, description: 5 }
+* })
 * ```
 */
-declare function toJSON2(spec: OpenPkg5, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+declare function toPagefindRecords2(spec: OpenPkg5, options?: SearchOptions): PagefindRecord[];
 /**
-* Serialize to JSON string with formatting.
+* Generate Algolia-compatible records.
 *
-* @param spec - The OpenPkg spec to serialize
-* @param options - JSON options plus pretty formatting option
-* @returns JSON string
+* @param spec - The OpenPkg spec to index
+* @param options - Search configuration
+* @returns Array of Algolia-compatible search records with hierarchy
+*
+* @example
+* ```ts
+* const records = toAlgoliaRecords(spec, { baseUrl: '/api' })
+* // Upload to Algolia index
+* ```
+*/
+declare function toAlgoliaRecords2(spec: OpenPkg5, options?: SearchOptions): AlgoliaRecord[];
+/**
+* Serialize search index to JSON string.
+*
+* @param spec - The OpenPkg spec to index
+* @param options - Search options plus pretty formatting option
+* @returns JSON string of search index
+*
+* @example
+* ```ts
+* const json = toSearchIndexJSON(spec, { pretty: true })
+* fs.writeFileSync('search-index.json', json)
+* ```
 */
-declare function toJSONString(spec: OpenPkg5, options?: JSONOptions & {
+declare function toSearchIndexJSON(spec: OpenPkg5, options?: SearchOptions & {
 	pretty?: boolean;
 }): string;
-import { OpenPkg as OpenPkg6, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
-interface MarkdownOptions {
-	/** Include frontmatter in output */
-	frontmatter?: boolean;
-	/** Sections to include */
-	sections?: {
-		signature?: boolean;
-		description?: boolean;
-		parameters?: boolean;
-		returns?: boolean;
-		examples?: boolean;
-		members?: boolean;
-		properties?: boolean;
-		methods?: boolean;
-	};
-	/** Custom frontmatter fields */
-	customFrontmatter?: Record<string, unknown>;
-	/** Use code fences for signatures */
-	codeSignatures?: boolean;
-	/** Heading level offset (0 = starts at h1, 1 = starts at h2) */
-	headingOffset?: number;
+interface LoadOptions {
+	/** Path to openpkg.json file or the spec object directly */
+	input: string | OpenPkg6;
 }
-interface ExportMarkdownOptions extends MarkdownOptions {
-	/** Export to render */
-	export?: string;
+interface DocsInstance {
+	/** The parsed OpenPkg spec */
+	spec: OpenPkg6;
+	/** Get an by its ID */
+	getExport(id: string): SpecExport2 | undefined;
+	/** Get a type definition by its ID */
+	getType(id: string): SpecType | undefined;
+	/** Get all exports of a specific kind */
+	getExportsByKind(kind: SpecExportKind4): SpecExport2[];
+	/** Get all exports */
+	getAllExports(): SpecExport2[];
+	/** Get all type definitions */
+	getAllTypes(): SpecType[];
+	/** Get exports by JSDoc tag (e.g., '@beta', '@internal') */
+	getExportsByTag(tagName: string): SpecExport2[];
+	/** Search exports by name or description */
+	search(query: string): SpecExport2[];
+	/** Get exports belonging to a specific module/namespace */
+	getModule(moduleName: string): SpecExport2[];
+	/** Get deprecated exports */
+	getDeprecated(): SpecExport2[];
+	/** Get exports grouped by kind */
+	groupByKind(): Record<SpecExportKind4, SpecExport2[]>;
+	/** Render spec or single to MDX */
+	toMarkdown(options?: ExportMarkdownOptions): string;
+	/** Render spec or single to HTML */
+	toHTML(options?: HTMLOptions): string;
+	/** Render spec or single to JSON structure */
+	toJSON(options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+	/** Generate navigation structure */
+	toNavigation(options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+	/** Generate search index */
+	toSearchIndex(options?: SearchOptions): SearchIndex;
+	/** Generate Pagefind-compatible records */
+	toPagefindRecords(options?: SearchOptions): PagefindRecord[];
+	/** Generate Algolia-compatible records */
+	toAlgoliaRecords(options?: SearchOptions): AlgoliaRecord[];
 }
 /**
-* Render a single to MDX.
-*
-* @param exp - The to render
-* @param options - Markdown rendering options
-* @returns MDX string with frontmatter
+* Loads an OpenPkg spec from file or object.
 *
 * @example
 * ```ts
-* const mdx = exportToMarkdown(fn, {
-*   frontmatter: true,
-*   codeSignatures: true,
-*   sections: { examples: true }
-* })
+* import { loadSpec } from '@openpkg-ts/sdk'
+*
+* // From spec object
+* import spec from './openpkg.json'
+* const docs = loadSpec(spec)
 * ```
 */
-declare function exportToMarkdown(exp: SpecExport3, options?: MarkdownOptions): string;
+declare function loadSpec(spec: OpenPkg6): DocsInstance;
 /**
-* Render entire spec to MDX.
-*
-* @param spec - The OpenPkg spec to render
-* @param options - Markdown options, optionally with name for single mode
-* @returns MDX string
+* Creates a docs instance for querying and rendering API documentation.
 *
 * @example
 * ```ts
 * import { createDocs } from '@openpkg-ts/sdk'
 *
+* // From file path
 * const docs = createDocs('./openpkg.json')
 *
-* // Full spec
-* const fullMdx = docs.toMarkdown()
+* // From spec object
+* import spec from './openpkg.json'
+* const docs = createDocs(spec)
 *
-* // Single * const fnMdx = docs.toMarkdown({ export: 'greet' })
+* // Query
+* docs.getExport('useState')
+* docs.getExportsByKind('function')
+* docs.getExportsByTag('@beta')
+* docs.search('hook')
 * ```
 */
-declare function toMarkdown2(spec: OpenPkg6, options?: ExportMarkdownOptions): string;
-import { OpenPkg as OpenPkg7, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
-type NavFormat = "fumadocs" | "docusaurus" | "generic";
-type GroupBy = "kind" | "module" | "tag" | "none";
-interface NavOptions {
-	/** Output format */
-	format?: NavFormat;
-	/** How to group exports */
-	groupBy?: GroupBy;
-	/** Base path for links */
-	basePath?: string;
-	/** Custom slug generator */
-	slugify?: (name: string) => string;
-	/** Include index pages for groups */
-	includeGroupIndex?: boolean;
-	/** Custom kind labels */
-	kindLabels?: Partial<Record<SpecExportKind3, string>>;
-	/** Sort exports alphabetically */
-	sortAlphabetically?: boolean;
-}
-interface NavItem {
-	title: string;
-	href?: string;
-	items?: NavItem[];
-}
-interface NavGroup {
-	title: string;
-	items: NavItem[];
-	index?: string;
-}
-interface GenericNav {
-	title: string;
-	groups: NavGroup[];
-	items: NavItem[];
-}
-interface FumadocsMetaItem {
-	title: string;
-	pages?: string[];
-	defaultOpen?: boolean;
-}
-interface FumadocsMeta {
-	root?: boolean;
-	title?: string;
-	pages?: (string | FumadocsMetaItem)[];
-}
-interface DocusaurusSidebarItem {
-	type: "category" | "doc" | "link";
-	label: string;
-	items?: DocusaurusSidebarItem[];
-	id?: string;
-	href?: string;
+declare function createDocs(input: string | OpenPkg6): DocsInstance;
+import { OpenPkg as OpenPkg7, SpecExport as SpecExport3, SpecMember as SpecMember2, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";
+interface FormatSchemaOptions {
+	/** Include package attribution for external types */
+	includePackage?: boolean;
 }
-type DocusaurusSidebar = DocusaurusSidebarItem[];
 /**
-* Generate navigation structure for doc frameworks.
+* Format a schema to a human-readable type string.
+*
+* @param schema - The schema to format
+* @param options - Formatting options
+* @returns Formatted type string
+*
+* @example
+* ```ts
+* formatSchema({ type: 'string' }) // 'string'
+* formatSchema({ $ref: '#/types/User' }) // 'User'
+* formatSchema({ anyOf: [{ type: 'string' }, { type: 'number' }] }) // 'string | number'
+* formatSchema({ type: 'integer', 'x-ts-type': 'bigint' }) // 'bigint'
+* formatSchema({ 'x-ts-type': 'Response', 'x-ts-package': 'express' }, { includePackage: true }) // 'Response (from express)'
+* ```
+*/
+declare function formatSchema(schema: SpecSchema | undefined, options?: FormatSchemaOptions): string;
+/**
+* Format type parameters to a string like `<T, U extends string>`.
+*
+* @param typeParams - Array of type parameters
+* @returns Formatted type parameters string or empty string
+*
+* @example
+* ```ts
+* formatTypeParameters([{ name: 'T' }]) // '<T>'
+* formatTypeParameters([{ name: 'T', constraint: 'object' }]) // '<T extends object>'
+* formatTypeParameters([{ name: 'T', default: 'unknown' }]) // '<T = unknown>'
+* formatTypeParameters([{ name: 'T', variance: 'in' }]) // '<in T>'
+* ```
+*/
+declare function formatTypeParameters(typeParams?: SpecTypeParameter[]): string;
+/**
+* Format function parameters to a string like `(a: string, b?: number)`.
+*
+* @param sig - The signature containing parameters
+* @returns Formatted parameters string
+*
+* @example
+* ```ts
+* formatParameters({ parameters: [{ name: 'id', schema: { type: 'string' } }] })
+* // '(id: string)'
+* ```
+*/
+declare function formatParameters(sig?: SpecSignature): string;
+/**
+* Format return type from signature.
+*
+* @param sig - The signature containing return type
+* @returns Formatted return type string
+*
+* @example
+* ```ts
+* formatReturnType({ returns: { schema: { type: 'Promise', items: { type: 'string' } } } })
+* // 'Promise<string>'
+* ```
+*/
+declare function formatReturnType(sig?: SpecSignature): string;
+/**
+* Build a full signature string for an export.
 *
-* @param spec - The OpenPkg spec
-* @param options - Navigation options including format and grouping
-* @returns Navigation structure in requested format
+* @param exp - The to build a signature for
+* @param sigIndex - Index of signature to use for overloaded functions
+* @returns Complete signature string
 *
 * @example
 * ```ts
-* import { createDocs } from '@openpkg-ts/sdk'
+* buildSignatureString({ kind: 'function', name: 'greet', signatures: [...] })
+* // 'function greet(name: string): string'
 *
-* const docs = createDocs('./openpkg.json')
+* buildSignatureString({ kind: 'class', name: 'Logger', extends: 'EventEmitter' })
+* // 'class Logger extends EventEmitter'
+* ```
+*/
+declare function buildSignatureString(exp: SpecExport3, sigIndex?: number): string;
+/**
+* Resolve a type reference to its definition.
 *
-* // Generic nav
-* const nav = docs.toNavigation({ format: 'generic', groupBy: 'kind' })
+* @param ref - Type reference string (e.g., '#/types/User')
+* @param spec - The OpenPkg spec containing type definitions
+* @returns The resolved type definition or undefined
 *
-* // Fumadocs meta.json
-* const meta = docs.toNavigation({ format: 'fumadocs' })
+* @example
+* ```ts
+* resolveTypeRef('#/types/User', spec)
+* // { id: 'User', name: 'User', kind: 'interface', ... }
+* ```
+*/
+declare function resolveTypeRef(ref: string, spec: OpenPkg7): SpecType2 | undefined;
+/**
+* Check if a member is a method (has signatures).
 *
-* // Docusaurus sidebar
-* const sidebar = docs.toNavigation({ format: 'docusaurus' })
+* @param member - The member to check
+* @returns True if the member is a method
+*
+* @example
+* ```ts
+* isMethod({ name: 'foo', signatures: [{ parameters: [] }] }) // true
+* isMethod({ name: 'bar', schema: { type: 'string' } }) // false
 * ```
 */
-declare function toNavigation2(spec: OpenPkg7, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+declare function isMethod(member: SpecMember2): boolean;
 /**
-* Generate Fumadocs meta.json file content.
+* Check if a member is a property (no signatures).
 *
-* @param spec - The OpenPkg spec
-* @param options - Navigation options (format is forced to fumadocs)
-* @returns JSON string for meta.json file
+* @param member - The member to check
+* @returns True if the member is a property
+*/
+declare function isProperty(member: SpecMember2): boolean;
+/**
+* Get methods from members list.
+*
+* @param members - Array of members to filter
+* @returns Array of method members
+*/
+declare function getMethods(members?: SpecMember2[]): SpecMember2[];
+/**
+* Get properties from members list.
+*
+* @param members - Array of members to filter
+* @returns Array of property members
+*/
+declare function getProperties(members?: SpecMember2[]): SpecMember2[];
+/**
+* Group members by visibility (public, protected, private).
+*
+* @param members - Array of members to group
+* @returns Object with public, protected, and private arrays
 *
 * @example
 * ```ts
-* const meta = toFumadocsMetaJSON(spec, { groupBy: 'kind' })
-* fs.writeFileSync('docs/api/meta.json', meta)
+* const groups = groupByVisibility(classExport.members)
+* groups.public  // [{ name: 'foo', visibility: 'public' }]
+* groups.private // [{ name: 'bar', visibility: 'private' }]
 * ```
 */
-declare function toFumadocsMetaJSON(spec: OpenPkg7, options?: Omit<NavOptions, "format">): string;
+declare function groupByVisibility(members?: SpecMember2[]): {
+	public: SpecMember2[];
+	protected: SpecMember2[];
+	private: SpecMember2[];
+};
 /**
-* Generate Docusaurus sidebar config.
+* Sort exports alphabetically by name.
 *
-* @param spec - The OpenPkg spec
-* @param options - Navigation options (format is forced to docusaurus)
-* @returns JavaScript module.exports string for sidebars.js
+* @param items - Array of items with a name property
+* @returns New sorted array
+*/
+declare function sortByName<T extends {
+	name: string;
+}>(items: T[]): T[];
+/**
+* Conditional type structure from the spec.
+*/
+interface SpecConditionalType {
+	checkType: SpecSchema;
+	extendsType: SpecSchema;
+	trueType: SpecSchema;
+	falseType: SpecSchema;
+}
+/**
+* Mapped type structure from the spec.
+*/
+interface SpecMappedType {
+	keyType: SpecSchema;
+	valueType: SpecSchema;
+	readonly?: boolean | "add" | "remove";
+	optional?: boolean | "add" | "remove";
+}
+/**
+* Format a conditional type to a human-readable string.
+*
+* @param condType - The conditional type structure
+* @returns Formatted conditional type string
 *
 * @example
 * ```ts
-* const sidebar = toDocusaurusSidebarJS(spec, { basePath: 'api' })
-* fs.writeFileSync('sidebars.js', sidebar)
+* formatConditionalType({
+*   checkType: { 'x-ts-type': 'T' },
+*   extendsType: { type: 'string' },
+*   trueType: { type: 'boolean', const: true },
+*   falseType: { type: 'boolean', const: false }
+* })
+* // 'T extends string ? true : false'
 * ```
 */
-declare function toDocusaurusSidebarJS(spec: OpenPkg7, options?: Omit<NavOptions, "format">): string;
-interface LoadOptions {
-	/** Path to openpkg.json file or the spec object directly */
-	input: string | OpenPkg8;
+declare function formatConditionalType(condType: SpecConditionalType): string;
+/**
+* Format a mapped type to a human-readable string.
+*
+* @param mappedType - The mapped type structure
+* @returns Formatted mapped type string
+*
+* @example
+* ```ts
+* formatMappedType({
+*   keyType: { 'x-ts-type': 'K in keyof T' },
+*   valueType: { 'x-ts-type': 'T[K]' },
+*   readonly: true
+* })
+* // '{ readonly [K in keyof T]: T[K] }'
+* ```
+*/
+declare function formatMappedType(mappedType: SpecMappedType): string;
+import { SpecExport as SpecExport4, SpecType as SpecType3 } from "@openpkg-ts/spec";
+interface GetExportOptions {
+	/** Entry point file path */
+	entryFile: string;
+	/** Export name to get */
+	exportName: string;
+	/** Base directory for resolution */
+	baseDir?: string;
+	/** Optional in-memory content (for testing) */
+	content?: string;
+	/** Max depth for type resolution */
+	maxTypeDepth?: number;
+}
+interface GetExportResult {
+	/** The spec, or null if not found */
+	export: SpecExport4 | null;
+	/** Related types referenced by the */
+	types: SpecType3[];
+	/** Errors encountered */
+	errors: string[];
+}
+/**
+* Get detailed spec for a single */
+declare function getExport2(options: GetExportOptions): Promise<GetExportResult>;
+interface ListExportsOptions {
+	/** Entry point file path */
+	entryFile: string;
+	/** Base directory for resolution */
+	baseDir?: string;
+	/** Optional in-memory content (for testing) */
+	content?: string;
+}
+interface ExportItem {
+	/** Export name */
+	name: string;
+	/** Export kind */
+	kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace";
+	/** Source file path */
+	file: string;
+	/** Line number (1-indexed) */
+	line: number;
+	/** JSDoc description (first line, max 80 chars) */
+	description?: string;
+	/** Whether is deprecated */
+	deprecated?: boolean;
+	/** Whether this is a re-from another module */
+	reexport?: boolean;
+}
+interface ListExportsResult {
+	exports: ExportItem[];
+	errors: string[];
+}
+/**
+* List all exports from a TypeScript entry point
+*/
+declare function listExports(options: ListExportsOptions): Promise<ListExportsResult>;
+import { OpenPkg as OpenPkg8 } from "@openpkg-ts/spec";
+interface ExtractOptions {
+	entryFile: string;
+	baseDir?: string;
+	content?: string;
+	maxTypeDepth?: number;
+	maxExternalTypeDepth?: number;
+	resolveExternalTypes?: boolean;
+	schemaExtraction?: "static" | "hybrid";
+	/** Target JSON Schema dialect for runtime schema extraction */
+	schemaTarget?: "draft-2020-12" | "draft-07" | "openapi-3.0";
+	/** Include $schema URL in output */
+	includeSchema?: boolean;
+	/** Only extract these exports (supports * wildcards) */
+	only?: string[];
+	/** Ignore these exports (supports * wildcards) */
+	ignore?: string[];
+	/** Progress callback for tracking extraction progress */
+	onProgress?: (current: number, total: number, item: string) => void;
+	/** Whether source is a .d.ts file (degraded mode - TSDoc may be missing) */
+	isDtsSource?: boolean;
+}
+interface ExtractResult {
+	spec: OpenPkg8;
+	diagnostics: Diagnostic[];
+	forgottenExports?: ForgottenExport[];
+	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
+	runtimeSchemas?: {
+		/** Number of schema exports found */
+		extracted: number;
+		/** Number of schemas successfully merged with static types */
+		merged: number;
+		/** Schema vendors detected (e.g., 'zod', 'arktype', 'valibot', 'typebox') */
+		vendors: string[];
+		/** Any errors encountered during runtime extraction */
+		errors: string[];
+		/** Extraction method used: 'compiled' or 'direct-ts (runtime)' */
+		method?: string;
+	};
+	/** Degraded mode info when extracting from .d.ts files */
+	degradedMode?: {
+		reason: "dts-source";
+		stats: {
+			exportsWithoutDescription: number;
+			paramsWithoutDocs: number;
+			missingExamples: number;
+		};
+	};
+	/** Export verification comparing discovered vs extracted */
+	verification?: ExportVerification;
+}
+interface Diagnostic {
+	message: string;
+	severity: "error" | "warning" | "info";
+	code?: string;
+	suggestion?: string;
+	location?: {
+		file?: string;
+		line?: number;
+		column?: number;
+	};
+}
+/** Context tracking for type references in public API */
+interface TypeReference2 {
+	typeName: string;
+	exportName: string;
+	location: "return" | "parameter" | "property" | "extends" | "type-parameter";
+	path?: string;
 }
-interface DocsInstance {
-	/** The parsed OpenPkg spec */
-	spec: OpenPkg8;
-	/** Get an by its ID */
-	getExport(id: string): SpecExport4 | undefined;
-	/** Get a type definition by its ID */
-	getType(id: string): SpecType3 | undefined;
-	/** Get all exports of a specific kind */
-	getExportsByKind(kind: SpecExportKind4): SpecExport4[];
-	/** Get all exports */
-	getAllExports(): SpecExport4[];
-	/** Get all type definitions */
-	getAllTypes(): SpecType3[];
-	/** Get exports by JSDoc tag (e.g., '@beta', '@internal') */
-	getExportsByTag(tagName: string): SpecExport4[];
-	/** Search exports by name or description */
-	search(query: string): SpecExport4[];
-	/** Get exports belonging to a specific module/namespace */
-	getModule(moduleName: string): SpecExport4[];
-	/** Get deprecated exports */
-	getDeprecated(): SpecExport4[];
-	/** Get exports grouped by kind */
-	groupByKind(): Record<SpecExportKind4, SpecExport4[]>;
-	/** Render spec or single to MDX */
-	toMarkdown(options?: ExportMarkdownOptions): string;
-	/** Render spec or single to HTML */
-	toHTML(options?: HTMLOptions): string;
-	/** Render spec or single to JSON structure */
-	toJSON(options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
-	/** Generate navigation structure */
-	toNavigation(options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
-	/** Generate search index */
-	toSearchIndex(options?: SearchOptions): SearchIndex;
-	/** Generate Pagefind-compatible records */
-	toPagefindRecords(options?: SearchOptions): PagefindRecord[];
-	/** Generate Algolia-compatible records */
-	toAlgoliaRecords(options?: SearchOptions): AlgoliaRecord[];
+/** Structured data for forgotten exports */
+interface ForgottenExport {
+	name: string;
+	definedIn?: string;
+	referencedBy: TypeReference2[];
+	isExternal: boolean;
+	fix?: string;
+}
+/** Tracks status of each discovered through serialization pipeline */
+interface ExportTracker {
+	name: string;
+	discovered: boolean;
+	status: "pending" | "success" | "skipped" | "failed";
+	skipReason?: "filtered" | "no-declaration" | "internal";
+	error?: string;
+	kind?: string;
+}
+/** Verification result comparing discovered vs extracted exports */
+interface ExportVerification {
+	/** Total exports discovered by TypeScript */
+	discovered: number;
+	/** Exports successfully extracted */
+	extracted: number;
+	/** Exports skipped (filtered, no-declaration, internal) */
+	skipped: number;
+	/** Exports that failed during serialization */
+	failed: number;
+	/** Delta: discovered - extracted */
+	delta: number;
+	details: {
+		skipped: Array<{
+			name: string;
+			reason: "filtered" | "no-declaration" | "internal";
+		}>;
+		failed: Array<{
+			name: string;
+			error: string;
+		}>;
+	};
 }
 /**
-* Loads an OpenPkg spec from file or object.
-*
-* @example
-* ```ts
-* import { loadSpec } from '@openpkg-ts/sdk'
-*
-* // From spec object
-* import spec from './openpkg.json'
-* const docs = loadSpec(spec)
-* ```
-*/
-declare function loadSpec(spec: OpenPkg8): DocsInstance;
-/**
-* Creates a docs instance for querying and rendering API documentation.
+* Extract full OpenPkg spec from a TypeScript entry point
 *
 * @example
-* ```ts
-* import { createDocs } from '@openpkg-ts/sdk'
-*
-* // From file path
-* const docs = createDocs('./openpkg.json')
+* ```typescript
+* import { extractSpec } from '@openpkg-ts/sdk';
 *
-* // From spec object
-* import spec from './openpkg.json'
-* const docs = createDocs(spec)
+* const result = await extractSpec({
+*   entryFile: './src/index.ts'
+* });
 *
-* // Query
-* docs.getExport('useState')
-* docs.getExportsByKind('function')
-* docs.getExportsByTag('@beta')
-* docs.search('hook')
+* console.log(result.spec.exports.length);
 * ```
 */
-declare function createDocs(input: string | OpenPkg8): DocsInstance;
+declare const extractSpec: (options: ExtractOptions) => Promise<ExtractResult>;
 import { SpecType as SpecType4 } from "@openpkg-ts/spec";
 import ts2 from "typescript";
 import ts from "typescript";
@@ -1005,75 +1004,6 @@ declare function extractTypeParameters(node: DeclarationWithTypeParams, checker:
 * Check if a symbol is marked as deprecated via @deprecated JSDoc tag.
 */
 declare function isSymbolDeprecated(symbol: ts4.Symbol | undefined): boolean;
-import ts5 from "typescript";
-interface ProgramOptions {
-	entryFile: string;
-	baseDir?: string;
-	content?: string;
-}
-interface ProgramResult {
-	program: ts5.Program;
-	compilerHost: ts5.CompilerHost;
-	compilerOptions: ts5.CompilerOptions;
-	sourceFile?: ts5.SourceFile;
-	configPath?: string;
-	/** Resolved project references (workspace packages) */
-	projectReferences?: ts5.ResolvedProjectReference[];
-}
-declare function createProgram({ entryFile, baseDir, content }: ProgramOptions): ProgramResult;
-import * as TS from "typescript";
-/**
-* A schema adapter can detect and extract output types from a specific
-* schema validation library.
-*/
-interface SchemaAdapter {
-	/** Unique identifier for this adapter */
-	readonly id: string;
-	/** npm package name(s) this adapter handles */
-	readonly packages: readonly string[];
-	/**
-	* Check if a type matches this adapter's schema library.
-	* Should be fast - called for every export.
-	*/
-	matches(type: TS.Type, checker: TS.TypeChecker): boolean;
-	/**
-	* Extract the output type from a schema type.
-	* Returns null if extraction fails.
-	*/
-	extractOutputType(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
-	/**
-	* Extract the input type from a schema type (optional).
-	* Useful for transforms where input differs from output.
-	*/
-	extractInputType?(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
-}
-/**
-* Result of schema type extraction
-*/
-interface SchemaExtractionResult {
-	/** The adapter that matched */
-	adapter: SchemaAdapter;
-	/** The extracted output type */
-	outputType: TS.Type;
-	/** The extracted input type (if different from output) */
-	inputType?: TS.Type;
-}
-/**
-* Utility: Check if type is an object type reference (has type arguments)
-*/
-declare function isTypeReference(type: TS.Type): type is TS.TypeReference;
-/**
-* Utility: Remove undefined/null from a union type
-*/
-declare function getNonNullableType(type: TS.Type): TS.Type;
-declare function registerAdapter(adapter: SchemaAdapter): void;
-declare function findAdapter(type: TS.Type, checker: TS.TypeChecker): SchemaAdapter | undefined;
-declare function isSchemaType(type: TS.Type, checker: TS.TypeChecker): boolean;
-declare function extractSchemaType(type: TS.Type, checker: TS.TypeChecker): SchemaExtractionResult | null;
-declare const arktypeAdapter: SchemaAdapter;
-declare const typeboxAdapter: SchemaAdapter;
-declare const valibotAdapter: SchemaAdapter;
-declare const zodAdapter: SchemaAdapter;
 /**
 * Target version for JSON Schema generation.
 * @see https://standardschema.dev/json-schema
@@ -1227,24 +1157,94 @@ interface ProjectExtractionOutput extends StandardSchemaExtractionOutput {
 * @param options - Extraction options
 */
 declare function extractStandardSchemasFromProject(entryFile: string, baseDir: string, options?: ExtractFromProjectOptions): Promise<ProjectExtractionOutput>;
-import { SpecExport as SpecExport5 } from "@openpkg-ts/spec";
-import ts6 from "typescript";
-declare function serializeClass(node: ts6.ClassDeclaration, ctx: SerializerContext): SpecExport5 | null;
+declare function extract(options: ExtractOptions): Promise<ExtractResult>;
+import ts5 from "typescript";
+interface ProgramOptions {
+	entryFile: string;
+	baseDir?: string;
+	content?: string;
+}
+interface ProgramResult {
+	program: ts5.Program;
+	compilerHost: ts5.CompilerHost;
+	compilerOptions: ts5.CompilerOptions;
+	sourceFile?: ts5.SourceFile;
+	configPath?: string;
+	/** Resolved project references (workspace packages) */
+	projectReferences?: ts5.ResolvedProjectReference[];
+}
+declare function createProgram({ entryFile, baseDir, content }: ProgramOptions): ProgramResult;
+import * as TS from "typescript";
+/**
+* A schema adapter can detect and extract output types from a specific
+* schema validation library.
+*/
+interface SchemaAdapter {
+	/** Unique identifier for this adapter */
+	readonly id: string;
+	/** npm package name(s) this adapter handles */
+	readonly packages: readonly string[];
+	/**
+	* Check if a type matches this adapter's schema library.
+	* Should be fast - called for every export.
+	*/
+	matches(type: TS.Type, checker: TS.TypeChecker): boolean;
+	/**
+	* Extract the output type from a schema type.
+	* Returns null if extraction fails.
+	*/
+	extractOutputType(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
+	/**
+	* Extract the input type from a schema type (optional).
+	* Useful for transforms where input differs from output.
+	*/
+	extractInputType?(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
+}
+/**
+* Result of schema type extraction
+*/
+interface SchemaExtractionResult {
+	/** The adapter that matched */
+	adapter: SchemaAdapter;
+	/** The extracted output type */
+	outputType: TS.Type;
+	/** The extracted input type (if different from output) */
+	inputType?: TS.Type;
+}
+/**
+* Utility: Check if type is an object type reference (has type arguments)
+*/
+declare function isTypeReference(type: TS.Type): type is TS.TypeReference;
+/**
+* Utility: Remove undefined/null from a union type
+*/
+declare function getNonNullableType(type: TS.Type): TS.Type;
+declare function registerAdapter(adapter: SchemaAdapter): void;
+declare function findAdapter(type: TS.Type, checker: TS.TypeChecker): SchemaAdapter | undefined;
+declare function isSchemaType(type: TS.Type, checker: TS.TypeChecker): boolean;
+declare function extractSchemaType(type: TS.Type, checker: TS.TypeChecker): SchemaExtractionResult | null;
+declare const arktypeAdapter: SchemaAdapter;
+declare const typeboxAdapter: SchemaAdapter;
+declare const valibotAdapter: SchemaAdapter;
+declare const zodAdapter: SchemaAdapter;
 import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
-import ts7 from "typescript";
-declare function serializeEnum(node: ts7.EnumDeclaration, ctx: SerializerContext): SpecExport6 | null;
+import ts6 from "typescript";
+declare function serializeClass(node: ts6.ClassDeclaration, ctx: SerializerContext): SpecExport6 | null;
 import { SpecExport as SpecExport7 } from "@openpkg-ts/spec";
-import ts8 from "typescript";
-declare function serializeFunctionExport(node: ts8.FunctionDeclaration | ts8.ArrowFunction, ctx: SerializerContext): SpecExport7 | null;
+import ts7 from "typescript";
+declare function serializeEnum(node: ts7.EnumDeclaration, ctx: SerializerContext): SpecExport7 | null;
 import { SpecExport as SpecExport8 } from "@openpkg-ts/spec";
-import ts9 from "typescript";
-declare function serializeInterface(node: ts9.InterfaceDeclaration, ctx: SerializerContext): SpecExport8 | null;
+import ts8 from "typescript";
+declare function serializeFunctionExport(node: ts8.FunctionDeclaration | ts8.ArrowFunction, ctx: SerializerContext): SpecExport8 | null;
 import { SpecExport as SpecExport9 } from "@openpkg-ts/spec";
-import ts10 from "typescript";
-declare function serializeTypeAlias(node: ts10.TypeAliasDeclaration, ctx: SerializerContext): SpecExport9 | null;
+import ts9 from "typescript";
+declare function serializeInterface(node: ts9.InterfaceDeclaration, ctx: SerializerContext): SpecExport9 | null;
 import { SpecExport as SpecExport10 } from "@openpkg-ts/spec";
+import ts10 from "typescript";
+declare function serializeTypeAlias(node: ts10.TypeAliasDeclaration, ctx: SerializerContext): SpecExport10 | null;
+import { SpecExport as SpecExport11 } from "@openpkg-ts/spec";
 import ts11 from "typescript";
-declare function serializeVariable(node: ts11.VariableDeclaration, statement: ts11.VariableStatement, ctx: SerializerContext): SpecExport10 | null;
+declare function serializeVariable(node: ts11.VariableDeclaration, statement: ts11.VariableStatement, ctx: SerializerContext): SpecExport11 | null;
 import { SpecSignatureParameter } from "@openpkg-ts/spec";
 import ts12 from "typescript";
 declare function extractParameters(signature: ts12.Signature, ctx: SerializerContext): SpecSignatureParameter[];
@@ -1321,7 +1321,7 @@ declare function deduplicateSchemas(schemas: SpecSchema2[]): SpecSchema2[];
 * A valid discriminator has a unique literal value in each union member.
 */
 declare function findDiscriminatorProperty(unionTypes: ts13.Type[], checker: ts13.TypeChecker): string | undefined;
-import { SpecExport as SpecExport11, SpecMember as SpecMember3, SpecSchema as SpecSchema3, SpecType as SpecType5 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport12, SpecMember as SpecMember3, SpecSchema as SpecSchema3, SpecType as SpecType5 } from "@openpkg-ts/spec";
 /**
 * Options for schema normalization
 */
@@ -1352,7 +1352,7 @@ declare function normalizeSchema(schema: SpecSchema3, options?: NormalizeOptions
 * 2. Normalize member schemas
 * 3. Generate a JSON Schema from members if members exist (populates `schema` field)
 */
-declare function normalizeExport(exp: SpecExport11, options?: NormalizeOptions): SpecExport11;
+declare function normalizeExport(exp: SpecExport12, options?: NormalizeOptions): SpecExport12;
 /**
 * Normalize a SpecType, normalizing its schema and nested schemas.
 *
@@ -1386,5 +1386,4 @@ declare function normalizeMembers(members: SpecMember3[], options?: NormalizeOpt
 import ts14 from "typescript";
 declare function isExported(node: ts14.Node): boolean;
 declare function getNodeName(node: ts14.Node): string | undefined;
-declare function extract(options: ExtractOptions): Promise<ExtractResult>;
 export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, loadSpec, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExport2 as getExport, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecConditionalType, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, Diagnostic, CategorizedBreaking, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };