Feature/v2/fuzzy tool search (#4482)

# Description of Changes

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [x] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [x] I have performed a self-review of my own code
- [x] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

frontend/src/components/tools/SearchResults.tsx

@@ -9,13 +9,22 @@ import NoToolsFound from './shared/NoToolsFound';
 import "./toolPicker/ToolPicker.css";
 
 interface SearchResultsProps {
-  filteredTools: [string, ToolRegistryEntry][];
+  filteredTools: Array<{ item: [string, ToolRegistryEntry]; matchedText?: string }>;
   onSelect: (id: string) => void;
+  searchQuery?: string;
 }
 
-const SearchResults: React.FC<SearchResultsProps> = ({ filteredTools, onSelect }) => {
+const SearchResults: React.FC<SearchResultsProps> = ({ filteredTools, onSelect, searchQuery }) => {
   const { t } = useTranslation();
-  const { searchGroups } = useToolSections(filteredTools);
+  const { searchGroups } = useToolSections(filteredTools, searchQuery);
+
+  // Create a map of matched text for quick lookup
+  const matchedTextMap = new Map<string, string>();
+  if (filteredTools && Array.isArray(filteredTools)) {
+    filteredTools.forEach(({ item: [id], matchedText }) => {
+      if (matchedText) matchedTextMap.set(id, matchedText);
+    });
+  }
 
   if (searchGroups.length === 0) {
     return <NoToolsFound />;
@@ -28,15 +37,27 @@ const SearchResults: React.FC<SearchResultsProps> = ({ filteredTools, onSelect }
         <Box key={group.subcategoryId}  w="100%">
           <SubcategoryHeader label={getSubcategoryLabel(t, group.subcategoryId)} />
           <Stack  gap="xs">
-            {group.tools.map(({ id, tool }) => (
-              <ToolButton
-                key={id}
-                id={id}
-                tool={tool}
-                isSelected={false}
-                onSelect={onSelect}
-              />
-            ))}
+            {group.tools.map(({ id, tool }) => {
+              const matchedText = matchedTextMap.get(id);
+              // Check if the match was from synonyms and show the actual synonym that matched
+              const isSynonymMatch = matchedText && tool.synonyms?.some(synonym => 
+                matchedText.toLowerCase().includes(synonym.toLowerCase())
+              );
+              const matchedSynonym = isSynonymMatch ? tool.synonyms?.find(synonym => 
+                matchedText.toLowerCase().includes(synonym.toLowerCase())
+              ) : undefined;
+              
+              return (
+                <ToolButton
+                  key={id}
+                  id={id}
+                  tool={tool}
+                  isSelected={false}
+                  onSelect={onSelect}
+                  matchedSynonym={matchedSynonym}
+                />
+              );
+            })}
           </Stack>
         </Box>
       ))}

frontend/src/components/tools/ToolPanel.tsx

@@ -72,6 +72,7 @@ export default function ToolPanel() {
               <SearchResults
                 filteredTools={filteredTools}
                 onSelect={handleToolSelect}
+                searchQuery={searchQuery}
               />
           </div>
         ) : leftPanelView === 'toolPicker' ? (

frontend/src/components/tools/ToolPicker.tsx

@@ -10,7 +10,7 @@ import { renderToolButtons } from "./shared/renderToolButtons";
 interface ToolPickerProps {
   selectedToolKey: string | null;
   onSelect: (id: string) => void;
-  filteredTools: [string, ToolRegistryEntry][];
+  filteredTools: Array<{ item: [string, ToolRegistryEntry]; matchedText?: string }>;
   isSearching?: boolean;
 }
 

frontend/src/components/tools/automate/ToolSelector.tsx

@@ -58,8 +58,13 @@ export default function ToolSelector({
     return registry;
   }, [baseFilteredTools]);
 
+  // Transform filteredTools to the expected format for useToolSections
+  const transformedFilteredTools = useMemo(() => {
+    return filteredTools.map(([id, tool]) => ({ item: [id, tool] as [string, ToolRegistryEntry] }));
+  }, [filteredTools]);
+
   // Use the same tool sections logic as the main ToolPicker
-  const { sections, searchGroups } = useToolSections(filteredTools);
+  const { sections, searchGroups } = useToolSections(transformedFilteredTools);
 
   // Determine what to display: search results or organized sections
   const isSearching = searchTerm.trim().length > 0;

frontend/src/components/tools/shared/renderToolButtons.tsx

@@ -13,23 +13,39 @@ export const renderToolButtons = (
   selectedToolKey: string | null,
   onSelect: (id: string) => void,
   showSubcategoryHeader: boolean = true,
-  disableNavigation: boolean = false
-) => (
-  <Box key={subcategory.subcategoryId} w="100%">
-    {showSubcategoryHeader && (
-      <SubcategoryHeader label={getSubcategoryLabel(t, subcategory.subcategoryId)} />
-    )}
-    <div>
-      {subcategory.tools.map(({ id, tool }) => (
-        <ToolButton
-          key={id}
-          id={id}
-          tool={tool}
-          isSelected={selectedToolKey === id}
-          onSelect={onSelect}
-          disableNavigation={disableNavigation}
-        />
-      ))}
-    </div>
-  </Box>
-);
+  disableNavigation: boolean = false,
+  searchResults?: Array<{ item: [string, any]; matchedText?: string }>
+) => {
+  // Create a map of matched text for quick lookup
+  const matchedTextMap = new Map<string, string>();
+  if (searchResults) {
+    searchResults.forEach(({ item: [id], matchedText }) => {
+      if (matchedText) matchedTextMap.set(id, matchedText);
+    });
+  }
+
+  return (
+    <Box key={subcategory.subcategoryId} w="100%">
+      {showSubcategoryHeader && (
+        <SubcategoryHeader label={getSubcategoryLabel(t, subcategory.subcategoryId)} />
+      )}
+      <div>
+        {subcategory.tools.map(({ id, tool }) => {
+          const matchedSynonym = matchedTextMap.get(id);
+          
+          return (
+            <ToolButton
+              key={id}
+              id={id}
+              tool={tool}
+              isSelected={selectedToolKey === id}
+              onSelect={onSelect}
+              disableNavigation={disableNavigation}
+              matchedSynonym={matchedSynonym}
+            />
+          );
+        })}
+      </div>
+    </Box>
+  );
+};

frontend/src/components/tools/toolPicker/ToolButton.tsx

@@ -13,9 +13,10 @@ interface ToolButtonProps {
   onSelect: (id: string) => void;
   rounded?: boolean;
   disableNavigation?: boolean;
+  matchedSynonym?: string;
 }
 
-const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect, disableNavigation = false }) => {
+const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect, disableNavigation = false, matchedSynonym }) => {
   const isUnavailable = !tool.component && !tool.link;
   const { getToolNavigation } = useToolNavigation();
 
@@ -40,13 +41,27 @@ const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect,
   const buttonContent = (
     <>
       <div className="tool-button-icon" style={{ color: "var(--tools-text-and-icon-color)", marginRight: "0.5rem", transform: "scale(0.8)", transformOrigin: "center", opacity: isUnavailable ? 0.25 : 1 }}>{tool.icon}</div>
-      <FitText
-        text={tool.name}
-        lines={1}
-        minimumFontScale={0.8}
-        as="span"
-        style={{ display: 'inline-block', maxWidth: '100%', opacity: isUnavailable ? 0.25 : 1 }}
-      />
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-start', flex: 1, overflow: 'visible' }}>
+        <FitText
+          text={tool.name}
+          lines={1}
+          minimumFontScale={0.8}
+          as="span"
+          style={{ display: 'inline-block', maxWidth: '100%', opacity: isUnavailable ? 0.25 : 1 }}
+        />
+        {matchedSynonym && (
+          <span style={{ 
+            fontSize: '0.75rem', 
+            color: 'var(--mantine-color-dimmed)', 
+            opacity: isUnavailable ? 0.25 : 1,
+            marginTop: '1px',
+            overflow: 'visible',
+            whiteSpace: 'nowrap'
+          }}>
+            {matchedSynonym}
+          </span>
+        )}
+      </div>
     </>
   );
 
@@ -66,7 +81,10 @@ const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect,
       fullWidth
       justify="flex-start"
       className="tool-button"
-      styles={{ root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)" } }}
+      styles={{ 
+        root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)", overflow: 'visible' },
+        label: { overflow: 'visible' }
+      }}
     >
       {buttonContent}
     </Button>
@@ -84,7 +102,10 @@ const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect,
       fullWidth
       justify="flex-start"
       className="tool-button"
-      styles={{ root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)" } }}
+      styles={{ 
+        root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)", overflow: 'visible' },
+        label: { overflow: 'visible' }
+      }}
     >
       {buttonContent}
     </Button>
@@ -99,7 +120,7 @@ const ToolButton: React.FC<ToolButtonProps> = ({ id, tool, isSelected, onSelect,
       justify="flex-start"
       className="tool-button"
       aria-disabled={isUnavailable}
-      styles={{ root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)", cursor: isUnavailable ? 'not-allowed' : undefined } }}
+      styles={{ root: { borderRadius: 0, color: "var(--tools-text-and-icon-color)", cursor: isUnavailable ? 'not-allowed' : undefined, overflow: 'visible' }, label: { overflow: 'visible' } }}
     >
       {buttonContent}
     </Button>

frontend/src/components/tools/toolPicker/ToolSearch.tsx

@@ -5,6 +5,7 @@ import LocalIcon from '../../shared/LocalIcon';
 import { ToolRegistryEntry } from "../../../data/toolsTaxonomy";
 import { TextInput } from "../../shared/TextInput";
 import "./ToolPicker.css";
+import { rankByFuzzy, idToWords } from "../../../utils/fuzzySearch";
 
 interface ToolSearchProps {
   value: string;
@@ -38,15 +39,14 @@ const ToolSearch = ({
 
   const filteredTools = useMemo(() => {
     if (!value.trim()) return [];
-    return Object.entries(toolRegistry)
-      .filter(([id, tool]) => {
-        if (mode === "dropdown" && id === selectedToolKey) return false;
-        return (
-          tool.name.toLowerCase().includes(value.toLowerCase()) || tool.description.toLowerCase().includes(value.toLowerCase())
-        );
-      })
-      .slice(0, 6)
-      .map(([id, tool]) => ({ id, tool }));
+    const entries = Object.entries(toolRegistry).filter(([id]) => !(mode === "dropdown" && id === selectedToolKey));
+    const ranked = rankByFuzzy(entries, value, [
+      ([key]) => idToWords(key),
+      ([, v]) => v.name,
+      ([, v]) => v.description,
+      ([, v]) => v.synonyms?.join(' ') || '',
+    ]).slice(0, 6);
+    return ranked.map(({ item: [id, tool] }) => ({ id, tool }));
   }, [value, toolRegistry, mode, selectedToolKey]);
 
   const handleSearchChange = (searchValue: string) => {

frontend/src/contexts/ToolWorkflowContext.tsx

@@ -11,6 +11,7 @@ import { useNavigationActions, useNavigationState } from './NavigationContext';
 import { ToolId, isValidToolId } from '../types/toolId';
 import { useNavigationUrlSync } from '../hooks/useUrlSync';
 import { getDefaultWorkbench } from '../types/workbench';
+import { filterToolRegistryByQuery } from '../utils/toolSearch';
 
 // State interface
 interface ToolWorkflowState {
@@ -100,7 +101,7 @@ interface ToolWorkflowContextValue extends ToolWorkflowState {
   handleReaderToggle: () => void;
 
   // Computed values
-  filteredTools: [string, ToolRegistryEntry][]; // Filtered by search
+  filteredTools: Array<{ item: [string, ToolRegistryEntry]; matchedText?: string }>; // Filtered by search
   isPanelVisible: boolean;
 }
 
@@ -219,12 +220,10 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
     setReaderMode(true);
   }, [setReaderMode]);
 
-  // Filter tools based on search query
+  // Filter tools based on search query with fuzzy matching (name, description, id, synonyms)
   const filteredTools = useMemo(() => {
     if (!toolRegistry) return [];
-    return Object.entries(toolRegistry).filter(([_, { name }]) =>
-      name.toLowerCase().includes(state.searchQuery.toLowerCase())
-    );
+    return filterToolRegistryByQuery(toolRegistry as Record<string, ToolRegistryEntry>, state.searchQuery);
   }, [toolRegistry, state.searchQuery]);
 
   const isPanelVisible = useMemo(() =>

frontend/src/data/toolsTaxonomy.ts

@@ -45,6 +45,8 @@ export type ToolRegistryEntry = {
 	operationConfig?: ToolOperationConfig<any>;
 	// Settings component for automation configuration
 	settingsComponent?: React.ComponentType<any>;
+	// Synonyms for search (optional)
+	synonyms?: string[];
 }
 
 export type ToolRegistry = Record<ToolId, ToolRegistryEntry>;

frontend/src/data/useTranslatedToolRegistry.tsx

@@ -12,6 +12,7 @@ import RemoveBlanks from "../tools/RemoveBlanks";
 import RemovePages from "../tools/RemovePages";
 import RemovePassword from "../tools/RemovePassword";
 import { SubcategoryId, ToolCategoryId, ToolRegistry } from "./toolsTaxonomy";
+import { getSynonyms } from "../utils/toolSynonyms";
 import AddWatermark from "../tools/AddWatermark";
 import AddStamp from "../tools/AddStamp";
 import Merge from '../tools/Merge';
@@ -172,6 +173,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.certSign.desc", "Sign PDF documents using digital certificates"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.SIGNING,
+        synonyms: getSynonyms(t, "certSign"),
         maxFiles: -1,
         endpoints: ["cert-sign"],
         operationConfig: certSignOperationConfig,
@@ -184,6 +186,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.sign.desc", "Adds signature to PDF by drawing, text or image"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.SIGNING,
+        synonyms: getSynonyms(t, "sign")
       },
 
       // Document Security
@@ -199,7 +202,8 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["add-password"],
         operationConfig: addPasswordOperationConfig,
         settingsComponent: AddPasswordSettings,
-      },
+        synonyms: getSynonyms(t, "addPassword")
+     },
       watermark: {
         icon: <LocalIcon icon="branding-watermark-outline-rounded" width="1.5rem" height="1.5rem" />,
         name: t("home.watermark.title", "Add Watermark"),
@@ -211,6 +215,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["add-watermark"],
         operationConfig: addWatermarkOperationConfig,
         settingsComponent: AddWatermarkSingleStepSettings,
+        synonyms: getSynonyms(t, "watermark")
       },
       addStamp: {
         icon: <LocalIcon icon="approval-rounded" width="1.5rem" height="1.5rem" />,
@@ -219,6 +224,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.addStamp.desc", "Add text or add image stamps at set locations"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.DOCUMENT_SECURITY,
+        synonyms: getSynonyms(t, "addStamp"),
         maxFiles: -1,
         endpoints: ["add-stamp"],
         operationConfig: addStampOperationConfig,
@@ -234,6 +240,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["sanitize-pdf"],
         operationConfig: sanitizeOperationConfig,
         settingsComponent: SanitizeSettings,
+        synonyms: getSynonyms(t, "sanitize")
       },
       flatten: {
         icon: <LocalIcon icon="layers-clear-rounded" width="1.5rem" height="1.5rem" />,
@@ -246,6 +253,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["flatten"],
         operationConfig: flattenOperationConfig,
         settingsComponent: FlattenSettings,
+        synonyms: getSynonyms(t, "flatten")
       },
       unlockPDFForms: {
         icon: <LocalIcon icon="preview-off-rounded" width="1.5rem" height="1.5rem" />,
@@ -258,6 +266,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["unlock-pdf-forms"],
         operationConfig: unlockPdfFormsOperationConfig,
         settingsComponent: UnlockPdfFormsSettings,
+        synonyms: getSynonyms(t, "unlockPDFForms"),
       },
       manageCertificates: {
         icon: <LocalIcon icon="license-rounded" width="1.5rem" height="1.5rem" />,
@@ -269,6 +278,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         ),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.DOCUMENT_SECURITY,
+        synonyms: getSynonyms(t, "manageCertificates"),
       },
       changePermissions: {
         icon: <LocalIcon icon="lock-outline" width="1.5rem" height="1.5rem" />,
@@ -281,6 +291,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["add-password"],
         operationConfig: changePermissionsOperationConfig,
         settingsComponent: ChangePermissionsSettings,
+        synonyms: getSynonyms(t, "changePermissions"),
       },
       getPdfInfo: {
         icon: <LocalIcon icon="fact-check-rounded" width="1.5rem" height="1.5rem" />,
@@ -289,6 +300,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.getPdfInfo.desc", "Grabs any and all information possible on PDFs"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.VERIFICATION,
+        synonyms: getSynonyms(t, "getPdfInfo"),
       },
       validateSignature: {
         icon: <LocalIcon icon="verified-rounded" width="1.5rem" height="1.5rem" />,
@@ -297,11 +309,12 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.validateSignature.desc", "Verify digital signatures and certificates in PDF documents"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.VERIFICATION,
+        synonyms: getSynonyms(t, "validateSignature"),
       },
 
       // Document Review
 
-     read: {
+      read: {
         icon: <LocalIcon icon="article-rounded" width="1.5rem" height="1.5rem" />,
         name: t("home.read.title", "Read"),
         component: null,
@@ -312,6 +325,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         ),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.DOCUMENT_REVIEW,
+        synonyms: getSynonyms(t, "read")
       },
       changeMetadata: {
         icon: <LocalIcon icon="assignment-rounded" width="1.5rem" height="1.5rem" />,
@@ -324,6 +338,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["update-metadata"],
         operationConfig: changeMetadataOperationConfig,
         settingsComponent: ChangeMetadataSingleStep,
+        synonyms: getSynonyms(t, "changeMetadata")
       },
       // Page Formatting
 
@@ -350,6 +365,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["rotate-pdf"],
         operationConfig: rotateOperationConfig,
         settingsComponent: RotateSettings,
+        synonyms: getSynonyms(t, "rotate")
       },
       split: {
         icon: <LocalIcon icon="content-cut-rounded" width="1.5rem" height="1.5rem" />,
@@ -360,6 +376,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         subcategoryId: SubcategoryId.PAGE_FORMATTING,
         operationConfig: splitOperationConfig,
         settingsComponent: SplitSettings,
+        synonyms: getSynonyms(t, "split")
       },
       reorganizePages: {
         icon: <LocalIcon icon="move-down-rounded" width="1.5rem" height="1.5rem" />,
@@ -372,6 +389,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         ),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.PAGE_FORMATTING,
+        synonyms: getSynonyms(t, "reorganizePages")
       },
       scalePages: {
         icon: <LocalIcon icon="crop-free-rounded" width="1.5rem" height="1.5rem" />,
@@ -384,6 +402,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["scale-pages"],
         operationConfig: adjustPageScaleOperationConfig,
         settingsComponent: AdjustPageScaleSettings,
+        synonyms: getSynonyms(t, "scalePages")
       },
       addPageNumbers: {
         icon: <LocalIcon icon="123-rounded" width="1.5rem" height="1.5rem" />,
@@ -393,6 +412,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.addPageNumbers.desc", "Add Page numbers throughout a document in a set location"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.PAGE_FORMATTING,
+        synonyms: getSynonyms(t, "addPageNumbers")
       },
       pageLayout: {
         icon: <LocalIcon icon="dashboard-rounded" width="1.5rem" height="1.5rem" />,
@@ -402,6 +422,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.pageLayout.desc", "Merge multiple pages of a PDF document into a single page"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.PAGE_FORMATTING,
+        synonyms: getSynonyms(t, "pageLayout")
       },
       bookletImposition: {
         icon: <LocalIcon icon="menu-book-rounded" width="1.5rem" height="1.5rem" />,
@@ -426,6 +447,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         urlPath: '/pdf-to-single-page',
         endpoints: ["pdf-to-single-page"],
         operationConfig: singleLargePageOperationConfig,
+        synonyms: getSynonyms(t, "pdfToSinglePage")
       },
       addAttachments: {
         icon: <LocalIcon icon="attachment-rounded" width="1.5rem" height="1.5rem" />,
@@ -435,6 +457,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.addAttachments.desc", "Add or remove embedded files (attachments) to/from a PDF"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.PAGE_FORMATTING,
+        synonyms: getSynonyms(t, "addAttachments")
       },
 
       // Extraction
@@ -446,6 +469,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.extractPages.desc", "Extract specific pages from a PDF document"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.EXTRACTION,
+        synonyms: getSynonyms(t, "extractPages")
       },
       extractImages: {
         icon: <LocalIcon icon="filter-alt" width="1.5rem" height="1.5rem" />,
@@ -454,6 +478,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.extractImages.desc", "Extract images from PDF documents"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.EXTRACTION,
+        synonyms: getSynonyms(t, "extractImages")
       },
 
       // Removal
@@ -467,6 +492,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         subcategoryId: SubcategoryId.REMOVAL,
         maxFiles: 1,
         endpoints: ["remove-pages"],
+        synonyms: getSynonyms(t, "removePages")
       },
       removeBlanks: {
         icon: <LocalIcon icon="scan-delete-rounded" width="1.5rem" height="1.5rem" />,
@@ -477,6 +503,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         subcategoryId: SubcategoryId.REMOVAL,
         maxFiles: 1,
         endpoints: ["remove-blanks"],
+        synonyms: getSynonyms(t, "removeBlanks")
       },
       removeAnnotations: {
         icon: <LocalIcon icon="thread-unread-rounded" width="1.5rem" height="1.5rem" />,
@@ -485,6 +512,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.removeAnnotations.desc", "Remove annotations and comments from PDF documents"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.REMOVAL,
+        synonyms: getSynonyms(t, "removeAnnotations")
       },
       removeImage: {
         icon: <LocalIcon icon="remove-selection-rounded" width="1.5rem" height="1.5rem" />,
@@ -493,6 +521,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.removeImage.desc", "Remove images from PDF documents"),
         categoryId: ToolCategoryId.STANDARD_TOOLS,
         subcategoryId: SubcategoryId.REMOVAL,
+        synonyms: getSynonyms(t, "removeImage"),
       },
       removePassword: {
         icon: <LocalIcon icon="lock-open-right-outline-rounded" width="1.5rem" height="1.5rem" />,
@@ -505,6 +534,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         maxFiles: -1,
         operationConfig: removePasswordOperationConfig,
         settingsComponent: RemovePasswordSettings,
+        synonyms: getSynonyms(t, "removePassword")
       },
       removeCertSign: {
         icon: <LocalIcon icon="remove-moderator-outline-rounded" width="1.5rem" height="1.5rem" />,
@@ -516,6 +546,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         maxFiles: -1,
         endpoints: ["remove-certificate-sign"],
         operationConfig: removeCertificateSignOperationConfig,
+        synonyms: getSynonyms(t, "removeCertSign"),
       },
 
       // Automation
