@openpkg-ts/sdk 0.33.1 → 0.34.1

package/dist/index.js

@@ -1,3 +1,32 @@
+import {
+  QueryBuilder,
+  analyzeSpec,
+  buildSignatureString,
+  findMissingParamDocs,
+  formatBadges,
+  formatConditionalType,
+  formatMappedType,
+  formatParameters,
+  formatReturnType,
+  formatSchema,
+  formatTypeParameters,
+  getDeprecationMessage,
+  getMemberBadges,
+  getMethods,
+  getProperties,
+  groupByVisibility,
+  hasDeprecatedTag,
+  isMethod,
+  isProperty,
+  query,
+  resolveTypeRef,
+  sortByName,
+  toAlgoliaRecords,
+  toPagefindRecords,
+  toSearchIndex,
+  toSearchIndexJSON
+} from "./shared/chunk-skapcfq1.js";
+
 // src/primitives/diff.ts
 import {
   calculateNextVersion,
@@ -42,312 +71,9 @@ function mergeConfig(fileConfig, cliOptions) {
     }
   };
 }
-// src/core/diagnostics.ts
-function hasDeprecatedTag(exp) {
-  if (exp.deprecated === true)
-    return true;
-  return exp.tags?.some((t) => t.name === "deprecated" || t.name === "@deprecated") ?? false;
-}
-function getDeprecationMessage(exp) {
-  const tag = exp.tags?.find((t) => t.name === "deprecated" || t.name === "@deprecated");
-  if (tag?.text.trim()) {
-    return tag.text.trim();
-  }
-  return;
-}
-function findMissingParamDocs(exp) {
-  const missing = [];
-  for (const sig of exp.signatures ?? []) {
-    for (const param of sig.parameters ?? []) {
-      if (!param.description?.trim()) {
-        missing.push(param.name);
-      }
-    }
-  }
-  return missing;
-}
-function checkMemberDescriptions(exp, members) {
-  const items = [];
-  for (const member of members) {
-    if (!member.description?.trim() && member.name) {
-      items.push({
-        exportId: exp.id,
-        exportName: exp.name,
-        issue: "member missing description",
-        member: member.name
-      });
-    }
-  }
-  return items;
-}
-function analyzeSpec(spec) {
-  const missingDescriptions = [];
-  const deprecatedNoReason = [];
-  const missingParamDocs = [];
-  for (const exp of spec.exports) {
-    if (!exp.description?.trim()) {
-      missingDescriptions.push({
-        exportId: exp.id,
-        exportName: exp.name,
-        issue: "missing description"
-      });
-    }
-    if (exp.members) {
-      missingDescriptions.push(...checkMemberDescriptions(exp, exp.members));
-    }
-    if (hasDeprecatedTag(exp) && !getDeprecationMessage(exp)) {
-      deprecatedNoReason.push({
-        exportId: exp.id,
-        exportName: exp.name,
-        issue: "deprecated without reason"
-      });
-    }
-    const missingParams = findMissingParamDocs(exp);
-    for (const param of missingParams) {
-      missingParamDocs.push({
-        exportId: exp.id,
-        exportName: exp.name,
-        issue: "param missing description",
-        param
-      });
-    }
-  }
-  return {
-    missingDescriptions,
-    deprecatedNoReason,
-    missingParamDocs
-  };
-}
-// src/core/format.ts
-function getMemberBadges(member) {
-  const badges = [];
-  const visibility = member.visibility ?? "public";
-  if (visibility !== "public") {
-    badges.push(visibility);
-  }
-  const flags = member.flags;
-  if (flags?.static)
-    badges.push("static");
-  if (flags?.readonly)
-    badges.push("readonly");
-  if (flags?.async)
-    badges.push("async");
-  if (flags?.abstract)
-    badges.push("abstract");
-  return badges;
-}
-function formatBadges(badges) {
-  return badges.join(" ");
-}
 // src/core/loader.ts
 import * as fs2 from "node:fs";
