From 81a7a8c2157a400f709c15ee5aa9f6ddb3efc489 Mon Sep 17 00:00:00 2001
From: muhammadali-imran <imranmuhammadali633@gmail.com>
Date: Wed, 14 Oct 2026 08:00:55 +0500
Subject: [PATCH 1/2] feat: async video upload and fetch. toast system.

---
 frontend/README.md                           |  17 ++-
 frontend/docs/architecture.md                |  28 ++++-
 frontend/src/components/BasePlayer.jsx       |   8 +-
 frontend/src/components/UploadToaster.jsx    |  42 +++++++
 frontend/src/context/LibraryProvider.jsx     |  27 ++--
 frontend/src/context/UploadQueueContext.js   |   9 ++
 frontend/src/context/UploadQueueProvider.jsx | 122 +++++++++++++++++++
 frontend/src/hooks/useCachedVideo.js         |  37 ++++++
 frontend/src/main.jsx                        |  13 +-
 frontend/src/pages/Player.jsx                |  30 ++++-
 frontend/src/pages/RecordingEditor.jsx       |  34 +++---
 frontend/src/services/api.js                 |  82 +++++++++++++
 frontend/src/styles/player.css               |  16 +++
 frontend/src/utils/videoCache.js             |  86 +++++++++++++
 frontend/test/UploadQueueProvider.test.jsx   |  85 +++++++++++++
 15 files changed, 585 insertions(+), 51 deletions(-)
 create mode 100644 frontend/src/components/UploadToaster.jsx
 create mode 100644 frontend/src/context/UploadQueueContext.js
 create mode 100644 frontend/src/context/UploadQueueProvider.jsx
 create mode 100644 frontend/src/hooks/useCachedVideo.js
 create mode 100644 frontend/src/utils/videoCache.js
 create mode 100644 frontend/test/UploadQueueProvider.test.jsx

diff --git a/frontend/README.md b/frontend/README.md
index 774027c..c3d2eba 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -68,8 +68,19 @@ Contributor recordings stay in memory as a `Blob` while the user moves between
 the player and editor; closing the tab discards an unsubmitted take. On
 submission, the frontend uploads the recording and trim/mirror metadata to the
 backend. The backend validates and stores the recording and enforces the
-submission cooldown. Admins prepare reference and demo videos in the browser
-before upload: they can remove audio and trim the clip, with processing performed
+submission cooldown. After submission, the recording uploads in the background:
+one upload can run while one waits, and the contributor can continue browsing.
+Failed uploads remain in the queue until retried or discarded. The queue is
+memory-only, so the browser warns before a pending upload is lost; switching
+accounts clears that account's queue.
+
+Reference videos are downloaded into an in-memory cache for five minutes after
+download completes, and the next video in the category is prefetched. Individual
+videos larger than 100 MB bypass the cache, and cached entries are limited to
+250 MB total; videos still playing are not revoked mid-playback.
+
+Admins prepare reference and demo videos in the browser before upload: they can
+remove audio and trim the clip, with processing performed
 locally by ffmpeg.wasm when changes are applied. The browser also reports the
 video's displayed dimensions and duration; the backend stores these values for
 responsive playback and display. No video-processing worker is required on the
@@ -90,7 +101,7 @@ src/
   main.jsx            Browser entry point and provider setup
   components/         Shared layouts, controls, navigation, and route guards
   config/             UI configuration
-  context/            Auth, library, recording, notification, and theme state
+  context/            Auth, library, recording, upload queue, notification, and theme state
   hooks/              Reusable hooks, including camera/MediaRecorder handling
   pages/              Public and contributor pages
   pages/admin/        Admin workspace pages
diff --git a/frontend/docs/architecture.md b/frontend/docs/architecture.md
index 72a1e7f..6e9b34a 100644
--- a/frontend/docs/architecture.md
+++ b/frontend/docs/architecture.md
@@ -54,6 +54,7 @@ management library.
 | `AuthProvider` | Loads the current session from the API and exposes login, signup, email verification, logout, and connection updates. |
 | `LibraryProvider` | Loads categories, visible videos, and the current user's submissions; provides derived category, contribution, and cooldown state plus admin mutations. |
 | `RecordingProvider` | Holds unsubmitted recording blobs and trim/mirror edits in memory, keyed by video ID. These drafts are discarded on submit, replacement, user change, or tab close. |
+| `UploadQueueProvider` | Holds up to two submitted recordings in an in-memory queue (one uploading and one waiting). Failed uploads keep their slot for retry or discard; the queue is cleared when the signed-in user changes. |
 | `NotificationProvider` | Stores per-user notification items and read state in browser `localStorage`; notifications do not sync across devices. |
 | `ThemeProvider` | Follows the OS theme until a user selects one, then persists the selection locally. |
 
@@ -88,9 +89,24 @@ interface hint; the backend independently enforces the cooldown.
 `useRecorder` captures camera and microphone media through browser media APIs.
 The `RecordingProvider` keeps the current take available while a contributor
 moves between `/watch` and `/watch/edit`. The editor applies trim and mirror
-settings as submission metadata, then uploads the recording blob and metadata
-through the API service. The backend stores the uploaded recording and metadata;
-it does not physically trim or transcode contributor recordings.
+settings as submission metadata, then hands the recording blob and metadata to
+`UploadQueueProvider`. Uploads run one at a time through an XMLHttpRequest so
+the UI can report byte progress and abort on account changes. The editor returns
+to the player immediately; a page-level toaster reports waiting, active, failed,
+and completed uploads. Failed uploads retain their queue slot until retried or
+discarded. Queue data is memory-only, and a `beforeunload` prompt warns if the
+tab is closed or reloaded while work remains. The backend stores contributor
+recordings and metadata; it does not physically trim or transcode them.
+
+### Reference-video cache
+
+`useCachedVideo` loads reference videos into an in-memory Blob cache and falls
+back to the normal media URL if the download fails or exceeds the per-video
+100 MB cap. Entries expire five minutes after download and the cache evicts
+oldest entries to stay within a 250 MB total budget. A player holds its entry
+while it is in use so an expired or evicted object URL is not revoked during
+playback. The player also prefetches the next video in its category after the
+current video's load attempt finishes.
 
 ### Admin video preparation and responsive playback
 