@@ -533,6 +564,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         maxFiles: -1,
         supportedFormats: CONVERT_SUPPORTED_FORMATS,
         endpoints: ["handleData"],
+        synonyms: getSynonyms(t, "automate"),
       },
       autoRename: {
         icon: <LocalIcon icon="match-word-rounded" width="1.5rem" height="1.5rem" />,
@@ -544,6 +576,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.autoRename.desc", "Automatically rename PDF files based on their content"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.AUTOMATION,
+        synonyms: getSynonyms(t, "autoRename"),
       },
       autoSplitPDF: {
         icon: <LocalIcon icon="split-scene-right-rounded" width="1.5rem" height="1.5rem" />,
@@ -552,6 +585,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.autoSplitPDF.desc", "Automatically split PDF pages based on content detection"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.AUTOMATION,
+        synonyms: getSynonyms(t, "autoSplitPDF"),
       },
       autoSizeSplitPDF: {
         icon: <LocalIcon icon="content-cut-rounded" width="1.5rem" height="1.5rem" />,
@@ -560,6 +594,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.autoSizeSplitPDF.desc", "Automatically split PDFs by file size or page count"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.AUTOMATION,
+        synonyms: getSynonyms(t, "autoSizeSplitPDF"),
       },
 
       // Advanced Formatting
