From ca74e2ed3ab05b2c09f052312f9e4a51e02ae4cf Mon Sep 17 00:00:00 2001
From: Varad Modhekar <varadmodhekar101@gmail.com>
Date: Thu, 7 May 2026 17:36:01 +0530
Subject: [PATCH] Add comments explaining upload , worker and crypto flow

---
 xftp-web/web/crypto.worker.ts |  2 ++
 xftp-web/web/progress.ts      |  1 +
 xftp-web/web/upload.ts        | 15 ++++++++++++---
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/xftp-web/web/crypto.worker.ts b/xftp-web/web/crypto.worker.ts
index a2bd84843d..a61667e090 100644
--- a/xftp-web/web/crypto.worker.ts
+++ b/xftp-web/web/crypto.worker.ts
@@ -18,6 +18,8 @@ const memoryChunks = new Map<number, Uint8Array>()
 async function getSessionDir(): Promise<FileSystemDirectoryHandle> {
   if (!sessionDir) {
     const root = await navigator.storage.getDirectory()
+       //XFTP behaves more like a real file-transfer system than a database app, 
+    //and OPFS/file handles are much better for large chunked binary file operations.
     sessionDir = await root.getDirectoryHandle(SESSION_DIR, {create: true})
   }
   return sessionDir
diff --git a/xftp-web/web/progress.ts b/xftp-web/web/progress.ts
index 9872b74fd4..3b1f6d8ec6 100644
--- a/xftp-web/web/progress.ts
+++ b/xftp-web/web/progress.ts
@@ -32,6 +32,7 @@ export function createProgressRing(): ProgressRing {
     const appEl = document.querySelector('[data-xftp-app]') ?? document.getElementById('app')
     const s = appEl ? getComputedStyle(appEl) : null
     return {
+      // embedding customization  
       bg: s?.getPropertyValue('--xftp-ring-bg').trim() || '#e0e0e0',
       fg: s?.getPropertyValue('--xftp-ring-fg').trim() || '#3b82f6',
       text: s?.getPropertyValue('--xftp-ring-text').trim() || '#333',
diff --git a/xftp-web/web/upload.ts b/xftp-web/web/upload.ts
index 78906bb354..d476a1d0c2 100644
--- a/xftp-web/web/upload.ts
+++ b/xftp-web/web/upload.ts
@@ -9,9 +9,13 @@ import {
 import {getDescriptionServers, serverOrigin} from '../src/protocol/address.js'
 import {XFTPPermanentError} from '../src/client.js'
 
+//Maximum allowed upload size
 const MAX_SIZE = 100 * 1024 * 1024
+//How much progress bar reserved for encryption phase.
 const ENCRYPT_WEIGHT = 0.15
+// Only show encryption UI for files large enough to notice.
 const ENCRYPT_MIN_FILE_SIZE = 100 * 1024
+// Keep encryption progress visible long enough to feel smooth.
 const ENCRYPT_MIN_DISPLAY_MS = 1000
 
 export function initUpload(app: HTMLElement) {
@@ -61,7 +65,7 @@ export function initUpload(app: HTMLElement) {
   const copyBtn = document.getElementById('copy-btn')!
   const errorMsg = document.getElementById('error-msg')!
   const retryBtn = document.getElementById('retry-btn')!
-
+  //“ If the browser supports the native Web Share API, dynamically create and insert a Share button and store its reference; otherwise keep it null.”
   const shareBtn = typeof navigator.share === 'function'
     ? (() => {
         const btn = document.createElement('button')
@@ -71,7 +75,7 @@ export function initUpload(app: HTMLElement) {
         return btn
       })()
     : null
-
+ //aborted tracks whether the current async upload operation should stop, while pendingFile stores the currently selected file being processed or prepared for upload.
   let aborted = false
   let pendingFile: File | null = null
 
@@ -83,6 +87,8 @@ export function initUpload(app: HTMLElement) {
     const f = e.dataTransfer?.files[0]
     if (f) startUpload(f)
   })
+
+// This app currently supports single file upload
   fileInput.addEventListener('change', () => {
     if (fileInput.files?.[0]) startUpload(fileInput.files[0])
   })
@@ -92,6 +98,7 @@ export function initUpload(app: HTMLElement) {
     showStage(dropZone)
   })
 
+  //“Hide every application stage, then make only the requested stage visible.”
   function showStage(stage: HTMLElement) {
     for (const s of [dropZone, progressStage, completeStage, errorStage]) s.hidden = true
     stage.hidden = false
@@ -119,7 +126,9 @@ export function initUpload(app: HTMLElement) {
     const ring = createProgressRing()
     progressContainer.innerHTML = ''
     progressContainer.appendChild(ring.canvas)
-
+//adds the visual progress ring to the page, 
+// decides whether encryption progress should be shown based on file size, 
+// reserves part of the progress bar for encryption work, and updates the UI status text accordingly.
     const showEncrypt = file.size >= ENCRYPT_MIN_FILE_SIZE
     const encryptWeight = showEncrypt ? ENCRYPT_WEIGHT : 0
     statusText.textContent = showEncrypt