docs: Adds JSDoc comments and improves utils

Enhances code documentation by adding JSDoc comments to utility functions, improving clarity and maintainability.

Refactors the utils/index.ts file to include a brief description of its purpose.

Removes settings.ts which appears to be deprecated.

Author: allozaur

tools/server/webui/src/lib/types/settings.d.ts

@@ -1,3 +1,5 @@
+import type { SETTING_CONFIG_DEFAULT } from "$lib/constants/settings-config";
+
 export type ConfigValue = string | number | boolean;
 
 export interface FieldConfig {
@@ -6,3 +8,7 @@ export interface FieldConfig {
 	type: 'input' | 'textarea' | 'checkbox';
 	help?: string;
 }
+
+export type SettingsConfigType = typeof SETTING_CONFIG_DEFAULT & {
+	[key: string]: string | number | boolean;
+};

tools/server/webui/src/lib/utils/autoresize-textarea.ts

@@ -1,3 +1,7 @@
+/**
+ * Automatically resizes a textarea element to fit its content
+ * @param textareaElement - The textarea element to resize
+ */
 export default function autoResizeTextarea(textareaElement: HTMLTextAreaElement) {
 	if (textareaElement) {
 		textareaElement.style.height = 'auto';

tools/server/webui/src/lib/utils/index.ts

@@ -1,3 +1,8 @@
+/**
+ * Utility functions for the webui application
+ * Exports commonly used helper functions for file processing, UI interactions, and data manipulation
+ */
+
 import autoResizeTextarea from './autoresize-textarea';
 import { copyCodeToClipboard, copyToClipboard } from './copy';
 import { convertPDFToText, convertPDFToImage, isPdfMimeType } from './pdf-processing';

tools/server/webui/src/lib/utils/pdf-processing.ts

@@ -1,3 +1,8 @@
+/**
+ * PDF processing utilities using PDF.js
+ * Handles PDF text extraction and image conversion in the browser
+ */
+
 import { browser } from '$app/environment';
 
 // Types for PDF.js (imported conditionally)
@@ -12,7 +17,10 @@ type TextItem = {
 // PDF.js instance (loaded dynamically)
 let pdfjs: any = null;
 
-// Initialize PDF.js only on the client side
+/**
+ * Initialize PDF.js only on the client side
+ * Sets up the PDF.js library and worker for processing
+ */
 async function initializePdfJs() {
 	if (!browser || pdfjs) return;
 
@@ -31,6 +39,11 @@ async function initializePdfJs() {
 	}
 }
 
+/**
+ * Convert a File object to ArrayBuffer for PDF.js processing
+ * @param file - The PDF file to convert
+ * @returns Promise resolving to the file's ArrayBuffer
+ */
 async function getFileAsBuffer(file: File): Promise<ArrayBuffer> {
 	return new Promise((resolve, reject) => {
 		const reader = new FileReader();
@@ -49,6 +62,11 @@ async function getFileAsBuffer(file: File): Promise<ArrayBuffer> {
 }
 
 
+/**
+ * Extract text content from a PDF file
+ * @param file - The PDF file to process
+ * @returns Promise resolving to the extracted text content
+ */
 export async function convertPDFToText(file: File): Promise<string> {
 	if (!browser) {
 		throw new Error('PDF processing is only available in the browser');
@@ -80,6 +98,12 @@ export async function convertPDFToText(file: File): Promise<string> {
 	}
 }
 
+/**
+ * Convert PDF pages to PNG images as data URLs
+ * @param file - The PDF file to convert
+ * @param scale - Rendering scale factor (default: 1.5)
+ * @returns Promise resolving to array of PNG data URLs
+ */
 export async function convertPDFToImage(file: File, scale: number = 1.5): Promise<string[]> {
 	if (!browser) {
 		throw new Error('PDF processing is only available in the browser');
@@ -124,10 +148,20 @@ export async function convertPDFToImage(file: File, scale: number = 1.5): Promis
 	}
 }
 
+/**
+ * Check if a file is a PDF based on its MIME type
+ * @param file - The file to check
+ * @returns True if the file is a PDF
+ */
 export function isPdfFile(file: File): boolean {
 	return file.type === 'application/pdf';
 }
 
+/**
+ * Check if a MIME type represents a PDF
+ * @param mimeType - The MIME type to check
+ * @returns True if the MIME type is application/pdf
+ */
 export function isPdfMimeType(mimeType: string): boolean {
 	return mimeType === 'application/pdf';
 }

tools/server/webui/src/lib/utils/settings.ts

@@ -1,3 +1,9 @@
+/**
+ * Convert an SVG base64 data URL to a PNG data URL
+ * @param base64UrlSvg - The SVG base64 data URL to convert
+ * @param backgroundColor - Background color for the PNG (default: 'white')
+ * @returns Promise resolving to PNG data URL
+ */
 export function svgBase64UrlToPngDataURL(
 	base64UrlSvg: string,
 	backgroundColor: string = 'white'
@@ -46,10 +52,20 @@ export function svgBase64UrlToPngDataURL(
 	});
 }
 
+/**
+ * Check if a file is an SVG based on its MIME type
+ * @param file - The file to check
+ * @returns True if the file is an SVG
+ */
 export function isSvgFile(file: File): boolean {
 	return file.type === 'image/svg+xml';
 }
 
+/**
+ * Check if a MIME type represents an SVG
+ * @param mimeType - The MIME type to check
+ * @returns True if the MIME type is image/svg+xml
+ */
 export function isSvgMimeType(mimeType: string): boolean {
 	return mimeType === 'image/svg+xml';
 }

tools/server/webui/src/lib/utils/svg-to-png.ts

@@ -1,9 +1,24 @@
+/**
+ * Text file processing utilities
+ * Handles text file detection, reading, and validation
+ */
+
 import { TEXT_FILE_EXTENSIONS } from "$lib/constants/text-file-extensions";
 
+/**
+ * Check if a filename indicates a text file based on its extension
+ * @param filename - The filename to check
+ * @returns True if the filename has a recognized text file extension
+ */
 export function isTextFileByName(filename: string): boolean {
     return TEXT_FILE_EXTENSIONS.some((ext) => filename.toLowerCase().endsWith(ext));
 }
 
+/**
+ * Read a file's content as text
+ * @param file - The file to read
+ * @returns Promise resolving to the file's text content
+ */
 export async function readFileAsText(file: File): Promise<string> {
     return new Promise((resolve, reject) => {
         const reader = new FileReader();
@@ -19,6 +34,12 @@ export async function readFileAsText(file: File): Promise<string> {
     });
 }
 
+/**
+ * Heuristic check to determine if content is likely from a text file
+ * Detects binary files by counting suspicious characters and null bytes
+ * @param content - The file content to analyze
+ * @returns True if the content appears to be text-based
+ */
 export function isLikelyTextFile(content: string): boolean {
     if (!content) return true;
 

tools/server/webui/src/lib/utils/text-files.ts

@@ -2,6 +2,8 @@
  * Parses thinking content from a message that may contain <think> tags
  * Returns an object with thinking content and cleaned message content
  * Handles both complete <think>...</think> blocks and incomplete <think> blocks (streaming)
+ * @param content - The message content to parse
+ * @returns An object containing the extracted thinking content and the cleaned message content
  */
 export function parseThinkingContent(content: string): {
 	thinking: string | null;
@@ -38,13 +40,17 @@ export function parseThinkingContent(content: string): {
 
 /**
  * Checks if content contains an opening <think> tag (for streaming)
+ * @param content - The message content to check
+ * @returns True if the content contains an opening <think> tag
  */
 export function hasThinkingStart(content: string): boolean {
 	return content.includes('<think>');
 }
 
 /**
  * Checks if content contains a closing </think> tag (for streaming)
+ * @param content - The message content to check
+ * @returns True if the content contains a closing </think> tag
  */
 export function hasThinkingEnd(content: string): boolean {
 	return content.includes('</think>');
@@ -53,6 +59,8 @@ export function hasThinkingEnd(content: string): boolean {
 /**
  * Extracts partial thinking content during streaming
  * Used when we have <think> but not yet </think>
+ * @param content - The message content to extract partial thinking from
+ * @returns An object containing the extracted partial thinking content and the remaining content
  */
 export function extractPartialThinking(content: string): {
 	thinking: string | null;

tools/server/webui/src/lib/utils/thinking.ts

@@ -23,6 +23,8 @@ export function estimateTokenCount(text: string): number {
 
 /**
  * Estimate token count for a single message including its extras (attachments)
+ * @param message - The message to estimate tokens for
+ * @returns The estimated token count for the message
  */
 export function estimateMessageTokens(message: DatabaseMessage): number {
 	let totalTokens = 0;
@@ -63,6 +65,8 @@ export function estimateMessageTokens(message: DatabaseMessage): number {
 
 /**
  * Estimate total token count for a conversation including all messages
+ * @param messages - The messages to estimate tokens for
+ * @returns The estimated token count for the conversation
  */
 export function estimateConversationTokens(messages: DatabaseMessage[]): number {
 	let totalTokens = 0;
@@ -82,6 +86,9 @@ export function estimateConversationTokens(messages: DatabaseMessage[]): number
 
 /**
  * Estimate tokens for a new message with extras before sending
+ * @param content - The content of the new message
+ * @param extras - The extras (attachments) of the new message
+ * @returns The estimated token count for the new message
  */
 export function estimateNewMessageTokens(content: string, extras?: DatabaseMessageExtra[]): number {
 	let totalTokens = estimateTokenCount(content);
@@ -115,6 +122,12 @@ export function estimateNewMessageTokens(content: string, extras?: DatabaseMessa
 
 /**
  * Check if adding a new message would exceed the context length
+ * @param existingMessages - The existing messages in the conversation
+ * @param newMessageContent - The content of the new message
+ * @param newMessageExtras - The extras (attachments) of the new message
+ * @param maxContextLength - The maximum allowed context length
+ * @param reserveTokens - Number of tokens to reserve for response generation (default: 512)
+ * @returns An object containing the estimated tokens, whether it would exceed the context length, and the maximum allowed tokens
  */
 export function wouldExceedContextLength(
 	existingMessages: DatabaseMessage[],