-
-// src/core/query.ts
-function formatFunctionSchema(schema) {
-  const sigs = schema["x-ts-signatures"];
-  if (!sigs?.length)
-    return "(...args: unknown[]) => unknown";
-  const sig = sigs[0];
-  const params = formatParameters(sig);
-  const ret = sig.returns ? formatSchema(sig.returns.schema) : "void";
-  return `${params} => ${ret}`;
-}
-function formatSchema(schema, options) {
-  if (!schema)
-    return "unknown";
-  if (typeof schema === "string")
-    return schema;
-  const withPackage = (typeStr) => {
-    if (options?.includePackage && typeof schema === "object" && "x-ts-package" in schema) {
-      const pkg = schema["x-ts-package"];
-      return `${typeStr} (from ${pkg})`;
-    }
-    return typeStr;
-  };
-  if (typeof schema === "object" && schema !== null) {
-    if ("x-ts-type" in schema && typeof schema["x-ts-type"] === "string") {
-      const tsType = schema["x-ts-type"];
-      if (tsType === "function" || schema["x-ts-function"]) {
-        return withPackage(formatFunctionSchema(schema));
-      }
-      return withPackage(tsType);
-    }
-    if ("x-ts-function" in schema && schema["x-ts-function"]) {
-      return withPackage(formatFunctionSchema(schema));
-    }
-    if ("x-ts-type-predicate" in schema) {
-      const pred = schema["x-ts-type-predicate"];
-      return `${pred.parameterName} is ${formatSchema(pred.type, options)}`;
-    }
-    if ("$ref" in schema && typeof schema.$ref === "string") {
-      const baseName = schema.$ref.replace("#/types/", "");
-      if ("x-ts-type-arguments" in schema && Array.isArray(schema["x-ts-type-arguments"])) {
-        const args = schema["x-ts-type-arguments"].map((s) => formatSchema(s, options)).join(", ");
-        return withPackage(`${baseName}<${args}>`);
-      }
-      return withPackage(baseName);
-    }
-    if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
-      const threshold = options?.collapseUnionThreshold;
-      const members = schema.anyOf;
-      if (threshold && members.length > threshold) {
-        const shown = members.slice(0, 3);
-        const remaining = members.length - 3;
-        const shownStr = shown.map((s) => formatSchema(s, options)).join(" | ");
-        return `${shownStr} | ... (${remaining} more)`;
-      }
-      return members.map((s) => formatSchema(s, options)).join(" | ");
-    }
-    if ("allOf" in schema && Array.isArray(schema.allOf)) {
-      return schema.allOf.map((s) => formatSchema(s, options)).join(" & ");
-    }
-    if ("type" in schema && schema.type === "array") {
-      const items = "items" in schema ? formatSchema(schema.items, options) : "unknown";
-      return `${items}[]`;
-    }
-    if ("type" in schema && schema.type === "tuple" && "items" in schema) {
-      const items = schema.items.map((s) => formatSchema(s, options)).join(", ");
-      return `[${items}]`;
-    }
-    if ("type" in schema && schema.type === "object") {
-      if ("properties" in schema && schema.properties) {
-        const props = Object.entries(schema.properties).map(([k, v]) => `${k}: ${formatSchema(v, options)}`).join("; ");
-        return `{ ${props} }`;
-      }
-      return "object";
-    }
-    if ("type" in schema && typeof schema.type === "string") {
-      return withPackage(schema.type);
-    }
-  }
-  return "unknown";
-}
-function formatTypeParameters(typeParams) {
-  if (!typeParams?.length)
-    return "";
-  const params = typeParams.map((tp) => {
-    let str = "";
-    if ("const" in tp && tp.const)
-      str += "const ";
-    if (tp.variance === "in")
-      str += "in ";
-    else if (tp.variance === "out")
-      str += "out ";
-    else if (tp.variance === "inout")
-      str += "in out ";
-    str += tp.name;
-    if (tp.constraint)
-      str += ` extends ${tp.constraint}`;
-    if (tp.default)
-      str += ` = ${tp.default}`;
-    return str;
-  });
-  return `<${params.join(", ")}>`;
-}
-function formatParameters(sig) {
-  if (!sig?.parameters?.length)
-    return "()";
-  const params = sig.parameters.map((p) => {
-    const optional = p.required === false ? "?" : "";
-    const rest = p.rest ? "..." : "";
-    const type = formatSchema(p.schema);
-    return `${rest}${p.name}${optional}: ${type}`;
-  });
-  return `(${params.join(", ")})`;
-}
-function formatReturnType(sig) {
-  if (!sig?.returns)
-    return "void";
-  return formatSchema(sig.returns.schema);
-}
-function buildSignatureString(exp, sigIndex = 0) {
-  const sig = exp.signatures?.[sigIndex];
-  const typeParams = formatTypeParameters(exp.typeParameters || sig?.typeParameters);
-  switch (exp.kind) {
-    case "function": {
-      const params = formatParameters(sig);
-      const returnType = formatReturnType(sig);
-      return `function ${exp.name}${typeParams}${params}: ${returnType}`;
-    }
-    case "class": {
-      const ext = exp.extends ? ` extends ${exp.extends}` : "";
-      const impl = exp.implements?.length ? ` implements ${exp.implements.join(", ")}` : "";
-      return `class ${exp.name}${typeParams}${ext}${impl}`;
-    }
-    case "interface": {
-      const ext = exp.extends ? ` extends ${exp.extends}` : "";
-      return `interface ${exp.name}${typeParams}${ext}`;
-    }
-    case "type": {
-      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
-      return `type ${exp.name}${typeParams} = ${typeValue}`;
-    }
-    case "enum": {
-      return `enum ${exp.name}`;
-    }
-    case "variable": {
-      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
-      return `const ${exp.name}: ${typeValue}`;
-    }
-    default:
-      return exp.name;
-  }
-}
-function resolveTypeRef(ref, spec) {
-  const id = ref.replace("#/types/", "");
-  return spec.types?.find((t) => t.id === id);
-}
-function isMethod(member) {
-  return !!member.signatures?.length;
-}
-function isProperty(member) {
-  return !member.signatures?.length;
-}
-function getMethods(members) {
-  return members?.filter(isMethod) ?? [];
-}
-function getProperties(members) {
-  return members?.filter(isProperty) ?? [];
-}
-function groupByVisibility(members) {
-  const groups = {
-    public: [],
-    protected: [],
-    private: []
-  };
-  for (const member of members ?? []) {
-    const visibility = member.visibility ?? "public";
-    groups[visibility].push(member);
-  }
-  return groups;
-}
-function sortByName(items) {
-  return [...items].sort((a, b) => a.name.localeCompare(b.name));
-}
-function formatConditionalType(condType) {
-  const check = formatSchema(condType.checkType);
-  const ext = formatSchema(condType.extendsType);
-  const trueT = formatSchema(condType.trueType);
-  const falseT = formatSchema(condType.falseType);
-  return `${check} extends ${ext} ? ${trueT} : ${falseT}`;
-}
-function formatMappedType(mappedType) {
-  const keyStr = formatSchema(mappedType.keyType);
-  const valueStr = formatSchema(mappedType.valueType);
-  let readonlyMod = "";
-  if (mappedType.readonly === true || mappedType.readonly === "add") {
-    readonlyMod = "readonly ";
-  } else if (mappedType.readonly === "remove") {
-    readonlyMod = "-readonly ";
-  }
-  let optionalMod = "";
-  if (mappedType.optional === true || mappedType.optional === "add") {
-    optionalMod = "?";
-  } else if (mappedType.optional === "remove") {
-    optionalMod = "-?";
-  }
-  return `{ ${readonlyMod}[${keyStr}]${optionalMod}: ${valueStr} }`;
-}
+import { validateSpec } from "@openpkg-ts/spec";
 
 // src/render/html.ts
 var defaultCSS = `
@@ -1368,177 +1094,26 @@ function toDocusaurusSidebarJS(spec, options = {}) {
   return `module.exports = ${JSON.stringify(sidebar, null, 2)};`;
 }
 
-// src/core/search.ts
-var defaultSlugify2 = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
-function extractKeywords(exp, options = {}) {
-  const keywords = new Set;
-  keywords.add(exp.name);
-  keywords.add(exp.name.toLowerCase());
-  const camelParts = exp.name.split(/(?=[A-Z])/);
-  for (const part of camelParts) {
-    if (part.length > 2)
-      keywords.add(part.toLowerCase());
-  }
-  if (exp.tags) {
-    for (const tag of exp.tags) {
-      keywords.add(tag.name.replace("@", ""));
-      const tagWords = tag.text.split(/\s+/);
-      for (const word of tagWords) {
-        if (word.length > 2)
-          keywords.add(word.toLowerCase());
-      }
-    }
-  }
-  if (exp.description) {
-    const descWords = exp.description.toLowerCase().split(/\W+/).filter((w) => w.length > 2);
-    for (const word of descWords) {
-      keywords.add(word);
-    }
-  }
-  if (options.includeMembers && exp.members) {
-    for (const member of exp.members) {
-      if (member.name) {
-        keywords.add(member.name.toLowerCase());
-      }
-    }
-  }
-  if (options.includeParameters && exp.signatures) {
-    for (const sig of exp.signatures) {
-      for (const param of sig.parameters || []) {
-        keywords.add(param.name.toLowerCase());
-      }
-    }
-  }
-  return Array.from(keywords);
-}
-function buildContent(exp, options = {}) {
-  const parts = [];
-  parts.push(exp.name);
-  if (exp.description) {
-    parts.push(exp.description);
-  }
-  if (options.includeSignatures !== false) {
-    parts.push(buildSignatureString(exp));
-  }
-  if (exp.tags) {
-    parts.push(...exp.tags.map((t) => `${t.name} ${t.text}`));
-  }
-  if (options.includeMembers !== false && exp.members) {
-    const props = getProperties(exp.members);
-    const methods = getMethods(exp.members);
-    for (const prop of props) {
-      if (prop.name) {
-        parts.push(prop.name);
-        if (prop.description)
-          parts.push(prop.description);
-      }
-    }
-    for (const method of methods) {
-      if (method.name) {
-        parts.push(method.name);
-        if (method.description)
-          parts.push(method.description);
-      }
-    }
-  }
-  if (options.includeParameters !== false && exp.signatures) {
-    for (const sig of exp.signatures) {
-      for (const param of sig.parameters || []) {
-        parts.push(param.name);
-        if (param.description)
-          parts.push(param.description);
-      }
-    }
-  }
-  return parts.join(" ");
-}
-function createSearchRecord(exp, _packageName, options = {}) {
-  const { baseUrl = "/api", slugify = defaultSlugify2 } = options;
-  return {
-    id: exp.id,
-    name: exp.name,
-    kind: exp.kind,
-    signature: buildSignatureString(exp),
-    description: exp.description,
-    content: buildContent(exp, options),
-    keywords: extractKeywords(exp, options),
-    url: `${baseUrl}/${slugify(exp.name)}`,
-    deprecated: exp.deprecated === true
-  };
-}
-function toSearchIndex(spec, options = {}) {
-  const records = spec.exports.map((exp) => createSearchRecord(exp, spec.meta.name, options));
-  return {
-    records,
-    version: spec.meta.version || "0.0.0",
-    generatedAt: new Date().toISOString(),
-    packageName: spec.meta.name
-  };
-}
-function toPagefindRecords(spec, options = {}) {
-  const { baseUrl = "/api", slugify = defaultSlugify2, weights = {} } = options;
-  const { name: nameWeight = 10, description: descWeight = 5, signature: sigWeight = 3 } = weights;
-  return spec.exports.map((exp) => {
-    const content = buildContent(exp, options);
-    const signature = buildSignatureString(exp);
-    const filters = {
-      kind: [exp.kind]
-    };
-    if (exp.deprecated) {
-      filters.deprecated = ["true"];
-    }
-    if (exp.tags?.length) {
-      filters.tags = exp.tags.map((t) => t.name.replace("@", ""));
-    }
-    return {
-      url: `${baseUrl}/${slugify(exp.name)}`,
-      content,
-      word_count: content.split(/\s+/).length,
-      filters,
-      meta: {
-        title: exp.name,
-        kind: exp.kind,
-        description: exp.description?.slice(0, 160),
-        signature
-      },
-      weighted_sections: [
-        { weight: nameWeight, text: exp.name },
-        ...exp.description ? [{ weight: descWeight, text: exp.description }] : [],
-        { weight: sigWeight, text: signature }
-      ]
-    };
-  });
-}
-function toAlgoliaRecords(spec, options = {}) {
-  const { baseUrl = "/api", slugify = defaultSlugify2 } = options;
-  return spec.exports.map((exp) => ({
-    objectID: exp.id,
-    name: exp.name,
-    kind: exp.kind,
-    description: exp.description,
-    signature: buildSignatureString(exp),
-    content: buildContent(exp, options),
-    tags: (exp.tags || []).map((t) => t.name.replace("@", "")),
-    deprecated: exp.deprecated === true,
-    url: `${baseUrl}/${slugify(exp.name)}`,
-    hierarchy: {
-      lvl0: spec.meta.name,
-      lvl1: `${exp.kind.charAt(0).toUpperCase() + exp.kind.slice(1)}s`,
-      lvl2: exp.name
-    }
-  }));
-}
-function toSearchIndexJSON(spec, options = {}) {
-  const index = toSearchIndex(spec, options);
-  return options.pretty ? JSON.stringify(index, null, 2) : JSON.stringify(index);
-}
-
 // src/core/loader.ts
 function loadSpec(spec) {
   return createDocsInstance(spec);
 }
 function createDocs(input) {
-  const spec = typeof input === "string" ? JSON.parse(fs2.readFileSync(input, "utf-8")) : input;
+  let spec;
+  if (typeof input === "string") {
+    try {
+      spec = JSON.parse(fs2.readFileSync(input, "utf-8"));
+    } catch (err) {
+      throw new Error(`Failed to parse spec file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    spec = input;
+  }
+  const validation = validateSpec(spec);
+  if (!validation.ok) {
+    const errors = validation.errors.slice(0, 5).map((e) => `${e.instancePath || "/"}: ${e.message}`).join("; ");
+    throw new Error(`Invalid OpenPkg spec: ${errors}`);
+  }
   return createDocsInstance(spec);
 }
 function createDocsInstance(spec) {
@@ -1589,8 +1164,8 @@ function createDocsInstance(spec) {
       const normalizedTag = tagName.startsWith("@") ? tagName : `@${tagName}`;
       return exportsByTag.get(normalizedTag) ?? [];
     },
-    search(query) {
-      const lowerQuery = query.toLowerCase();
+    search(query2) {
+      const lowerQuery = query2.toLowerCase();
       return spec.exports.filter((exp) => {
         if (exp.name.toLowerCase().includes(lowerQuery))
           return true;
@@ -1654,6 +1229,221 @@ function extractModuleName(exp) {
   }
   return;
 }
+// src/render/react.ts
+import * as fs3 from "node:fs";
+import * as path2 from "node:path";
+function generateFullLayout(spec, componentsPath) {
+  const pkgName = spec.meta.name;
+  return `'use client';
+
+import type { OpenPkg, SpecExport } from '@openpkg-ts/spec';
+import spec from './openpkg.json';
+
+// Add components via: openpkg docs add function-section class-section interface-section
+// Then uncomment the imports below and customize as needed.
+
+// import { FunctionSection } from '${componentsPath}/function-section';
+// import { ClassSection } from '${componentsPath}/class-section';
+// import { InterfaceSection } from '${componentsPath}/interface-section';
+// import { VariableSection } from '${componentsPath}/variable-section';
+// import { EnumSection } from '${componentsPath}/enum-section';
+
+/**
+ * Renders a single export based on its kind.
+ * Customize this to match your design system.
+ */
+function ExportSection({ exp }: { exp: SpecExport }) {
+  // Uncomment the switch once you've added components:
+  // switch (exp.kind) {
+  //   case 'function':
+  //     return <FunctionSection key={exp.id} export={exp} spec={spec as OpenPkg} />;
+  //   case 'class':
+  //     return <ClassSection key={exp.id} export={exp} spec={spec as OpenPkg} />;
+  //   case 'interface':
+  //   case 'type':
+  //     return <InterfaceSection key={exp.id} export={exp} spec={spec as OpenPkg} />;
+  //   case 'variable':
+  //     return <VariableSection key={exp.id} export={exp} spec={spec as OpenPkg} />;
+  //   case 'enum':
+  //     return <EnumSection key={exp.id} export={exp} spec={spec as OpenPkg} />;
+  //   default:
+  //     return null;
+  // }
+
+  // Placeholder: replace with component imports above
+  return (
+    <section id={exp.id} className="py-8 border-b">
+      <h2 className="text-xl font-semibold">{exp.name}</h2>
+      <p className="text-muted-foreground">{exp.description || 'No description'}</p>
+      <code className="text-sm">{exp.kind}</code>
+    </section>
+  );
+}
+
+/**
+ * Full API Reference Page for ${pkgName}
+ *
+ * This layout renders all exports on a single page.
+ * Customize the grouping, styling, and components to match your docs.
+ */
+export default function APIReferencePage() {
+  const typedSpec = spec as OpenPkg;
+  const exports = typedSpec.exports;
+
+  // Group exports by kind
+  const functions = exports.filter((e) => e.kind === 'function');
+  const classes = exports.filter((e) => e.kind === 'class');
+  const interfaces = exports.filter((e) => e.kind === 'interface' || e.kind === 'type');
+  const variables = exports.filter((e) => e.kind === 'variable');
+  const enums = exports.filter((e) => e.kind === 'enum');
+
+  return (
+    <div className="max-w-4xl mx-auto px-4 py-8">
+      <header className="mb-12">
+        <h1 className="text-3xl font-bold">{typedSpec.meta.name}</h1>
+        {typedSpec.meta.description && (
+          <p className="text-lg text-muted-foreground mt-2">{typedSpec.meta.description}</p>
+        )}
+        {typedSpec.meta.version && (
+          <p className="text-sm text-muted-foreground">v{typedSpec.meta.version}</p>
+        )}
+      </header>
+
+      {functions.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">Functions</h2>
+          {functions.map((exp) => (
+            <ExportSection key={exp.id} exp={exp} />
+          ))}
+        </section>
+      )}
+
+      {classes.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">Classes</h2>
+          {classes.map((exp) => (
+            <ExportSection key={exp.id} exp={exp} />
+          ))}
+        </section>
+      )}
+
+      {interfaces.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">Types & Interfaces</h2>
+          {interfaces.map((exp) => (
+            <ExportSection key={exp.id} exp={exp} />
+          ))}
+        </section>
+      )}
+
+      {variables.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">Variables</h2>
+          {variables.map((exp) => (
+            <ExportSection key={exp.id} exp={exp} />
+          ))}
+        </section>
+      )}
+
+      {enums.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">Enums</h2>
+          {enums.map((exp) => (
+            <ExportSection key={exp.id} exp={exp} />
+          ))}
+        </section>
+      )}
+    </div>
+  );
+}
+
+export { spec };
+`;
+}
+function generateIndexLayout(spec, componentsPath) {
+  const pkgName = spec.meta.name;
+  return `'use client';
+
+import type { OpenPkg } from '@openpkg-ts/spec';
+import spec from './openpkg.json';
+
+// Add the export-card component: openpkg docs add export-card
+// import { ExportCard } from '${componentsPath}/export-card';
+
+/**
+ * API Reference Index Page for ${pkgName}
+ *
+ * Links to individual export pages. Best with file-based routing.
+ * Customize the card component and links to match your docs.
+ */
+export default function APIReferenceIndex() {
+  const typedSpec = spec as OpenPkg;
+  const exports = typedSpec.exports;
+
+  // Group exports by kind
+  const groups = [
+    { title: 'Functions', items: exports.filter((e) => e.kind === 'function') },
+    { title: 'Classes', items: exports.filter((e) => e.kind === 'class') },
+    { title: 'Types & Interfaces', items: exports.filter((e) => e.kind === 'interface' || e.kind === 'type') },
+    { title: 'Variables', items: exports.filter((e) => e.kind === 'variable') },
+    { title: 'Enums', items: exports.filter((e) => e.kind === 'enum') },
+  ].filter((g) => g.items.length > 0);
+
+  return (
+    <div className="max-w-4xl mx-auto px-4 py-8">
+      <header className="mb-12">
+        <h1 className="text-3xl font-bold">{typedSpec.meta.name}</h1>
+        {typedSpec.meta.description && (
+          <p className="text-lg text-muted-foreground mt-2">{typedSpec.meta.description}</p>
+        )}
+      </header>
+
+      {groups.map((group) => (
+        <section key={group.title} className="mb-12">
+          <h2 className="text-2xl font-bold mb-6">{group.title}</h2>
+          <div className="grid gap-4 md:grid-cols-2">
+            {group.items.map((exp) => (
+              // Replace with ExportCard once installed:
+              // <ExportCard key={exp.id} export={exp} href={\`/api/\${exp.name}\`} />
+              <a
+                key={exp.id}
+                href={\`/api/\${exp.name}\`}
+                className="block p-4 border rounded-lg hover:bg-muted transition-colors"
+              >
+                <h3 className="font-semibold">{exp.name}</h3>
+                <p className="text-sm text-muted-foreground line-clamp-2">
+                  {exp.description || 'No description'}
+                </p>
+                <span className="text-xs bg-muted px-2 py-1 rounded mt-2 inline-block">
+                  {exp.kind}
+                </span>
+              </a>
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+export { spec };
+`;
+}
+async function toReact(spec, options) {
+  const { outDir, variant = "full", componentsPath = "@/components/api" } = options;
+  if (!fs3.existsSync(outDir)) {
+    fs3.mkdirSync(outDir, { recursive: true });
+  }
+  const specPath = path2.join(outDir, "openpkg.json");
+  fs3.writeFileSync(specPath, JSON.stringify(spec, null, 2));
+  const layoutContent = variant === "index" ? generateIndexLayout(spec, componentsPath) : generateFullLayout(spec, componentsPath);
+  const layoutPath = path2.join(outDir, "page.tsx");
+  fs3.writeFileSync(layoutPath, layoutContent);
+}
+function toReactString(spec, options = {}) {
+  const { variant = "full", componentsPath = "@/components/api" } = options;
+  return variant === "index" ? generateIndexLayout(spec, componentsPath) : generateFullLayout(spec, componentsPath);
+}
 // src/primitives/filter.ts
 function matchesExport(exp, criteria) {
   if (criteria.kinds && criteria.kinds.length > 0) {
@@ -1761,8 +1551,8 @@ function filterSpec(spec, criteria) {
 import ts11 from "typescript";
 
 // src/compiler/program.ts
-import * as fs3 from "node:fs";
-import * as path2 from "node:path";
+import * as fs4 from "node:fs";
+import * as path3 from "node:path";
 import ts from "typescript";
 function isJsFile(file) {
   return /\.(js|mjs|cjs|jsx)$/.test(file);
@@ -1788,16 +1578,16 @@ function resolveProjectReferences(configPath, parsedConfig) {
   if (!parsedConfig.projectReferences?.length) {
     return additionalFiles;
   }
-  const configDir = path2.dirname(configPath);
+  const configDir = path3.dirname(configPath);
   for (const ref of parsedConfig.projectReferences) {
-    const refPath = path2.resolve(configDir, ref.path);
-    const refConfigPath = fs3.existsSync(path2.join(refPath, "tsconfig.json")) ? path2.join(refPath, "tsconfig.json") : refPath;
-    if (!fs3.existsSync(refConfigPath))
+    const refPath = path3.resolve(configDir, ref.path);
+    const refConfigPath = fs4.existsSync(path3.join(refPath, "tsconfig.json")) ? path3.join(refPath, "tsconfig.json") : refPath;
+    if (!fs4.existsSync(refConfigPath))
       continue;
     const refConfigFile = ts.readConfigFile(refConfigPath, ts.sys.readFile);
     if (refConfigFile.error)
       continue;
-    const refParsed = ts.parseJsonConfigFileContent(refConfigFile.config, ts.sys, path2.dirname(refConfigPath));
+    const refParsed = ts.parseJsonConfigFileContent(refConfigFile.config, ts.sys, path3.dirname(refConfigPath));
     additionalFiles.push(...refParsed.fileNames);
   }
   return additionalFiles;
@@ -1830,10 +1620,10 @@ function buildWorkspaceMap(baseDir) {
   let rootDir;
   let workspaceGlobs = [];
   for (let i = 0;i < 10; i++) {
-    const pnpmPath = path2.join(currentDir, "pnpm-workspace.yaml");
-    if (fs3.existsSync(pnpmPath)) {
+    const pnpmPath = path3.join(currentDir, "pnpm-workspace.yaml");
+    if (fs4.existsSync(pnpmPath)) {
       try {
-        const yamlContent = fs3.readFileSync(pnpmPath, "utf-8");
+        const yamlContent = fs4.readFileSync(pnpmPath, "utf-8");
         workspaceGlobs = parsePnpmWorkspace(yamlContent);
         if (workspaceGlobs.length > 0) {
           rootDir = currentDir;
@@ -1841,10 +1631,10 @@ function buildWorkspaceMap(baseDir) {
         }
       } catch {}
     }
-    const pkgPath = path2.join(currentDir, "package.json");
-    if (fs3.existsSync(pkgPath)) {
+    const pkgPath = path3.join(currentDir, "package.json");
+    if (fs4.existsSync(pkgPath)) {
       try {
-        const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
+        const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
         if (pkg.workspaces) {
           rootDir = currentDir;
           workspaceGlobs = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages || [];
@@ -1852,7 +1642,7 @@ function buildWorkspaceMap(baseDir) {
         }
       } catch {}
     }
-    const parent = path2.dirname(currentDir);
+    const parent = path3.dirname(currentDir);
     if (parent === currentDir)
       break;
     currentDir = parent;
@@ -1861,21 +1651,21 @@ function buildWorkspaceMap(baseDir) {
     return;
   const packages = new Map;
   for (const glob of workspaceGlobs) {
-    const globDir = path2.join(rootDir, glob.replace(/\/\*$/, ""));
-    if (!fs3.existsSync(globDir) || !fs3.statSync(globDir).isDirectory())
+    const globDir = path3.join(rootDir, glob.replace(/\/\*$/, ""));
+    if (!fs4.existsSync(globDir) || !fs4.statSync(globDir).isDirectory())
       continue;
-    const entries = fs3.readdirSync(globDir, { withFileTypes: true });
+    const entries = fs4.readdirSync(globDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
-      const pkgDir = path2.join(globDir, entry.name);
-      const pkgJsonPath = path2.join(pkgDir, "package.json");
-      if (!fs3.existsSync(pkgJsonPath))
+      const pkgDir = path3.join(globDir, entry.name);
+      const pkgJsonPath = path3.join(pkgDir, "package.json");
+      if (!fs4.existsSync(pkgJsonPath))
         continue;
       try {
-        const pkg = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+        const pkg = JSON.parse(fs4.readFileSync(pkgJsonPath, "utf-8"));
         if (pkg.name) {
-          const srcDir = fs3.existsSync(path2.join(pkgDir, "src")) ? path2.join(pkgDir, "src") : pkgDir;
+          const srcDir = fs4.existsSync(path3.join(pkgDir, "src")) ? path3.join(pkgDir, "src") : pkgDir;
           packages.set(pkg.name, srcDir);
         }
       } catch {}
@@ -1885,7 +1675,7 @@ function buildWorkspaceMap(baseDir) {
 }
 function createProgram({
   entryFile,
-  baseDir = path2.dirname(entryFile),
+  baseDir = path3.dirname(entryFile),
   content
 }) {
   let configPath = ts.findConfigFile(baseDir, ts.sys.fileExists, "tsconfig.json");
@@ -1896,7 +1686,7 @@ function createProgram({
   let additionalRootFiles = [];
   if (configPath) {
     const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
-    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path2.dirname(configPath));
+    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path3.dirname(configPath));
     compilerOptions = { ...compilerOptions, ...parsedConfig.options };
     additionalRootFiles = resolveProjectReferences(configPath, parsedConfig);
     const sourceFiles = parsedConfig.fileNames.filter((f) => !f.includes(".test.") && !f.includes(".spec.") && !f.includes("/dist/") && !f.includes("/node_modules/"));
@@ -1924,8 +1714,8 @@ function createProgram({
       return moduleNames.map((moduleName) => {
         const srcDir = workspaceMap.packages.get(moduleName);
         if (srcDir) {
-          const indexFile = path2.join(srcDir, "index.ts");
-          if (fs3.existsSync(indexFile)) {
+          const indexFile = path3.join(srcDir, "index.ts");
+          if (fs4.existsSync(indexFile)) {
             return { resolvedFileName: indexFile, isExternalLibraryImport: false };
           }
         }
@@ -4817,7 +4607,7 @@ function serializeDeclaration(declaration, _exportSymbol, _targetSymbol, exportN
   return result;
 }
 // src/primitives/list.ts
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 import ts12 from "typescript";
 async function listExports(options) {
   const { entryFile, baseDir, content } = options;
@@ -4865,7 +4655,7 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
     return {
       name,
       kind: "namespace",
-      file: path3.relative(path3.dirname(entryFile), declaration.fileName),
+      file: path4.relative(path4.dirname(entryFile), declaration.fileName),
       line: 1,
       reexport: true
     };
@@ -4879,7 +4669,7 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
   return {
     name,
     kind,
-    file: path3.relative(path3.dirname(entryFile), sourceFile.fileName),
+    file: path4.relative(path4.dirname(entryFile), sourceFile.fileName),
     line: line + 1,
     ...description ? { description } : {},
     ...deprecated ? { deprecated: true } : {},
@@ -4931,10 +4721,10 @@ function getDescriptionPreview(symbol, checker) {
   return `${firstLine.slice(0, 77)}...`;
 }
 // src/builder/spec-builder.ts
-import * as fs6 from "node:fs";
-import * as path6 from "node:path";
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
-import ts15 from "typescript";
+import ts16 from "typescript";
 
 // src/ast/resolve.ts
 import ts13 from "typescript";
@@ -4968,9 +4758,9 @@ function resolveExportTarget2(symbol, checker) {
 
 // src/schema/standard-schema.ts
 import { spawn, spawnSync } from "node:child_process";
-import * as fs4 from "node:fs";
+import * as fs5 from "node:fs";
 import * as os from "node:os";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 function isStandardJSONSchema(obj) {
   if (typeof obj !== "object" || obj === null)
     return false;
@@ -5216,21 +5006,21 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
     result.errors.push("No TypeScript runtime available. Install bun, tsx, or ts-node, or use Node 22+.");
     return result;
   }
-  if (!fs4.existsSync(tsFilePath)) {
+  if (!fs5.existsSync(tsFilePath)) {
     result.errors.push(`TypeScript file not found: ${tsFilePath}`);
     return result;
   }
   const tempDir = os.tmpdir();
-  const workerPath = path4.join(tempDir, `openpkg-extract-worker-${Date.now()}.ts`);
+  const workerPath = path5.join(tempDir, `openpkg-extract-worker-${Date.now()}.ts`);
   try {
-    fs4.writeFileSync(workerPath, TS_WORKER_SCRIPT);
+    fs5.writeFileSync(workerPath, TS_WORKER_SCRIPT);
     const optionsJson = JSON.stringify({ target, libraryOptions });
     const args = [...runtime.args, workerPath, tsFilePath, optionsJson];
     return await new Promise((resolve2) => {
       const child = spawn(runtime.cmd, args, {
         timeout,
         stdio: ["ignore", "pipe", "pipe"],
-        cwd: path4.dirname(tsFilePath)
+        cwd: path5.dirname(tsFilePath)
       });
       let stdout = "";
       let stderr = "";
@@ -5242,7 +5032,7 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
       });
       child.on("close", (code) => {
         try {
-          fs4.unlinkSync(workerPath);
+          fs5.unlinkSync(workerPath);
         } catch {}
         if (code !== 0) {
           result.errors.push(`Extraction failed (${runtime.name}): ${stderr || `exit code ${code}`}`);
@@ -5271,7 +5061,7 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
       });
       child.on("error", (err) => {
         try {
-          fs4.unlinkSync(workerPath);
+          fs5.unlinkSync(workerPath);
         } catch {}
         result.errors.push(`Subprocess error: ${err.message}`);
         resolve2(result);
@@ -5279,19 +5069,19 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
     });
   } catch (e) {
     try {
-      fs4.unlinkSync(workerPath);
+      fs5.unlinkSync(workerPath);
     } catch {}
     result.errors.push(`Failed to create worker script: ${e}`);
     return result;
   }
 }
 function readTsconfigOutDir(baseDir) {
-  const tsconfigPath = path4.join(baseDir, "tsconfig.json");
+  const tsconfigPath = path5.join(baseDir, "tsconfig.json");
   try {
-    if (!fs4.existsSync(tsconfigPath)) {
+    if (!fs5.existsSync(tsconfigPath)) {
       return null;
     }
-    const content = fs4.readFileSync(tsconfigPath, "utf-8");
+    const content = fs5.readFileSync(tsconfigPath, "utf-8");
     const stripped = content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
     const tsconfig = JSON.parse(stripped);
     if (tsconfig.compilerOptions?.outDir) {
@@ -5301,7 +5091,7 @@ function readTsconfigOutDir(baseDir) {
   return null;
 }
 function resolveCompiledPath(tsPath, baseDir) {
-  const relativePath = path4.relative(baseDir, tsPath);
+  const relativePath = path5.relative(baseDir, tsPath);
   const withoutExt = relativePath.replace(/\.tsx?$/, "");
   const srcPrefix = withoutExt.replace(/^src\//, "");
   const tsconfigOutDir = readTsconfigOutDir(baseDir);
@@ -5309,7 +5099,7 @@ function resolveCompiledPath(tsPath, baseDir) {
   const candidates = [];
   if (tsconfigOutDir) {
     for (const ext of extensions) {
-      candidates.push(path4.join(baseDir, tsconfigOutDir, `${srcPrefix}${ext}`));
+      candidates.push(path5.join(baseDir, tsconfigOutDir, `${srcPrefix}${ext}`));
     }
   }
   const commonOutDirs = ["dist", "build", "lib", "out"];
@@ -5317,21 +5107,21 @@ function resolveCompiledPath(tsPath, baseDir) {
     if (outDir === tsconfigOutDir)
       continue;
     for (const ext of extensions) {
-      candidates.push(path4.join(baseDir, outDir, `${srcPrefix}${ext}`));
+      candidates.push(path5.join(baseDir, outDir, `${srcPrefix}${ext}`));
     }
   }
   for (const ext of extensions) {
-    candidates.push(path4.join(baseDir, `${withoutExt}${ext}`));
+    candidates.push(path5.join(baseDir, `${withoutExt}${ext}`));
   }
   const workspaceMatch = baseDir.match(/^(.+\/packages\/[^/]+)$/);
   if (workspaceMatch) {
     const pkgRoot = workspaceMatch[1];
     for (const ext of extensions) {
-      candidates.push(path4.join(pkgRoot, "dist", `${srcPrefix}${ext}`));
+      candidates.push(path5.join(pkgRoot, "dist", `${srcPrefix}${ext}`));
     }
   }
   for (const candidate of candidates) {
-    if (fs4.existsSync(candidate)) {
+    if (fs5.existsSync(candidate)) {
       return candidate;
     }
   }
@@ -5343,7 +5133,7 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
     schemas: new Map,
     errors: []
   };
-  if (!fs4.existsSync(compiledJsPath)) {
+  if (!fs5.existsSync(compiledJsPath)) {
     result.errors.push(`Compiled JS not found: ${compiledJsPath}`);
     return result;
   }
@@ -5425,8 +5215,8 @@ async function extractStandardSchemasFromProject(entryFile, baseDir, options = {
 }
 
 // src/builder/external-resolver.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import picomatch from "picomatch";
 import ts14 from "typescript";
 function matchesExternalPattern(packageName, include, exclude) {
@@ -5460,20 +5250,20 @@ function findPackageJson(resolvedPath, packageName) {
   const isScoped = packageName.startsWith("@");
   const packageParts = isScoped ? packageName.split("/").slice(0, 2) : [packageName.split("/")[0]];
   const packageDir = packageParts.join("/");
-  let dir = path5.dirname(resolvedPath);
+  let dir = path6.dirname(resolvedPath);
   const maxDepth = 10;
   for (let i = 0;i < maxDepth; i++) {
     if (dir.endsWith(`node_modules/${packageDir}`)) {
-      const pkgPath = path5.join(dir, "package.json");
-      if (fs5.existsSync(pkgPath)) {
+      const pkgPath = path6.join(dir, "package.json");
+      if (fs6.existsSync(pkgPath)) {
         try {
-          return JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+          return JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
         } catch {
           return;
         }
       }
     }
-    const parent = path5.dirname(dir);
+    const parent = path6.dirname(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -5619,72 +5409,149 @@ function mergeRuntimeSchemas(staticExports, runtimeSchemas) {
   return { merged, exports };
 }
 
-// src/builder/spec-builder.ts
-var typeDefinitionCache = null;
-function getTypeDefinitionCache() {
-  if (!typeDefinitionCache) {
-    typeDefinitionCache = new Map;
+// src/builder/type-cache.ts
+import ts15 from "typescript";
+
+// src/utils/cache-manager.ts
+class CacheManager {
+  cache;
+  maxSize;
+  ttl;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 1000;
+    this.ttl = options.ttl;
+    this.cache = new Map;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry)
+      return;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
   }
-  return typeDefinitionCache;
-}
-var internalTagCache = null;
-function getInternalTagCache() {
-  if (!internalTagCache) {
-    internalTagCache = new Map;
+  has(key) {
+    const entry = this.cache.get(key);
+    if (!entry)
+      return false;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
   }
-  return internalTagCache;
-}
-function clearTypeDefinitionCache() {
-  typeDefinitionCache = null;
-  internalTagCache = null;
-}
-var YIELD_BATCH_SIZE = 5;
-function computeDegradedStats(exports) {
-  let exportsWithoutDescription = 0;
-  let paramsWithoutDocs = 0;
-  let missingExamples = 0;
-  for (const exp of exports) {
-    if (!exp.description)
-      exportsWithoutDescription++;
-    if (!exp.examples || exp.examples.length === 0)
-      missingExamples++;
-    const signatures = exp.signatures;
-    if (signatures) {
-      for (const sig of signatures) {
-        for (const param of sig.parameters ?? []) {
-          if (!param.description)
-            paramsWithoutDocs++;
-        }
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
       }
     }
+    const entry = {
+      value,
+      ...this.ttl ? { expiresAt: Date.now() + this.ttl } : {}
+    };
+    this.cache.set(key, entry);
   }
-  return { exportsWithoutDescription, paramsWithoutDocs, missingExamples };
-}
-function buildVerificationSummary(discoveredCount, extractedCount, tracker) {
-  const skippedDetails = [];
-  const failedDetails = [];
-  for (const entry of tracker.values()) {
-    if (entry.status === "skipped" && entry.skipReason) {
-      skippedDetails.push({ name: entry.name, reason: entry.skipReason });
-    } else if (entry.status === "failed" && entry.error) {
-      failedDetails.push({ name: entry.name, error: entry.error });
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  get size() {
+    return this.cache.size;
+  }
+  keys() {
+    return this.cache.keys();
+  }
+  values() {
+    const result = [];
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.cache.delete(key);
+        continue;
+      }
+      result.push(entry.value);
     }
+    return result;
   }
-  const skipped = skippedDetails.length;
-  const failed = failedDetails.length;
-  const delta = discoveredCount - extractedCount - skipped;
-  return {
-    discovered: discoveredCount,
-    extracted: extractedCount,
-    skipped,
-    failed,
-    delta,
-    details: {
-      skipped: skippedDetails,
-      failed: failedDetails
+}
+
+// src/builder/type-cache.ts
+var typeDefinitionCache = new CacheManager({ maxSize: 1000 });
+var internalTagCache = new CacheManager({ maxSize: 1000 });
+var regexCache = new CacheManager({ maxSize: 100 });
+function clearTypeDefinitionCache() {
+  typeDefinitionCache.clear();
+  internalTagCache.clear();
+  regexCache.clear();
+}
+function getRegexCache() {
+  return regexCache;
+}
+function findTypeDefinition(typeName, program, sourceFile) {
+  if (typeDefinitionCache.has(typeName)) {
+    return typeDefinitionCache.get(typeName);
+  }
+  const checker = program.getTypeChecker();
+  const findInNode = (node) => {
+    if ((ts15.isInterfaceDeclaration(node) || ts15.isTypeAliasDeclaration(node) || ts15.isClassDeclaration(node) || ts15.isEnumDeclaration(node)) && node.name?.text === typeName) {
+      const sf = node.getSourceFile();
+      return sf.fileName;
     }
+    return ts15.forEachChild(node, findInNode);
   };
+  const entryResult = findInNode(sourceFile);
+  if (entryResult) {
+    typeDefinitionCache.set(typeName, entryResult);
+    return entryResult;
+  }
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
+      const result = findInNode(sf);
+      if (result) {
+        typeDefinitionCache.set(typeName, result);
+        return result;
+      }
+    }
+  }
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
+  if (symbol?.declarations?.[0]) {
+    const result = symbol.declarations[0].getSourceFile().fileName;
+    typeDefinitionCache.set(typeName, result);
+    return result;
+  }
+  typeDefinitionCache.set(typeName, undefined);
+  return;
+}
+function hasInternalTag(typeName, program, sourceFile) {
+  const cached = internalTagCache.get(typeName);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const checker = program.getTypeChecker();
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
+  if (!symbol) {
+    internalTagCache.set(typeName, false);
+    return false;
+  }
+  const jsTags = symbol.getJsDocTags();
+  const isInternal = jsTags.some((tag) => tag.name === "internal");
+  internalTagCache.set(typeName, isInternal);
+  return isInternal;
 }
+
+// src/builder/verification.ts
+import * as path7 from "node:path";
 var BUILTIN_TYPES2 = new Set([
   "Array",
   "ArrayBuffer",
@@ -5743,19 +5610,39 @@ var BUILTIN_TYPES2 = new Set([
   "InstanceType",
   "ThisType"
 ]);
-function matchesPattern(name, pattern) {
-  if (!pattern.includes("*"))
-    return name === pattern;
-  const regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
-  return regex.test(name);
-}
-function shouldIncludeExport(name, only, ignore) {
-  if (ignore?.some((p) => matchesPattern(name, p)))
-    return false;
-  if (only && only.length > 0) {
-    return only.some((p) => matchesPattern(name, p));
+function buildVerificationSummary(discoveredCount, extractedCount, tracker) {
+  const skippedDetails = [];
+  const failedDetails = [];
+  for (const entry of tracker.values()) {
+    if (entry.status === "skipped" && entry.skipReason) {
+      skippedDetails.push({ name: entry.name, reason: entry.skipReason });
+    } else if (entry.status === "failed" && entry.error) {
+      failedDetails.push({ name: entry.name, error: entry.error });
+    }
   }
-  return true;
+  const skipped = skippedDetails.length;
+  const failed = failedDetails.length;
+  const delta = discoveredCount - extractedCount - skipped;
+  return {
+    discovered: discoveredCount,
+    extracted: extractedCount,
+    skipped,
+    failed,
+    delta,
+    details: {
+      skipped: skippedDetails,
+      failed: failedDetails
+    }
+  };
+}
+function isExternalType2(definedIn, baseDir) {
+  if (!definedIn)
+    return true;
+  if (definedIn.includes("node_modules"))
+    return true;
+  const normalizedDefined = path7.resolve(definedIn);
+  const normalizedBase = path7.resolve(baseDir);
+  return !normalizedDefined.startsWith(normalizedBase);
 }
 function shouldSkipDanglingRef(name) {
   if (name.startsWith("__"))
@@ -5768,255 +5655,6 @@ function shouldSkipDanglingRef(name) {
     return true;
   return false;
 }
-async function extract(options) {
-  clearTypeDefinitionCache();
-  const {
-    entryFile,
-    baseDir,
-    content,
-    maxTypeDepth,
-    maxExternalTypeDepth,
-    resolveExternalTypes,
-    includeSchema,
-    only,
-    ignore,
-    onProgress,
-    isDtsSource,
-    includePrivate
-  } = options;
-  const diagnostics = [];
-  let exports = [];
-  const result = createProgram({ entryFile, baseDir, content });
-  const { program, sourceFile } = result;
-  if (!sourceFile) {
-    return {
-      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-      diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
-    };
-  }
-  const typeChecker = program.getTypeChecker();
-  const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
-  if (!moduleSymbol) {
-    return {
-      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-      diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
-    };
-  }
-  const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
-  const exportedIds = new Set;
-  for (const symbol of exportedSymbols) {
-    exportedIds.add(symbol.getName());
-  }
-  const exportTracker = new Map;
-  for (const symbol of exportedSymbols) {
-    const name = symbol.getName();
-    const included = shouldIncludeExport(name, only, ignore);
-    exportTracker.set(name, {
-      name,
-      discovered: true,
-      status: included ? "pending" : "skipped",
-      ...included ? {} : { skipReason: "filtered" }
-    });
-  }
-  const ctx = createContext(program, sourceFile, {
-    maxTypeDepth,
-    maxExternalTypeDepth,
-    resolveExternalTypes,
-    includePrivate
-  });
-  ctx.exportedIds = exportedIds;
-  const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
-  const total = filteredSymbols.length;
-  for (let i = 0;i < filteredSymbols.length; i++) {
-    const symbol = filteredSymbols[i];
-    const exportName = symbol.getName();
-    const tracker = exportTracker.get(exportName);
-    onProgress?.(i + 1, total, exportName);
-    if (i > 0 && i % YIELD_BATCH_SIZE === 0) {
-      await new Promise((r) => setImmediate(r));
-    }
-    try {
-      const { declaration, targetSymbol, isTypeOnly } = resolveExportTarget2(symbol, typeChecker);
-      if (!declaration) {
-        let externalPackage;
-        const allDecls = [
-          ...targetSymbol.declarations ?? [],
-          ...symbol.declarations ?? []
-        ];
-        for (const decl of allDecls) {
-          const sf = decl.getSourceFile();
-          if (sf?.fileName.includes("node_modules")) {
-            const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
-            if (match) {
-              externalPackage = match[1];
-              break;
-            }
-          }
-          if (ts15.isExportSpecifier(decl)) {
-            const exportDecl = decl.parent?.parent;
-            if (exportDecl && ts15.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
-              const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
-              if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
-                externalPackage = moduleText;
-                break;
-              }
-            }
-          }
-        }
-        if (externalPackage) {
-          const shouldResolve = matchesExternalPattern(externalPackage, options.externals?.include, options.externals?.exclude);
-          if (shouldResolve) {
-            const resolvedModule = resolveExternalModule(externalPackage, sourceFile.fileName, program.getCompilerOptions());
-            if (resolvedModule) {
-              const visitedExternals = new Set;
-              const extractedExport = extractExternalExport(exportName, resolvedModule, program, ctx, visitedExternals);
-              if (extractedExport) {
-                exports.push(extractedExport);
-                tracker.status = "success";
-                tracker.kind = extractedExport.kind;
-                continue;
-              }
-            }
-          }
-          const externalExport = {
-            id: exportName,
-            name: exportName,
-            kind: "external",
-            source: {
-              package: externalPackage
-            }
-          };
-          exports.push(externalExport);
-          tracker.status = "success";
-          tracker.kind = "external";
-        } else {
-          tracker.status = "skipped";
-          tracker.skipReason = "no-declaration";
-        }
-        continue;
-      }
-      const exp = serializeDeclaration2(declaration, symbol, targetSymbol, exportName, ctx, isTypeOnly);
-      if (exp) {
-        exports.push(exp);
-        tracker.status = "success";
-        tracker.kind = exp.kind;
-      } else {
-        tracker.status = "skipped";
-        tracker.skipReason = "internal";
-      }
-    } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      tracker.status = "failed";
-      tracker.error = errorMsg;
-      diagnostics.push({
-        message: `Failed to serialize '${exportName}': ${errorMsg}`,
-        severity: "warning",
-        code: "SERIALIZATION_FAILED"
-      });
-    }
-  }
-  const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
-  const meta = await getPackageMeta(entryFile, baseDir);
-  const types = ctx.typeRegistry.getAll();
-  const projectBaseDir = baseDir ?? path6.dirname(entryFile);
-  const definedTypes = new Set(types.map((t) => t.id));
-  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir, definedTypes);
-  for (const forgotten of forgottenExports) {
-    const refSummary = forgotten.referencedBy.slice(0, 3).map((r) => `${r.exportName} (${r.location})`).join(", ");
-    const moreRefs = forgotten.referencedBy.length > 3 ? ` +${forgotten.referencedBy.length - 3} more` : "";
-    if (forgotten.isExternal) {
-      diagnostics.push({
-        message: `External type '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
-        severity: "info",
-        code: "EXTERNAL_TYPE_REF",
-        suggestion: forgotten.definedIn ? `Type is from: ${forgotten.definedIn}` : "Type is from an external package"
-      });
-    } else {
-      diagnostics.push({
-        message: `Forgotten export: '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
-        severity: "warning",
-        code: "FORGOTTEN_EXPORT",
-        suggestion: forgotten.fix ?? `Export this type from your public API`,
-        location: forgotten.definedIn ? { file: forgotten.definedIn } : undefined
-      });
-    }
-  }
-  const externalTypes = types.filter((t) => t.kind === "external");
-  if (externalTypes.length > 0) {
-    diagnostics.push({
-      message: `${externalTypes.length} external type(s) from dependencies: ${externalTypes.slice(0, 5).map((t) => t.id).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
-      severity: "info",
-      code: "EXTERNAL_TYPES"
-    });
-  }
-  let runtimeMetadata;
-  if (options.schemaExtraction === "hybrid") {
-    const projectBaseDir2 = baseDir || path6.dirname(entryFile);
-    const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
-      target: options.schemaTarget || "draft-2020-12",
-      timeout: 15000
-    });
-    if (runtimeResult.schemas.size > 0) {
-      const mergeResult = mergeRuntimeSchemas(exports, runtimeResult.schemas);
-      exports = mergeResult.exports;
-      const method = runtimeResult.info?.method === "direct-ts" ? `direct-ts (${runtimeResult.info.runtime})` : "compiled";
-      runtimeMetadata = {
-        extracted: runtimeResult.schemas.size,
-        merged: mergeResult.merged,
-        vendors: [...new Set([...runtimeResult.schemas.values()].map((s) => s.vendor))],
-        errors: runtimeResult.errors,
-        method
-      };
-    }
-    for (const error of runtimeResult.errors) {
-      diagnostics.push({
-        message: `Runtime schema extraction: ${error}`,
-        severity: "warning",
-        code: "RUNTIME_SCHEMA_ERROR"
-      });
-    }
-  }
-  const normalizedExports = exports.map((exp) => normalizeExport(exp, { dialect: "draft-2020-12" }));
-  const normalizedTypes = types.map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
-  const spec = {
-    ...includeSchema ? { $schema: SCHEMA_URL } : {},
-    openpkg: SCHEMA_VERSION,
-    meta,
-    exports: normalizedExports,
-    types: normalizedTypes,
-    generation: {
-      generator: "@openpkg-ts/sdk",
-      timestamp: new Date().toISOString(),
-      mode: isDtsSource ? "declaration-only" : "source",
-      ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
-      ...isDtsSource && {
-        limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
-      },
-      ...verification.details.skipped.length > 0 && {
-        skipped: verification.details.skipped
-      }
-    }
-  };
-  const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
-  const degradedMode = isDtsSource ? { reason: "dts-source", stats: computeDegradedStats(normalizedExports) } : undefined;
-  if (verification.failed > 0) {
-    const failedNames = verification.details.failed.map((f) => f.name).join(", ");
-    diagnostics.push({
-      message: `Export verification: ${verification.failed} export(s) failed: ${failedNames}`,
-      severity: "warning",
-      code: "EXPORT_VERIFICATION_FAILED",
-      suggestion: "Check serialization errors for these exports"
-    });
-  }
-  return {
-    spec,
-    diagnostics,
-    verification,
-    ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {},
-    ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
-    ...degradedMode ? { degradedMode } : {}
-  };
-}
 function collectAllRefsWithContext(obj, refs, state) {
   if (obj === null || obj === undefined)
     return;
@@ -6060,68 +5698,6 @@ function collectAllRefsWithContext(obj, refs, state) {
     }
   }
 }
-function findTypeDefinition(typeName, program, sourceFile) {
-  const cache = getTypeDefinitionCache();
-  if (cache.has(typeName)) {
-    return cache.get(typeName);
-  }
-  const checker = program.getTypeChecker();
-  const findInNode = (node) => {
-    if ((ts15.isInterfaceDeclaration(node) || ts15.isTypeAliasDeclaration(node) || ts15.isClassDeclaration(node) || ts15.isEnumDeclaration(node)) && node.name?.text === typeName) {
-      const sf = node.getSourceFile();
-      return sf.fileName;
-    }
-    return ts15.forEachChild(node, findInNode);
-  };
-  const entryResult = findInNode(sourceFile);
-  if (entryResult) {
-    cache.set(typeName, entryResult);
-    return entryResult;
-  }
-  for (const sf of program.getSourceFiles()) {
-    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
-      const result = findInNode(sf);
-      if (result) {
-        cache.set(typeName, result);
-        return result;
-      }
-    }
-  }
-  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
-  if (symbol?.declarations?.[0]) {
-    const result = symbol.declarations[0].getSourceFile().fileName;
-    cache.set(typeName, result);
-    return result;
-  }
-  cache.set(typeName, undefined);
-  return;
-}
-function isExternalType2(definedIn, baseDir) {
-  if (!definedIn)
-    return true;
-  if (definedIn.includes("node_modules"))
-    return true;
-  const normalizedDefined = path6.resolve(definedIn);
-  const normalizedBase = path6.resolve(baseDir);
-  return !normalizedDefined.startsWith(normalizedBase);
-}
-function hasInternalTag(typeName, program, sourceFile) {
-  const cache = getInternalTagCache();
-  const cached = cache.get(typeName);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const checker = program.getTypeChecker();
-  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
-  if (!symbol) {
-    cache.set(typeName, false);
-    return false;
-  }
-  const jsTags = symbol.getJsDocTags();
-  const isInternal = jsTags.some((tag) => tag.name === "internal");
-  cache.set(typeName, isInternal);
-  return isInternal;
-}
 function collectForgottenExports(exports, types, program, sourceFile, exportedIds, baseDir, definedTypes) {
   const referencedTypes = new Map;
   for (const exp of exports) {
@@ -6162,29 +5738,322 @@ function collectForgottenExports(exports, types, program, sourceFile, exportedId
   }
   return forgottenExports;
 }
+
+// src/builder/spec-builder.ts
+var YIELD_BATCH_SIZE = 5;
+function computeDegradedStats(exports) {
+  let exportsWithoutDescription = 0;
+  let paramsWithoutDocs = 0;
+  let missingExamples = 0;
+  for (const exp of exports) {
+    if (!exp.description)
+      exportsWithoutDescription++;
+    if (!exp.examples || exp.examples.length === 0)
+      missingExamples++;
+    const signatures = exp.signatures;
+    if (signatures) {
+      for (const sig of signatures) {
+        for (const param of sig.parameters ?? []) {
+          if (!param.description)
+            paramsWithoutDocs++;
+        }
+      }
+    }
+  }
+  return { exportsWithoutDescription, paramsWithoutDocs, missingExamples };
+}
+function matchesPattern(name, pattern) {
+  if (!pattern.includes("*"))
+    return name === pattern;
+  const regexCache2 = getRegexCache();
+  let regex = regexCache2.get(pattern);
+  if (!regex) {
+    regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
+    regexCache2.set(pattern, regex);
+  }
+  return regex.test(name);
+}
+function shouldIncludeExport(name, only, ignore) {
+  if (ignore?.some((p) => matchesPattern(name, p)))
+    return false;
+  if (only && only.length > 0) {
+    return only.some((p) => matchesPattern(name, p));
+  }
+  return true;
+}
+async function extract(options) {
+  clearTypeDefinitionCache();
+  try {
+    const {
+      entryFile,
+      baseDir,
+      content,
+      maxTypeDepth,
+      maxExternalTypeDepth,
+      resolveExternalTypes,
+      includeSchema,
+      only,
+      ignore,
+      onProgress,
+      isDtsSource,
+      includePrivate
+    } = options;
+    const diagnostics = [];
+    let exports = [];
+    const result = createProgram({ entryFile, baseDir, content });
+    const { program, sourceFile } = result;
+    if (!sourceFile) {
+      return {
+        spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
+        diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
+      };
+    }
+    const typeChecker = program.getTypeChecker();
+    const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) {
+      return {
+        spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
+        diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
+      };
+    }
+    const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
+    const exportedIds = new Set;
+    for (const symbol of exportedSymbols) {
+      exportedIds.add(symbol.getName());
+    }
+    const exportTracker = new Map;
+    for (const symbol of exportedSymbols) {
+      const name = symbol.getName();
+      const included = shouldIncludeExport(name, only, ignore);
+      exportTracker.set(name, {
+        name,
+        discovered: true,
+        status: included ? "pending" : "skipped",
+        ...included ? {} : { skipReason: "filtered" }
+      });
+    }
+    const ctx = createContext(program, sourceFile, {
+      maxTypeDepth,
+      maxExternalTypeDepth,
+      resolveExternalTypes,
+      includePrivate
+    });
+    ctx.exportedIds = exportedIds;
+    const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
+    const total = filteredSymbols.length;
+    for (let i = 0;i < filteredSymbols.length; i++) {
+      const symbol = filteredSymbols[i];
+      const exportName = symbol.getName();
+      const tracker = exportTracker.get(exportName);
+      onProgress?.(i + 1, total, exportName);
+      if (i > 0 && i % YIELD_BATCH_SIZE === 0) {
+        await new Promise((r) => setImmediate(r));
+      }
+      try {
+        const { declaration, targetSymbol, isTypeOnly } = resolveExportTarget2(symbol, typeChecker);
+        if (!declaration) {
+          let externalPackage;
+          const allDecls = [...targetSymbol.declarations ?? [], ...symbol.declarations ?? []];
+          for (const decl of allDecls) {
+            const sf = decl.getSourceFile();
+            if (sf?.fileName.includes("node_modules")) {
+              const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+              if (match) {
+                externalPackage = match[1];
+                break;
+              }
+            }
+            if (ts16.isExportSpecifier(decl)) {
+              const exportDecl = decl.parent?.parent;
+              if (exportDecl && ts16.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
+                const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
+                if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
+                  externalPackage = moduleText;
+                  break;
+                }
+              }
+            }
+          }
+          if (externalPackage) {
+            const shouldResolve = matchesExternalPattern(externalPackage, options.externals?.include, options.externals?.exclude);
+            if (shouldResolve) {
+              const resolvedModule = resolveExternalModule(externalPackage, sourceFile.fileName, program.getCompilerOptions());
+              if (resolvedModule) {
+                const visitedExternals = new Set;
+                const extractedExport = extractExternalExport(exportName, resolvedModule, program, ctx, visitedExternals);
+                if (extractedExport) {
+                  exports.push(extractedExport);
+                  tracker.status = "success";
+                  tracker.kind = extractedExport.kind;
+                  continue;
+                }
+              }
+            }
+            const externalExport = {
+              id: exportName,
+              name: exportName,
+              kind: "external",
+              source: {
+                package: externalPackage
+              }
+            };
+            exports.push(externalExport);
+            tracker.status = "success";
+            tracker.kind = "external";
+          } else {
+            tracker.status = "skipped";
+            tracker.skipReason = "no-declaration";
+          }
+          continue;
+        }
+        const exp = serializeDeclaration2(declaration, symbol, targetSymbol, exportName, ctx, isTypeOnly);
+        if (exp) {
+          exports.push(exp);
+          tracker.status = "success";
+          tracker.kind = exp.kind;
+        } else {
+          tracker.status = "skipped";
+          tracker.skipReason = "internal";
+        }
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        tracker.status = "failed";
+        tracker.error = errorMsg;
+        diagnostics.push({
+          message: `Failed to serialize '${exportName}': ${errorMsg}`,
+          severity: "warning",
+          code: "SERIALIZATION_FAILED"
+        });
+      }
+    }
+    const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
+    const meta = await getPackageMeta(entryFile, baseDir);
+    const types = ctx.typeRegistry.getAll();
+    const projectBaseDir = baseDir ?? path8.dirname(entryFile);
+    const definedTypes = new Set(types.map((t) => t.id));
+    const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir, definedTypes);
+    for (const forgotten of forgottenExports) {
+      const refSummary = forgotten.referencedBy.slice(0, 3).map((r) => `${r.exportName} (${r.location})`).join(", ");
+      const moreRefs = forgotten.referencedBy.length > 3 ? ` +${forgotten.referencedBy.length - 3} more` : "";
+      if (forgotten.isExternal) {
+        diagnostics.push({
+          message: `External type '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+          severity: "info",
+          code: "EXTERNAL_TYPE_REF",
+          suggestion: forgotten.definedIn ? `Type is from: ${forgotten.definedIn}` : "Type is from an external package"
+        });
+      } else {
+        diagnostics.push({
+          message: `Forgotten export: '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+          severity: "warning",
+          code: "FORGOTTEN_EXPORT",
+          suggestion: forgotten.fix ?? `Export this type from your public API`,
+          location: forgotten.definedIn ? { file: forgotten.definedIn } : undefined
+        });
+      }
+    }
+    const externalTypes = types.filter((t) => t.kind === "external");
+    if (externalTypes.length > 0) {
+      diagnostics.push({
+        message: `${externalTypes.length} external type(s) from dependencies: ${externalTypes.slice(0, 5).map((t) => t.id).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
+        severity: "info",
+        code: "EXTERNAL_TYPES"
+      });
+    }
+    let runtimeMetadata;
+    if (options.schemaExtraction === "hybrid") {
+      const projectBaseDir2 = baseDir || path8.dirname(entryFile);
+      const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
+        target: options.schemaTarget || "draft-2020-12",
+        timeout: 15000
+      });
+      if (runtimeResult.schemas.size > 0) {
+        const mergeResult = mergeRuntimeSchemas(exports, runtimeResult.schemas);
+        exports = mergeResult.exports;
+        const method = runtimeResult.info?.method === "direct-ts" ? `direct-ts (${runtimeResult.info.runtime})` : "compiled";
+        runtimeMetadata = {
+          extracted: runtimeResult.schemas.size,
+          merged: mergeResult.merged,
+          vendors: [...new Set([...runtimeResult.schemas.values()].map((s) => s.vendor))],
+          errors: runtimeResult.errors,
+          method
+        };
+      }
+      for (const error of runtimeResult.errors) {
+        diagnostics.push({
+          message: `Runtime schema extraction: ${error}`,
+          severity: "warning",
+          code: "RUNTIME_SCHEMA_ERROR"
+        });
+      }
+    }
+    const normalizedExports = exports.map((exp) => normalizeExport(exp, { dialect: "draft-2020-12" }));
+    const normalizedTypes = types.map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
+    const spec = {
+      ...includeSchema ? { $schema: SCHEMA_URL } : {},
+      openpkg: SCHEMA_VERSION,
+      meta,
+      exports: normalizedExports,
+      types: normalizedTypes,
+      generation: {
+        generator: "@openpkg-ts/sdk",
+        timestamp: new Date().toISOString(),
+        mode: isDtsSource ? "declaration-only" : "source",
+        ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
+        ...isDtsSource && {
+          limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
+        },
+        ...verification.details.skipped.length > 0 && {
+          skipped: verification.details.skipped
+        }
+      }
+    };
+    const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
+    const degradedMode = isDtsSource ? { reason: "dts-source", stats: computeDegradedStats(normalizedExports) } : undefined;
+    if (verification.failed > 0) {
+      const failedNames = verification.details.failed.map((f) => f.name).join(", ");
+      diagnostics.push({
+        message: `Export verification: ${verification.failed} export(s) failed: ${failedNames}`,
+        severity: "warning",
+        code: "EXPORT_VERIFICATION_FAILED",
+        suggestion: "Check serialization errors for these exports"
+      });
+    }
+    return {
+      spec,
+      diagnostics,
+      verification,
+      ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {},
+      ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
+      ...degradedMode ? { degradedMode } : {}
+    };
+  } finally {
+    clearTypeDefinitionCache();
+  }
+}
 function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportName, ctx, isTypeOnly = false) {
   let result = null;
-  if (ts15.isFunctionDeclaration(declaration)) {
+  if (ts16.isFunctionDeclaration(declaration)) {
     result = serializeFunctionExport(declaration, ctx);
-  } else if (ts15.isClassDeclaration(declaration)) {
+  } else if (ts16.isClassDeclaration(declaration)) {
     result = serializeClass(declaration, ctx);
-  } else if (ts15.isInterfaceDeclaration(declaration)) {
+  } else if (ts16.isInterfaceDeclaration(declaration)) {
     result = serializeInterface(declaration, ctx);
-  } else if (ts15.isTypeAliasDeclaration(declaration)) {
+  } else if (ts16.isTypeAliasDeclaration(declaration)) {
     result = serializeTypeAlias(declaration, ctx);
-  } else if (ts15.isEnumDeclaration(declaration)) {
+  } else if (ts16.isEnumDeclaration(declaration)) {
     result = serializeEnum(declaration, ctx);
-  } else if (ts15.isVariableDeclaration(declaration)) {
+  } else if (ts16.isVariableDeclaration(declaration)) {
     const varStatement = declaration.parent?.parent;
-    if (varStatement && ts15.isVariableStatement(varStatement)) {
-      if (declaration.initializer && ts15.isArrowFunction(declaration.initializer)) {
-        const varName = ts15.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
+    if (varStatement && ts16.isVariableStatement(varStatement)) {
+      if (declaration.initializer && ts16.isArrowFunction(declaration.initializer)) {
+        const varName = ts16.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
         result = serializeFunctionExport(declaration.initializer, ctx, varName);
       } else {
         result = serializeVariable(declaration, varStatement, ctx);
       }
     }
-  } else if (ts15.isNamespaceExport(declaration) || ts15.isModuleDeclaration(declaration)) {
+  } else if (ts16.isNamespaceExport(declaration) || ts16.isModuleDeclaration(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -6197,7 +6066,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts15.isNamespaceImport(declaration)) {
+  } else if (ts16.isNamespaceImport(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -6210,7 +6079,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts15.isSourceFile(declaration)) {
+  } else if (ts16.isSourceFile(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -6240,7 +6109,7 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
   const members = [];
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts15.SymbolFlags.Alias) {
+  if (symbol.flags & ts16.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
@@ -6267,31 +6136,31 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
 function serializeNamespaceMember(symbol, memberName, ctx) {
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts15.SymbolFlags.Alias) {
+  if (symbol.flags & ts16.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
     }
   }
   const declarations = targetSymbol.declarations ?? [];
-  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts15.SyntaxKind.ExportSpecifier) || declarations[0];
+  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts16.SyntaxKind.ExportSpecifier) || declarations[0];
   if (!declaration)
     return null;
   const type = checker.getTypeAtLocation(declaration);
   const callSignatures = type.getCallSignatures();
   const deprecated = isSymbolDeprecated(targetSymbol);
   let kind = "variable";
-  if (ts15.isFunctionDeclaration(declaration) || ts15.isFunctionExpression(declaration)) {
+  if (ts16.isFunctionDeclaration(declaration) || ts16.isFunctionExpression(declaration)) {
     kind = "function";
-  } else if (ts15.isClassDeclaration(declaration)) {
+  } else if (ts16.isClassDeclaration(declaration)) {
     kind = "class";
-  } else if (ts15.isInterfaceDeclaration(declaration)) {
+  } else if (ts16.isInterfaceDeclaration(declaration)) {
     kind = "interface";
-  } else if (ts15.isTypeAliasDeclaration(declaration)) {
+  } else if (ts16.isTypeAliasDeclaration(declaration)) {
     kind = "type";
-  } else if (ts15.isEnumDeclaration(declaration)) {
+  } else if (ts16.isEnumDeclaration(declaration)) {
     kind = "enum";
-  } else if (ts15.isVariableDeclaration(declaration)) {
+  } else if (ts16.isVariableDeclaration(declaration)) {
     if (callSignatures.length > 0) {
       kind = "function";
     }
@@ -6338,11 +6207,11 @@ function getJSDocFromExportSymbol(symbol) {
   const examples = [];
   const decl = symbol.declarations?.[0];
   if (decl) {
-    const exportDecl = ts15.isNamespaceExport(decl) ? decl.parent : decl;
-    if (exportDecl && ts15.isExportDeclaration(exportDecl)) {
-      const jsDocs = ts15.getJSDocCommentsAndTags(exportDecl);
+    const exportDecl = ts16.isNamespaceExport(decl) ? decl.parent : decl;
+    if (exportDecl && ts16.isExportDeclaration(exportDecl)) {
+      const jsDocs = ts16.getJSDocCommentsAndTags(exportDecl);
       for (const doc of jsDocs) {
-        if (ts15.isJSDoc(doc) && doc.comment) {
+        if (ts16.isJSDoc(doc) && doc.comment) {
           const commentText = typeof doc.comment === "string" ? doc.comment : doc.comment.map((c) => ("text" in c) ? c.text : "").join("");
           if (commentText) {
             return {
@@ -6404,7 +6273,7 @@ function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   return {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
-    meta: { name: path6.basename(entryFile, path6.extname(entryFile)) },
+    meta: { name: path8.basename(entryFile, path8.extname(entryFile)) },
     exports: [],
     generation: {
       generator: "@openpkg-ts/sdk",
@@ -6417,19 +6286,19 @@ function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   };
 }
 async function getPackageMeta(entryFile, baseDir) {
-  const searchDir = baseDir ?? path6.dirname(entryFile);
-  const pkgPath = path6.join(searchDir, "package.json");
+  const searchDir = baseDir ?? path8.dirname(entryFile);
+  const pkgPath = path8.join(searchDir, "package.json");
   try {
-    if (fs6.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
+    if (fs7.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs7.readFileSync(pkgPath, "utf-8"));
       return {
-        name: pkg.name ?? path6.basename(searchDir),
+        name: pkg.name ?? path8.basename(searchDir),
         version: pkg.version,
         description: pkg.description
       };
     }
   } catch {}
-  return { name: path6.basename(searchDir) };
+  return { name: path8.basename(searchDir) };
 }
 
 // src/primitives/spec.ts
@@ -6455,6 +6324,8 @@ export {
   typeboxAdapter,
   toSearchIndexJSON,
   toSearchIndex,
+  toReactString,
+  toReact,
   toPagefindRecords,
   toNavigation,
   toMarkdown,
@@ -6479,6 +6350,7 @@ export {
   registerReferencedTypes,
   registerAdapter,
   recommendSemverBump,
+  query,
   normalizeType,
   normalizeSchema,
   normalizeMembers,
@@ -6547,6 +6419,8 @@ export {
   arktypeAdapter,
   analyzeSpec,
   TypeRegistry,
+  QueryBuilder,
+  CacheManager,
   CONFIG_FILENAME,
   BUILTIN_TYPE_SCHEMAS,
   ARRAY_PROTOTYPE_METHODS