docs: create-and-check-documentation

src/components/Logging/Filters.tsx

@@ -4,8 +4,15 @@ import type {LogFilterPredicate} from "./useLogs.ts";
 
 import styles from "./Filters.module.css";
 
+/**
+ * A generic setter type compatible with React's state setters.
+ */
 type Setter<T> = (value: T | ((prev: T) => T)) => void;
 
+/**
+ * Mapping of log level names to their corresponding numeric severity.
+ * Used for comparison in log filtering predicates.
+ */
 const optionMapping = new Map([
   ["ALL", 0],
   ["DEBUG", 10],
@@ -16,6 +23,17 @@ const optionMapping = new Map([
   ["NONE", 999_999_999_999], // It is technically possible to have a higher level, but this is fine
 ]);
 
+/**
+ * Renders a single log-level selector (dropdown) for a specific filter target.
+ *
+ * Used by both the global filter and agent-specific filters.
+ *
+ * @param name - The display name or identifier for the filter target.
+ * @param level - The currently selected log level.
+ * @param setLevel - Function to update the selected log level.
+ * @param onDelete - Optional callback for deleting this filter element.
+ * @returns A JSX element that renders a labeled dropdown for selecting log levels.
+ */
 function LevelPredicateElement({
   name,
   level,
@@ -54,8 +72,19 @@ function LevelPredicateElement({
   </div>
 }
 
+/** Key used for the global log-level predicate in the filter map. */
 const GLOBAL_LOG_LEVEL_PREDICATE_KEY = "global_log_level";
 
+/**
+ * Renders and manages the **global log-level filter**.
+ *
+ * This component defines a baseline log level that all logs must meet or exceed
+ * to be displayed, unless overridden by per-agent filters.
+ *
+ * @param filterPredicates - Map of current log filter predicates.
+ * @param setFilterPredicates - Setter function to update the filter predicates map.
+ * @returns A JSX element rendering the global log-level selector.
+ */
 function GlobalLevelFilter({
   filterPredicates,
   setFilterPredicates,
@@ -78,6 +107,7 @@ function GlobalLevelFilter({
     });
   }
 
+  // Initialize default global level on mount.
   useEffect(() => {
     if (filterPredicates.has(GLOBAL_LOG_LEVEL_PREDICATE_KEY)) return;
     setSelected("INFO");
@@ -91,8 +121,21 @@ function GlobalLevelFilter({
   />;
 }
 
+/** Prefix for agent-specific log-level predicate keys in the filter map. */
 const AGENT_LOG_LEVEL_PREDICATE_KEY_PREFIX = "agent_log_level_";
 
+/**
+ * Renders and manages **per-agent log-level filters**.
+ *
+ * Allows the user to set specific log levels for individual agents, overriding
+ * the global filter for those agents. Includes functionality to add, edit,
+ * or remove agent-level filters.
+ *
+ * @param filterPredicates - Map of current log filter predicates.
+ * @param setFilterPredicates - Setter function to update the filter predicates map.
+ * @param agentNames - Set of agent names available for filtering.
+ * @returns A JSX element rendering agent-level filters and a dropdown to add new ones.
+ */
 function AgentLevelFilters({
   filterPredicates,
   setFilterPredicates,
@@ -105,7 +148,7 @@ function AgentLevelFilters({
   const rootRef = useRef<HTMLDivElement>(null);
   const [open, setOpen] = useState(false);
 
-  // Click outside to close
+  // Close dropdown or panels when clicking outside or pressing Escape.
   useEffect(() => {
     if (!open) return;
     const onDocClick = (e: MouseEvent) => {
@@ -124,13 +167,16 @@ function AgentLevelFilters({
     };
   }, [open]);
 
+  // Identify which predicates correspond to agents.
   const agentPredicates = [...filterPredicates.keys()].filter((key) =>
     key.startsWith(AGENT_LOG_LEVEL_PREDICATE_KEY_PREFIX));
 
-  /**
-   * Create or change the predicate for an agent. If the level is not given, the global level is used.
-   * @param agentName The name of the agent.
-   * @param level The level to filter by. If not given, the global level is used.
+ /**
+   * Creates or updates the log filter predicate for a specific agent.
+   * Falls back to the global log level if no level is specified.
+   *
+   * @param agentName - The name of the agent to filter.
+   * @param level - Optional log level to apply; defaults to the global level.
    */
   const setAgentPredicate = (agentName: string, level?: string ) => {
     level = level ?? filterPredicates.get(GLOBAL_LOG_LEVEL_PREDICATE_KEY)?.value ?? "ALL";
@@ -147,6 +193,11 @@ function AgentLevelFilters({
     });
   }
 
+  /**
+   * Deletes the log filter predicate for a specific agent.
+   *
+   * @param agentName - The name of the agent whose filter should be removed.
+   */
   const deleteAgentPredicate = (agentName: string) => {
     setFilterPredicates((curr) => {
       const fullName = AGENT_LOG_LEVEL_PREDICATE_KEY_PREFIX + agentName;
@@ -184,6 +235,17 @@ function AgentLevelFilters({
   </>;
 }
 
+/**
+ * Main Filters component that aggregates global and per-agent log filters.
+ *
+ * Combines the global log-level filter and agent-specific filters into a unified UI.
+ * Updates a shared `Map<string, LogFilterPredicate>` to determine which logs are shown.
+ *
+ * @param filterPredicates - The map of all active log filter predicates.
+ * @param setFilterPredicates - Setter to update the map of predicates.
+ * @param agentNames - Set of available agent names to display filters for.
+ * @returns A React component that renders all log filter controls.
+ */
 export default function Filters({
   filterPredicates,
   setFilterPredicates,

src/components/Logging/Logging.tsx

@@ -8,13 +8,26 @@ import {type Cell, useCell} from "../../utils/cellStore.ts";
 
 import styles from "./Logging.module.css";
 
+
+/**
+ * Zustand store definition for managing user preferences related to logging.
+ *
+ * Includes flags for toggling relative timestamps and automatic scroll behavior.
+ */
 type LoggingSettings = {
+  /** Whether to display log timestamps as relative (e.g., "2m 15s ago") instead of absolute. */
   showRelativeTime: boolean;
+  /** Updates the `showRelativeTime` setting. */
   setShowRelativeTime: (showRelativeTime: boolean) => void;
+  /** Whether the log view should automatically scroll to the newest entry. */
   scrollToBottom: boolean;
+  /** Updates the `scrollToBottom` setting. */
   setScrollToBottom: (scrollToBottom: boolean) => void;
 };
 
+/**
+ * Global Zustand store for logging UI preferences.
+ */
 const useLoggingSettings = create<LoggingSettings>((set) => ({
   showRelativeTime: false,
   setShowRelativeTime: (showRelativeTime: boolean) => set({ showRelativeTime }),
@@ -22,6 +35,16 @@ const useLoggingSettings = create<LoggingSettings>((set) => ({
   setScrollToBottom: (scrollToBottom: boolean) => set({ scrollToBottom }),
 }));
 
+/**
+ * Renders a single log message entry with colored level indicators and timestamp formatting.
+ *
+ * This component automatically re-renders when the underlying log record (`recordCell`)
+ * changes. It also triggers the `onUpdate` callback whenever the record updates (e.g., for auto-scrolling).
+ *
+ * @param recordCell - A reactive `Cell` containing a single `LogRecord`.
+ * @param onUpdate - Optional callback triggered when the log entry updates.
+ * @returns A JSX element displaying a formatted log message.
+ */
 function LogMessage({
   recordCell,
   onUpdate,
@@ -33,7 +56,8 @@ function LogMessage({
   const record = useCell(recordCell);
 
   /**
-   * Normalizes the log level number to a multiple of 10, for which there are CSS styles.
+   * Normalizes the log level number to a multiple of 10, 
+   * for which there are CSS styles. (e.g., INFO = 20, ERROR = 40).
    */
   const normalizedLevelNo = (() => {
     // By default, the highest level is 50 (CRITICAL). Custom levels can be higher, but we don't have more critical color.
@@ -42,8 +66,10 @@ function LogMessage({
     return Math.round(record.levelno / 10) * 10;
   })();
 
+  /** Simplifies the logger name by showing only the last path segment. */
   const normalizedName = record.name.split(".").pop() || record.name;
 
+  // Notify parent component (e.g. for scroll updates) when this record changes.
   useEffect(() => {
     if (onUpdate) onUpdate();
   }, [record, onUpdate]);
@@ -65,11 +91,23 @@ function LogMessage({
   </div>;
 }
 
+/**
+ * Displays a scrollable list of log messages.
+ *
+ * Handles:
+ * - Auto-scrolling when new messages arrive.
+ * - Allowing users to scroll manually and disable auto-scroll.
+ * - A floating "Scroll to bottom" button when not at the bottom.
+ *
+ * @param recordCells - Array of reactive log records to display.
+ * @returns A scrollable log list component.
+ */
 function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
   const scrollableRef = useRef<HTMLDivElement>(null);
   const lastElementRef = useRef<HTMLLIElement>(null)
   const { scrollToBottom, setScrollToBottom } = useLoggingSettings();
 
+  // Disable auto-scroll if the user manually scrolls.
   useEffect(() => {
     if (!scrollableRef.current) return;
     const currentScrollableRef = scrollableRef.current;
@@ -85,6 +123,12 @@ function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
     }
   }, [scrollableRef, setScrollToBottom]);
 
+  /**
+   * Scrolls the last log message into view if auto-scroll is enabled,
+   * or if forced (e.g., user clicks "Scroll to bottom").
+   *
+   * @param force - If true, forces scrolling even if `scrollToBottom` is false.
+   */
   function scrollLastElementIntoView(force = false) {
     if ((!scrollToBottom && !force) || !lastElementRef.current) return;
     lastElementRef.current.scrollIntoView({ behavior: "smooth" });
@@ -111,6 +155,19 @@ function LogMessages({ recordCells }: { recordCells: Cell<LogRecord>[] }) {
   </div>;
 }
 
+/**
+ * Top-level logging panel component.
+ *
+ * Combines:
+ * - The `Filters` component for adjusting log visibility.
+ * - The `LogMessages` component for displaying filtered logs.
+ * - Zustand-managed UI settings (auto-scroll, timestamp display).
+ *
+ * This component uses the `useLogs` hook to fetch and filter logs based on
+ * active predicates, and re-renders automatically as new logs arrive.
+ *
+ * @returns The complete logging UI as a React element.
+ */
 export default function Logging() {
   const [filterPredicates, setFilterPredicates] = useState(new Map<string, LogFilterPredicate>());
   const { filteredLogs, distinctNames } = useLogs(filterPredicates)

src/components/Logging/useLogs.ts

@@ -3,6 +3,19 @@ import {useCallback, useEffect, useRef, useState} from "react";
 import {applyPriorityPredicates, type PriorityFilterPredicate} from "../../utils/priorityFiltering.ts";
 import {cell, type Cell} from "../../utils/cellStore.ts";
 
+/**
+ * Represents a single log record emitted by the backend logging system.
+ *
+ * @property name - The name of the logger or source (e.g., `"agent.core"`).
+ * @property message - The message content of the log record.
+ * @property levelname - The human-readable severity level (e.g., `"INFO"`, `"ERROR"`).
+ * @property levelno - The numeric severity value corresponding to `levelname`.
+ * @property created - The UNIX timestamp (in seconds) when this record was created.
+ * @property relativeCreated - The time (in milliseconds) since the logging system started.
+ * @property reference - (Optional) A reference identifier linking related log messages.
+ * @property firstCreated - Timestamp of the first log in this reference group.
+ * @property firstRelativeCreated - Relative timestamp of the first log in this reference group.
+ */
 export type LogRecord = {
   name: string;
   message: string;
@@ -15,29 +28,68 @@ export type LogRecord = {
   firstRelativeCreated: number;
 };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type LogFilterPredicate = PriorityFilterPredicate<LogRecord> & { value: any };
+/**
+ * A log filter predicate with priority support, used to determine whether
+ * a log record should be displayed.
+ *
+ * This extends a general `PriorityFilterPredicate` and includes an optional
+ * `value` field for UI metadata (e.g., selected log level or agent).
+ *
+ * @template T - The type of record being filtered (here, `LogRecord`).
+ */
+export type LogFilterPredicate = PriorityFilterPredicate<LogRecord> & { 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: any };
 
+ /**
+ * React hook that manages the lifecycle of log records, including:
+ * - Receiving live log messages via Server-Sent Events (SSE),
+ * - Applying priority-based filtering rules,
+ * - Managing distinct logger names and reference-linked messages.
+ *
+ * Returns both the filtered logs (as reactive `Cell<LogRecord>` objects)
+ * and a set of distinct logger names for use in UI components (e.g., Filters).
+ *
+ * @param filterPredicates - A `Map` of log filter predicates, keyed by ID or type.
+ * @returns An object containing:
+ * - `filteredLogs`: The currently visible (filtered) log messages.
+ * - `distinctNames`: A set of all distinct logger names encountered.
+ *
+ * @example
+ * ```ts
+ * const { filteredLogs, distinctNames } = useLogs(activeFilters);
+ * ```
+ */
 export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
+  /** Distinct logger names encountered across all logs. */
   const [distinctNames, setDistinctNames] = useState<Set<string>>(new Set());
+  /** Filtered logs that pass all active predicates, stored as reactive cells. */
   const [filtered, setFiltered] = useState<Cell<LogRecord>[]>([]);
 
+  /** Persistent reference to the active EventSource connection. */
   const sseRef = useRef<EventSource | null>(null);
+  /** Keeps a stable reference to the current filter map (avoids re-renders). */
   const filtersRef = useRef(filterPredicates);
+  /** Stores all received logs (the unfiltered full history). */
   const logsRef = useRef<LogRecord[]>([]);
 
   /** Map to store the first message for each reference, instance can be updated to change contents. */
   const firstByRefRef = useRef<Map<string, Cell<LogRecord>>>(new Map());
 
   /**
-   * Apply the filter predicates to a log record.
+   * Apply all active filter predicates to a log record.
    * @param log The log record to apply the filters to.
-   * @returns `true` if the record passes.
+   * @returns `true` if the record passes all filters; otherwise `false`.
    */
   const applyFilters = useCallback((log: LogRecord) =>
     applyPriorityPredicates(log, [...filtersRef.current.values()]), []);
 
-  /** Recomputes the entire filtered list. Use when filter predicates change. */
+  /**
+   * Fully recomputes the filtered log list based on the current
+   * filter predicates and historical logs.
+   *
+   * Should be invoked whenever the filter map changes.
+   */
   const recomputeFiltered = useCallback(() => {
     const newFiltered: Cell<LogRecord>[] = [];
     firstByRefRef.current = new Map();
@@ -49,6 +101,7 @@ export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
         firstRelativeCreated: message.relativeCreated,
       });
 
+      // Handle reference grouping: update the first message in the group.
       if (message.reference) {
         const first = firstByRefRef.current.get(message.reference);
         if (first) {
@@ -59,14 +112,14 @@ export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
             firstRelativeCreated: prev.firstRelativeCreated ?? prev.relativeCreated,
           }));
 
-          // Don't add it to the list again
-          continue;
+          continue; // Don't add it to the list again (it's a duplicate).
         } else {
           // Add the first message with this reference to the registry
           firstByRefRef.current.set(message.reference, messageCell);
         }
       }
 
+      // Include only if it passes current filters.
       if (applyFilters(message)) {
         newFiltered.push(messageCell);
       }
@@ -75,20 +128,23 @@ export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
     setFiltered(newFiltered);
   }, [applyFilters, setFiltered]);
 
-  // Reapply filters to all logs, only when filters change
+  // Re-filter all logs whenever filter predicates change.
   useEffect(() => {
     filtersRef.current = filterPredicates;
     recomputeFiltered();
   }, [filterPredicates, recomputeFiltered]);
 
   /**
-   * Handle a new log message. Updates the filtered list and to the full history.
-   * @param message The new log message.
+   * Handles a newly received log record.
+   * Updates the full log history, distinct names set, and filtered log list.
+   *
+   * @param message - The new log record to process.
    */
   const handleNewMessage = useCallback((message: LogRecord) => {
-    // Add to the full history for re-filtering on filter changes
+    // Store in complete history for future refiltering.
     logsRef.current.push(message);
 
+    // Track distinct logger names.
     setDistinctNames((prev) => {
       if (prev.has(message.name)) return prev;
       const newSet = new Set(prev);
@@ -96,12 +152,14 @@ export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
       return newSet;
     });
 
+    // Wrap in a reactive cell for UI binding.
     const messageCell = cell<LogRecord>({
       ...message,
       firstCreated: message.created,
       firstRelativeCreated: message.relativeCreated,
     });
 
+    // Handle reference-linked updates.
     if (message.reference) {
       const first = firstByRefRef.current.get(message.reference);
       if (first) {
@@ -112,20 +170,28 @@ export function useLogs(filterPredicates: Map<string, LogFilterPredicate>) {
           firstRelativeCreated: prev.firstRelativeCreated ?? prev.relativeCreated,
         }));
 
-        // Don't add it to the list again
-        return;
+        return; // Do not duplicate reference group entries.
       } else {
-        // Add the first message with this reference to the registry
         firstByRefRef.current.set(message.reference, messageCell);
       }
     }
 
+    // Only append if message passes filters.
     if (applyFilters(message)) {
       setFiltered((curr) => [...curr, messageCell]);
     }
   }, [applyFilters, setFiltered]);
 
+  /**
+   * Initializes the SSE (Server-Sent Events) stream for real-time logs.
+   *
+   * Subscribes to messages from the backend logging endpoint and
+   * dispatches each message to `handleNewMessage`.
+   *
+   * Cleans up the EventSource connection when the component unmounts.
+   */
   useEffect(() => {
+    // Only create one SSE connection for the lifetime of the hook.
     if (sseRef.current) return;
 
     const es = new EventSource("http://localhost:8000/logs/stream");