semantic markup update

frontend/src/components/DashboardGrid.svelte

@@ -61,6 +61,8 @@
 
   // [DEF:handleSort:Function]
   // @PURPOSE: Toggles sort direction or changes sort column.
+  // @PRE: column name is provided.
+  // @POST: sortColumn and sortDirection state updated.
   function handleSort(column: keyof DashboardMetadata) {
     if (sortColumn === column) {
       sortDirection = sortDirection === "asc" ? "desc" : "asc";
@@ -73,6 +75,8 @@
 
   // [DEF:handleSelectionChange:Function]
   // @PURPOSE: Handles individual checkbox changes.
+  // @PRE: dashboard ID and checked status provided.
+  // @POST: selectedIds array updated and selectionChanged event dispatched.
   function handleSelectionChange(id: number, checked: boolean) {
     let newSelected = [...selectedIds];
     if (checked) {
@@ -87,6 +91,8 @@
 
   // [DEF:handleSelectAll:Function]
   // @PURPOSE: Handles select all checkbox.
+  // @PRE: checked status provided.
+  // @POST: selectedIds array updated for all paginated items and event dispatched.
   function handleSelectAll(checked: boolean) {
     let newSelected = [...selectedIds];
     if (checked) {
@@ -105,6 +111,8 @@
 
   // [DEF:goToPage:Function]
   // @PURPOSE: Changes current page.
+  // @PRE: page index is provided.
+  // @POST: currentPage state updated if within valid range.
   function goToPage(page: number) {
     if (page >= 0 && page < totalPages) {
       currentPage = page;

frontend/src/components/DynamicForm.svelte

@@ -23,6 +23,8 @@
     // [DEF:handleSubmit:Function]
     /**
      * @purpose Dispatches the submit event with the form data.
+     * @pre formData contains user input.
+     * @post 'submit' event is dispatched with formData.
      */
     function handleSubmit() {
         console.log("[DynamicForm][Action] Submitting form data.", { formData });
@@ -33,6 +35,8 @@
     // [DEF:initializeForm:Function]
     /**
      * @purpose Initialize form data with default values from the schema.
+     * @pre schema is provided and contains properties.
+     * @post formData is initialized with default values or empty strings.
      */
     function initializeForm() {
         if (schema && schema.properties) {

frontend/src/components/EnvSelector.svelte

@@ -24,6 +24,8 @@
   // [DEF:handleSelect:Function]
   /**
    * @purpose Dispatches the selection change event.
+   * @pre     event.target must be an HTMLSelectElement.
+   * @post    selectedId is updated and 'change' event is dispatched.
    * @param   {Event} event - The change event from the select element.
    */
   function handleSelect(event: Event) {

frontend/src/components/MappingTable.svelte

@@ -25,6 +25,8 @@
   // [DEF:updateMapping:Function]
   /**
    * @purpose Updates a mapping for a specific source database.
+   * @pre sourceUuid and targetUuid are provided.
+   * @post 'update' event is dispatched.
    */
   function updateMapping(sourceUuid: string, targetUuid: string) {
     dispatch('update', { sourceUuid, targetUuid });
@@ -34,6 +36,8 @@
   // [DEF:getSuggestion:Function]
   /**
    * @purpose Finds a suggestion for a source database.
+   * @pre sourceUuid is provided.
+   * @post Returns matching suggestion object or undefined.
    */
   function getSuggestion(sourceUuid: string) {
     return suggestions.find(s => s.source_db_uuid === sourceUuid);

frontend/src/components/MissingMappingModal.svelte

@@ -25,6 +25,8 @@
 
   // [DEF:resolve:Function]
   // @PURPOSE: Dispatches the resolution event with the selected mapping.
+  // @PRE: selectedTargetUuid must be set.
+  // @POST: 'resolve' event is dispatched and modal is hidden.
   function resolve() {
     if (!selectedTargetUuid) return;
     dispatch('resolve', {
@@ -38,6 +40,8 @@
 
   // [DEF:cancel:Function]
   // @PURPOSE: Cancels the mapping resolution modal.
+  // @PRE: Modal is open.
+  // @POST: 'cancel' event is dispatched and modal is hidden.
   function cancel() {
     dispatch('cancel');
     show = false;

frontend/src/components/PasswordPrompt.svelte

@@ -20,6 +20,8 @@
     
     // [DEF:handleSubmit:Function]
     // @PURPOSE: Validates and dispatches the passwords to resume the task.
+    // @PRE: All database passwords must be entered.
+    // @POST: 'resume' event is dispatched with passwords.
     function handleSubmit() {
         if (submitting) return;
         
@@ -38,6 +40,8 @@
     
     // [DEF:handleCancel:Function]
     // @PURPOSE: Cancels the password prompt.
+    // @PRE: Modal is open.
+    // @POST: 'cancel' event is dispatched and show is set to false.
     function handleCancel() {
         dispatch('cancel');
         show = false;

frontend/src/components/TaskHistory.svelte

@@ -17,6 +17,8 @@
     
     // [DEF:fetchTasks:Function]
     // @PURPOSE: Fetches the list of recent tasks from the API.
+    // @PRE: None.
+    // @POST: tasks array is updated and selectedTask status synchronized.
     async function fetchTasks() {
         try {
             const res = await fetch('/api/tasks?limit=10');
@@ -47,6 +49,8 @@
     
     // [DEF:clearTasks:Function]
     // @PURPOSE: Clears tasks from the history, optionally filtered by status.
+    // @PRE: User confirms deletion via prompt.
+    // @POST: Tasks are deleted from backend and list is re-fetched.
     async function clearTasks(status = null) {
         if (!confirm('Are you sure you want to clear tasks?')) return;
         try {
@@ -66,6 +70,8 @@
 
     // [DEF:selectTask:Function]
     // @PURPOSE: Selects a task and fetches its full details.
+    // @PRE: task object is provided.
+    // @POST: selectedTask store is updated with full task details.
     async function selectTask(task) {
         try {
             // Fetch the full task details (including logs) before setting it as selected
@@ -86,6 +92,8 @@
     
     // [DEF:getStatusColor:Function]
     // @PURPOSE: Returns the CSS color class for a given task status.
+    // @PRE: status string is provided.
+    // @POST: Returns tailwind color class string.
     function getStatusColor(status) {
         switch (status) {
             case 'SUCCESS': return 'bg-green-100 text-green-800';
@@ -100,6 +108,8 @@
     
     // [DEF:onMount:Function]
     // @PURPOSE: Initializes the component by fetching tasks and starting polling.
+    // @PRE: Component is mounting.
+    // @POST: Tasks are fetched and 5s polling interval is started.
     onMount(() => {
         fetchTasks();
         interval = setInterval(fetchTasks, 5000); // Poll every 5s
@@ -108,6 +118,8 @@
     
     // [DEF:onDestroy:Function]
     // @PURPOSE: Cleans up the polling interval when the component is destroyed.
+    // @PRE: Component is being destroyed.
+    // @POST: Polling interval is cleared.
     onDestroy(() => {
         clearInterval(interval);
     });

frontend/src/components/TaskList.svelte

@@ -17,6 +17,8 @@
 
   // [DEF:getStatusColor:Function]
   // @PURPOSE: Returns the CSS color class for a given task status.
+  // @PRE: status string is provided.
+  // @POST: Returns tailwind color class string.
   function getStatusColor(status: string) {
     switch (status) {
       case 'SUCCESS': return 'bg-green-100 text-green-800';
@@ -32,6 +34,8 @@
 
   // [DEF:formatTime:Function]
   // @PURPOSE: Formats a date string using date-fns.
+  // @PRE: dateStr is a valid date string or null.
+  // @POST: Returns human-readable relative time string.
   function formatTime(dateStr: string | null) {
     if (!dateStr) return 'N/A';
     try {
@@ -44,6 +48,8 @@
 
   // [DEF:handleTaskClick:Function]
   // @PURPOSE: Dispatches a select event when a task is clicked.
+  // @PRE: taskId is provided.
+  // @POST: 'select' event is dispatched with task ID.
   function handleTaskClick(taskId: string) {
     dispatch('select', { id: taskId });
   }

frontend/src/components/TaskLogViewer.svelte

@@ -24,6 +24,8 @@
 
     // [DEF:fetchLogs:Function]
     // @PURPOSE: Fetches logs for the current task.
+    // @PRE: taskId must be set.
+    // @POST: logs array is updated with data from taskService.
     async function fetchLogs() {
         if (!taskId) return;
         try {
@@ -41,6 +43,8 @@
 
     // [DEF:scrollToBottom:Function]
     // @PURPOSE: Scrolls the log container to the bottom.
+    // @PRE: logContainer element must be bound.
+    // @POST: logContainer scrollTop is set to scrollHeight.
     function scrollToBottom() {
         if (logContainer) {
             setTimeout(() => {
@@ -52,6 +56,8 @@
 
     // [DEF:handleScroll:Function]
     // @PURPOSE: Updates auto-scroll preference based on scroll position.
+    // @PRE: logContainer scroll event fired.
+    // @POST: autoScroll boolean is updated.
     function handleScroll() {
         if (!logContainer) return;
         // If user scrolls up, disable auto-scroll
@@ -63,6 +69,8 @@
 
     // [DEF:close:Function]
     // @PURPOSE: Closes the log viewer modal.
+    // @PRE: Modal is open.
+    // @POST: Modal is closed and close event is dispatched.
     function close() {
         dispatch('close');
         show = false;
@@ -71,6 +79,8 @@
 
     // [DEF:getLogLevelColor:Function]
     // @PURPOSE: Returns the CSS color class for a given log level.
+    // @PRE: level string is provided.
+    // @POST: Returns tailwind color class string.
     function getLogLevelColor(level) {
         switch (level) {
             case 'INFO': return 'text-blue-600';
@@ -99,6 +109,8 @@
 
     // [DEF:onDestroy:Function]
     // @PURPOSE: Cleans up the polling interval.
+    // @PRE: Component is being destroyed.
+    // @POST: Polling interval is cleared.
     onDestroy(() => {
         if (interval) clearInterval(interval);
     });

frontend/src/components/TaskRunner.svelte

@@ -38,6 +38,8 @@
     // [DEF:connect:Function]
     /**
      * @purpose Establishes WebSocket connection with exponential backoff.
+     * @pre selectedTask must be set in the store.
+     * @post WebSocket instance created and listeners attached.
      */
     function connect() {
         const task = get(selectedTask);
@@ -131,6 +133,8 @@
 
     // [DEF:fetchTargetDatabases:Function]
     // @PURPOSE: Fetches the list of databases in the target environment.
+    // @PRE: task must be selected and have a target environment parameter.
+    // @POST: targetDatabases array is populated with database objects.
     async function fetchTargetDatabases() {
         const task = get(selectedTask);
         if (!task || !task.params.to_env) return;
@@ -153,6 +157,8 @@
 
     // [DEF:handleMappingResolve:Function]
     // @PURPOSE: Handles the resolution of a missing database mapping.
+    // @PRE: event.detail contains sourceDbUuid, targetDbUuid, and targetDbName.
+    // @POST: Mapping is saved and task is resumed.
     async function handleMappingResolve(event) {
         const task = get(selectedTask);
         const { sourceDbUuid, targetDbUuid, targetDbName } = event.detail;
@@ -196,6 +202,8 @@
     
     // [DEF:handlePasswordResume:Function]
     // @PURPOSE: Handles the submission of database passwords to resume a task.
+    // @PRE: event.detail contains passwords dictionary.
+    // @POST: Task resume endpoint is called with passwords.
     async function handlePasswordResume(event) {
         const task = get(selectedTask);
         const { passwords } = event.detail;
@@ -218,6 +226,8 @@
 
     // [DEF:startDataTimeout:Function]
     // @PURPOSE: Starts a timeout to detect when the log stream has stalled.
+    // @PRE: None.
+    // @POST: dataTimeout is set to check connection status after 5s.
     function startDataTimeout() {
         waitingForData = false;
         dataTimeout = setTimeout(() => {
@@ -230,6 +240,8 @@
 
     // [DEF:resetDataTimeout:Function]
     // @PURPOSE: Resets the data stall timeout.
+    // @PRE: dataTimeout must be active.
+    // @POST: dataTimeout is cleared and restarted.
     function resetDataTimeout() {
         clearTimeout(dataTimeout);
         waitingForData = false;
@@ -239,6 +251,8 @@
 
     // [DEF:onMount:Function]
     // @PURPOSE: Initializes the component and subscribes to task selection changes.
+    // @PRE: Svelte component is mounting.
+    // @POST: Store subscription is created and returned for cleanup.
     onMount(() => {
         // Subscribe to selectedTask changes
         const unsubscribe = selectedTask.subscribe(task => {
@@ -267,6 +281,8 @@
     // [DEF:onDestroy:Function]
     /**
      * @purpose Close WebSocket connection when the component is destroyed.
+     * @pre Component is being destroyed.
+     * @post WebSocket is closed and timeouts are cleared.
      */
     onDestroy(() => {
         clearTimeout(reconnectTimeout);

frontend/src/components/tools/ConnectionForm.svelte

@@ -25,6 +25,8 @@
 
     // [DEF:handleSubmit:Function]
     // @PURPOSE: Submits the connection form to the backend.
+    // @PRE: All required fields (name, host, database, username, password) must be filled.
+    // @POST: A new connection is created via the connection service and a success event is dispatched.
     async function handleSubmit() {
         if (!name || !host || !database || !username || !password) {
             addToast('Please fill in all required fields', 'warning');
@@ -47,6 +49,11 @@
     }
     // [/DEF:handleSubmit:Function]
 
+    // [DEF:resetForm:Function]
+    /* @PURPOSE: Resets the connection form fields to their default values.
+       @PRE: None.
+       @POST: All form input variables are reset.
+    */
     function resetForm() {
         name = '';
         host = '';
@@ -55,6 +62,7 @@
         username = '';
         password = '';
     }
+    // [/DEF:resetForm:Function]
 </script>
 
 <!-- [SECTION: TEMPLATE] -->

frontend/src/components/tools/ConnectionList.svelte

@@ -19,6 +19,8 @@
 
     // [DEF:fetchConnections:Function]
     // @PURPOSE: Fetches the list of connections from the backend.
+    // @PRE: None.
+    // @POST: connections array is populated.
     async function fetchConnections() {
         isLoading = true;
         try {
@@ -33,6 +35,8 @@
 
     // [DEF:handleDelete:Function]
     // @PURPOSE: Deletes a connection configuration.
+    // @PRE: id is provided and user confirms deletion.
+    // @POST: Connection is deleted from backend and list is reloaded.
     async function handleDelete(id) {
         if (!confirm('Are you sure you want to delete this connection?')) return;
         

frontend/src/components/tools/MapperTool.svelte

@@ -28,6 +28,8 @@
 
     // [DEF:fetchData:Function]
     // @PURPOSE: Fetches environments and saved connections.
+    // @PRE: None.
+    // @POST: envs and connections arrays are populated.
     async function fetchData() {
         try {
             const envsRes = await fetch('/api/environments');
@@ -41,6 +43,8 @@
 
     // [DEF:handleRunMapper:Function]
     // @PURPOSE: Triggers the MapperPlugin task.
+    // @PRE: selectedEnv and datasetId are set; source-specific fields are valid.
+    // @POST: Mapper task is started and selectedTask is updated.
     async function handleRunMapper() {
         if (!selectedEnv || !datasetId) {
             addToast('Please fill in required fields', 'warning');

frontend/src/components/tools/SearchTool.svelte

@@ -22,6 +22,8 @@
 
     // [DEF:fetchEnvironments:Function]
     // @PURPOSE: Fetches the list of available environments.
+    // @PRE: None.
+    // @POST: envs array is populated.
     async function fetchEnvironments() {
         try {
             const res = await fetch('/api/environments');
@@ -34,6 +36,8 @@
 
     // [DEF:handleSearch:Function]
     // @PURPOSE: Triggers the SearchPlugin task.
+    // @PRE: selectedEnv and searchQuery must be set.
+    // @POST: Task is started and polling begins.
     async function handleSearch() {
         if (!selectedEnv || !searchQuery) {
             addToast('Please select environment and enter query', 'warning');
@@ -61,6 +65,8 @@
 
     // [DEF:startPolling:Function]
     // @PURPOSE: Polls for task completion and results.
+    // @PRE: taskId is provided.
+    // @POST: pollInterval is set and results are updated on success.
     function startPolling(taskId) {
         if (pollInterval) clearInterval(pollInterval);