Data Layer (Footprints)

function searchFootprints(query: string, page = 1, limit = 20): FootprintSearchResult;
function getFootprintById(id: string): Footprint | undefined;
function getFootprintsByLibrary(libraryId: string, page = 1, limit = 60): FootprintSearchResult;
function getAllFootprintLibraries(): FootprintLibrary[];               // { id, name, footprintCount }
function getTopFootprintLibraries(limit = 12): FootprintLibrary[];     // sorted by count desc
function getFootprintStats(): { totalFootprints: number; totalLibraries: number };

// catalog
searchFootprints(query, { page?, limit? }): Promise<FootprintSearchResult>;
fetchFootprintById(id): Promise<Footprint | null>;
// generation / persistence (auth)
generateFootprint(description, { package_type? }): Promise<{ data: GenerateFootprintResult; status }>;
saveGeneratedComponent(payload: SaveComponentPayload): Promise<SaveResult>;   // type: "footprint"
// contribution (auth)
validateFootprint(file): Promise<ValidationResult>;        // { valid, errors, warnings, footprintName, padCount }
submitContribution(data: ContributionData): Promise<SubmissionResponse>;
// user
fetchUserProfile(): Promise<UserProfile | null>;

interface Footprint {
  id: string; name: string; library: string; description: string; tags: string;
  padCount: number; pads: Array<{ number: string; type: string }>;
  model3d?: string | null; source?: "trace" | "cern";
}
interface FootprintLibrary { id: string; name: string; footprintCount: number; }
interface FootprintSearchResult {
  footprints: Footprint[]; total: number; page: number; limit: number; totalPages: number;
}
interface GenerateFootprintResult {
  success: boolean; footprintName: string; description?: string;
  kicadMod: string | null; padCount: number; pads: Array<{ number: string; type: string }>;
  traceJson?: object; source?: string; note?: string; error?: string;
}