@@ -571,6 +606,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.adjustContrast.desc", "Adjust colors and contrast of PDF documents"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "adjustContrast"),
       },
       repair: {
         icon: <LocalIcon icon="build-outline-rounded" width="1.5rem" height="1.5rem" />,
@@ -583,6 +619,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["repair"],
         operationConfig: repairOperationConfig,
         settingsComponent: RepairSettings,
+        synonyms: getSynonyms(t, "repair")
       },
       scannerImageSplit: {
         icon: <LocalIcon icon="scanner-rounded" width="1.5rem" height="1.5rem" />,
@@ -591,6 +628,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.scannerImageSplit.desc", "Detect and split scanned photos into separate pages"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "ScannerImageSplit"),
       },
       overlayPdfs: {
         icon: <LocalIcon icon="layers-rounded" width="1.5rem" height="1.5rem" />,
@@ -599,6 +637,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.overlayPdfs.desc", "Overlay one PDF on top of another"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "overlayPdfs"),
       },
       replaceColorPdf: {
         icon: <LocalIcon icon="format-color-fill-rounded" width="1.5rem" height="1.5rem" />,
@@ -607,6 +646,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.replaceColorPdf.desc", "Replace or invert colors in PDF documents"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "replaceColorPdf"),
       },
       addImage: {
         icon: <LocalIcon icon="image-rounded" width="1.5rem" height="1.5rem" />,
@@ -615,6 +655,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.addImage.desc", "Add images to PDF documents"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "addImage"),
       },
       editTableOfContents: {
         icon: <LocalIcon icon="bookmark-add-rounded" width="1.5rem" height="1.5rem" />,
@@ -623,6 +664,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.editTableOfContents.desc", "Add or edit bookmarks and table of contents in PDF documents"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "editTableOfContents"),
       },
       fakeScan: {
         icon: <LocalIcon icon="scanner-rounded" width="1.5rem" height="1.5rem" />,
@@ -631,6 +673,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.fakeScan.desc", "Create a PDF that looks like it was scanned"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.ADVANCED_FORMATTING,
+        synonyms: getSynonyms(t, "fakeScan"),
       },
 
       // Developer Tools
