Posthog, scarf and url navigation overhaul (#4318)

Added post hog project - always enabled
Added scarf pixel - Always enabled 
Reworked Url navigation 
Forward and back now works without reloading page

---------

Co-authored-by: Connor Yoh <connor@stirlingpdf.com>

frontend/package-lock.json

@@ -32,6 +32,7 @@
         "jszip": "^3.10.1",
         "pdf-lib": "^1.17.1",
         "pdfjs-dist": "^3.11.174",
+        "posthog-js": "^1.261.0",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
         "react-i18next": "^15.5.2",
@@ -1774,6 +1775,12 @@
         "url": "https://opencollective.com/popperjs"
       }
     },
+    "node_modules/@posthog/core": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.0.2.tgz",
+      "integrity": "sha512-hWk3rUtJl2crQK0WNmwg13n82hnTwB99BT99/XI5gZSvIlYZ1TPmMZE8H2dhJJ98J/rm9vYJ/UXNzw3RV5HTpQ==",
+      "license": "MIT"
+    },
     "node_modules/@rolldown/pluginutils": {
       "version": "1.0.0-beta.9",
       "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.9.tgz",
@@ -3813,6 +3820,17 @@
         "node": ">=18"
       }
     },
+    "node_modules/core-js": {
+      "version": "3.45.1",
+      "resolved": "https://registry.npmjs.org/core-js/-/core-js-3.45.1.tgz",
+      "integrity": "sha512-L4NPsJlCfZsPeXukyzHFlg/i7IIVwHSItR0wg0FLNqYClJ4MQYTYLbC7EkjKYRLZF2iof2MUgN0EGy7MdQFChg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/core-js"
+      }
+    },
     "node_modules/core-util-is": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
@@ -4614,6 +4632,12 @@
         "reusify": "^1.0.4"
       }
     },
+    "node_modules/fflate": {
+      "version": "0.4.8",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.4.8.tgz",
+      "integrity": "sha512-FJqqoDBR00Mdj9ppamLa/Y7vxm+PRmNWA67N846RvsoYVMKB4q3y/de5PA7gUmRMYK/8CMz2GDZQmCRN1wBcWA==",
+      "license": "MIT"
+    },
     "node_modules/file-selector": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/file-selector/-/file-selector-2.1.2.tgz",
@@ -7388,6 +7412,47 @@
         "postcss": "^8.2.9"
       }
     },