@@ -164,10 +180,10 @@ frontend/
     seo/                    # SEO metadata and helpers
     styles/                 # Theme tokens and feature styles
     utils/                  # Shared browser and media utilities
-    test/
-      RecorderPanel.test.jsx # Recorder workflow component tests
     docs/
-    ARCHITECTURE.md         # This guide
+      architecture.md       # This guide
+  test/
+    RecorderPanel.test.jsx  # Recorder workflow component tests
   scripts/
     generateSeoAssets.js    # Sitemap, robots, and prerender route generation
     runReactSnap.js         # Static route prerendering
diff --git a/frontend/src/components/BasePlayer.jsx b/frontend/src/components/BasePlayer.jsx
index e2c6de1..47a0272 100644
--- a/frontend/src/components/BasePlayer.jsx
+++ b/frontend/src/components/BasePlayer.jsx
@@ -6,7 +6,7 @@ import ResponsiveVideo from './ResponsiveVideo'
 const SPEEDS = [0.5, 0.75, 1]
 
 /** Base video player: play/pause, replay, seek, speed and fullscreen. The parent owns the <video> ref. */
-export default function BasePlayer({ video, videoRef, onAspect }) {
+export default function BasePlayer({ video, videoRef, onAspect, src, loading, progress }) {
   const frame = useRef(null)
   const [playing, setPlaying] = useState(false)
   const [time, setTime] = useState(0)
@@ -45,7 +45,7 @@ export default function BasePlayer({ video, videoRef, onAspect }) {
       <div className="base-player-stage">
         <ResponsiveVideo
           videoRef={videoRef}
-          src={video.videoUrl}
+          src={src}
           poster={video.poster}
           aspect={aspectOf(video)}
           onAspect={onAspect}
@@ -63,7 +63,9 @@ export default function BasePlayer({ video, videoRef, onAspect }) {
           onLoadedMetadata={(event) => setDuration(event.currentTarget.duration)}
           onError={() => setFailed(true)}
         >
-          {failed ? (
+          {loading && !failed ? (
+            <p className="base-player-loading" role="status">Loading video{Number.isFinite(progress) && progress > 0 ? ` ${Math.round(progress * 100)}%` : '…'}</p>
+          ) : failed ? (
             <p className="base-player-error" role="alert">This video could not be loaded. Try again later or pick another video.</p>
           ) : (
             !playing && <button type="button" className="base-player-big" onClick={toggle} aria-label="Play video">▶</button>
diff --git a/frontend/src/components/UploadToaster.jsx b/frontend/src/components/UploadToaster.jsx
new file mode 100644
index 0000000..e889ea2
--- /dev/null
+++ b/frontend/src/components/UploadToaster.jsx
@@ -0,0 +1,42 @@
+import { Button } from './ui'
+
+const percent = (fraction) => `${Math.round((fraction || 0) * 100)}%`
+
+/**
+ * Upload status in the corner of every page. Uploads that are waiting or running cannot be closed:
+ * they stay until they finish. A failed one offers Retry or Discard, and a finished one fades after a few seconds.
+ */
+export default function UploadToaster({ items, toasts, onRetry, onDiscard, onDismiss }) {
+  if (!items.length && !toasts.length) return null
+  return (
+    <div className="toaster" role="region" aria-label="Recording uploads" aria-live="polite">
+      {items.map((item) => (
+        <div key={item.id} className={`toast ${item.status === 'failed' ? 'is-error' : ''}`}>
+          {item.status === 'failed' ? (
+            <>
+              <p className="toast-title">Upload failed</p>
+              <p className="toast-body">“{item.title}”: {item.error}</p>
+              <div className="toast-actions">
+                <Button onClick={() => onRetry(item.id)}>Try again</Button>
+                <Button variant="outline" onClick={() => onDiscard(item.id)}>Discard recording</Button>
+              </div>
+            </>
+          ) : (
+            <>
+              <p className="toast-title">{item.status === 'uploading' ? `Uploading ${percent(item.progress)}` : 'Waiting to upload'}</p>
+              <p className="toast-body">“{item.title}”{item.status === 'waiting' ? ' starts when the previous upload finishes.' : ' — you can keep browsing.'}</p>
+              {item.status === 'uploading' && <progress className="toast-progress" max="1" value={item.progress} aria-label={`Uploading ${item.title}`} />}
+            </>
+          )}
+        </div>
+      ))}
+      {toasts.map((toast) => (
+        <div key={toast.id} className="toast is-success">
+          <p className="toast-title">✓ {toast.title}</p>
+          <p className="toast-body">“{toast.body}” is saved. Thank you for contributing.</p>
+          <button type="button" className="toast-close" onClick={() => onDismiss(toast.id)} aria-label="Dismiss">×</button>
+        </div>
+      ))}
+    </div>
+  )
+}
diff --git a/frontend/src/context/LibraryProvider.jsx b/frontend/src/context/LibraryProvider.jsx
index a197545..6b31b1b 100644
--- a/frontend/src/context/LibraryProvider.jsx
+++ b/frontend/src/context/LibraryProvider.jsx
@@ -5,6 +5,7 @@ import { api } from '../services/api'
 import { paths } from '../routes/appRoutes'
 import { useAuth } from './AuthContext'
 import { LibraryContext } from './LibraryContext'
+import { useUploadQueue } from './UploadQueueContext'
 
 const EMPTY = { ready: false, ownerId: null, categories: [], videos: [], submissions: [] }
 const SUBMISSION_COOLDOWN_MS = Number(import.meta.env.VITE_SUBMISSION_COOLDOWN_MS || 30_000)
@@ -30,6 +31,7 @@ function isLibraryRoute(pathname) {
 
 export default function LibraryProvider({ children }) {
   const { user } = useAuth()
+  const { lastSubmission } = useUploadQueue()
   const location = useLocation()
   const [data, setData] = useState(EMPTY)
   const [loadError, setLoadError] = useState(null)
@@ -45,6 +47,18 @@ export default function LibraryProvider({ children }) {
     setLoadError(null)
   }, [user])
 
+  // A background upload just finished: fold it into the library so counts, badges and the
+  // record-again cooldown update without a page change.
+  const seenSubmission = useRef(lastSubmission)
+  useEffect(() => {
+    if (!lastSubmission || lastSubmission === seenSubmission.current) return
+    seenSubmission.current = lastSubmission
+    setData((current) => (current.ready
+      ? { ...current, submissions: [lastSubmission, ...current.submissions.filter((item) => item.id !== lastSubmission.id)] }
+      : current))
+    void refresh().catch(() => {})
+  }, [lastSubmission, refresh])
+
   useEffect(() => {
     if (!user || !shouldLoad || (data.ready && data.ownerId === user.id)) return undefined
 
@@ -107,19 +121,6 @@ export default function LibraryProvider({ children }) {
       totalSubmissionCount: mySubmissions.length,
       cooldownMs: SUBMISSION_COOLDOWN_MS,
 
-      async submitRecording(video, recording) {
-        const submission = await api.submissions.create({
-          videoId: video.id, recording: recording.blob, trimStart: recording.edit.start, trimEnd: recording.edit.end,
-          mirrored: recording.edit.mirrored, duration: recording.duration, size: recording.blob.size, mimeType: recording.mimeType,
-        })
-        void refresh().catch(() => {
-          setData((current) => ({
-            ...current,
-            submissions: [submission, ...current.submissions.filter((item) => item.id !== submission.id)],
-          }))
-        })
-        return submission
-      },
       async addCategory(values) { const created = await api.categories.create(values); await refresh(); return created },
       async editCategory(id, patch) { await api.categories.update(id, patch); await refresh() },
       async deleteCategory(id) { await api.categories.remove(id); await refresh() },
diff --git a/frontend/src/context/UploadQueueContext.js b/frontend/src/context/UploadQueueContext.js
new file mode 100644
index 0000000..c88227d
--- /dev/null
+++ b/frontend/src/context/UploadQueueContext.js
@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react'
+
+export const UploadQueueContext = createContext(null)
+
+export function useUploadQueue() {
+  const value = useContext(UploadQueueContext)
+  if (!value) throw new Error('useUploadQueue must be used inside <UploadQueueProvider>')
+  return value
+}
diff --git a/frontend/src/context/UploadQueueProvider.jsx b/frontend/src/context/UploadQueueProvider.jsx
new file mode 100644
index 0000000..9676b0b
--- /dev/null
+++ b/frontend/src/context/UploadQueueProvider.jsx
@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import UploadToaster from '../components/UploadToaster'
+import { api } from '../services/api'
+import { watchUrl } from '../routes/appRoutes'
+import { useAuth } from './AuthContext'
+import { useNotifications } from './NotificationContext'
+import { UploadQueueContext } from './UploadQueueContext'
+
+/** One recording uploading and one waiting in the browser. Failed ones still hold a slot until retried or discarded. */
+export const MAX_QUEUED = 2
+const SUCCESS_TOAST_MS = 7000
+
+let nextId = 0
+const newId = (prefix) => `${prefix}_${Date.now()}_${nextId++}`
+
+/**
+ * Uploads submitted recordings in the background, strictly one at a time, so a contributor can
+ * keep browsing, watching and recording while earlier takes are still going up.
+ *
+ * Mounted above LibraryProvider on purpose: that provider swaps its children for a loading screen
+ * while the library loads, which would otherwise unmount an upload in progress.
+ * Recordings wait in memory only; leaving the tab with uploads pending shows the browser's warning.
+ */
+export default function UploadQueueProvider({ children }) {
+  const { user } = useAuth()
+  const { notify } = useNotifications()
+  const userId = user?.id
+  const [items, setItems] = useState([]) // { id, videoId, title, status: waiting|uploading|failed, progress, error, recording }
+  const [toasts, setToasts] = useState([]) // finished uploads, shown briefly
+  const [lastSubmission, setLastSubmission] = useState(null)
+  const running = useRef(null) // { id, controller }
+  const notifyRef = useRef(notify)
+  useEffect(() => { notifyRef.current = notify }, [notify])
+
+  const patch = useCallback((id, changes) => {
+    setItems((current) => current.map((item) => (item.id === id ? { ...item, ...changes } : item)))
+  }, [])
+
+  const addToast = useCallback((toast) => {
+    const id = newId('toast')
+    setToasts((current) => [...current, { id, ...toast }])
+    setTimeout(() => setToasts((current) => current.filter((item) => item.id !== id)), SUCCESS_TOAST_MS)
+  }, [])
+
+  const run = useCallback(async (item) => {
+    const controller = new AbortController()
+    running.current = { id: item.id, controller }
+    const { recording } = item
+    try {
+      const submission = await api.submissions.upload({
+        videoId: item.videoId, recording: recording.blob, trimStart: recording.edit.start, trimEnd: recording.edit.end,
+        mirrored: recording.edit.mirrored, duration: recording.duration, signal: controller.signal,
+        onProgress: (progress) => patch(item.id, { progress }),
+      })
+      setItems((current) => current.filter((entry) => entry.id !== item.id))
+      setLastSubmission(submission)
+      addToast({ title: 'Recording submitted', body: item.title })
+      notifyRef.current({ type: 'submission', title: 'Recording submitted', body: item.title, href: watchUrl(item.videoId) }).catch(() => {})
+    } catch (error) {
+      if (error?.name === 'AbortError') return
+      const message = error?.message || 'The upload failed.'
+      patch(item.id, { status: 'failed', error: message })
+      notifyRef.current({ type: 'submission', title: 'Recording not uploaded', body: `${item.title}: ${message}`, href: watchUrl(item.videoId) }).catch(() => {})
+    } finally {
+      if (running.current?.id === item.id) running.current = null
+    }
+  }, [addToast, patch])
+
+  // The queue's heartbeat: whenever nothing is uploading, start the oldest waiting recording.
+  useEffect(() => {
+    if (running.current) return
+    const next = items.find((item) => item.status === 'waiting')
+    if (!next) return
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- advancing the queue is a state machine step; `running` guards against starting twice
+    patch(next.id, { status: 'uploading', progress: 0 })
+    void run(next)
+  }, [items, patch, run])
+
+  // A different person (or nobody) on this tab: drop their queue and stop the upload.
+  useEffect(() => () => {
+    running.current?.controller.abort()
+    running.current = null
+    setItems([])
+    setToasts([])
+  }, [userId])
+
+  // Pending recordings only exist in this tab's memory, so warn before it is closed or reloaded.
+  const pending = items.length > 0
+  useEffect(() => {
+    if (!pending) return undefined
+    const warn = (event) => { event.preventDefault(); event.returnValue = '' }
+    window.addEventListener('beforeunload', warn)
+    return () => window.removeEventListener('beforeunload', warn)
+  }, [pending])
+
+  const enqueue = useCallback((video, recording) => {
+    if (!userId) return { ok: false, reason: 'Log in to submit recordings.' }
+    if (items.some((item) => item.videoId === video.id)) return { ok: false, reason: 'This video is already in the upload queue.' }
+    if (items.length >= MAX_QUEUED) return { ok: false, reason: 'Two recordings are already queued. Submit this one when an upload finishes.' }
+    setItems((current) => [...current, { id: newId('upload'), videoId: video.id, title: video.title, status: 'waiting', progress: 0, error: '', recording }])
+    return { ok: true }
+  }, [items, userId])
+
+  const retry = useCallback((id) => patch(id, { status: 'waiting', progress: 0, error: '' }), [patch])
+  const discard = useCallback((id) => {
+    if (running.current?.id === id) running.current.controller.abort()
+    setItems((current) => current.filter((item) => item.id !== id))
+  }, [])
+  const dismissToast = useCallback((id) => setToasts((current) => current.filter((item) => item.id !== id)), [])
+
+  const value = useMemo(() => ({
+    items, lastSubmission, isFull: items.length >= MAX_QUEUED, enqueue, retry, discard,
+    itemFor: (videoId) => items.find((item) => item.videoId === videoId) || null,
+  }), [items, lastSubmission, enqueue, retry, discard])
+
+  return (
+    <UploadQueueContext.Provider value={value}>
+      {children}
+      {userId && <UploadToaster items={items} toasts={toasts} onRetry={retry} onDiscard={discard} onDismiss={dismissToast} />}
+    </UploadQueueContext.Provider>
+  )
+}
diff --git a/frontend/src/hooks/useCachedVideo.js b/frontend/src/hooks/useCachedVideo.js
new file mode 100644
index 0000000..51a2b24
--- /dev/null
+++ b/frontend/src/hooks/useCachedVideo.js
@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react'
+import { holdVideo, loadVideo, releaseVideo, removeVideoProgressListener } from '../utils/videoCache'
+
+/**
+ * Gives a player the cached copy of a video, downloading it first if needed.
+ * status: 'loading' (progress is 0-1 or null) | 'ready' (src is a local blob URL)
+ *       | 'network' (caching was not possible, so src is the plain server URL).
+ */
+export function useCachedVideo(video) {
+  const url = video?.videoUrl
+  const [state, setState] = useState({ url, status: 'loading', progress: 0, src: undefined })
+
+  useEffect(() => {
+    if (!url) return undefined
+    let active = true
+    let held = null
+    const onProgress = (progress) => { if (active) setState((current) => (current.status === 'loading' ? { ...current, progress } : current)) }
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- restart from "loading" whenever the video changes
+    setState({ url, status: 'loading', progress: 0, src: undefined })
+    loadVideo({ videoUrl: url }, onProgress)
+      .then((entry) => {
+        if (!active || entry.expired || !entry.url) { if (active) setState({ url, status: 'network', progress: 1, src: url }); return }
+        holdVideo(entry)
+        held = entry
+        setState({ url, status: 'ready', progress: 1, src: entry.url })
+      })
+      .catch(() => { if (active) setState({ url, status: 'network', progress: 1, src: url }) })
+    return () => {
+      active = false
+      removeVideoProgressListener(url, onProgress)
+      if (held) releaseVideo(held)
+    }
+  }, [url])
+
+  // A state object for a previous video must never be applied to the current one.
+  return state.url === url ? state : { url, status: 'loading', progress: 0, src: undefined }
+}
diff --git a/frontend/src/main.jsx b/frontend/src/main.jsx
index 4539bee..ac47b15 100644
--- a/frontend/src/main.jsx
+++ b/frontend/src/main.jsx
@@ -8,6 +8,7 @@ import LibraryProvider from './context/LibraryProvider.jsx'
 import NotificationProvider from './context/NotificationProvider.jsx'
 import RecordingProvider from './context/RecordingProvider.jsx'
 import ThemeProvider from './context/ThemeProvider.jsx'
+import UploadQueueProvider from './context/UploadQueueProvider.jsx'
 
 createRoot(document.getElementById('root')).render(
   <StrictMode>
@@ -15,11 +16,13 @@ createRoot(document.getElementById('root')).render(
       <BrowserRouter>
         <AuthProvider>
           <NotificationProvider>
-            <LibraryProvider>
-              <RecordingProvider>
-                <App />
-              </RecordingProvider>
-            </LibraryProvider>
+            <UploadQueueProvider>
+              <LibraryProvider>
+                <RecordingProvider>
+                  <App />
+                </RecordingProvider>
+              </LibraryProvider>
+            </UploadQueueProvider>
           </NotificationProvider>
         </AuthProvider>
       </BrowserRouter>
diff --git a/frontend/src/pages/Player.jsx b/frontend/src/pages/Player.jsx
index 263ab9e..f7e6298 100644
--- a/frontend/src/pages/Player.jsx
+++ b/frontend/src/pages/Player.jsx
@@ -3,9 +3,12 @@ import { Link, useLocation, useNavigate, useSearchParams } from 'react-router-do
 import BasePlayer from '../components/BasePlayer'
 import RecorderPanel from '../components/RecorderPanel'
 import { Alert, Button, ButtonLink, Eyebrow, PageState } from '../components/ui'
+import { useCachedVideo } from '../hooks/useCachedVideo'
 import { useLibrary } from '../context/LibraryContext'
+import { useUploadQueue } from '../context/UploadQueueContext'
 import { categoryUrl, paths, watchEditUrl, watchUrl } from '../routes/appRoutes'
 import { aspectOf, orientationOf } from '../utils/media'
+import { prefetchVideo } from '../utils/videoCache'
 import { safeRouteId } from '../utils/validators'
 
 export default function Player() {
@@ -43,10 +46,18 @@ function PlayerScreen({ videoId }) {
     refresh 
   } = useLibrary()
 
+  const uploads = useUploadQueue()
   const navigate = useNavigate()
   const location = useLocation()
   const baseRef = useRef(null)
   const video = publishedVideos.find((item) => item.id === videoId)
+  // The video downloads once and stays in the browser for 5 minutes; the next one is fetched while this one plays.
+  const cached = useCachedVideo(video)
+  const upNext = video ? nextVideo(video) : null
+  const cachedStatus = cached.status
+  useEffect(() => {
+    if (cachedStatus !== 'loading' && upNext) prefetchVideo(upNext)
+  }, [cachedStatus, upNext])
 
   // The page layout follows the video's shape: tall phone videos get a narrow window and more room for the recorder.
   const [measuredAspect, setMeasuredAspect] = useState(null)
@@ -100,7 +111,7 @@ function PlayerScreen({ videoId }) {
 
       <section className="shell player-grid" data-orientation={aspect ? orientationOf(aspect) : 'landscape'}>
         <div>
-          <BasePlayer video={video} videoRef={baseRef} onAspect={setMeasuredAspect} />
+          <BasePlayer video={video} videoRef={baseRef} onAspect={setMeasuredAspect} src={cached.src} loading={cached.status === 'loading'} progress={cached.progress} />
           
           <div className="player-meta">
             <div>
@@ -114,13 +125,26 @@ function PlayerScreen({ videoId }) {
 
           {justSubmitted && (
             <Alert tone="success">
-              Recording received — thank you for contributing.
+              Recording queued — it uploads in the background, so you can pick your next video now.
             </Alert>
           )}
         </div>
 
         <aside className="player-side">
-          {remaining > 0 ? (
+          {uploads.itemFor(video.id) ? (
+            <div className="cooldown">
+              <p className="recorder-status is-live"><span aria-hidden="true">●</span> {uploads.itemFor(video.id).status === 'failed' ? 'Upload failed' : uploads.itemFor(video.id).status === 'uploading' ? `Uploading ${Math.round(uploads.itemFor(video.id).progress * 100)}%` : 'Waiting to upload'}</p>
+              <h2 className="display display-md">
+                Your recording<br /><em>is on its way.</em>
+              </h2>
+              <p className="recorder-copy">
+                You don't have to wait. Watch and record other videos while this one uploads; details are in the corner of the screen.
+              </p>
+              <Button block onClick={goNext}>
+                {next ? 'Next video' : 'Back to videos'} →
+              </Button>
+            </div>
+          ) : remaining > 0 ? (
             <div className="cooldown">
               <p className="recorder-status">
                 <span aria-hidden="true">✓</span> {count > 1 ? `Recorded ${count} times` : 'Recorded'}
diff --git a/frontend/src/pages/RecordingEditor.jsx b/frontend/src/pages/RecordingEditor.jsx
index c1717a8..ca92525 100644
--- a/frontend/src/pages/RecordingEditor.jsx
+++ b/frontend/src/pages/RecordingEditor.jsx
@@ -4,8 +4,8 @@ import ResponsiveVideo from '../components/ResponsiveVideo'
 import TrimSlider from '../components/TrimSlider'
 import { Alert, Arrow, Button, ButtonLink, Eyebrow, PageState } from '../components/ui'
 import { useLibrary } from '../context/LibraryContext'
-import { useNotifications } from '../context/NotificationContext'
 import { useRecordings } from '../context/RecordingContext'
+import { useUploadQueue } from '../context/UploadQueueContext'
 import { paths, watchUrl } from '../routes/appRoutes'
 import { formatTime } from '../utils/format'
 import { aspectOf, orientationOf } from '../utils/media'
@@ -19,8 +19,8 @@ export default function RecordingEditor() {
 }
 
 function EditScreen({ videoId }) {
-  const { publishedVideos, submitRecording } = useLibrary()
-  const { notify } = useNotifications()
+  const { publishedVideos } = useLibrary()
+  const uploads = useUploadQueue()
   const { recordings, removeRecording, updateEdit } = useRecordings()
   const navigate = useNavigate()
   const video = publishedVideos.find((item) => item.id === videoId)
@@ -55,22 +55,19 @@ function EditScreen({ videoId }) {
       video={video} 
       recording={recording}
       onEdit={(patch) => updateEdit(video.id, patch)}
-      onSubmit={async () => {
-        await submitRecording(video, recording)
+      queueFull={uploads.isFull}
+      onSubmit={() => {
+        // Hand the take to the background queue, then free the editor straight away.
+        const result = uploads.enqueue(video, recording)
+        if (!result.ok) throw new Error(result.reason)
         removeRecording(video.id)
-        await notify({ 
-          type: 'submission', 
-          title: 'Recording submitted', 
-          body: video.title, 
-          href: watchUrl(video.id) 
-        }).catch(() => {})
         navigate(watchUrl(video.id), { state: { justSubmitted: true } })
       }}
     />
   )
 }
 
-function Editor({ video, recording, onEdit, onSubmit }) {
+function Editor({ video, recording, queueFull, onEdit, onSubmit }) {
   const preview = useRef(null)
   const { start, end, mirrored } = recording.edit
   const total = recording.duration
@@ -134,11 +131,11 @@ function Editor({ video, recording, onEdit, onSubmit }) {
     }
   }
 
-  const submit = async () => {
+  const submit = () => {
     setBusy(true)
     setError('')
     try { 
-      await onSubmit() 
+      onSubmit()
     } catch (caught) { 
       setError(caught.message || 'Your recording could not be submitted. Try again.')
       setBusy(false) 
@@ -229,13 +226,14 @@ function Editor({ video, recording, onEdit, onSubmit }) {
           </label>
 
           {error && <Alert tone="error">{error}</Alert>}
+          {queueFull && !confirming && <Alert tone="info">Two recordings are already queued. You can submit this one as soon as an upload finishes.</Alert>}
 
           {confirming ? (
             <div className="confirm">
-              <p>Submit this recording? Once submitted it can't be watched, edited or deleted, but you can record this video again after a short cooldown.</p>
+              <p>Submit this recording? It uploads in the background, so you can keep browsing and record the next video. Once submitted it can't be watched, edited or deleted, but you can record this video again after a short cooldown.</p>
               <div className="confirm-actions">
-                <Button onClick={submit} disabled={busy || !trimApplied}>
-                  {busy ? 'Submitting…' : 'Yes, submit'}
+                <Button onClick={submit} disabled={busy || !trimApplied || queueFull}>
+                  {busy ? 'Queuing…' : 'Yes, submit'}
                 </Button>
                 <Button variant="outline" onClick={() => setConfirming(false)} disabled={busy}>
                   Keep editing
@@ -247,7 +245,7 @@ function Editor({ video, recording, onEdit, onSubmit }) {
               block 
               className="editor-submit" 
               onClick={() => setConfirming(true)} 
-              disabled={!trimApplied}
+              disabled={!trimApplied || queueFull}
             >
               Submit recording <Arrow />
             </Button>
diff --git a/frontend/src/services/api.js b/frontend/src/services/api.js
index f8a0b37..8f173e8 100644
--- a/frontend/src/services/api.js
+++ b/frontend/src/services/api.js
@@ -64,6 +64,40 @@ async function request(path, options = {}) {
   return payload.data
 }
 
+/**
+ * POST a FormData body with real upload progress (fetch cannot report it).
+ * Rejects with the same Error shape as request(); an aborted upload rejects with name 'AbortError'.
+ */
+function uploadWithProgress(path, body, { onProgress, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest()
+    const abort = () => xhr.abort()
+    xhr.open('POST', path)
+    xhr.withCredentials = true
+    const deviceId = getDeviceId()
+    if (deviceId) xhr.setRequestHeader('X-Device-ID', deviceId)
+    xhr.upload.onprogress = (event) => { if (event.lengthComputable) onProgress?.(event.loaded / event.total) }
+    xhr.onload = () => {
+      let payload = {}
+      try { payload = JSON.parse(xhr.responseText) } catch { /* non-JSON error page */ }
+      if (xhr.status >= 200 && xhr.status < 300) { resolve(payload.data); return }
+      const error = new Error(payload.error?.message || `Request failed (${xhr.status})`)
+      error.fields = payload.error?.fields || {}
+      error.status = xhr.status
+      reject(error)
+    }
+    xhr.onerror = () => reject(new Error('The connection was lost while uploading. Check your internet and try again.'))
+    xhr.onabort = () => reject(Object.assign(new Error('Upload cancelled.'), { name: 'AbortError' }))
+    if (signal?.aborted) {
+      reject(Object.assign(new Error('Upload cancelled.'), { name: 'AbortError' }))
+      return
+    }
+    signal?.addEventListener('abort', abort, { once: true })
+    xhr.onloadend = () => signal?.removeEventListener('abort', abort)
+    xhr.send(body)
+  })
+}
+
 const json = (method, body) => ({ method, body: JSON.stringify(body) })
 const normalizeList = (items) => (items || []).map(normalize)
 const PUBLIC_STATS_CACHE_KEY = `${PREFIX}public-stats`
@@ -202,8 +236,56 @@ export const api = {
     async remove() { await request(apiRoutes.demoVideo.remove(), { method: 'DELETE' }) },
   },
 
+  media: {
+    /**
+     * Downloads a whole video into a Blob, reporting progress as a 0-1 fraction (or null when the
+     * size is unknown). Throws an Error with code 'TOO_LARGE' before downloading when it exceeds maxBytes.
+     */
+    async fetchVideo(url, { onProgress, signal, maxBytes } = {}) {
+      const headers = new Headers()
+      const deviceId = getDeviceId()
+      if (deviceId) headers.set('X-Device-ID', deviceId)
+      const response = await fetch(url, { credentials: 'include', headers, signal })
+      if (!response.ok) throw new Error(`The video could not be loaded (${response.status}).`)
+      const total = Number(response.headers.get('Content-Length')) || 0
+      if (maxBytes && total > maxBytes) throw Object.assign(new Error('The video is too large to keep in the browser.'), { code: 'TOO_LARGE' })
+      const type = response.headers.get('Content-Type') || 'video/mp4'
+      if (!response.body) {
+        const blob = await response.blob()
+        if (maxBytes && blob.size > maxBytes) throw Object.assign(new Error('The video is too large to keep in the browser.'), { code: 'TOO_LARGE' })
+        return blob
+      }
+      const reader = response.body.getReader()
+      const chunks = []
+      let loaded = 0
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        chunks.push(value)
+        loaded += value.length
+        if (maxBytes && loaded > maxBytes) {
+          await reader.cancel().catch(() => {})
+          throw Object.assign(new Error('The video is too large to keep in the browser.'), { code: 'TOO_LARGE' })
+        }
+        onProgress?.(total ? Math.min(loaded / total, 1) : null)
+      }
+      return new Blob(chunks, { type })
+    },
+  },
+
   submissions: {
     async list() { return normalizeList(await request(apiRoutes.submissions.list())) },
+    /** Same as create(), but reports upload progress (0-1) and can be aborted with `signal`. */
+    async upload({ recording, videoId, trimStart, trimEnd, mirrored, duration, onProgress, signal }) {
+      const body = new FormData()
+      body.append('recording', recording, 'recording.webm')
+      body.append('videoId', videoId)
+      body.append('trimStart', String(trimStart))
+      body.append('trimEnd', String(trimEnd))
+      body.append('mirrored', String(Boolean(mirrored)))
+      body.append('duration', String(duration))
+      return normalize(await uploadWithProgress(apiRoutes.submissions.create(), body, { onProgress, signal }))
+    },
     async create({ recording, videoId, trimStart, trimEnd, mirrored, duration }) {
       const body = new FormData()
       body.append('recording', recording, 'recording.webm')
diff --git a/frontend/src/styles/player.css b/frontend/src/styles/player.css
index 6c244f3..3a6dea8 100644
--- a/frontend/src/styles/player.css
+++ b/frontend/src/styles/player.css
@@ -109,3 +109,19 @@
   .submitted-check { @apply mb-6 grid h-16 w-16 place-items-center rounded-full bg-success-soft text-2xl text-success; }
   .submitted-actions { @apply mt-10 flex flex-wrap items-center gap-3; }
 }
+
+/* Background upload toaster and video loading state. */
+@layer components {
+  .base-player-loading { @apply absolute inset-0 grid place-content-center px-6 text-center font-ui text-base font-semibold text-white; }
+  .toaster { @apply fixed bottom-4 right-4 z-50 grid w-[min(24rem,calc(100vw-2rem))] gap-3; }
+  .toast { @apply relative grid gap-1.5 rounded-2xl border border-line bg-surface p-4 shadow-lift; }
+  .toast.is-error { @apply border-danger; }
+  .toast.is-success { @apply border-success; }
+  .toast-title { @apply m-0 font-ui text-sm font-bold text-heading; }
+  .toast.is-error .toast-title { @apply text-danger; }
+  .toast.is-success .toast-title { @apply pr-8 text-success; }
+  .toast-body { @apply m-0 text-sm leading-snug text-muted; }
+  .toast-progress { @apply mt-1 h-2 w-full; accent-color: var(--brand); }
+  .toast-actions { @apply mt-2 flex flex-wrap gap-2; }
+  .toast-close { @apply absolute right-2 top-2 grid h-8 w-8 place-items-center rounded-full text-lg text-muted hover:bg-panel hover:text-heading; }
+}
diff --git a/frontend/src/utils/videoCache.js b/frontend/src/utils/videoCache.js
new file mode 100644
index 0000000..3e3ee43
--- /dev/null
+++ b/frontend/src/utils/videoCache.js
@@ -0,0 +1,86 @@
+import { api } from '../services/api'
+
+/**
+ * In-memory cache of reference videos. A video that has been fetched stays in the browser for
+ * VIDEO_TTL_MS, so replaying it or coming back to it needs no download, and the next video can be
+ * fetched ahead of time. It lives at module level, so it survives navigating between pages.
+ *
+ * Why not rely on the browser's HTTP cache: <video> streams use Range requests, which browsers cache
+ * unpredictably (Safari and Firefox often skip them), so "kept for 5 minutes" could not be promised.
+ */
+export const VIDEO_TTL_MS = 5 * 60 * 1000
+const MAX_VIDEO_BYTES = 100 * 1024 * 1024 // bigger files are streamed from the network instead
+const MAX_TOTAL_BYTES = 250 * 1024 * 1024 // oldest entries are dropped past this
+
+const entries = new Map() // videoUrl -> entry
+
+function dispose(entry) {
+  clearTimeout(entry.timer)
+  if (entries.get(entry.key) === entry) entries.delete(entry.key)
+  entry.expired = true
+  if (!entry.holders && entry.url) { URL.revokeObjectURL(entry.url); entry.url = '' }
+  entry.listeners.clear()
+}
+
+function enforceBudget(keep) {
+  let total = 0
+  for (const entry of entries.values()) total += entry.blob?.size || 0
+  for (const entry of [...entries.values()].sort((a, b) => a.fetchedAt - b.fetchedAt)) {
+    if (total <= MAX_TOTAL_BYTES) break
+    if (entry === keep || !entry.blob) continue
+    total -= entry.blob.size
+    dispose(entry)
+  }
+}
+
+/**
+ * Starts (or joins) the download for a video. Resolves with its entry once cached: { url, blob }.
+ * Rejects when the file is too large or the request fails; callers then play from the network.
+ */
+export function loadVideo(video, onProgress) {
+  const key = video.videoUrl
+  let entry = entries.get(key)
+  if (entry && !entry.expired) {
+    if (entry.blob) {
+      onProgress?.(1)
+    } else if (onProgress) {
+      entry.listeners.add(onProgress)
+    }
+    return entry.promise
+  }
+  entry = { key, blob: null, url: '', fetchedAt: 0, holders: 0, expired: false, timer: null, listeners: new Set(onProgress ? [onProgress] : []) }
+  entry.promise = api.media.fetchVideo(key, {
+    maxBytes: MAX_VIDEO_BYTES,
+    onProgress: (fraction) => entry.listeners.forEach((listener) => listener(fraction)),
+  }).then((blob) => {
+    entry.blob = blob
+    entry.url = URL.createObjectURL(blob)
+    entry.fetchedAt = Date.now()
+    entry.timer = setTimeout(() => dispose(entry), VIDEO_TTL_MS)
+    enforceBudget(entry)
+    entry.listeners.forEach((listener) => listener(1))
+    entry.listeners.clear()
+    return entry
+  }).catch((error) => {
+    if (entries.get(key) === entry) entries.delete(key)
+    throw error
+  })
+  entries.set(key, entry)
+  return entry.promise
+}
+
+/** Fire-and-forget download, e.g. for the next video in a category. Errors are ignored. */
+export function prefetchVideo(video) {
+  if (video?.videoUrl) loadVideo(video).catch(() => {})
+}
+
+export function removeVideoProgressListener(videoUrl, listener) {
+  entries.get(videoUrl)?.listeners.delete(listener)
+}
+
+/** A player holds an entry while it plays from it, so its object URL is not revoked mid-playback. */
+export const holdVideo = (entry) => { entry.holders += 1 }
+export function releaseVideo(entry) {
+  entry.holders = Math.max(0, entry.holders - 1)
+  if (entry.expired && !entry.holders && entry.url) { URL.revokeObjectURL(entry.url); entry.url = '' }
+}
diff --git a/frontend/test/UploadQueueProvider.test.jsx b/frontend/test/UploadQueueProvider.test.jsx
new file mode 100644
index 0000000..0e90723
--- /dev/null
+++ b/frontend/test/UploadQueueProvider.test.jsx
@@ -0,0 +1,85 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import UploadQueueProvider from '../src/context/UploadQueueProvider'
+import { useUploadQueue } from '../src/context/UploadQueueContext'
+
+const { api, notify } = vi.hoisted(() => ({
+  api: { submissions: { upload: vi.fn() } },
+  notify: vi.fn(),
+}))
+
+vi.mock('../src/services/api', () => ({ api }))
+vi.mock('../src/context/AuthContext', () => ({ useAuth: () => ({ user: { id: 'user-1' } }) }))
+vi.mock('../src/context/NotificationContext', () => ({ useNotifications: () => ({ notify }) }))
+
+function QueueHarness() {
+  const queue = useUploadQueue()
+  const recording = { blob: new Blob(['video']), edit: { start: 0, end: 2, mirrored: false }, duration: 2 }
+  return (
+    <>
+      <button onClick={() => queue.enqueue({ id: 'video-1', title: 'First video' }, recording)}>Queue first</button>
+      <button onClick={() => queue.enqueue({ id: 'video-2', title: 'Second video' }, recording)}>Queue second</button>
+      <button onClick={() => queue.enqueue({ id: 'video-3', title: 'Third video' }, recording)}>Queue third</button>
+      <output aria-label="queued uploads">{queue.items.map(({ title, status }) => `${title}: ${status}`).join('; ')}</output>
+    </>
+  )
+}
+
+function deferred() {
+  let resolve
+  let reject
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise
+    reject = rejectPromise
+  })
+  return { promise, resolve, reject }
+}
+
+describe('UploadQueueProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    notify.mockResolvedValue(undefined)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('serializes two queued uploads and retries a failure', async () => {
+    const firstAttempt = deferred()
+    const firstRetry = deferred()
+    const secondUpload = deferred()
+    api.submissions.upload
+      .mockReturnValueOnce(firstAttempt.promise)
+      .mockReturnValueOnce(firstRetry.promise)
+      .mockReturnValueOnce(secondUpload.promise)
+
+    render(
+      <UploadQueueProvider>
+        <QueueHarness />
+      </UploadQueueProvider>,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Queue first' }))
+    await waitFor(() => expect(api.submissions.upload).toHaveBeenCalledTimes(1))
+    fireEvent.click(screen.getByRole('button', { name: 'Queue second' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Queue third' }))
+
+    expect(screen.getByText(/First video: uploading; Second video: waiting/)).toBeTruthy()
+    expect(api.submissions.upload).toHaveBeenCalledTimes(1)
+
+    firstAttempt.reject(new Error('Network unavailable'))
+    await screen.findByText(/First video: failed/)
+    fireEvent.click(screen.getByRole('button', { name: 'Try again' }))
+    expect(api.submissions.upload).toHaveBeenCalledTimes(2)
+    expect(screen.getByLabelText('queued uploads').textContent).toBe('First video: waiting; Second video: uploading')
+
+    firstRetry.resolve({ id: 'submission-1' })
+    await waitFor(() => expect(api.submissions.upload).toHaveBeenCalledTimes(3))
+    expect(screen.getByLabelText('queued uploads').textContent).toBe('First video: uploading')
+
+    secondUpload.resolve({ id: 'submission-2' })
+    await waitFor(() => expect(screen.getByLabelText('queued uploads').textContent).toBe(''))
+    expect(notify).toHaveBeenCalledTimes(3)
+  })
+})

From f19f2211f815ff78653c4ff82ab380b653821d88 Mon Sep 17 00:00:00 2001
From: muhammadali-imran <imranmuhammadali633@gmail.com>
Date: Wed, 14 Oct 2026 09:38:41 +0500
Subject: [PATCH 2/2] v1.0.5 and v1.0.2

---
 frontend/package-lock.json | 4 ++--
 frontend/package.json      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 0a4c37f..766f9df 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "frontend",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frontend",
-      "version": "1.0.4",
+      "version": "1.0.5",
       "dependencies": {
         "@ffmpeg/ffmpeg": "^0.12.15",
         "@ffmpeg/util": "^0.12.2",
diff --git a/frontend/package.json b/frontend/package.json
index 2ca9315..70b697a 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "engines": {
     "node": ">=20.19.0"