@@ -642,6 +685,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.showJS.desc", "Extract and display JavaScript code from PDF documents"),
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.DEVELOPER_TOOLS,
+        synonyms: getSynonyms(t, "showJS"),
       },
       devApi: {
         icon: <LocalIcon icon="open-in-new-rounded" width="1.5rem" height="1.5rem" style={{ color: "#2F7BF6" }} />,
@@ -651,6 +695,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.DEVELOPER_TOOLS,
         link: "https://stirlingpdf.io/swagger-ui/5.21.0/index.html",
+        synonyms: getSynonyms(t, "devApi"),
       },
       devFolderScanning: {
         icon: <LocalIcon icon="open-in-new-rounded" width="1.5rem" height="1.5rem" style={{ color: "#2F7BF6" }} />,
@@ -660,6 +705,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.DEVELOPER_TOOLS,
         link: "https://docs.stirlingpdf.com/Advanced%20Configuration/Folder%20Scanning/",
+        synonyms: getSynonyms(t, "devFolderScanning"),
       },
       devSsoGuide: {
         icon: <LocalIcon icon="open-in-new-rounded" width="1.5rem" height="1.5rem" style={{ color: "#2F7BF6" }} />,
@@ -669,6 +715,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.DEVELOPER_TOOLS,
         link: "https://docs.stirlingpdf.com/Advanced%20Configuration/Single%20Sign-On%20Configuration",
+        synonyms: getSynonyms(t, "devSsoGuide"),
       },
       devAirgapped: {
         icon: <LocalIcon icon="open-in-new-rounded" width="1.5rem" height="1.5rem" style={{ color: "#2F7BF6" }} />,
@@ -678,6 +725,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         categoryId: ToolCategoryId.ADVANCED_TOOLS,
         subcategoryId: SubcategoryId.DEVELOPER_TOOLS,
         link: "https://docs.stirlingpdf.com/Pro/#activation",
+        synonyms: getSynonyms(t, "devAirgapped"),
       },
 
       // Recommended Tools
