semantic update

frontend/src/components/storage/FileList.svelte

@@ -19,10 +19,23 @@
   export let files = [];
   const dispatch = createEventDispatcher();
 
+  // [DEF:isDirectory:Function]
+  /**
+   * @purpose Checks if a file object represents a directory.
+   * @param   {Object} file - The file object to check.
+   * @return  {boolean} True if it's a directory, false otherwise.
+   */
   function isDirectory(file) {
     return file.mime_type === 'directory';
   }
+  // [/DEF:isDirectory:Function]
 
+  // [DEF:formatSize:Function]
+  /**
+   * @purpose Formats file size in bytes into a human-readable string.
+   * @param   {number} bytes - The size in bytes.
+   * @return  {string} Formatted size (e.g., "1.2 MB").
+   */
   function formatSize(bytes) {
     if (bytes === 0) return '0 B';
     const k = 1024;
@@ -30,10 +43,18 @@
     const i = Math.floor(Math.log(bytes) / Math.log(k));
     return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
   }
+  // [/DEF:formatSize:Function]
 
+  // [DEF:formatDate:Function]
+  /**
+   * @purpose Formats an ISO date string into a localized readable format.
+   * @param   {string} dateStr - The date string to format.
+   * @return  {string} Localized date and time.
+   */
   function formatDate(dateStr) {
     return new Date(dateStr).toLocaleString();
   }
+  // [/DEF:formatDate:Function]
 </script>
 
 <!-- [SECTION: TEMPLATE] -->

frontend/src/routes/tools/storage/+page.svelte

@@ -76,11 +76,21 @@
   }
   // [/DEF:handleDelete:Function]
 
+  // [DEF:handleNavigate:Function]
+  /**
+   * @purpose Updates the current path and reloads files when navigating into a directory.
+   * @param   {CustomEvent} event - The navigation event containing the new path.
+   */
   function handleNavigate(event) {
     currentPath = event.detail;
     loadFiles();
   }
+  // [/DEF:handleNavigate:Function]
 
+  // [DEF:navigateUp:Function]
+  /**
+   * @purpose Navigates one level up in the directory structure.
+   */
   function navigateUp() {
     if (!currentPath || currentPath === activeTab) return;
     const parts = currentPath.split('/');
@@ -88,6 +98,7 @@
     currentPath = parts.join('/') || '';
     loadFiles();
   }
+  // [/DEF:navigateUp:Function]
 
   onMount(loadFiles);
 

frontend/src/services/storageService.js

@@ -3,6 +3,7 @@
  * @purpose Frontend API client for file storage management.
  * @layer   Service
  * @relation DEPENDS_ON -> backend.api.storage
+ * @SEMANTICS: storage, api, client
  */
 
 const API_BASE = '/api/storage';
@@ -13,6 +14,8 @@ const API_BASE = '/api/storage';
  * @param   {string} [category] - Optional category filter.
  * @param   {string} [path] - Optional subpath filter.
  * @returns {Promise<Array>}
+ * @PRE     category and path should be valid strings if provided.
+ * @POST    Returns a promise resolving to an array of StoredFile objects.
  */
 export async function listFiles(category, path) {
     const params = new URLSearchParams();
@@ -37,6 +40,8 @@ export async function listFiles(category, path) {
  * @param   {string} category - Target category.
  * @param   {string} [path] - Target subpath.
  * @returns {Promise<Object>}
+ * @PRE     file must be a valid File object; category must be specified.
+ * @POST    Returns a promise resolving to the metadata of the uploaded file.
  */
 export async function uploadFile(file, category, path) {
     const formData = new FormData();
@@ -65,6 +70,8 @@ export async function uploadFile(file, category, path) {
  * @param   {string} category - File category.
  * @param   {string} path - Relative path of the item.
  * @returns {Promise<void>}
+ * @PRE     category and path must identify an existing file or directory.
+ * @POST    The specified file or directory is removed from storage.
  */
 export async function deleteFile(category, path) {
     const response = await fetch(`${API_BASE}/files/${category}/${path}`, {
@@ -84,6 +91,8 @@ export async function deleteFile(category, path) {
  * @param   {string} category - File category.
  * @param   {string} path - Relative path of the file.
  * @returns {string}
+ * @PRE     category and path must identify an existing file.
+ * @POST    Returns a valid API URL for file download.
  */
 export function downloadFileUrl(category, path) {
     return `${API_BASE}/download/${category}/${path}`;