+    "node_modules/posthog-js": {
+      "version": "1.261.0",
+      "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.261.0.tgz",
+      "integrity": "sha512-jyiXqyrCU+VlpbNNVRA6OQYAVut0XZMYNELCZH+XvTd981VqbE4jXn4XCBreo7XCL2gdPgDVxUVOuzNvEuKcmw==",
+      "license": "SEE LICENSE IN LICENSE",
+      "dependencies": {
+        "@posthog/core": "1.0.2",
+        "core-js": "^3.38.1",
+        "fflate": "^0.4.8",
+        "preact": "^10.19.3",
+        "web-vitals": "^4.2.4"
+      },
+      "peerDependencies": {
+        "@rrweb/types": "2.0.0-alpha.17",
+        "rrweb-snapshot": "2.0.0-alpha.17"
+      },
+      "peerDependenciesMeta": {
+        "@rrweb/types": {
+          "optional": true
+        },
+        "rrweb-snapshot": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/posthog-js/node_modules/web-vitals": {
+      "version": "4.2.4",
+      "resolved": "https://registry.npmjs.org/web-vitals/-/web-vitals-4.2.4.tgz",
+      "integrity": "sha512-r4DIlprAGwJ7YM11VZp4R884m0Vmgr6EAKe3P+kO0PPj3Unqyvv59rczf6UiGcb9Z8QxZVcqKNwv/g0WNdWwsw==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/preact": {
+      "version": "10.27.1",
+      "resolved": "https://registry.npmjs.org/preact/-/preact-10.27.1.tgz",
+      "integrity": "sha512-V79raXEWch/rbqoNc7nT9E4ep7lu+mI3+sBmfRD4i1M73R3WLYcCtdI0ibxGVf4eQL8ZIz2nFacqEC+rmnOORQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/preact"
+      }
+    },
     "node_modules/precinct": {
       "version": "12.2.0",
       "resolved": "https://registry.npmjs.org/precinct/-/precinct-12.2.0.tgz",

frontend/package.json

@@ -28,6 +28,7 @@
     "jszip": "^3.10.1",
     "pdf-lib": "^1.17.1",
     "pdfjs-dist": "^3.11.174",
+    "posthog-js": "^1.261.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-i18next": "^15.5.2",

frontend/scripts/generate-licenses.js

@@ -182,6 +182,7 @@ function getLicenseUrl(licenseType) {
 
     const licenseUrls = {
         'MIT': 'https://opensource.org/licenses/MIT',
+        'MIT*': 'https://opensource.org/licenses/MIT',
         'Apache-2.0': 'https://www.apache.org/licenses/LICENSE-2.0',
         'Apache License 2.0': 'https://www.apache.org/licenses/LICENSE-2.0',
         'BSD-3-Clause': 'https://opensource.org/licenses/BSD-3-Clause',
@@ -270,7 +271,7 @@ function checkLicenseCompatibility(licenseSummary, licenseArray) {
 
     // Known good licenses (no warnings needed)
     const goodLicenses = new Set([
-        'MIT', 'Apache-2.0', 'Apache License 2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'BSD',
+        'MIT', 'MIT*', 'Apache-2.0', 'Apache License 2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'BSD',
         'ISC', 'CC0-1.0', 'Public Domain', 'Unlicense', '0BSD', 'BlueOak-1.0.0',
         'Zlib', 'Artistic-2.0', 'Python-2.0', 'Ruby', 'MPL-2.0', 'CC-BY-4.0',
         'SEE LICENSE IN https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/refs/heads/main/proprietary/LICENSE'

frontend/src/components/fileEditor/FileEditor.tsx

@@ -412,9 +412,9 @@ const FileEditor = ({
     if (record) {
       // Set the file as selected in context and switch to viewer for preview
       setSelectedFiles([fileId]);
-      navActions.setMode('viewer');
+      navActions.setWorkbench('viewer');
     }
-  }, [activeFileRecords, setSelectedFiles, navActions.setMode]);
+  }, [activeFileRecords, setSelectedFiles, navActions.setWorkbench]);
 
   const handleMergeFromHere = useCallback((fileId: FileId) => {
     const startIndex = activeFileRecords.findIndex(r => r.id === fileId);

frontend/src/components/layout/Workbench.tsx

@@ -6,13 +6,13 @@ import { useToolWorkflow } from '../../contexts/ToolWorkflowContext';
 import { useFileHandler } from '../../hooks/useFileHandler';
 import { useFileState, useFileActions } from '../../contexts/FileContext';
 import { useNavigationState, useNavigationActions } from '../../contexts/NavigationContext';
+import { useToolManagement } from '../../hooks/useToolManagement';
 
 import TopControls from '../shared/TopControls';
 import FileEditor from '../fileEditor/FileEditor';
 import PageEditor from '../pageEditor/PageEditor';
 import PageEditorControls from '../pageEditor/PageEditorControls';
 import Viewer from '../viewer/Viewer';
-import ToolRenderer from '../tools/ToolRenderer';
 import LandingPage from '../shared/LandingPage';
 
 // No props needed - component uses contexts directly
@@ -23,9 +23,9 @@ export default function Workbench() {
   // Use context-based hooks to eliminate all prop drilling
   const { state } = useFileState();
   const { actions } = useFileActions();
-  const { currentMode: currentView } = useNavigationState();
+  const { workbench: currentView } = useNavigationState();
   const { actions: navActions } = useNavigationActions();
-  const setCurrentView = navActions.setMode;
+  const setCurrentView = navActions.setWorkbench;
   const activeFiles = state.files.ids;
   const {
     previewFile,
@@ -36,7 +36,14 @@ export default function Workbench() {
     setSidebarsVisible
   } = useToolWorkflow();
 
-  const { selectedToolKey, selectedTool, handleToolSelect } = useToolWorkflow();
+  const { handleToolSelect } = useToolWorkflow();
+  
+  // Get navigation state - this is the source of truth
+  const { selectedTool: selectedToolId } = useNavigationState();
+  
+  // Get tool registry to look up selected tool
+  const { toolRegistry } = useToolManagement();
+  const selectedTool = selectedToolId ? toolRegistry[selectedToolId] : null;
   const { addToActiveFiles } = useFileHandler();
 
   const handlePreviewClose = () => {
@@ -69,11 +76,11 @@ export default function Workbench() {
       case "fileEditor":
         return (
           <FileEditor
-            toolMode={!!selectedToolKey}
+            toolMode={!!selectedToolId}
             showUpload={true}
-            showBulkActions={!selectedToolKey}
+            showBulkActions={!selectedToolId}
             supportedExtensions={selectedTool?.supportedFormats || ["pdf"]}
-            {...(!selectedToolKey && {
+            {...(!selectedToolId && {
               onOpenPageEditor: (file) => {
                 setCurrentView("pageEditor");
               },
@@ -127,14 +134,6 @@ export default function Workbench() {
         );
 
       default:
-        // Check if it's a tool view
-        if (selectedToolKey && selectedTool) {
-          return (
-            <ToolRenderer
-              selectedToolKey={selectedToolKey}
-            />
-          );
-        }
         return (
           <LandingPage/>
         );
@@ -154,7 +153,7 @@ export default function Workbench() {
       <TopControls
         currentView={currentView}
         setCurrentView={setCurrentView}
-        selectedToolKey={selectedToolKey}
+        selectedToolKey={selectedToolId}
       />
 
       {/* Main content area */}

frontend/src/components/pageEditor/PageEditor.tsx

@@ -6,7 +6,6 @@ import {
 } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useFileState, useFileActions, useCurrentFile, useFileSelection } from "../../contexts/FileContext";
-import { ModeType } from "../../contexts/NavigationContext";
 import { PDFDocument, PDFPage, PageEditorFunctions } from "../../types/pageEditor";
 import { ProcessedFile as EnhancedProcessedFile } from "../../types/processing";
 import { pdfExportService } from "../../services/pdfExportService";

frontend/src/components/shared/RightRail.tsx

@@ -25,7 +25,7 @@ export default function RightRail() {
   const [csvInput, setCsvInput] = useState<string>("");
 
   // Navigation view
-  const { currentMode: currentView } = useNavigationState();
+  const { workbench: currentView } = useNavigationState();
 
   // File state and selection
   const { state, selectors } = useFileState();

frontend/src/components/shared/TopControls.tsx

@@ -5,7 +5,7 @@ import rainbowStyles from '../../styles/rainbow.module.css';
 import VisibilityIcon from "@mui/icons-material/Visibility";
 import EditNoteIcon from "@mui/icons-material/EditNote";
 import FolderIcon from "@mui/icons-material/Folder";
-import { ModeType, isValidMode } from '../../contexts/NavigationContext';
+import { WorkbenchType, isValidWorkbench } from '../../types/workbench';
 import { Tooltip } from "./Tooltip";
 
 const viewOptionStyle = {
@@ -19,7 +19,7 @@ const viewOptionStyle = {
 
 
 // Build view options showing text only for current view; others icon-only with tooltip
-const createViewOptions = (currentView: ModeType, switchingTo: ModeType | null) => [
+const createViewOptions = (currentView: WorkbenchType, switchingTo: WorkbenchType | null) => [
   {
     label: (
       <div style={viewOptionStyle as React.CSSProperties}>
@@ -70,8 +70,8 @@ const createViewOptions = (currentView: ModeType, switchingTo: ModeType | null)
 ];
 
 interface TopControlsProps {
-  currentView: ModeType;
+  currentView: WorkbenchType;
-  setCurrentView: (view: ModeType) => void;
+  setCurrentView: (view: WorkbenchType) => void;
   selectedToolKey?: string | null;
 }
 
@@ -81,25 +81,25 @@ const TopControls = ({
   selectedToolKey,
 }: TopControlsProps) => {
   const { isRainbowMode } = useRainbowThemeContext();
-  const [switchingTo, setSwitchingTo] = useState<ModeType | null>(null);
+  const [switchingTo, setSwitchingTo] = useState<WorkbenchType | null>(null);
 
   const isToolSelected = selectedToolKey !== null;
 
   const handleViewChange = useCallback((view: string) => {
-    if (!isValidMode(view)) {
+    if (!isValidWorkbench(view)) {
-      // Ignore invalid values defensively
       return;
     }
-    const mode = view as ModeType;
+    
+    const workbench = view;
 
     // Show immediate feedback
-    setSwitchingTo(mode as ModeType);
+    setSwitchingTo(workbench);
 
     // Defer the heavy view change to next frame so spinner can render
     requestAnimationFrame(() => {
       // Give the spinner one more frame to show
       requestAnimationFrame(() => {
-        setCurrentView(mode as ModeType);
+        setCurrentView(workbench);
 
         // Clear the loading state after view change completes
         setTimeout(() => setSwitchingTo(null), 300);

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

@@ -11,7 +11,7 @@ import {
   Modal
 } from '@mantine/core';
 import CheckIcon from '@mui/icons-material/Check';
-import { ToolRegistryEntry } from '../../../data/toolsTaxonomy';
+import { ToolRegistry } from '../../../data/toolsTaxonomy';
 import ToolConfigurationModal from './ToolConfigurationModal';
 import ToolList from './ToolList';
 import IconSelector from './IconSelector';
@@ -24,7 +24,7 @@ interface AutomationCreationProps {
   existingAutomation?: AutomationConfig;
   onBack: () => void;
   onComplete: (automation: AutomationConfig) => void;
-  toolRegistry: Record<string, ToolRegistryEntry>;
+  toolRegistry: ToolRegistry;
 }
 
 export default function AutomationCreation({ mode, existingAutomation, onBack, onComplete, toolRegistry }: AutomationCreationProps) {

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

@@ -33,7 +33,7 @@ export default function AutomationRun({ automation, onComplete, automateOperatio
   React.useEffect(() => {
     if (automation?.operations) {
       const steps = automation.operations.map((op: any, index: number) => {
-        const tool = toolRegistry[op.operation];
+        const tool = toolRegistry[op.operation as keyof typeof toolRegistry];
         return {
           id: `${op.operation}-${index}`,
           operation: op.operation,

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

@@ -35,7 +35,7 @@ export default function ToolConfigurationModal({ opened, tool, onSave, onCancel,
   const [isValid, setIsValid] = useState(true);
 
   // Get tool info from registry
-  const toolInfo = toolRegistry[tool.operation];
+  const toolInfo = toolRegistry[tool.operation as keyof ToolRegistry];
   const SettingsComponent = toolInfo?.settingsComponent;
 
   // Initialize parameters from tool (which should contain defaults from registry)

frontend/src/contexts/NavigationContext.tsx

@@ -1,6 +1,7 @@
 import React, { createContext, useContext, useReducer, useCallback } from 'react';
-import { useNavigationUrlSync } from '../hooks/useUrlSync';
+import { WorkbenchType, getDefaultWorkbench } from '../types/workbench';
-import { ModeType, isValidMode, getDefaultMode } from '../types/navigation';
+import { ToolId, isValidToolId } from '../types/toolId';
+import { useFlatToolRegistry } from '../data/useTranslatedToolRegistry';
 
 /**
  * NavigationContext - Complete navigation management system
@@ -11,27 +12,38 @@ import { ModeType, isValidMode, getDefaultMode } from '../types/navigation';
  */
 
 // Navigation state
-interface NavigationState {
+interface NavigationContextState {
-  currentMode: ModeType;
+  workbench: WorkbenchType;
+  selectedTool: ToolId | null;
   hasUnsavedChanges: boolean;
   pendingNavigation: (() => void) | null;
   showNavigationWarning: boolean;
-  selectedToolKey: string | null; // Add tool selection to navigation state
 }
 
 // Navigation actions
 type NavigationAction =
-  | { type: 'SET_MODE'; payload: { mode: ModeType } }
+  | { type: 'SET_WORKBENCH'; payload: { workbench: WorkbenchType } }
+  | { type: 'SET_SELECTED_TOOL'; payload: { toolId: ToolId | null } }
+  | { type: 'SET_TOOL_AND_WORKBENCH'; payload: { toolId: ToolId | null; workbench: WorkbenchType } }
   | { type: 'SET_UNSAVED_CHANGES'; payload: { hasChanges: boolean } }
   | { type: 'SET_PENDING_NAVIGATION'; payload: { navigationFn: (() => void) | null } }
-  | { type: 'SHOW_NAVIGATION_WARNING'; payload: { show: boolean } }
+  | { type: 'SHOW_NAVIGATION_WARNING'; payload: { show: boolean } };
-  | { type: 'SET_SELECTED_TOOL'; payload: { toolKey: string | null } };
 
 // Navigation reducer
-const navigationReducer = (state: NavigationState, action: NavigationAction): NavigationState => {
+const navigationReducer = (state: NavigationContextState, action: NavigationAction): NavigationContextState => {
   switch (action.type) {
-    case 'SET_MODE':
+    case 'SET_WORKBENCH':
-      return { ...state, currentMode: action.payload.mode };
+      return { ...state, workbench: action.payload.workbench };
+
+    case 'SET_SELECTED_TOOL':
+      return { ...state, selectedTool: action.payload.toolId };
+
+    case 'SET_TOOL_AND_WORKBENCH':
+      return {
+        ...state,
+        selectedTool: action.payload.toolId,
+        workbench: action.payload.workbench
+      };
 
     case 'SET_UNSAVED_CHANGES':
       return { ...state, hasUnsavedChanges: action.payload.hasChanges };
@@ -42,43 +54,41 @@ const navigationReducer = (state: NavigationState, action: NavigationAction): Na
     case 'SHOW_NAVIGATION_WARNING':
       return { ...state, showNavigationWarning: action.payload.show };
 
-    case 'SET_SELECTED_TOOL':
-      return { ...state, selectedToolKey: action.payload.toolKey };
-    
     default:
       return state;
   }
 };
 
 // Initial state
-const initialState: NavigationState = {
+const initialState: NavigationContextState = {
-  currentMode: getDefaultMode(),
+  workbench: getDefaultWorkbench(),
+  selectedTool: null,
   hasUnsavedChanges: false,
   pendingNavigation: null,
-  showNavigationWarning: false,
+  showNavigationWarning: false
-  selectedToolKey: null
 };
 
 // Navigation context actions interface
 export interface NavigationContextActions {
-  setMode: (mode: ModeType) => void;
+  setWorkbench: (workbench: WorkbenchType) => void;
+  setSelectedTool: (toolId: ToolId | null) => void;
+  setToolAndWorkbench: (toolId: ToolId | null, workbench: WorkbenchType) => void;
   setHasUnsavedChanges: (hasChanges: boolean) => void;
   showNavigationWarning: (show: boolean) => void;
   requestNavigation: (navigationFn: () => void) => void;
   confirmNavigation: () => void;
   cancelNavigation: () => void;
-  selectTool: (toolKey: string) => void;
   clearToolSelection: () => void;
   handleToolSelect: (toolId: string) => void;
 }
 
-// Split context values
+// Context state values
 export interface NavigationContextStateValue {
-  currentMode: ModeType;
+  workbench: WorkbenchType;
+  selectedTool: ToolId | null;
   hasUnsavedChanges: boolean;
   pendingNavigation: (() => void) | null;
   showNavigationWarning: boolean;
-  selectedToolKey: string | null;
 }
 
 export interface NavigationContextActionsValue {
@@ -95,10 +105,19 @@ export const NavigationProvider: React.FC<{
   enableUrlSync?: boolean;
 }> = ({ children, enableUrlSync = true }) => {
   const [state, dispatch] = useReducer(navigationReducer, initialState);
+  const toolRegistry = useFlatToolRegistry();
 
   const actions: NavigationContextActions = {
-    setMode: useCallback((mode: ModeType) => {
+    setWorkbench: useCallback((workbench: WorkbenchType) => {
-      dispatch({ type: 'SET_MODE', payload: { mode } });
+      dispatch({ type: 'SET_WORKBENCH', payload: { workbench } });
+    }, []),
+
+    setSelectedTool: useCallback((toolId: ToolId | null) => {
+      dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolId } });
+    }, []),
+
+    setToolAndWorkbench: useCallback((toolId: ToolId | null, workbench: WorkbenchType) => {
+      dispatch({ type: 'SET_TOOL_AND_WORKBENCH', payload: { toolId, workbench } });
     }, []),
 
     setHasUnsavedChanges: useCallback((hasChanges: boolean) => {
@@ -110,75 +129,67 @@ export const NavigationProvider: React.FC<{
     }, []),
 
     requestNavigation: useCallback((navigationFn: () => void) => {
-      // If no unsaved changes, navigate immediately
       if (!state.hasUnsavedChanges) {
         navigationFn();
         return;
       }
 
-      // Otherwise, store the navigation and show warning
       dispatch({ type: 'SET_PENDING_NAVIGATION', payload: { navigationFn } });
       dispatch({ type: 'SHOW_NAVIGATION_WARNING', payload: { show: true } });
     }, [state.hasUnsavedChanges]),
 
     confirmNavigation: useCallback(() => {
-      // Execute pending navigation
       if (state.pendingNavigation) {
         state.pendingNavigation();
       }
 
-      // Clear navigation state
       dispatch({ type: 'SET_PENDING_NAVIGATION', payload: { navigationFn: null } });
       dispatch({ type: 'SHOW_NAVIGATION_WARNING', payload: { show: false } });
     }, [state.pendingNavigation]),
 
     cancelNavigation: useCallback(() => {
-      // Clear navigation without executing
       dispatch({ type: 'SET_PENDING_NAVIGATION', payload: { navigationFn: null } });
       dispatch({ type: 'SHOW_NAVIGATION_WARNING', payload: { show: false } });
     }, []),
 
-    selectTool: useCallback((toolKey: string) => {
-      dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolKey } });
-    }, []),
-
     clearToolSelection: useCallback(() => {
-      dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolKey: null } });
+      dispatch({ type: 'SET_TOOL_AND_WORKBENCH', payload: { toolId: null, workbench: getDefaultWorkbench() } });
     }, []),
 
     handleToolSelect: useCallback((toolId: string) => {
-      // Handle special cases
       if (toolId === 'allTools') {
-        dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolKey: null } });
+        dispatch({ type: 'SET_TOOL_AND_WORKBENCH', payload: { toolId: null, workbench: getDefaultWorkbench() } });
         return;
       }
 
-      // Special-case: if tool is a dedicated reader tool, enter reader mode
       if (toolId === 'read' || toolId === 'view-pdf') {
-        dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolKey: null } });
+        dispatch({ type: 'SET_TOOL_AND_WORKBENCH', payload: { toolId: null, workbench: 'viewer' } });
         return;
       }
 
-      dispatch({ type: 'SET_SELECTED_TOOL', payload: { toolKey: toolId } });
+      // Look up the tool in the registry to get its proper workbench
-      dispatch({ type: 'SET_MODE', payload: { mode: 'fileEditor' as ModeType } });
+
-    }, [])
+      const tool = isValidToolId(toolId)? toolRegistry[toolId] : null;
+      const workbench = tool ? (tool.workbench || getDefaultWorkbench()) : getDefaultWorkbench();
+
+      // Validate toolId and convert to ToolId type
+      const validToolId = isValidToolId(toolId) ? toolId : null;
+      dispatch({ type: 'SET_TOOL_AND_WORKBENCH', payload: { toolId: validToolId, workbench } });
+    }, [toolRegistry])
   };
 
   const stateValue: NavigationContextStateValue = {
-    currentMode: state.currentMode,
+    workbench: state.workbench,
+    selectedTool: state.selectedTool,
     hasUnsavedChanges: state.hasUnsavedChanges,
     pendingNavigation: state.pendingNavigation,
-    showNavigationWarning: state.showNavigationWarning,
+    showNavigationWarning: state.showNavigationWarning
-    selectedToolKey: state.selectedToolKey
   };
 
   const actionsValue: NavigationContextActionsValue = {
     actions
   };
 
-  // Enable URL synchronization
-  useNavigationUrlSync(state.currentMode, actions.setMode, enableUrlSync);
-
   return (
     <NavigationStateContext.Provider value={stateValue}>
       <NavigationActionsContext.Provider value={actionsValue}>
@@ -228,13 +239,3 @@ export const useNavigationGuard = () => {
     setShowNavigationWarning: actions.showNavigationWarning
   };
 };
-
-// Re-export utility functions from types for backward compatibility
-export { isValidMode, getDefaultMode, type ModeType } from '../types/navigation';
-
-// TODO: This will be expanded for URL-based routing system
-// - URL parsing utilities
-// - Route definitions  
-// - Navigation hooks with URL sync
-// - History management
-// - Breadcrumb restoration from URL params

frontend/src/contexts/ToolWorkflowContext.tsx

@@ -6,9 +6,11 @@
 import React, { createContext, useContext, useReducer, useCallback, useMemo } from 'react';
 import { useToolManagement } from '../hooks/useToolManagement';
 import { PageEditorFunctions } from '../types/pageEditor';
-import { ToolRegistryEntry } from '../data/toolsTaxonomy';
+import { ToolRegistryEntry, ToolRegistry } from '../data/toolsTaxonomy';
-import { useToolWorkflowUrlSync } from '../hooks/useUrlSync';
 import { useNavigationActions, useNavigationState } from './NavigationContext';
+import { ToolId, isValidToolId } from '../types/toolId';
+import { useNavigationUrlSync } from '../hooks/useUrlSync';
+import { getDefaultWorkbench } from '../types/workbench';
 
 // State interface
 interface ToolWorkflowState {
@@ -83,7 +85,7 @@ interface ToolWorkflowContextValue extends ToolWorkflowState {
   setSearchQuery: (query: string) => void;
 
   // Tool Actions
-  selectTool: (toolId: string) => void;
+  selectTool: (toolId: ToolId | null) => void;
   clearToolSelection: () => void;
 
   // Tool Reset Actions
@@ -124,7 +126,7 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
   } = useToolManagement();
 
   // Get selected tool from navigation context
-  const selectedTool = getSelectedTool(navigationState.selectedToolKey);
+  const selectedTool = getSelectedTool(navigationState.selectedTool);
 
   // UI Action creators
   const setSidebarsVisible = useCallback((visible: boolean) => {
@@ -142,7 +144,7 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
   const setPreviewFile = useCallback((file: File | null) => {
     dispatch({ type: 'SET_PREVIEW_FILE', payload: file });
     if (file) {
-      actions.setMode('viewer');
+      actions.setWorkbench('viewer');
     }
   }, [actions]);
 
@@ -172,7 +174,17 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
 
   // Workflow actions (compound actions that coordinate multiple state changes)
   const handleToolSelect = useCallback((toolId: string) => {
-    actions.handleToolSelect(toolId);
+    // Set the selected tool and determine the appropriate workbench
+    const validToolId = isValidToolId(toolId) ? toolId : null;
+    actions.setSelectedTool(validToolId);
+
+    // Get the tool from registry to determine workbench
+    const tool = getSelectedTool(toolId);
+    if (tool && tool.workbench) {
+      actions.setWorkbench(tool.workbench);
+    } else {
+      actions.setWorkbench(getDefaultWorkbench());
+    }
 
     // Clear search query when selecting a tool
     setSearchQuery('');
@@ -189,13 +201,13 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
       setLeftPanelView('toolContent');
       setReaderMode(false); // Disable read mode when selecting tools
     }
-  }, [actions, setLeftPanelView, setReaderMode, setSearchQuery]);
+  }, [actions, getSelectedTool, setLeftPanelView, setReaderMode, setSearchQuery]);
 
   const handleBackToTools = useCallback(() => {
     setLeftPanelView('toolPicker');
     setReaderMode(false);
-    actions.clearToolSelection();
+    actions.setSelectedTool(null);
-  }, [setLeftPanelView, setReaderMode, actions]);
+  }, [setLeftPanelView, setReaderMode, actions.setSelectedTool]);
 
   const handleReaderToggle = useCallback(() => {
     setReaderMode(true);
@@ -214,14 +226,20 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
     [state.sidebarsVisible, state.readerMode]
   );
 
-  // Enable URL synchronization for tool selection
+  // URL sync for proper tool navigation
-  useToolWorkflowUrlSync(navigationState.selectedToolKey, actions.selectTool, actions.clearToolSelection, true);
+  useNavigationUrlSync(
+    navigationState.selectedTool,
+    handleToolSelect,
+    handleBackToTools,
+    toolRegistry as ToolRegistry,
+    true
+  );
 
   // Properly memoized context value
   const contextValue = useMemo((): ToolWorkflowContextValue => ({
     // State
     ...state,
-    selectedToolKey: navigationState.selectedToolKey,
+    selectedToolKey: navigationState.selectedTool,
     selectedTool,
     toolRegistry,
 
@@ -232,8 +250,8 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
     setPreviewFile,
     setPageEditorFunctions,
     setSearchQuery,
-    selectTool: actions.selectTool,
+    selectTool: actions.setSelectedTool,
-    clearToolSelection: actions.clearToolSelection,
+    clearToolSelection: () => actions.setSelectedTool(null),
 
     // Tool Reset Actions
     registerToolReset,
@@ -249,7 +267,7 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
     isPanelVisible,
   }), [
     state,
-    navigationState.selectedToolKey,
+    navigationState.selectedTool,
     selectedTool,
     toolRegistry,
     setSidebarsVisible,
@@ -258,8 +276,7 @@ export function ToolWorkflowProvider({ children }: ToolWorkflowProviderProps) {
     setPreviewFile,
     setPageEditorFunctions,
     setSearchQuery,
-    actions.selectTool,
+    actions.setSelectedTool,
-    actions.clearToolSelection,
     registerToolReset,
     resetTool,
     handleToolSelect,

frontend/src/data/toolsTaxonomy.ts

@@ -1,8 +1,9 @@
 import { type TFunction } from 'i18next';
 import React from 'react';
-import { ToolOperationHook, ToolOperationConfig } from '../hooks/tools/shared/useToolOperation';
+import { ToolOperationConfig } from '../hooks/tools/shared/useToolOperation';
 import { BaseToolProps } from '../types/tool';
-import { BaseParameters } from '../types/parameters';
+import { WorkbenchType } from '../types/workbench';
+import { ToolId } from '../types/toolId';
 
 export enum SubcategoryId {
   SIGNING = 'signing',
@@ -28,7 +29,6 @@ export type ToolRegistryEntry = {
 	icon: React.ReactNode;
 	name: string;
 	component: React.ComponentType<BaseToolProps> | null;
-	view: 'sign' | 'security' | 'format' | 'extract' | 'view' | 'merge' | 'pageEditor' | 'convert' | 'redact' | 'split' | 'convert' | 'remove' | 'compress' | 'external';
 	description: string;
 	categoryId: ToolCategoryId;
 	subcategoryId: SubcategoryId;
@@ -37,13 +37,17 @@ export type ToolRegistryEntry = {
 	endpoints?: string[];
 	link?: string;
 	type?: string;
+	// URL path for routing (e.g., '/split-pdfs', '/compress-pdf')
+	urlPath?: string;
+	// Workbench type for navigation
+	workbench?: WorkbenchType;
 	// Operation configuration for automation
 	operationConfig?: ToolOperationConfig<any>;
 	// Settings component for automation configuration
 	settingsComponent?: React.ComponentType<any>;
 }
 
-export type ToolRegistry = Record<string /* FIX ME: Should be ToolId */, ToolRegistryEntry>;
+export type ToolRegistry = Record<ToolId, ToolRegistryEntry>;
 
 export const SUBCATEGORY_ORDER: SubcategoryId[] = [
   SubcategoryId.SIGNING,
@@ -107,3 +111,30 @@ export const getAllApplicationEndpoints = (
   const convEp = extensionToEndpoint ? getConversionEndpoints(extensionToEndpoint) : [];
   return Array.from(new Set([...toolEp, ...convEp]));
 };
+
+/**
+ * Default workbench for tools that don't specify one
+ * Returns null to trigger the default case in Workbench component (ToolRenderer)
+ */
+export const getDefaultToolWorkbench = (): WorkbenchType => 'fileEditor';
+
+/**
+ * Get workbench type for a tool
+ */
+export const getToolWorkbench = (tool: ToolRegistryEntry): WorkbenchType => {
+  return tool.workbench || getDefaultToolWorkbench();
+};
+
+/**
+ * Get URL path for a tool
+ */
+export const getToolUrlPath = (toolId: string, tool: ToolRegistryEntry): string => {
+  return tool.urlPath || `/${toolId.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+};
+
+/**
+ * Check if a tool ID exists in the registry
+ */
+export const isValidToolId = (toolId: string, registry: ToolRegistry): boolean => {
+  return toolId in registry;
+};

frontend/src/hooks/tools/automate/useAutomationForm.ts

@@ -2,12 +2,12 @@ import { useState, useEffect, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import { AutomationTool, AutomationConfig, AutomationMode } from '../../../types/automation';
 import { AUTOMATION_CONSTANTS } from '../../../constants/automation';
-import { ToolRegistryEntry } from '../../../data/toolsTaxonomy';
+import { ToolRegistry } from '../../../data/toolsTaxonomy';
 
 interface UseAutomationFormProps {
   mode: AutomationMode;
   existingAutomation?: AutomationConfig;
-  toolRegistry: Record<string, ToolRegistryEntry>;
+  toolRegistry: ToolRegistry;
 }
 
 export function useAutomationForm({ mode, existingAutomation, toolRegistry }: UseAutomationFormProps) {
@@ -19,12 +19,12 @@ export function useAutomationForm({ mode, existingAutomation, toolRegistry }: Us
   const [selectedTools, setSelectedTools] = useState<AutomationTool[]>([]);
 
   const getToolName = useCallback((operation: string) => {
-    const tool = toolRegistry?.[operation] as any;
+    const tool = toolRegistry?.[operation as keyof ToolRegistry] as any;
     return tool?.name || t(`tools.${operation}.name`, operation);
   }, [toolRegistry, t]);
 
   const getToolDefaultParameters = useCallback((operation: string): Record<string, any> => {
-    const config = toolRegistry[operation]?.operationConfig;
+    const config = toolRegistry[operation as keyof ToolRegistry]?.operationConfig;
     if (config?.defaultParameters) {
       return { ...config.defaultParameters };
     }

frontend/src/hooks/useSuggestedTools.ts

@@ -1,5 +1,6 @@
 import { useMemo } from 'react';
 import { useNavigationActions, useNavigationState } from '../contexts/NavigationContext';
+import { ToolId } from '../types/toolId';
 
 // Material UI Icons
 import CompressIcon from '@mui/icons-material/Compress';
@@ -9,7 +10,7 @@ import CropIcon from '@mui/icons-material/Crop';
 import TextFieldsIcon from '@mui/icons-material/TextFields';
 
 export interface SuggestedTool {
-  id: string /* FIX ME: Should be ToolId */;
+  id: ToolId;
   title: string;
   icon: React.ComponentType<any>;
   navigate: () => void;
@@ -32,7 +33,7 @@ const ALL_SUGGESTED_TOOLS: Omit<SuggestedTool, 'navigate'>[] = [
     icon: CleaningServicesIcon
   },
   {
-    id: 'splitPdf',
+    id: 'split',
     title: 'Split',
     icon: CropIcon
   },
@@ -45,16 +46,16 @@ const ALL_SUGGESTED_TOOLS: Omit<SuggestedTool, 'navigate'>[] = [
 
 export function useSuggestedTools(): SuggestedTool[] {
   const { actions } = useNavigationActions();
-  const { selectedToolKey } = useNavigationState();
+  const { selectedTool } = useNavigationState();
 
   return useMemo(() => {
     // Filter out the current tool
-    const filteredTools = ALL_SUGGESTED_TOOLS.filter(tool => tool.id !== selectedToolKey);
+    const filteredTools = ALL_SUGGESTED_TOOLS.filter(tool => tool.id !== selectedTool);
 
     // Add navigation function to each tool
     return filteredTools.map(tool => ({
       ...tool,
-      navigate: () => actions.handleToolSelect(tool.id)
+      navigate: () => actions.setSelectedTool(tool.id)
     }));
-  }, [selectedToolKey, actions]);
+  }, [selectedTool, actions]);
 }

frontend/src/hooks/useToolManagement.tsx

@@ -35,7 +35,7 @@ export const useToolManagement = (): ToolManagementResult => {
 
   const isToolAvailable = useCallback((toolKey: string): boolean => {
     if (endpointsLoading) return true;
-    const endpoints = baseRegistry[toolKey]?.endpoints || [];
+    const endpoints = baseRegistry[toolKey as keyof typeof baseRegistry]?.endpoints || [];
     return endpoints.length === 0 || endpoints.some((endpoint: string) => endpointStatus[endpoint] === true);
   }, [endpointsLoading, endpointStatus, baseRegistry]);
 

frontend/src/hooks/useToolUrlRouting.ts

@@ -1,129 +0,0 @@
-// src/hooks/useToolUrlRouting.ts
-// Focused hook for URL <-> tool-key mapping and browser history sync.
-
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-
-export interface UseToolUrlRoutingOpts {
-  /** Currently selected tool key (from context). */
-  selectedToolKey: string | null;
-  /** Registry of available tools (key -> tool metadata). */
-  toolRegistry: Record<string, any> | null | undefined;
-  /** Select a tool (no extra side-effects). */
-  selectTool: (toolKey: string) => void;
-  /** Clear selection. */
-  clearToolSelection: () => void;
-  /** Called once during initialization if URL contains a tool; may trigger UI changes. */
-  onInitSelect?: (toolKey: string) => void;
-  /** Called when navigating via back/forward (popstate). Defaults to selectTool. */
-  onPopStateSelect?: (toolKey: string) => void;
-  /** Optional base path if the app isn't served at "/" (no trailing slash). Default: "" (root). */
-  basePath?: string;
-}
-
-export function useToolUrlRouting(opts: UseToolUrlRoutingOpts) {
-  const {
-    selectedToolKey,
-    toolRegistry,
-    selectTool,
-    clearToolSelection,
-    onInitSelect,
-    onPopStateSelect,
-    basePath = '',
-  } = opts;
-
-  // Central slug map; keep here to co-locate routing policy.
-  const urlMap = useMemo(
-    () =>
-      new Map<string, string>([
-        ['compress', 'compress-pdf'],
-        ['split', 'split-pdf'],
-        ['convert', 'convert-pdf'],
-        ['ocr', 'ocr-pdf'],
-        ['merge', 'merge-pdf'],
-        ['rotate', 'rotate-pdf'],
-      ]),
-    []
-  );
-
-  const getToolUrlSlug = useCallback(
-    (toolKey: string) => urlMap.get(toolKey) ?? toolKey,
-    [urlMap]
-  );
-
-  const getToolKeyFromSlug = useCallback(
-    (slug: string) => {
-      for (const [key, value] of urlMap) {
-        if (value === slug) return key;
-      }
-      return slug; // fall back to raw key
-    },
-    [urlMap]
-  );
-
-  // Internal flag to avoid clearing URL on initial mount.
-  const [hasInitialized, setHasInitialized] = useState(false);
-
-  // Normalize a pathname by stripping basePath and leading slash.
-  const normalizePath = useCallback(
-    (fullPath: string) => {
-      let p = fullPath;
-      if (basePath && p.startsWith(basePath)) {
-        p = p.slice(basePath.length);
-      }
-      if (p.startsWith('/')) p = p.slice(1);
-      return p;
-    },
-    [basePath]
-  );
-
-  // Update URL when tool changes (but not on first paint before any selection happens).
-  useEffect(() => {
-    if (selectedToolKey) {
-      const slug = getToolUrlSlug(selectedToolKey);
-      const newUrl = `${basePath}/${slug}`.replace(/\/+/, '/');
-      window.history.replaceState({}, '', newUrl);
-      setHasInitialized(true);
-    } else if (hasInitialized) {
-      const rootUrl = basePath || '/';
-      window.history.replaceState({}, '', rootUrl);
-    }
-  }, [selectedToolKey, getToolUrlSlug, hasInitialized, basePath]);
-
-  // Initialize from URL when the registry is ready and nothing is selected yet.
-  useEffect(() => {
-    if (!toolRegistry || Object.keys(toolRegistry).length === 0) return;
-    if (selectedToolKey) return; // don't override explicit selection
-
-    const currentPath = normalizePath(window.location.pathname);
-    if (currentPath) {
-      const toolKey = getToolKeyFromSlug(currentPath);
-      if (toolRegistry[toolKey]) {
-        (onInitSelect ?? selectTool)(toolKey);
-      }
-    }
-  }, [toolRegistry, selectedToolKey, getToolKeyFromSlug, selectTool, onInitSelect, normalizePath]);
-
-  // Handle browser back/forward. NOTE: useRef needs an initial value in TS.
-  const popHandlerRef = useRef<((this: Window, ev: PopStateEvent) => any) | null>(null);
-
-  useEffect(() => {
-    popHandlerRef.current = () => {
-      const path = normalizePath(window.location.pathname);
-      if (path) {
-        const toolKey = getToolKeyFromSlug(path);
-        if (toolRegistry && toolRegistry[toolKey]) {
-          (onPopStateSelect ?? selectTool)(toolKey);
-          return;
-        }
-      }
-      clearToolSelection();
-    };
-
-    const handler = (e: PopStateEvent) => popHandlerRef.current?.call(window, e);
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  }, [toolRegistry, selectTool, clearToolSelection, getToolKeyFromSlug, onPopStateSelect, normalizePath]);
-
-  // Expose pure helpers if you want them elsewhere (optional).
-  return { getToolUrlSlug, getToolKeyFromSlug };
-}

frontend/src/hooks/useUrlSync.ts

@@ -1,120 +1,107 @@
 /**
- * URL synchronization hooks for tool routing
+ * URL synchronization hooks for tool routing with registry support
  */
 
-import { useEffect, useCallback } from 'react';
+import { useEffect, useCallback, useRef } from 'react';
-import { ModeType } from '../types/navigation';
+import { ToolId } from '../types/toolId';
 import { parseToolRoute, updateToolRoute, clearToolRoute } from '../utils/urlRouting';
+import { ToolRegistry } from '../data/toolsTaxonomy';
+import { firePixel } from '../utils/scarfTracking';
 
 /**
- * Hook to sync navigation mode with URL
+ * Hook to sync workbench and tool with URL using registry
  */
 export function useNavigationUrlSync(
-  currentMode: ModeType,
+  selectedTool: ToolId | null,
-  setMode: (mode: ModeType) => void,
+  handleToolSelect: (toolId: string) => void,
+  clearToolSelection: () => void,
+  registry: ToolRegistry,
   enableSync: boolean = true
 ) {
-  // Initialize mode from URL on mount
+  const hasInitialized = useRef(false);
+  const prevSelectedTool = useRef<ToolId | null>(null);
+  // Initialize workbench and tool from URL on mount
   useEffect(() => {
     if (!enableSync) return;
 
-    const route = parseToolRoute();
+    // Fire pixel for initial page load
-    if (route.mode !== currentMode) {
+    const currentPath = window.location.pathname;
-      setMode(route.mode);
+    firePixel(currentPath);
+
+    const route = parseToolRoute(registry);
+    if (route.toolId !== selectedTool) {
+      if (route.toolId) {
+        handleToolSelect(route.toolId);
+      } else if (selectedTool !== null) {
+        // Only clear selection if we actually had a tool selected
+        // Don't clear on initial load when selectedTool starts as null
+        clearToolSelection();
+      }
     }
+
+    hasInitialized.current = true;
   }, []); // Only run on mount
 
-  // Update URL when mode changes
+  // Update URL when tool or workbench changes
   useEffect(() => {
     if (!enableSync) return;
 
-    if (currentMode === 'pageEditor') {
+    if (selectedTool) {
-      clearToolRoute();
+      updateToolRoute(selectedTool, registry, false); // Use pushState for user navigation
-    } else {
+    } else if (prevSelectedTool.current !== null) {
-      updateToolRoute(currentMode, currentMode);
+      // Only clear URL if we had a tool before (user navigated away)
+      // Don't clear on initial load when both current and previous are null
+      if (window.location.pathname !== '/') {
+        clearToolRoute(false); // Use pushState for user navigation
+      }
     }
-  }, [currentMode, enableSync]);
+
+    prevSelectedTool.current = selectedTool;
+  }, [selectedTool, registry, enableSync]);
 
   // Handle browser back/forward navigation
   useEffect(() => {
     if (!enableSync) return;
 
     const handlePopState = () => {
-      const route = parseToolRoute();
+      const route = parseToolRoute(registry);
-      if (route.mode !== currentMode) {
+      if (route.toolId !== selectedTool) {
-        setMode(route.mode);
+        // Fire pixel for back/forward navigation
+        const currentPath = window.location.pathname;
+        firePixel(currentPath);
+
+        if (route.toolId) {
+          handleToolSelect(route.toolId);
+        } else {
+          clearToolSelection();
+        }
       }
     };
 
     window.addEventListener('popstate', handlePopState);
     return () => window.removeEventListener('popstate', handlePopState);
-  }, [currentMode, setMode, enableSync]);
+  }, [selectedTool, handleToolSelect, clearToolSelection, registry, enableSync]);
 }
 
 /**
- * Hook to sync tool workflow with URL
+ * Hook to programmatically navigate to tools with registry support
  */
-export function useToolWorkflowUrlSync(
+export function useToolNavigation(registry: ToolRegistry) {
-  selectedToolKey: string | null,
+  const navigateToTool = useCallback((toolId: ToolId) => {
-  selectTool: (toolKey: string) => void,
+    updateToolRoute(toolId, registry);
-  clearTool: () => void,
-  enableSync: boolean = true
-) {
-  // Initialize tool from URL on mount
-  useEffect(() => {
-    if (!enableSync) return;
-    
-    const route = parseToolRoute();
-    if (route.toolKey && route.toolKey !== selectedToolKey) {
-      selectTool(route.toolKey);
-    } else if (!route.toolKey && selectedToolKey) {
-      clearTool();
-    }
-  }, []); // Only run on mount
-
-  // Update URL when tool changes
-  useEffect(() => {
-    if (!enableSync) return;
-    
-    if (selectedToolKey) {
-      const route = parseToolRoute();
-      if (route.toolKey !== selectedToolKey) {
-        updateToolRoute(selectedToolKey as ModeType, selectedToolKey);
-      }
-    }
-  }, [selectedToolKey, enableSync]);
-}
-
-/**
- * Hook to get current URL route information
- */
-export function useCurrentRoute() {
-  const getCurrentRoute = useCallback(() => {
-    return parseToolRoute();
-  }, []);
-
-  return getCurrentRoute;
-}
-
-/**
- * Hook to programmatically navigate to tools
- */
-export function useToolNavigation() {
-  const navigateToTool = useCallback((toolKey: string) => {
-    updateToolRoute(toolKey as ModeType, toolKey);
 
     // Dispatch a custom event to notify other components
     window.dispatchEvent(new CustomEvent('toolNavigation', {
-      detail: { toolKey } 
+      detail: { toolId }
     }));
-  }, []);
+  }, [registry]);
 
   const navigateToHome = useCallback(() => {
     clearToolRoute();
 
     // Dispatch a custom event to notify other components
     window.dispatchEvent(new CustomEvent('toolNavigation', {
-      detail: { toolKey: null } 
+      detail: { toolId: null }
     }));
   }, []);
 
@@ -123,3 +110,14 @@ export function useToolNavigation() {
     navigateToHome
   };
 }
+
+/**
+ * Hook to get current URL route information with registry support
+ */
+export function useCurrentRoute(registry: ToolRegistry) {
+  const getCurrentRoute = useCallback(() => {
+    return parseToolRoute(registry);
+  }, [registry]);
+
+  return getCurrentRoute;
+}

frontend/src/index.tsx

@@ -1,4 +1,5 @@
 import '@mantine/core/styles.css';
+import '../vite-env.d.ts';
 import './index.css'; // Import Tailwind CSS
 import React from 'react';
 import ReactDOM from 'react-dom/client';
@@ -6,6 +7,7 @@ import { ColorSchemeScript } from '@mantine/core';
 import { BrowserRouter } from 'react-router-dom';
 import App from './App';
 import './i18n'; // Initialize i18next
+import { PostHogProvider } from 'posthog-js/react';
 
 // Compute initial color scheme
 function getInitialScheme(): 'light' | 'dark' {
@@ -27,9 +29,18 @@ const root = ReactDOM.createRoot(container); // Finds the root DOM element
 root.render(
   <React.StrictMode>
     <ColorSchemeScript defaultColorScheme={getInitialScheme()} />
-    <BrowserRouter>
+    <PostHogProvider
-      <App />
+      apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_KEY}
-    </BrowserRouter>
+      options={{
+        api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
+        defaults: '2025-05-24',
+        capture_exceptions: true, // This enables capturing exceptions using Error Tracking, set to false if you don't want this
+        debug: import.meta.env.MODE === 'development',
+      }}
+    >
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </PostHogProvider>
   </React.StrictMode>
 );
-

frontend/src/tools/Automate.tsx

@@ -2,7 +2,7 @@ import React, { useState, useMemo, useEffect } from "react";
 import { useTranslation } from "react-i18next";
 import { useFileContext } from "../contexts/FileContext";
 import { useFileSelection } from "../contexts/FileContext";
-import { useNavigation } from "../contexts/NavigationContext";
+import { useNavigationActions } from "../contexts/NavigationContext";
 import { useToolWorkflow } from "../contexts/ToolWorkflowContext";
 
 import { createToolFlow } from "../components/tools/shared/createToolFlow";
@@ -21,7 +21,7 @@ import { AUTOMATION_STEPS } from "../constants/automation";
 const Automate = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
   const { t } = useTranslation();
   const { selectedFiles } = useFileSelection();
-  const { setMode } = useNavigation();
+  const { actions } = useNavigationActions();
   const { registerToolReset } = useToolWorkflow();
 
   const [currentStep, setCurrentStep] = useState<AutomationStep>(AUTOMATION_STEPS.SELECTION);
@@ -161,7 +161,7 @@ const Automate = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
   const filesPlaceholder = useMemo(() => {
     if (currentStep === AUTOMATION_STEPS.RUN && stepData.automation?.operations?.length) {
       const firstOperation = stepData.automation.operations[0];
-      const toolConfig = toolRegistry[firstOperation.operation];
+      const toolConfig = toolRegistry[firstOperation.operation as keyof typeof toolRegistry];
 
       // Check if the tool has supportedFormats that include non-PDF formats
       if (toolConfig?.supportedFormats && toolConfig.supportedFormats.length > 1) {
@@ -223,7 +223,7 @@ const Automate = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
       title: t('automate.reviewTitle', 'Automation Results'),
       onFileClick: (file: File) => {
         onPreviewFile?.(file);
-        setMode('viewer');
+        actions.setWorkbench('viewer');
       }
     }
   });

frontend/src/types/navigation.ts

@@ -1,42 +1,19 @@
 /**
- * Shared navigation types to avoid circular dependencies
+ * Navigation types for workbench and tool separation
  */
 
-// Navigation mode types - complete list to match contexts
+import { WorkbenchType } from './workbench';
-export type ModeType =
+import { ToolId } from './toolId';
-  | 'viewer'
-  | 'pageEditor'
-  | 'fileEditor'
-  | 'merge'
-  | 'split'
-  | 'compress'
-  | 'ocr'
-  | 'convert'
-  | 'sanitize'
-  | 'addPassword'
-  | 'changePermissions'
-  | 'addWatermark'
-  | 'removePassword'
-  | 'single-large-page'
-  | 'repair'
-  | 'unlockPdfForms'
-  | 'removeCertificateSign';
 
-// Utility functions for mode handling
+// Navigation state
-export const isValidMode = (mode: string): mode is ModeType => {
+export interface NavigationState {
-  const validModes: ModeType[] = [
+  workbench: WorkbenchType;
-    'viewer', 'pageEditor', 'fileEditor', 'merge', 'split', 
+  selectedTool: ToolId | null;
-    'compress', 'ocr', 'convert', 'addPassword', 'changePermissions', 
+}
-    'sanitize', 'addWatermark', 'removePassword', 'single-large-page',
-    'repair', 'unlockPdfForms', 'removeCertificateSign'
-  ];
-  return validModes.includes(mode as ModeType);
-};
 
-export const getDefaultMode = (): ModeType => 'fileEditor';
 
 // Route parsing result
 export interface ToolRoute {
-  mode: ModeType;
+  workbench: WorkbenchType;
-  toolKey: string | null;
+  toolId: ToolId | null;
 }

frontend/src/types/navigationActions.ts

@@ -2,10 +2,12 @@
  * Navigation action interfaces to break circular dependencies
  */
 
-import { ModeType } from './navigation';
+import { WorkbenchType } from './workbench';
+import { ToolId } from './toolId';
 
 export interface NavigationActions {
-  setMode: (mode: ModeType) => void;
+  setWorkbench: (workbench: WorkbenchType) => void;
+  setSelectedTool: (toolId: ToolId | null) => void;
   setHasUnsavedChanges: (hasChanges: boolean) => void;
   showNavigationWarning: (show: boolean) => void;
   requestNavigation: (navigationFn: () => void) => void;
@@ -14,7 +16,8 @@ export interface NavigationActions {
 }
 
 export interface NavigationState {
-  currentMode: ModeType;
+  workbench: WorkbenchType;
+  selectedTool: ToolId | null;
   hasUnsavedChanges: boolean;
   pendingNavigation: (() => void) | null;
   showNavigationWarning: boolean;

frontend/src/types/toolId.ts

@@ -0,0 +1,25 @@
+// Define all possible tool IDs as source of truth
+const TOOL_IDS = [
+  'certSign', 'sign', 'addPassword', 'remove-password', 'removePages', 'remove-blank-pages', 'remove-annotations', 'remove-image',
+  'change-permissions', 'addWatermark',
+  'sanitize', 'auto-split-pages', 'auto-split-by-size-count', 'split', 'mergePdfs',
+  'convert', 'ocr', 'add-image', 'rotate',
+  'detect-split-scanned-photos',
+  'edit-table-of-contents',
+  'scanner-effect',
+  'auto-rename-pdf-file', 'multi-page-layout', 'adjust-page-size-scale', 'adjust-contrast', 'cropPdf', 'single-large-page', 'multi-tool',
+  'repair', 'compare', 'addPageNumbers', 'redact',
+  'flatten', 'remove-certificate-sign',
+  'unlock-pdf-forms', 'compress', 'extract-page', 'reorganize-pages', 'extract-images',
+  'add-stamp', 'add-attachments', 'change-metadata', 'overlay-pdfs',
+  'manage-certificates', 'get-all-info-on-pdf', 'validate-pdf-signature', 'read', 'automate', 'replace-and-invert-color',
+  'show-javascript', 'dev-api', 'dev-folder-scanning', 'dev-sso-guide', 'dev-airgapped'
+] as const;
+
+// Tool identity - what PDF operation we're performing (type-safe)
+export type ToolId = typeof TOOL_IDS[number];
+
+// Type guard using the same source of truth
+export const isValidToolId = (value: string): value is ToolId => {
+  return TOOL_IDS.includes(value as ToolId);
+};

frontend/src/types/workbench.ts

@@ -0,0 +1,12 @@
+// Define workbench values once as source of truth
+const WORKBENCH_TYPES = ['viewer', 'pageEditor', 'fileEditor'] as const;
+
+// Workbench types - how the user interacts with content
+export type WorkbenchType = typeof WORKBENCH_TYPES[number];
+
+export const getDefaultWorkbench = (): WorkbenchType => 'fileEditor';
+
+// Type guard using the same source of truth
+export const isValidWorkbench = (value: string): value is WorkbenchType => {
+  return WORKBENCH_TYPES.includes(value as WorkbenchType);
+};

frontend/src/utils/automationExecutor.ts

@@ -31,7 +31,7 @@ export const executeToolOperationWithPrefix = async (
 ): Promise<File[]> => {
   console.log(`🔧 Executing tool: ${operationName}`, { parameters, fileCount: files.length });
 
-  const config = toolRegistry[operationName]?.operationConfig;
+  const config = toolRegistry[operationName as keyof ToolRegistry]?.operationConfig;
   if (!config) {
     console.error(`❌ Tool operation not supported: ${operationName}`);
     throw new Error(`Tool operation not supported: ${operationName}`);

frontend/src/utils/scarfTracking.ts

@@ -0,0 +1,28 @@
+let lastFiredPathname: string | null = null;
+let lastFiredTime = 0;
+
+/**
+ * Fire scarf pixel for analytics tracking
+ * Only fires if pathname is different from last call or enough time has passed
+ */
+export function firePixel(pathname: string): void {
+  const now = Date.now();
+
+  // Only fire if pathname changed or it's been at least 1 second since last fire
+  if (pathname === lastFiredPathname && now - lastFiredTime < 250) {
+    return;
+  }
+
+  lastFiredPathname = pathname;
+  lastFiredTime = now;
+
+  const url = 'https://static.scarf.sh/a.png?x-pxid=3c1d68de-8945-4e9f-873f-65320b6fabf7'
+             + '&path=' + encodeURIComponent(pathname)
+
+  const img = new Image();
+  img.referrerPolicy = "no-referrer-when-downgrade";
+  img.src = url;
+
+  console.log("ScarfPixel: Fire to... " + pathname);
+}
+

frontend/src/utils/urlMapping.ts

@@ -0,0 +1,33 @@
+import { ToolId } from '../types/toolId';
+
+// Map URL paths to tool keys (multiple URLs can map to same tool)
+export const URL_TO_TOOL_MAP: Record<string, ToolId> = {
+  '/split-pdfs': 'split',
+  '/split': 'split',
+  '/merge-pdfs': 'mergePdfs',
+  '/compress-pdf': 'compress',
+  '/convert': 'convert',
+  '/convert-pdf': 'convert',
+  '/file-to-pdf': 'convert',
+  '/eml-to-pdf': 'convert',
+  '/html-to-pdf': 'convert',
+  '/markdown-to-pdf': 'convert',
+  '/pdf-to-csv': 'convert',
+  '/pdf-to-img': 'convert',
+  '/pdf-to-markdown': 'convert',
+  '/pdf-to-pdfa': 'convert',
+  '/pdf-to-word': 'convert',
+  '/pdf-to-xml': 'convert',
+  '/add-password': 'addPassword',
+  '/change-permissions': 'change-permissions',
+  '/sanitize-pdf': 'sanitize',
+  '/ocr': 'ocr',
+  '/ocr-pdf': 'ocr',
+  '/add-watermark': 'addWatermark',
+  '/remove-password': 'remove-password',
+  '/single-large-page': 'single-large-page',
+  '/repair': 'repair',
+  '/unlock-pdf-forms': 'unlock-pdf-forms',
+  '/remove-certificate-sign': 'remove-certificate-sign',
+  '/remove-cert-sign': 'remove-certificate-sign'
+};

frontend/src/utils/urlRouting.ts

@@ -1,167 +1,127 @@
 /**
- * URL routing utilities for tool navigation
+ * URL routing utilities for tool navigation with registry support
- * Provides clean URL routing for the V2 tool system
  */
 
-import { ModeType, isValidMode as isValidModeType, getDefaultMode, ToolRoute } from '../types/navigation';
+import { ToolRoute } from '../types/navigation';
+import { ToolId, isValidToolId } from '../types/toolId';
+import { getDefaultWorkbench } from '../types/workbench';
+import { ToolRegistry, getToolWorkbench, getToolUrlPath } from '../data/toolsTaxonomy';
+import { firePixel } from './scarfTracking';
+import { URL_TO_TOOL_MAP } from './urlMapping';
 
 /**
  * Parse the current URL to extract tool routing information
  */
-export function parseToolRoute(): ToolRoute {
+export function parseToolRoute(registry: ToolRegistry): ToolRoute {
   const path = window.location.pathname;
   const searchParams = new URLSearchParams(window.location.search);
 
-  // Extract tool from URL path (e.g., /split-pdf -> split)
+  // First, check URL mapping for multiple URL aliases
-  const toolMatch = path.match(/\/([a-zA-Z-]+)(?:-pdf)?$/);
+  const mappedToolId = URL_TO_TOOL_MAP[path];
-  if (toolMatch) {
+  if (mappedToolId && registry[mappedToolId]) {
-    const toolKey = toolMatch[1].toLowerCase();
+    const tool = registry[mappedToolId];
-    
+    return {
-    // Map URL paths to tool keys and modes (excluding internal UI modes)
+      workbench: getToolWorkbench(tool),
-    const toolMappings: Record<string, { mode: ModeType; toolKey: string }> = {
+      toolId: mappedToolId
-      'split': { mode: 'split', toolKey: 'split' },
-      'merge': { mode: 'merge', toolKey: 'merge' },
-      'compress': { mode: 'compress', toolKey: 'compress' },
-      'convert': { mode: 'convert', toolKey: 'convert' },
-      'add-password': { mode: 'addPassword', toolKey: 'addPassword' },
-      'change-permissions': { mode: 'changePermissions', toolKey: 'changePermissions' },
-      'sanitize': { mode: 'sanitize', toolKey: 'sanitize' },
-      'ocr': { mode: 'ocr', toolKey: 'ocr' }
     };
+  }
 
-    const mapping = toolMappings[toolKey];
+  // Fallback: Try to find tool by primary URL path in registry
-    if (mapping) {
+  for (const [toolId, tool] of Object.entries(registry)) {
+    const toolUrlPath = getToolUrlPath(toolId, tool);
+    if (path === toolUrlPath && isValidToolId(toolId)) {
       return {
-        mode: mapping.mode,
+        workbench: getToolWorkbench(tool),
-        toolKey: mapping.toolKey
+        toolId
       };
     }
   }
 
   // Check for query parameter fallback (e.g., ?tool=split)
   const toolParam = searchParams.get('tool');
-  if (toolParam && isValidModeType(toolParam)) {
+  if (toolParam && isValidToolId(toolParam) && registry[toolParam]) {
+    const tool = registry[toolParam];
     return {
-      mode: toolParam as ModeType,
+      workbench: getToolWorkbench(tool),
-      toolKey: toolParam
+      toolId: toolParam
     };
   }
 
-  // Default to page editor for home page
+  // Default to fileEditor workbench for home page
   return {
-    mode: getDefaultMode(),
+    workbench: getDefaultWorkbench(),
-    toolKey: null
+    toolId: null
   };
 }
 
 /**
- * Update the URL to reflect the current tool selection
+ * Update URL and fire analytics pixel
- * Internal UI modes (viewer, fileEditor, pageEditor) don't get URLs
  */
-export function updateToolRoute(mode: ModeType, toolKey?: string): void {
+function updateUrl(newPath: string, searchParams: URLSearchParams, replace: boolean = false): void {
   const currentPath = window.location.pathname;
-  const searchParams = new URLSearchParams(window.location.search);
+  const queryString = searchParams.toString();
+  const fullUrl = newPath + (queryString ? `?${queryString}` : '');
 
-  // Don't create URLs for internal UI modes
+  // Only update URL and fire pixel if something actually changed
-  if (mode === 'viewer' || mode === 'fileEditor' || mode === 'pageEditor') {
+  if (currentPath !== newPath || window.location.search !== (queryString ? `?${queryString}` : '')) {
-    // If we're switching to an internal mode, clear any existing tool URL
+    if (replace) {
-    if (currentPath !== '/') {
+      window.history.replaceState(null, '', fullUrl);
-      clearToolRoute();
+    } else {
+      window.history.pushState(null, '', fullUrl);
     }
+    firePixel(newPath);
+  }
+}
+
+/**
+ * Update the URL to reflect the current tool selection
+ */
+export function updateToolRoute(toolId: ToolId, registry: ToolRegistry, replace: boolean = false): void {
+  const tool = registry[toolId];
+  if (!tool) {
+    console.warn(`Tool ${toolId} not found in registry`);
     return;
   }
 
-  let newPath = '/';
+  const newPath = getToolUrlPath(toolId, tool);
-  
+  const searchParams = new URLSearchParams(window.location.search);
-  // Map modes to URL paths (only for actual tools)
-  if (toolKey) {
-    const pathMappings: Record<string, string> = {
-      'split': '/split-pdf',
-      'merge': '/merge-pdf', 
-      'compress': '/compress-pdf',
-      'convert': '/convert-pdf',
-      'addPassword': '/add-password-pdf',
-      'changePermissions': '/change-permissions-pdf',
-      'sanitize': '/sanitize-pdf',
-      'ocr': '/ocr-pdf'
-    };
-    
-    newPath = pathMappings[toolKey] || `/${toolKey}`;
-  }
 
   // Remove tool query parameter since we're using path-based routing
   searchParams.delete('tool');
 
-  // Construct final URL
+  updateUrl(newPath, searchParams, replace);
-  const queryString = searchParams.toString();
-  const fullUrl = newPath + (queryString ? `?${queryString}` : '');
-  
-  // Update URL without triggering page reload
-  if (currentPath !== newPath || window.location.search !== (queryString ? `?${queryString}` : '')) {
-    window.history.replaceState(null, '', fullUrl);
-  }
 }
 
 /**
  * Clear tool routing and return to home page
  */
-export function clearToolRoute(): void {
+export function clearToolRoute(replace: boolean = false): void {
   const searchParams = new URLSearchParams(window.location.search);
   searchParams.delete('tool');
 
-  const queryString = searchParams.toString();
+  updateUrl('/', searchParams, replace);
-  const url = '/' + (queryString ? `?${queryString}` : '');
-  
-  window.history.replaceState(null, '', url);
 }
 
 /**
- * Get clean tool name for display purposes
+ * Get clean tool name for display purposes using registry
  */
-export function getToolDisplayName(toolKey: string): string {
+export function getToolDisplayName(toolId: ToolId, registry: ToolRegistry): string {
-  const displayNames: Record<string, string> = {
+  const tool = registry[toolId];
-    'split': 'Split PDF',
+  return tool ? tool.name : toolId;
-    'merge': 'Merge PDF',
-    'compress': 'Compress PDF', 
-    'convert': 'Convert PDF',
-    'addPassword': 'Add Password',
-    'changePermissions': 'Change Permissions',
-    'sanitize': 'Sanitize PDF',
-    'ocr': 'OCR PDF'
-  };
-  
-  return displayNames[toolKey] || toolKey;
 }
 
-// Note: isValidMode is now imported from types/navigation.ts
-
 /**
- * Generate shareable URL for current tool state
+ * Generate shareable URL for current tool state using registry
- * Only generates URLs for actual tools, not internal UI modes
  */
-export function generateShareableUrl(mode: ModeType, toolKey?: string): string {
+export function generateShareableUrl(toolId: ToolId | null, registry: ToolRegistry): string {
   const baseUrl = window.location.origin;
 
-  // Don't generate URLs for internal UI modes
+  if (!toolId || !registry[toolId]) {
-  if (mode === 'viewer' || mode === 'fileEditor' || mode === 'pageEditor') {
     return baseUrl;
   }
 
-  if (toolKey) {
+  const tool = registry[toolId];
-    const pathMappings: Record<string, string> = {
-      'split': '/split-pdf',
-      'merge': '/merge-pdf',
-      'compress': '/compress-pdf', 
-      'convert': '/convert-pdf',
-      'addPassword': '/add-password-pdf',
-      'changePermissions': '/change-permissions-pdf',
-      'sanitize': '/sanitize-pdf',
-      'ocr': '/ocr-pdf'
-    };
 
-    const path = pathMappings[toolKey] || `/${toolKey}`;
+  const path = getToolUrlPath(toolId, tool);
-    return `${baseUrl}${path}`;
+  return `${baseUrl}${path}`;
-  }
-  
-  return baseUrl;
 }

frontend/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_PUBLIC_POSTHOG_KEY: string;
+  readonly VITE_PUBLIC_POSTHOG_HOST: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}