@@ -688,6 +736,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         description: t("home.compare.desc", "Compare two PDF documents and highlight differences"),
         categoryId: ToolCategoryId.RECOMMENDED_TOOLS,
         subcategoryId: SubcategoryId.GENERAL,
+        synonyms: getSynonyms(t, "compare")
       },
       compress: {
         icon: <LocalIcon icon="zoom-in-map-rounded" width="1.5rem" height="1.5rem" />,
@@ -699,6 +748,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         maxFiles: -1,
         operationConfig: compressOperationConfig,
         settingsComponent: CompressSettings,
+        synonyms: getSynonyms(t, "compress")
       },
       convert: {
         icon: <LocalIcon icon="sync-alt-rounded" width="1.5rem" height="1.5rem" />,
@@ -728,6 +778,7 @@ export function useFlatToolRegistry(): ToolRegistry {
 
         operationConfig: convertOperationConfig,
         settingsComponent: ConvertSettings,
+        synonyms: getSynonyms(t, "convert")
       },
       merge: {
         icon: <LocalIcon icon="library-add-rounded" width="1.5rem" height="1.5rem" />,
@@ -739,7 +790,8 @@ export function useFlatToolRegistry(): ToolRegistry {
         maxFiles: -1,
         endpoints: ["merge-pdfs"],
         operationConfig: mergeOperationConfig,
-        settingsComponent: MergeSettings
+        settingsComponent: MergeSettings,
+        synonyms: getSynonyms(t, "merge")
       },
       multiTool: {
         icon: <LocalIcon icon="dashboard-customize-rounded" width="1.5rem" height="1.5rem" />,
@@ -750,6 +802,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         categoryId: ToolCategoryId.RECOMMENDED_TOOLS,
         subcategoryId: SubcategoryId.GENERAL,
         maxFiles: -1,
+        synonyms: getSynonyms(t, "multiTool"),
       },
       ocr: {
         icon: <LocalIcon icon="quick-reference-all-outline-rounded" width="1.5rem" height="1.5rem" />,
@@ -762,6 +815,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         urlPath: '/ocr-pdf',
         operationConfig: ocrOperationConfig,
         settingsComponent: OCRSettings,
+        synonyms: getSynonyms(t, "ocr")
       },
       redact: {
         icon: <LocalIcon icon="visibility-off-rounded" width="1.5rem" height="1.5rem" />,
@@ -774,6 +828,7 @@ export function useFlatToolRegistry(): ToolRegistry {
         endpoints: ["auto-redact"],
         operationConfig: redactOperationConfig,
         settingsComponent: RedactSingleStepSettings,
+        synonyms: getSynonyms(t, "redact")
       },
     };
 

frontend/src/hooks/useToolSections.ts

@@ -27,12 +27,19 @@ export interface ToolSection {
   subcategories: SubcategoryGroup[];
 };
 
-export function useToolSections(filteredTools: [string /* FIX ME: Should be ToolId */, ToolRegistryEntry][]) {
+export function useToolSections(
+  filteredTools: Array<{ item: [string /* FIX ME: Should be ToolId */, ToolRegistryEntry]; matchedText?: string }>,
+  searchQuery?: string
+) {
   const { t } = useTranslation();
 
   const groupedTools = useMemo(() => {
+    if (!filteredTools || !Array.isArray(filteredTools)) {
+      return {} as GroupedTools;
+    }
+    
     const grouped = {} as GroupedTools;
-    filteredTools.forEach(([id, tool]) => {
+    filteredTools.forEach(({ item: [id, tool] }) => {
       const categoryId = tool.categoryId;
       const subcategoryId = tool.subcategoryId;
       if (!grouped[categoryId]) grouped[categoryId] = {} as SubcategoryIdMap;
@@ -92,9 +99,13 @@ export function useToolSections(filteredTools: [string /* FIX ME: Should be Tool
   }, [groupedTools]);
 
   const searchGroups: SubcategoryGroup[] = useMemo(() => {
+    if (!filteredTools || !Array.isArray(filteredTools)) {
+      return [];
+    }
+    
     const subMap = {} as SubcategoryIdMap;
     const seen = new Set<string /* FIX ME: Should be ToolId */>();
-    filteredTools.forEach(([id, tool]) => {
+    filteredTools.forEach(({ item: [id, tool] }) => {
       const toolId = id as string /* FIX ME: Should be ToolId */;
       if (seen.has(toolId)) return;
       seen.add(toolId);
@@ -102,10 +113,31 @@ export function useToolSections(filteredTools: [string /* FIX ME: Should be Tool
       if (!subMap[sub]) subMap[sub] = [];
       subMap[sub].push({ id: toolId, tool });
     });
-    return Object.entries(subMap)
+    const entries = Object.entries(subMap);
+
+    // If a search query is present, always order subcategories by first occurrence in
+    // the ranked filteredTools list so the top-ranked tools' subcategory appears first.
+    if (searchQuery && searchQuery.trim()) {
+      const order: SubcategoryId[] = [];
+      filteredTools.forEach(({ item: [_, tool] }) => {
+        const sc = tool.subcategoryId;
+        if (!order.includes(sc)) order.push(sc);
+      });
+      return entries
+        .sort(([a], [b]) => {
+          const ai = order.indexOf(a as SubcategoryId);
+          const bi = order.indexOf(b as SubcategoryId);
+          if (ai !== bi) return ai - bi;
+          return (a as SubcategoryId).localeCompare(b as SubcategoryId);
+        })
+        .map(([subcategoryId, tools]) => ({ subcategoryId, tools } as SubcategoryGroup));
+    }
+
+    // No search: alphabetical subcategory ordering
+    return entries
       .sort(([a], [b]) => a.localeCompare(b))
       .map(([subcategoryId, tools]) => ({ subcategoryId, tools } as SubcategoryGroup));
-  }, [filteredTools]);
+  }, [filteredTools, searchQuery]);
 
   return { sections, searchGroups };
 }

frontend/src/utils/fuzzySearch.ts

@@ -0,0 +1,121 @@
+// Lightweight fuzzy search helpers without external deps
+// Provides diacritics-insensitive normalization and Levenshtein distance scoring
+
+function normalizeText(text: string): string {
+  return text
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/\p{Diacritic}+/gu, '')
+    .trim();
+}
+
+// Basic Levenshtein distance (iterative with two rows)
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const aLen = a.length;
+  const bLen = b.length;
+  if (aLen === 0) return bLen;
+  if (bLen === 0) return aLen;
+
+  const prev = new Array(bLen + 1);
+  const curr = new Array(bLen + 1);
+
+  for (let j = 0; j <= bLen; j++) prev[j] = j;
+
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    const aChar = a.charCodeAt(i - 1);
+    for (let j = 1; j <= bLen; j++) {
+      const cost = aChar === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1, // deletion
+        curr[j - 1] + 1, // insertion
+        prev[j - 1] + cost // substitution
+      );
+    }
+    for (let j = 0; j <= bLen; j++) prev[j] = curr[j];
+  }
+  return curr[bLen];
+}
+
+// Compute a heuristic match score (higher is better)
+// 1) Exact/substring hits get high base; 2) otherwise use normalized Levenshtein distance
+export function scoreMatch(queryRaw: string, targetRaw: string): number {
+  const query = normalizeText(queryRaw);
+  const target = normalizeText(targetRaw);
+  if (!query) return 0;
+  if (target.includes(query)) {
+    // Reward earlier/shorter substring matches
+    const pos = target.indexOf(query);
+    return 100 - pos - Math.max(0, target.length - query.length);
+  }
+
+  // Token-aware: check each word token too, but require better similarity
+  const tokens = target.split(/[^a-z0-9]+/g).filter(Boolean);
+  for (const token of tokens) {
+    if (token.includes(query)) {
+      // Only give high score if the match is substantial (not just "and" matching)
+      const similarity = query.length / Math.max(query.length, token.length);
+      if (similarity >= 0.6) { // Require at least 60% similarity
+        return 80 - Math.abs(token.length - query.length);
+      }
+    }
+  }
+
+  const distance = levenshtein(query, target.length > 64 ? target.slice(0, 64) : target);
+  const maxLen = Math.max(query.length, target.length, 1);
+  const similarity = 1 - distance / maxLen; // 0..1
+  return Math.floor(similarity * 60); // scale below substring scores
+}
+
+export function minScoreForQuery(query: string): number {
+  const len = normalizeText(query).length;
+  if (len <= 3) return 40; 
+  if (len <= 6) return 30; 
+  return 25; 
+}
+
+// Decide if a target matches a query based on a threshold
+export function isFuzzyMatch(query: string, target: string, minScore?: number): boolean {
+  const threshold = typeof minScore === 'number' ? minScore : minScoreForQuery(query);
+  return scoreMatch(query, target) >= threshold;
+}
+
+// Convenience: rank a list of items by best score across provided getters
+export function rankByFuzzy<T>(items: T[], query: string, getters: Array<(item: T) => string>, minScore?: number): Array<{ item: T; score: number; matchedText?: string }>{
+  const results: Array<{ item: T; score: number; matchedText?: string }> = [];
+  const threshold = typeof minScore === 'number' ? minScore : minScoreForQuery(query);
+  for (const item of items) {
+    let best = 0;
+    let matchedText = '';
+    for (const get of getters) {
+      const value = get(item);
+      if (!value) continue;
+      const s = scoreMatch(query, value);
+      if (s > best) {
+        best = s;
+        matchedText = value;
+      }
+      if (best >= 95) {
+        break;
+      }
+    }
+    if (best >= threshold) results.push({ item, score: best, matchedText });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+export function normalizeForSearch(text: string): string {
+  return normalizeText(text);
+}
+
+// Convert ids like "addPassword", "add-password", "add_password" to words for matching
+export function idToWords(id: string): string {
+  const spaced = id
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[._-]+/g, ' ');
+  return normalizeText(spaced);
+}
+
+

frontend/src/utils/toolSearch.ts

@@ -0,0 +1,99 @@
+import { ToolRegistryEntry } from "../data/toolsTaxonomy";
+import { scoreMatch, minScoreForQuery, normalizeForSearch } from "./fuzzySearch";
+
+export interface RankedToolItem {
+  item: [string, ToolRegistryEntry];
+  matchedText?: string;
+}
+
+export function filterToolRegistryByQuery(
+  toolRegistry: Record<string, ToolRegistryEntry>,
+  query: string
+): RankedToolItem[] {
+  const entries = Object.entries(toolRegistry);
+  if (!query.trim()) {
+    return entries.map(([id, tool]) => ({ item: [id, tool] as [string, ToolRegistryEntry] }));
+  }
+
+  const nq = normalizeForSearch(query);
+  const threshold = minScoreForQuery(query);
+
+  const exactName: Array<{ id: string; tool: ToolRegistryEntry; pos: number }> = [];
+  const exactSyn: Array<{ id: string; tool: ToolRegistryEntry; text: string; pos: number }> = [];
+  const fuzzyName: Array<{ id: string; tool: ToolRegistryEntry; score: number; text: string }> = [];
+  const fuzzySyn: Array<{ id: string; tool: ToolRegistryEntry; score: number; text: string }> = [];
+
+  for (const [id, tool] of entries) {
+    const nameNorm = normalizeForSearch(tool.name || '');
+    const pos = nameNorm.indexOf(nq);
+    if (pos !== -1) {
+      exactName.push({ id, tool, pos });
+      continue;
+    }
+
+    const syns = Array.isArray(tool.synonyms) ? tool.synonyms : [];
+    let matchedExactSyn: { text: string; pos: number } | null = null;
+    for (const s of syns) {
+      const sn = normalizeForSearch(s);
+      const sp = sn.indexOf(nq);
+      if (sp !== -1) {
+        matchedExactSyn = { text: s, pos: sp };
+        break;
+      }
+    }
+    if (matchedExactSyn) {
+      exactSyn.push({ id, tool, text: matchedExactSyn.text, pos: matchedExactSyn.pos });
+      continue;
+    }
+
+    // Fuzzy name
+    const nameScore = scoreMatch(query, tool.name || '');
+    if (nameScore >= threshold) {
+      fuzzyName.push({ id, tool, score: nameScore, text: tool.name || '' });
+    }
+
+    // Fuzzy synonyms (we'll consider these only if fuzzy name results are weak)
+    let bestSynScore = 0;
+    let bestSynText = '';
+    for (const s of syns) {
+      const synScore = scoreMatch(query, s);
+      if (synScore > bestSynScore) {
+        bestSynScore = synScore;
+        bestSynText = s;
+      }
+      if (bestSynScore >= 95) break;
+    }
+    if (bestSynScore >= threshold) {
+      fuzzySyn.push({ id, tool, score: bestSynScore, text: bestSynText });
+    }
+  }
+
+  // Sort within buckets
+  exactName.sort((a, b) => a.pos - b.pos || (a.tool.name || '').length - (b.tool.name || '').length);
+  exactSyn.sort((a, b) => a.pos - b.pos || a.text.length - b.text.length);
+  fuzzyName.sort((a, b) => b.score - a.score);
+  fuzzySyn.sort((a, b) => b.score - a.score);
+
+  // Concatenate buckets with de-duplication by tool id
+  const seen = new Set<string>();
+  const ordered: RankedToolItem[] = [];
+
+  const push = (id: string, tool: ToolRegistryEntry, matchedText?: string) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    ordered.push({ item: [id, tool], matchedText });
+  };
+
+  for (const { id, tool } of exactName) push(id, tool, tool.name);
+  for (const { id, tool, text } of exactSyn) push(id, tool, text);
+  for (const { id, tool, text } of fuzzyName) push(id, tool, text);
+  for (const { id, tool, text } of fuzzySyn) push(id, tool, text);
+
+  if (ordered.length > 0) return ordered;
+
+  // Fallback: return everything unchanged
+  return entries.map(([id, tool]) => ({ item: [id, tool] as [string, ToolRegistryEntry] }));
+}
+
+
+

frontend/src/utils/toolSynonyms.ts

@@ -0,0 +1,24 @@
+import { TFunction } from 'i18next';
+
+// Helper function to get synonyms for a tool (only from translations)
+export const getSynonyms = (t: TFunction, toolId: string): string[] => {
+  try {
+    const tagsKey = `${toolId}.tags`;
+    const tags = t(tagsKey) as unknown as string;
+
+    // If the translation key doesn't exist or returns the key itself, return empty array
+    if (!tags || tags === tagsKey) {
+      return [];
+    }
+
+    // Split by comma and clean up the tags
+    return tags
+      .split(',')
+      .map((tag: string) => tag.trim())
+      .filter((tag: string) => tag.length > 0);
+  } catch (error) {
+    console.warn(`Failed to get translated synonyms for tool ${toolId}:`, error);
+    return [];
+  }};
+
+