semantic update

frontend/src/components/TaskLogViewer.svelte

@@ -12,6 +12,8 @@
     /**
      * @TIER CRITICAL
      * @PURPOSE Displays detailed logs for a specific task inline or in a modal using TaskLogPanel.
+     * @PRE Needs a valid taskId to fetch logs for.
+     * @POST task logs are displayed and updated in real time.
      * @UX_STATE Loading -> Shows spinner/text while fetching initial logs
      * @UX_STATE Streaming -> Displays logs with auto-scroll, real-time appending
      * @UX_STATE Error -> Shows error message with recovery option
@@ -42,6 +44,9 @@
     let shouldShow = $derived(inline || show);
 
     // [DEF:handleRealTimeLogs:Action]
+    // @PURPOSE: Sync real-time logs to the current log list
+    // @PRE: None
+    // @POST: logs are updated with new real-time log entries
     $effect(() => {
         if (realTimeLogs && realTimeLogs.length > 0) {
             const lastLog = realTimeLogs[realTimeLogs.length - 1];
@@ -58,11 +63,20 @@
     // [/DEF:handleRealTimeLogs:Action]
 
     // [DEF:fetchLogs:Function]
+    // @PURPOSE: Fetches logs for a given task ID
+    // @PRE: taskId is set
+    // @POST: logs are populated with API response
     async function fetchLogs() {
         if (!taskId) return;
         try {
+            console.log(`[TaskLogViewer][API][fetchLogs:STARTED] id=${taskId}`);
             logs = await getTaskLogs(taskId);
+            console.log(`[TaskLogViewer][API][fetchLogs:SUCCESS] id=${taskId}`);
         } catch (e) {
+            console.error(
+                `[TaskLogViewer][API][fetchLogs:FAILED] id=${taskId}`,
+                e,
+            );
             error = e.message;
         } finally {
             loading = false;
@@ -70,13 +84,25 @@
     }
     // [/DEF:fetchLogs:Function]
 
+    // [DEF:handleFilterChange:Function]
+    // @PURPOSE: Updates filter conditions for the log viewer
+    // @PRE: event contains detail with source and level
+    // @POST: Log viewer filters updated
     function handleFilterChange(event) {
+        console.log("[TaskLogViewer][UI][handleFilterChange:START]");
         const { source, level } = event.detail;
     }
+    // [/DEF:handleFilterChange:Function]
 
+    // [DEF:handleRefresh:Function]
+    // @PURPOSE: Refreshes the logs by polling the API
+    // @PRE: None
+    // @POST: Logs refetched
     function handleRefresh() {
+        console.log("[TaskLogViewer][UI][handleRefresh:START]");
         fetchLogs();
     }
+    // [/DEF:handleRefresh:Function]
 
     $effect(() => {
         if (shouldShow && taskId) {
@@ -104,6 +130,11 @@
 </script>
 
 {#if shouldShow}
+    <!-- [DEF:showInline:Component] -->
+    <!-- @PURPOSE: Shows inline logs -->
+    <!-- @LAYER: UI -->
+    <!-- @SEMANTICS: logs, inline -->
+    <!-- @TIER: STANDARD -->
     {#if inline}
         <div class="flex flex-col h-full w-full">
             {#if loading && logs.length === 0}
@@ -136,7 +167,13 @@
                 />
             {/if}
         </div>
+        <!-- [/DEF:showInline:Component] -->
     {:else}
+        <!-- [DEF:showModal:Component] -->
+        <!-- @PURPOSE: Shows modal logs -->
+        <!-- @LAYER: UI -->
+        <!-- @SEMANTICS: logs, modal -->
+        <!-- @TIER: STANDARD -->
         <div
             class="fixed inset-0 z-50 overflow-y-auto"
             aria-labelledby="modal-title"
@@ -199,5 +236,6 @@
         </div>
     {/if}
 {/if}
+// [/DEF:showModal:Component]
 
 <!-- [/DEF:TaskLogViewer:Component] -->