style(ui): add color-coded accents and tags to shortcut cards

Introduce per-card accent colors to enhance the visual hierarchy of the documentation shortcut cards. This includes adding left borders, colored eyebrows, and matching hover glows using CSS variables.

Additionally, this commit:
- Adds color-coded tags (GET, POST, JSON, etc.) for API links.
- Implements retro-themed styling for both the shortcut cards and tags to maintain consistency with the classic 16-color VGA palette.
- Applies the new accent classes to the API page template.

.gitignore

@@ -17,3 +17,4 @@ scripts/env/dev.env
 docker-compose.yml
 
 .claude
+docs/possible_new_features

README.md

@@ -357,3 +357,9 @@ bbolt database and JSON logs always remain local under `./data/db` and `./data/l
 
 The static handler sets long-lived immutable caching for images, video, audio, and fonts, shorter
 caching for CSS/JS, and gzip compression for compressible responses.
+
+## AI Usage
+
+I have used AI to accelerate development, all of the code has been reviewed by humans. I have mostly used self-hosted models as well as big models from big companies for a monthly subscription fee. 
+
+I have nothing against AI as long as you can tell me what every single line of your code does. That's how I personally view things.

backend/libs/handlers/app.go

@@ -54,6 +54,8 @@ func (a *App) renderPage(w http.ResponseWriter, r *http.Request, status int, pag
 func (a *App) RegisterRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("GET /", a.Home)
 	mux.HandleFunc("GET /api", a.APIDocs)
+	mux.HandleFunc("GET /service-worker.js", a.ServiceWorker)
+	mux.HandleFunc("POST /share-target", a.ShareTargetFallback)
 	mux.HandleFunc("GET /register", a.Register)
 	mux.HandleFunc("POST /register", a.RegisterPost)
 	mux.HandleFunc("GET /login", a.Login)

backend/libs/handlers/download.go

@@ -59,6 +59,8 @@ type fileView struct {
 	ReactionMore int
 	Reacted      bool
 	Processing   bool
+	Failed       bool
+	Error        string
 }
 
 type reactionView struct {
@@ -139,7 +141,7 @@ func (a *App) DownloadPage(w http.ResponseWriter, r *http.Request) {
 
 	expiresLabel := boxExpiryLabel(box.ExpiresAt, "Jan 2, 2006 15:04 MST")
 	title := "Shared files on Warpbox"
-	description := fmt.Sprintf("%d file%s shared via Warpbox · expires %s", len(box.Files), plural(len(box.Files)), expiresLabel)
+	description := fmt.Sprintf("%d file%s shared via Warpbox | Expires %s.", len(box.Files), plural(len(box.Files)), expiresLabel)
 	ogImage := absoluteURL(r, fmt.Sprintf("/d/%s/og-image.jpg", box.ID))
 	imageAlt := fmt.Sprintf("%d shared file%s on Warp Box", len(box.Files), plural(len(box.Files)))
 	imageType := "image/jpeg"
@@ -201,7 +203,7 @@ func fileShareDescription(size, contentType string, expiresAt time.Time) string
 	if strings.TrimSpace(contentType) == "" {
 		contentType = "file"
 	}
-	return fmt.Sprintf("%s · %s · click to preview or download · expires %s", size, contentType, boxExpiryLabel(expiresAt, "Jan 2, 2006"))
+	return fmt.Sprintf("%s %s. Open to preview or download. Expires %s.", size, contentType, boxExpiryLabel(expiresAt, "Jan 2, 2006"))
 }
 
 func socialImageURL(r *http.Request, box services.Box, file services.File, view fileView) string {
@@ -242,12 +244,32 @@ func (a *App) DownloadFile(w http.ResponseWriter, r *http.Request) {
 			http.Error(w, "file is still processing", http.StatusAccepted)
 			return
 		}
+		if file.ProcessingError != "" {
+			a.logger.Warn("failed file preview blocked for social bot", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4241, "box_id", box.ID, "file_id", file.ID, "error", file.ProcessingError)...)
+			http.Error(w, "file processing failed: "+file.ProcessingError, http.StatusFailedDependency)
+			return
+		}
+		if services.BoxHasTrouble(box) {
+			a.logger.Warn("failed box preview blocked for social bot", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4245, "box_id", box.ID, "file_id", file.ID, "error", services.BoxTroubleReason(box))...)
+			http.Error(w, "box processing failed: "+services.BoxTroubleReason(box), http.StatusFailedDependency)
+			return
+		}
 		if shouldServeRawSocialMedia(file) {
 			a.serveFileContent(w, r, box, file, false)
 			a.logger.Info("media file served inline for social preview", withRequestLogAttrs(r, "source", "download", "severity", "user_activity", "code", 2009, "box_id", box.ID, "file_id", file.ID)...)
 			return
 		}
 	}
+	if file.ProcessingError != "" && !locked {
+		a.logger.Warn("failed file preview blocked", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4242, "box_id", box.ID, "file_id", file.ID, "error", file.ProcessingError)...)
+		http.Error(w, "file processing failed: "+file.ProcessingError, http.StatusFailedDependency)
+		return
+	}
+	if services.BoxHasTrouble(box) && !locked {
+		a.logger.Warn("failed box preview blocked", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4246, "box_id", box.ID, "file_id", file.ID, "error", services.BoxTroubleReason(box))...)
+		http.Error(w, "box processing failed: "+services.BoxTroubleReason(box), http.StatusFailedDependency)
+		return
+	}
 	view := a.fileView(box, file)
 	fileSize := helpers.FormatBytes(file.Size)
 	title := file.Name
@@ -306,6 +328,16 @@ func (a *App) DownloadFileContent(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "file is still processing", http.StatusAccepted)
 		return
 	}
+	if file.ProcessingError != "" {
+		a.logger.Warn("failed file download blocked", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4243, "box_id", box.ID, "file_id", file.ID, "error", file.ProcessingError)...)
+		http.Error(w, "file processing failed: "+file.ProcessingError, http.StatusFailedDependency)
+		return
+	}
+	if services.BoxHasTrouble(box) {
+		a.logger.Warn("failed box download blocked", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4247, "box_id", box.ID, "file_id", file.ID, "error", services.BoxTroubleReason(box))...)
+		http.Error(w, "box processing failed: "+services.BoxTroubleReason(box), http.StatusFailedDependency)
+		return
+	}
 
 	a.serveFileContent(w, r, box, file, r.URL.Query().Get("inline") != "1")
 	a.logger.Info("file content served", withRequestLogAttrs(r, "source", "download", "severity", "user_activity", "code", 2005, "box_id", box.ID, "file_id", file.ID, "attachment", r.URL.Query().Get("inline") != "1")...)
@@ -321,6 +353,11 @@ func (a *App) Thumbnail(w http.ResponseWriter, r *http.Request) {
 		a.servePlaceholderThumbnail(w, r)
 		return
 	}
+	if services.BoxHasTrouble(box) || services.FileHasTrouble(file) {
+		a.logger.Warn("thumbnail request skipped trouble file", withRequestLogAttrs(r, "source", "thumbnail", "severity", "warn", "code", 4110, "box_id", box.ID, "file_id", file.ID, "error", troubleReasonForLog(box, file))...)
+		a.servePlaceholderThumbnail(w, r)
+		return
+	}
 
 	object, err := a.uploadService.OpenThumbnailObject(r.Context(), box, file)
 	if err != nil {
@@ -363,6 +400,11 @@ func (a *App) VideoScenesPreview(w http.ResponseWriter, r *http.Request) {
 		a.servePlaceholderThumbnail(w, r)
 		return
 	}
+	if services.BoxHasTrouble(box) || services.FileHasTrouble(file) {
+		a.logger.Warn("video scenes preview request skipped trouble file", withRequestLogAttrs(r, "source", "thumbnail", "severity", "warn", "code", 4111, "box_id", box.ID, "file_id", file.ID, "error", troubleReasonForLog(box, file))...)
+		a.servePlaceholderThumbnail(w, r)
+		return
+	}
 
 	object, err := a.uploadService.OpenSceneThumbnailObject(r.Context(), box, file)
 	if err != nil {
@@ -400,6 +442,11 @@ func (a *App) ArchiveListing(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "password required", http.StatusUnauthorized)
 		return
 	}
+	if services.BoxHasTrouble(box) || services.FileHasTrouble(file) {
+		a.logger.Warn("archive listing request skipped trouble file", withRequestLogAttrs(r, "source", "thumbnail", "severity", "warn", "code", 4112, "box_id", box.ID, "file_id", file.ID, "error", troubleReasonForLog(box, file))...)
+		http.Error(w, "archive preview unavailable: file processing failed", http.StatusFailedDependency)
+		return
+	}
 
 	if strings.ToLower(filepath.Ext(file.ArchiveListing)) != ".json" {
 		if listing := a.generateMissingArchiveListingForRequest(r, box, file); listing != "" {
@@ -432,7 +479,7 @@ func (a *App) ArchiveListing(w http.ResponseWriter, r *http.Request) {
 }
 
 func (a *App) generateMissingThumbnailForRequest(r *http.Request, box services.Box, file services.File) string {
-	if file.Thumbnail != "" || !jobs.NeedsThumbnail(file) {
+	if file.Thumbnail != "" || !jobs.NeedsThumbnail(file) || services.BoxHasTrouble(box) || services.FileHasTrouble(file) || file.Processing {
 		return ""
 	}
 	thumbnail, err := jobs.GenerateThumbnailForFile(a.uploadService, box, file)
@@ -456,7 +503,7 @@ func (a *App) generateMissingThumbnailForRequest(r *http.Request, box services.B
 }
 
 func (a *App) generateMissingVideoScenesForRequest(r *http.Request, box services.Box, file services.File) string {
-	if file.SceneThumbnail != "" || !jobs.NeedsVideoScenes(file) {
+	if file.SceneThumbnail != "" || !jobs.NeedsVideoScenes(file) || services.BoxHasTrouble(box) || services.FileHasTrouble(file) || file.Processing {
 		return ""
 	}
 	scene, err := jobs.GenerateVideoScenesForFile(a.uploadService, box, file)
@@ -480,7 +527,7 @@ func (a *App) generateMissingVideoScenesForRequest(r *http.Request, box services
 }
 
 func (a *App) generateMissingArchiveListingForRequest(r *http.Request, box services.Box, file services.File) string {
-	if strings.ToLower(filepath.Ext(file.ArchiveListing)) == ".json" || !jobs.NeedsArchiveListing(file) {
+	if strings.ToLower(filepath.Ext(file.ArchiveListing)) == ".json" || !jobs.NeedsArchiveListing(file) || services.BoxHasTrouble(box) || services.FileHasTrouble(file) || file.Processing {
 		return ""
 	}
 	listing, err := jobs.GenerateArchiveListingForFile(a.uploadService, box, file)
@@ -504,6 +551,13 @@ func (a *App) generateMissingArchiveListingForRequest(r *http.Request, box servi
 	return listing
 }
 
+func troubleReasonForLog(box services.Box, file services.File) string {
+	if services.FileHasTrouble(file) {
+		return file.ProcessingError
+	}
+	return services.BoxTroubleReason(box)
+}
+
 // servePlaceholderThumbnail serves the fallback image with no-store so the
 // browser re-requests on the next load and picks up the real thumbnail as soon
 // as it has been generated.
@@ -572,9 +626,11 @@ func (a *App) serveFileContent(w http.ResponseWriter, r *http.Request, box servi
 	defer object.Body.Close()
 
 	w.Header().Set("Content-Type", file.ContentType)
+	disposition := "inline"
 	if attachment {
-		w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", file.Name))
+		disposition = "attachment"
 	}
+	w.Header().Set("Content-Disposition", contentDisposition(disposition, file.Name))
 	if seeker, ok := object.Body.(io.ReadSeeker); ok {
 		http.ServeContent(w, r, file.Name, object.ModTime, seeker)
 	} else {
@@ -590,6 +646,39 @@ func (a *App) serveFileContent(w http.ResponseWriter, r *http.Request, box servi
 	}
 }
 
+func contentDisposition(disposition, name string) string {
+	filename := cleanDownloadFilename(name)
+	return fmt.Sprintf(`%s; filename="%s"; filename*=UTF-8''%s`, disposition, asciiFilenameFallback(filename), url.PathEscape(filename))
+}
+
+func cleanDownloadFilename(name string) string {
+	clean := strings.TrimSpace(strings.ReplaceAll(name, "\\", "/"))
+	clean = filepath.Base(clean)
+	if clean == "" || clean == "." || clean == "/" {
+		return "download"
+	}
+	return clean
+}
+
+func asciiFilenameFallback(name string) string {
+	var fallback strings.Builder
+	for _, char := range name {
+		switch {
+		case char < 0x20 || char == 0x7f || char == '"' || char == '\\' || char == '/' || char == ';':
+			fallback.WriteByte('_')
+		case char <= 0x7e:
+			fallback.WriteRune(char)
+		default:
+			fallback.WriteByte('_')
+		}
+	}
+	clean := strings.TrimSpace(fallback.String())
+	if clean == "" {
+		return "download"
+	}
+	return clean
+}
+
 func readSeekCloser(source io.ReadCloser) io.ReadSeeker {
 	data, err := io.ReadAll(source)
 	if err != nil {
@@ -616,9 +705,25 @@ func (a *App) DownloadZip(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "password required", http.StatusUnauthorized)
 		return
 	}
+	for _, file := range box.Files {
+		if file.Processing {
+			http.Error(w, "file is still processing", http.StatusAccepted)
+			return
+		}
+		if file.ProcessingError != "" {
+			a.logger.Warn("zip download blocked by failed file", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4244, "box_id", box.ID, "file_id", file.ID, "error", file.ProcessingError)...)
+			http.Error(w, "file processing failed: "+file.ProcessingError, http.StatusFailedDependency)
+			return
+		}
+	}
+	if services.BoxHasTrouble(box) {
+		a.logger.Warn("zip download blocked by failed box", withRequestLogAttrs(r, "source", "download", "severity", "warn", "code", 4248, "box_id", box.ID, "error", services.BoxTroubleReason(box))...)
+		http.Error(w, "box processing failed: "+services.BoxTroubleReason(box), http.StatusFailedDependency)
+		return
+	}
 
 	w.Header().Set("Content-Type", "application/zip")
-	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", "warpbox-"+box.ID+".zip"))
+	w.Header().Set("Content-Disposition", contentDisposition("attachment", "warpbox-"+box.ID+".zip"))
 	w.Header().Set("Last-Modified", time.Now().UTC().Format(http.TimeFormat))
 
 	if err := a.uploadService.WriteZip(w, box); err != nil {
@@ -650,9 +755,9 @@ func (a *App) fileViewWithReactions(box services.Box, file services.File, reacti
 		ThumbnailURL: fmt.Sprintf("/d/%s/thumb/%s", box.ID, file.ID),
 		SceneURL:     fmt.Sprintf("/d/%s/scene/%s", box.ID, file.ID),
 		ArchiveURL:   fmt.Sprintf("/d/%s/archive/%s", box.ID, file.ID),
-		HasThumbnail: file.Thumbnail != "" || jobs.NeedsThumbnail(file),
-		HasScene:     file.SceneThumbnail != "" || jobs.NeedsVideoScenes(file),
-		HasArchive:   file.ArchiveListing != "" || jobs.NeedsArchiveListing(file),
+		HasThumbnail: !services.BoxHasTrouble(box) && !services.FileHasTrouble(file) && (file.Thumbnail != "" || jobs.NeedsThumbnail(file)),
+		HasScene:     !services.BoxHasTrouble(box) && !services.FileHasTrouble(file) && (file.SceneThumbnail != "" || jobs.NeedsVideoScenes(file)),
+		HasArchive:   !services.BoxHasTrouble(box) && !services.FileHasTrouble(file) && (file.ArchiveListing != "" || jobs.NeedsArchiveListing(file)),
 		IconURL:      fileIconURL("standard", icon.Standard),
 		IconRetroURL: fileIconURL("retro", icon.Retro),
 		ReactURL:     fmt.Sprintf("/d/%s/f/%s/react", box.ID, file.ID),
@@ -660,6 +765,8 @@ func (a *App) fileViewWithReactions(box services.Box, file services.File, reacti
 		ReactionMore: reactionOverflowCount(reactionViews),
 		Reacted:      reacted,
 		Processing:   file.Processing,
+		Failed:       services.BoxHasTrouble(box) || services.FileHasTrouble(file),
+		Error:        troubleReasonForLog(box, file),
 	}
 }
 

backend/libs/handlers/pages.go

@@ -10,6 +10,7 @@ import (
 
 type homeData struct {
 	MaxUploadSize        string
+	MaxUploadBytes       int64
 	LimitSummary         string
 	Collections          []collectionView
 	IsAdmin              bool
@@ -57,17 +58,18 @@ func (a *App) Home(w http.ResponseWriter, r *http.Request) {
 		"actor", actor,
 		"user_id", user.ID,
 	)...)
-	maxUploadSize, limitSummary := a.homeUploadPolicyLabels(settings, user, loggedIn, isAdmin)
+	maxUploadSize, maxUploadBytes, limitSummary := a.homeUploadPolicyLabels(settings, user, loggedIn, isAdmin)
 	expiryOptions, defaultExpiry := a.homeExpiryOptions(settings, user, loggedIn, isAdmin)
 	a.renderPage(w, r, http.StatusOK, "home.html", web.PageData{
 		Title:        "Upload your files",
-		Description:  "Upload and share files fast. Drop a file, get a link — private, temporary transfers that expire on your terms.",
+		Description:  "Upload and share files quickly. Drop a file, get a link.",
 		CanonicalURL: absoluteURL(r, "/"),
 		ImageURL:     absoluteURL(r, "/static/og-default.png"),
-		ImageAlt:     "Warp Box — simple file sharing and fast downloads",
+		ImageAlt:     "Warp Box | simple file sharing  and fast downloads",
 		CurrentUser:  currentUser,
 		Data: homeData{
 			MaxUploadSize:        maxUploadSize,
+			MaxUploadBytes:       maxUploadBytes,
 			LimitSummary:         limitSummary,
 			Collections:          collections,
 			IsAdmin:              isAdmin,
@@ -155,22 +157,25 @@ func expiryLabel(minutes int) string {
 	}
 }
 
-func (a *App) homeUploadPolicyLabels(settings services.UploadPolicySettings, user services.User, loggedIn, isAdmin bool) (string, string) {
+func (a *App) homeUploadPolicyLabels(settings services.UploadPolicySettings, user services.User, loggedIn, isAdmin bool) (string, int64, string) {
 	if isAdmin {
-		return "No file size limit", "Admin uploads bypass storage and daily caps."
+		return "No file size limit", -1, "Admin uploads bypass storage and daily caps."
 	}
 	if !loggedIn {
 		if !settings.AnonymousUploadsEnabled {
-			return "Anonymous uploads disabled", "Sign in to upload files."
+			return "Anonymous uploads disabled", 0, "Sign in to upload files."
 		}
-		return services.FormatMegabytesLabel(settings.AnonymousMaxUploadMB), "Daily anonymous cap: " + services.FormatMegabytesLabel(settings.AnonymousDailyUploadMB) + " per IP · " + strconv.Itoa(settings.AnonymousMaxDays) + " day max."
+		return services.FormatMegabytesLabel(settings.AnonymousMaxUploadMB), services.MegabytesToBytes(settings.AnonymousMaxUploadMB), "Daily anonymous cap: " + services.FormatMegabytesLabel(settings.AnonymousDailyUploadMB) + " per IP · " + strconv.Itoa(settings.AnonymousMaxDays) + " day max."
 	}
 	policy := a.settingsService.EffectivePolicyForUser(settings, user)
 	maxUpload := a.uploadService.MaxUploadSizeLabel()
+	maxUploadBytes := a.uploadService.MaxUploadSize()
 	if policy.MaxUploadMB < 0 {
 		maxUpload = "unlimited"
+		maxUploadBytes = -1
 	} else if policy.MaxUploadMB > 0 {
 		maxUpload = services.FormatMegabytesLabel(policy.MaxUploadMB)
+		maxUploadBytes = services.MegabytesToBytes(policy.MaxUploadMB)
 	}
 	quota := "unlimited"
 	if policy.StorageQuotaSet {
@@ -180,5 +185,5 @@ func (a *App) homeUploadPolicyLabels(settings services.UploadPolicySettings, use
 	if policy.MaxDays < 0 {
 		expiryLimit = "no expiry limit."
 	}
-	return maxUpload, "Daily cap: " + services.FormatMegabytesLabel(policy.DailyUploadMB) + " · Storage quota: " + quota + " · " + expiryLimit
+	return maxUpload, maxUploadBytes, "Daily cap: " + services.FormatMegabytesLabel(policy.DailyUploadMB) + " · Storage quota: " + quota + " · " + expiryLimit
 }

backend/libs/handlers/resumable.go

@@ -180,7 +180,7 @@ func (a *App) CompleteResumableUpload(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	if session.Status == services.ResumableStatusCompleted || session.Status == services.ResumableStatusProcessing {
+	if session.Status == services.ResumableStatusCompleted {
 		result, completed, err := a.uploadService.CompleteResumableSession(r.Context(), session.ID)
 		if err != nil {
 			a.logger.Warn("resumable upload completion replay failed", withRequestLogAttrs(r, "source", "user-upload", "severity", "warn", "code", 4004, "session_id", session.ID, "error", err.Error())...)
@@ -191,6 +191,17 @@ func (a *App) CompleteResumableUpload(w http.ResponseWriter, r *http.Request) {
 		helpers.WriteJSON(w, http.StatusOK, result)
 		return
 	}
+	if session.Status == services.ResumableStatusProcessing {
+		result, err := a.uploadService.FinalizeProcessingResumableSession(r.Context(), session.ID)
+		if err != nil {
+			a.logger.Warn("resumable upload completion replay failed", withRequestLogAttrs(r, "source", "user-upload", "severity", "warn", "code", 4004, "session_id", session.ID, "error", err.Error())...)
+			helpers.WriteJSONError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		a.logger.Info("resumable upload completion replayed", withRequestLogAttrs(r, "source", "user-upload", "severity", "user_activity", "code", 2004, "session_id", session.ID, "box_id", result.BoxID, "files", len(result.Files))...)
+		helpers.WriteJSON(w, http.StatusOK, result)
+		return
+	}
 	user, loggedIn, _ := a.currentUserWithAuthError(r)
 	isAdminUpload := loggedIn && user.Role == services.UserRoleAdmin
 	settings, policy, ok := a.loadUploadPolicyForAPI(w, r, user, loggedIn)

backend/libs/handlers/static.go

@@ -34,6 +34,17 @@ func (a *App) EmojiAsset(w http.ResponseWriter, r *http.Request) {
 	http.ServeFile(w, r, path)
 }
 
+func (a *App) ServiceWorker(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/javascript; charset=utf-8")
+	w.Header().Set("Cache-Control", "public, max-age=86400")
+	w.Header().Set("Service-Worker-Allowed", "/")
+	http.ServeFile(w, r, filepath.Join(a.cfg.StaticDir, "js", "service-worker.js"))
+}
+
+func (a *App) ShareTargetFallback(w http.ResponseWriter, r *http.Request) {
+	http.Redirect(w, r, "/?share-target=unsupported", http.StatusSeeOther)
+}
+
 func setStaticCacheHeaders(w http.ResponseWriter, path string) {
 	ext := strings.ToLower(filepath.Ext(path))
 

backend/libs/handlers/static_test.go

@@ -1,7 +1,11 @@
 package handlers
 
 import (
+	"encoding/json"
+	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"testing"
 )
 
@@ -24,3 +28,76 @@ func TestSetStaticCacheHeaders(t *testing.T) {
 		}
 	}
 }
+
+func TestWebManifestIncludesShareTarget(t *testing.T) {
+	data, err := os.ReadFile(filepath.Join("..", "..", "static", "site.webmanifest"))
+	if err != nil {
+		t.Fatalf("ReadFile returned error: %v", err)
+	}
+	var manifest struct {
+		ShareTarget struct {
+			Action  string `json:"action"`
+			Method  string `json:"method"`
+			EncType string `json:"enctype"`
+			Params  struct {
+				Title string `json:"title"`
+				Text  string `json:"text"`
+				URL   string `json:"url"`
+				Files []struct {
+					Name   string   `json:"name"`
+					Accept []string `json:"accept"`
+				} `json:"files"`
+			} `json:"params"`
+		} `json:"share_target"`
+	}
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		t.Fatalf("json.Unmarshal returned error: %v", err)
+	}
+	if manifest.ShareTarget.Action != "/share-target" || manifest.ShareTarget.Method != "POST" || manifest.ShareTarget.EncType != "multipart/form-data" {
+		t.Fatalf("unexpected share_target config: %+v", manifest.ShareTarget)
+	}
+	if manifest.ShareTarget.Params.Title != "title" || manifest.ShareTarget.Params.Text != "text" || manifest.ShareTarget.Params.URL != "url" {
+		t.Fatalf("unexpected share_target params: %+v", manifest.ShareTarget.Params)
+	}
+	if len(manifest.ShareTarget.Params.Files) != 1 || manifest.ShareTarget.Params.Files[0].Name != "files" || len(manifest.ShareTarget.Params.Files[0].Accept) != 1 || manifest.ShareTarget.Params.Files[0].Accept[0] != "*/*" {
+		t.Fatalf("unexpected share_target files: %+v", manifest.ShareTarget.Params.Files)
+	}
+}
+
+func TestServiceWorkerServedFromRootScope(t *testing.T) {
+	app, cleanup := newTestApp(t)
+	defer cleanup()
+
+	request := httptest.NewRequest(http.MethodGet, "/service-worker.js", nil)
+	response := httptest.NewRecorder()
+	app.ServiceWorker(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", response.Code, response.Body.String())
+	}
+	if got := response.Header().Get("Service-Worker-Allowed"); got != "/" {
+		t.Fatalf("Service-Worker-Allowed = %q, want /", got)
+	}
+	if got := response.Header().Get("Content-Type"); got != "text/javascript; charset=utf-8" {
+		t.Fatalf("Content-Type = %q", got)
+	}
+	if response.Body.Len() == 0 {
+		t.Fatalf("service worker body missing")
+	}
+}
+
+func TestShareTargetFallbackRedirectsHome(t *testing.T) {
+	app, cleanup := newTestApp(t)
+	defer cleanup()
+
+	request := httptest.NewRequest(http.MethodPost, "/share-target", nil)
+	response := httptest.NewRecorder()
+	app.ShareTargetFallback(response, request)
+
+	if response.Code != http.StatusSeeOther {
+		t.Fatalf("status = %d, want %d", response.Code, http.StatusSeeOther)
+	}
+	if got := response.Header().Get("Location"); got != "/?share-target=unsupported" {
+		t.Fatalf("Location = %q", got)
+	}
+}

backend/libs/handlers/upload.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"mime/multipart"
 	"net/http"
 	"strconv"
@@ -53,11 +54,16 @@ func (a *App) Upload(w http.ResponseWriter, r *http.Request) {
 	}
 	if err := r.ParseMultipartForm(parseLimit); err != nil {
 		a.logger.Warn("upload form parse failed", withRequestLogAttrs(r, "source", "user-upload", "severity", "warn", "code", 4000, "user_id", user.ID, "error", err.Error())...)
+		var maxBytesErr *http.MaxBytesError
+		if errors.As(err, &maxBytesErr) {
+			helpers.WriteJSONError(w, http.StatusRequestEntityTooLarge, "upload exceeds the configured upload limit")
+			return
+		}
 		helpers.WriteJSONError(w, http.StatusBadRequest, "upload form could not be read")
 		return
 	}
 
-	files := uploadFiles(r)
+	files := uploadIncomingFiles(r)
 	totalBytes := totalUploadBytes(files)
 	var ownerID string
 	var collectionID string
@@ -159,7 +165,7 @@ func (a *App) Upload(w http.ResponseWriter, r *http.Request) {
 // uploadGroupWindow are folded into one box. Without the header the behaviour is
 // identical to creating a fresh box every time. Returns the result and how many
 // boxes were created (1 for a new box, 0 for an append) for usage accounting.
-func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bool, policy services.EffectiveUploadPolicy, files []*multipart.FileHeader, opts services.UploadOptions, enforceBoxLimits bool) (services.UploadResult, int, int, string, error) {
+func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bool, policy services.EffectiveUploadPolicy, files []services.IncomingFile, opts services.UploadOptions, enforceBoxLimits bool) (services.UploadResult, int, int, string, error) {
 	batch := strings.TrimSpace(r.Header.Get(uploadBatchHeader))
 	if batch == "" {
 		if enforceBoxLimits {
@@ -167,7 +173,7 @@ func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bo
 				return services.UploadResult{}, 0, status, message, nil
 			}
 		}
-		result, err := a.uploadService.CreateBox(files, opts)
+		result, err := a.uploadService.CreateBoxFromIncoming(files, opts)
 		if err != nil {
 			return services.UploadResult{}, 0, 0, "", err
 		}
@@ -188,7 +194,7 @@ func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bo
 
 	if entry.boxID != "" && time.Since(entry.at) < uploadGroupWindow {
 		if box, err := a.uploadService.GetBox(entry.boxID); err == nil && a.batchBoxMatches(box, user, loggedIn, r) && a.uploadService.CanDownload(box) == nil {
-			if result, err := a.uploadService.AppendFiles(entry.boxID, files, opts); err == nil {
+			if result, err := a.uploadService.AppendIncomingFiles(entry.boxID, files, opts); err == nil {
 				// Re-attach the manage/delete URLs from the box's creation so every
 				// upload in the batch returns a working deletion URL.
 				result.ManageURL = entry.manageURL
@@ -204,7 +210,7 @@ func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bo
 			return services.UploadResult{}, 0, status, message, nil
 		}
 	}
-	result, err := a.uploadService.CreateBox(files, opts)
+	result, err := a.uploadService.CreateBoxFromIncoming(files, opts)
 	if err != nil {
 		return services.UploadResult{}, 0, 0, "", err
 	}
@@ -224,13 +230,13 @@ func (a *App) batchBoxMatches(box services.Box, user services.User, loggedIn boo
 	return box.OwnerID == "" && box.CreatorIP == uploadClientIP(r)
 }
 
-func (a *App) checkUploadPolicy(r *http.Request, user services.User, loggedIn bool, settings services.UploadPolicySettings, policy services.EffectiveUploadPolicy, files []*multipart.FileHeader, totalBytes int64) (int, string) {
+func (a *App) checkUploadPolicy(r *http.Request, user services.User, loggedIn bool, settings services.UploadPolicySettings, policy services.EffectiveUploadPolicy, files []services.IncomingFile, totalBytes int64) (int, string) {
 	if len(files) == 0 {
 		return 0, ""
 	}
 	sizes := make([]int64, 0, len(files))
 	for _, file := range files {
-		sizes = append(sizes, file.Size)
+		sizes = append(sizes, file.Size())
 	}
 	return a.checkUploadPolicyForSizes(r, user, loggedIn, settings, policy, sizes, totalBytes)
 }
@@ -244,7 +250,7 @@ func (a *App) checkUploadPolicyForSizes(r *http.Request, user services.User, log
 		maxBytes := services.MegabytesToBytes(policy.MaxUploadMB)
 		for _, fileSize := range fileSizes {
 			if fileSize > maxBytes {
-				return http.StatusRequestEntityTooLarge, "file exceeds upload size limit"
+				return http.StatusRequestEntityTooLarge, "file exceeds upload size limit of " + services.FormatMegabytesLabel(policy.MaxUploadMB)
 			}
 		}
 	}
@@ -378,10 +384,10 @@ func uploadRateKey(r *http.Request, user services.User, loggedIn bool) string {
 	return "ip:" + uploadClientIP(r)
 }
 
-func totalUploadBytes(files []*multipart.FileHeader) int64 {
+func totalUploadBytes(files []services.IncomingFile) int64 {
 	var total int64
 	for _, file := range files {
-		total += file.Size
+		total += file.Size()
 	}
 	return total
 }
@@ -404,13 +410,48 @@ func statusForDownloadError(err error) int {
 	return http.StatusForbidden
 }
 
-func uploadFiles(r *http.Request) []*multipart.FileHeader {
+type namedMultipartFile struct {
+	header *multipart.FileHeader
+	name   string
+}
+
+func (f namedMultipartFile) Name() string {
+	if strings.TrimSpace(f.name) != "" {
+		return f.name
+	}
+	return f.header.Filename
+}
+
+func (f namedMultipartFile) Size() int64 {
+	return f.header.Size
+}
+
+func (f namedMultipartFile) ContentType() string {
+	return f.header.Header.Get("Content-Type")
+}
+
+func (f namedMultipartFile) Open() (io.ReadCloser, error) {
+	return f.header.Open()
+}
+
+func uploadIncomingFiles(r *http.Request) []services.IncomingFile {
 	if r.MultipartForm == nil {
 		return nil
 	}
-	files := make([]*multipart.FileHeader, 0)
-	files = append(files, r.MultipartForm.File["file"]...)
-	files = append(files, r.MultipartForm.File["sharex"]...)
+	fileHeaders := r.MultipartForm.File["file"]
+	shareXHeaders := r.MultipartForm.File["sharex"]
+	paths := r.MultipartForm.Value["file_path"]
+	files := make([]services.IncomingFile, 0, len(fileHeaders)+len(shareXHeaders))
+	for index, header := range fileHeaders {
+		name := ""
+		if index < len(paths) {
+			name = paths[index]
+		}
+		files = append(files, namedMultipartFile{header: header, name: name})
+	}
+	for _, header := range shareXHeaders {
+		files = append(files, namedMultipartFile{header: header})
+	}
 	return files
 }
 

backend/libs/handlers/upload_stage3_test.go

@@ -17,6 +17,7 @@ import (
 	"time"
 
 	"warpbox.dev/backend/libs/config"
+	"warpbox.dev/backend/libs/jobs"
 	"warpbox.dev/backend/libs/services"
 	"warpbox.dev/backend/libs/web"
 )
@@ -127,7 +128,7 @@ func TestSocialPreviewBotGetsCardForSingleNonMediaBox(t *testing.T) {
 	if !strings.Contains(body, `class="file-thumb" src="/d/`+payload.BoxID+`/thumb/`+payload.Files[0].ID+`"`) {
 		t.Fatalf("download page did not render text thumbnail image: %s", body)
 	}
-	if !strings.Contains(body, "Click to preview or download") && !strings.Contains(body, "click to preview or download") {
+	if !strings.Contains(body, "Open to preview or download") {
 		t.Fatalf("social preview body missing preview/download description: %s", body)
 	}
 }
@@ -218,6 +219,99 @@ func TestFilePreviewPageIncludesPreviewMetadata(t *testing.T) {
 	}
 }
 
+func TestDownloadPageShowsProcessingFailure(t *testing.T) {
+	app, cleanup := newTestApp(t)
+	defer cleanup()
+	payload := uploadThroughApp(t, app)
+	box, err := app.uploadService.GetBox(payload.BoxID)
+	if err != nil {
+		t.Fatalf("GetBox returned error: %v", err)
+	}
+	box.Files[0].Processing = false
+	box.Files[0].ProcessingError = "Access Denied."
+	if err := app.uploadService.SaveBox(box); err != nil {
+		t.Fatalf("SaveBox returned error: %v", err)
+	}
+
+	request := httptest.NewRequest(http.MethodGet, "/d/"+payload.BoxID, nil)
+	request.SetPathValue("boxID", payload.BoxID)
+	response := httptest.NewRecorder()
+	app.DownloadPage(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", response.Code, response.Body.String())
+	}
+	body := response.Body.String()
+	for _, want := range []string{
+		"Upload processing failed",
+		"Access Denied.",
+		"is-failed",
+		"Failed",
+	} {
+		if !strings.Contains(body, want) {
+			t.Fatalf("download page missing %q: %s", want, body)
+		}
+	}
+	if strings.Contains(body, `data-download-url="/d/`+payload.BoxID+`/f/`+payload.Files[0].ID+`/download"`) {
+		t.Fatalf("failed file still exposed download context: %s", body)
+	}
+}
+
+func TestFileDownloadUsesOriginalFilename(t *testing.T) {
+	app, cleanup := newTestApp(t)
+	defer cleanup()
+	payload := uploadNamedFileThroughApp(t, app, "report final.txt", "hello")
+
+	request := httptest.NewRequest(http.MethodGet, "/d/"+payload.BoxID+"/f/"+payload.Files[0].ID+"/download", nil)
+	request.SetPathValue("boxID", payload.BoxID)
+	request.SetPathValue("fileID", payload.Files[0].ID)
+	response := httptest.NewRecorder()
+	app.DownloadFileContent(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", response.Code, response.Body.String())
+	}
+	disposition := response.Header().Get("Content-Disposition")
+	for _, want := range []string{
+		`attachment;`,
+		`filename="report final.txt"`,
+		`filename*=UTF-8''report%20final.txt`,
+	} {
+		if !strings.Contains(disposition, want) {
+			t.Fatalf("Content-Disposition missing %q: %q", want, disposition)
+		}
+	}
+	if response.Body.String() != "hello" {
+		t.Fatalf("body = %q", response.Body.String())
+	}
+}
+
+func TestInlineFileDownloadKeepsOriginalFilename(t *testing.T) {
+	app, cleanup := newTestApp(t)
+	defer cleanup()
+	payload := uploadNamedFileThroughApp(t, app, "résumé 2026.txt", "hello")
+
+	request := httptest.NewRequest(http.MethodGet, "/d/"+payload.BoxID+"/f/"+payload.Files[0].ID+"/download?inline=1", nil)
+	request.SetPathValue("boxID", payload.BoxID)
+	request.SetPathValue("fileID", payload.Files[0].ID)
+	response := httptest.NewRecorder()
+	app.DownloadFileContent(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", response.Code, response.Body.String())
+	}
+	disposition := response.Header().Get("Content-Disposition")
+	for _, want := range []string{
+		`inline;`,
+		`filename="r_sum_ 2026.txt"`,
+		`filename*=UTF-8''r%C3%A9sum%C3%A9%202026.txt`,
+	} {
+		if !strings.Contains(disposition, want) {
+			t.Fatalf("Content-Disposition missing %q: %q", want, disposition)
+		}
+	}
+}
+
 func TestResumableUploadFlowCreatesNormalBox(t *testing.T) {
 	app, cleanup := newTestApp(t)
 	defer cleanup()
@@ -724,6 +818,7 @@ func newTestApp(t *testing.T) (*App, func()) {
 		t.Fatalf("NewBanService returned error: %v", err)
 	}
 	return NewApp(cfg, logger, renderer, service, authService, settingsService, reactionService, banService), func() {
+		jobs.WaitForThumbnailJobs()
 		if err := service.Close(); err != nil {
 			t.Fatalf("Close returned error: %v", err)
 		}
@@ -731,8 +826,12 @@ func newTestApp(t *testing.T) (*App, func()) {
 }
 
 func uploadThroughApp(t *testing.T, app *App) services.UploadResult {
+	return uploadNamedFileThroughApp(t, app, "note.txt", "hello")
+}
+
+func uploadNamedFileThroughApp(t *testing.T, app *App, filename, body string) services.UploadResult {
 	t.Helper()
-	request := multipartUploadRequest(t, "/api/v1/upload", "file", "note.txt", "hello")
+	request := multipartUploadRequest(t, "/api/v1/upload", "file", filename, body)
 	request.Header.Set("Accept", "application/json")
 	response := httptest.NewRecorder()
 	app.Upload(response, request)

backend/libs/jobs/thumbnails.go

@@ -22,6 +22,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"golang.org/x/image/font"
@@ -38,13 +39,21 @@ type ThumbnailJobResult struct {
 	Failed    int
 }
 
+var thumbnailJobs sync.WaitGroup
+
 func GenerateThumbnailsForBoxAsync(uploadService *services.UploadService, logger *slog.Logger, boxID string) {
+	thumbnailJobs.Add(1)
 	go func() {
+		defer thumbnailJobs.Done()
 		box, err := uploadService.GetBox(boxID)
 		if err != nil {
 			logger.Warn("thumbnail box lookup failed", "source", "thumbnail", "severity", "warn", "code", 4204, "box_id", boxID, "error", err.Error())
 			return
 		}
+		if services.BoxHasTrouble(box) {
+			logger.Warn("thumbnail one-shot skipped trouble box", "source", "thumbnail", "severity", "warn", "code", 4206, "box_id", boxID, "error", services.BoxTroubleReason(box))
+			return
+		}
 
 		result, err := generateMissingThumbnailsForBox(uploadService, logger, box)
 		if err != nil {
@@ -57,6 +66,10 @@ func GenerateThumbnailsForBoxAsync(uploadService *services.UploadService, logger
 	}()
 }
 
+func WaitForThumbnailJobs() {
+	thumbnailJobs.Wait()
+}
+
 func newThumbnailsJob(cfg config.Config, logger *slog.Logger, uploadService *services.UploadService) job {
 	return job{
 		name:     "thumbnail",
@@ -91,6 +104,9 @@ func generateMissingThumbnails(uploadService *services.UploadService, logger *sl
 		if !box.ExpiresAt.After(now) {
 			continue
 		}
+		if services.BoxHasTrouble(box) {
+			continue
+		}
 
 		boxResult, err := generateMissingThumbnailsForBox(uploadService, logger, box)
 		result.Scanned += boxResult.Scanned
@@ -109,10 +125,16 @@ func generateMissingThumbnailsForBox(uploadService *services.UploadService, logg
 	if !box.ExpiresAt.After(time.Now().UTC()) {
 		return result, nil
 	}
+	if services.BoxHasTrouble(box) {
+		return result, nil
+	}
 
 	changed := false
 	for i := range box.Files {
 		file := &box.Files[i]
+		if file.Processing || services.FileHasTrouble(*file) {
+			continue
+		}
 		needsPrimary := file.Thumbnail == "" && needsThumbnail(*file)
 		needsScenes := file.SceneThumbnail == "" && needsVideoScenes(*file)
 		needsArchive := !archiveListingCurrent(*file) && needsArchiveListing(*file)
@@ -206,6 +228,15 @@ func GenerateArchiveListingForFile(uploadService *services.UploadService, box se
 }
 
 func generateThumbnail(uploadService *services.UploadService, box services.Box, file services.File) (string, error) {
+	if services.BoxHasTrouble(box) {
+		return "", fmt.Errorf("box is marked as trouble: %s", services.BoxTroubleReason(box))
+	}
+	if file.Processing {
+		return "", fmt.Errorf("file is still processing")
+	}
+	if services.FileHasTrouble(file) {
+		return "", fmt.Errorf("file processing failed: %s", file.ProcessingError)
+	}
 	thumbnailName := "@thumb@" + file.ID + ".jpg"
 	object, err := uploadService.OpenFileObject(context.Background(), box, file)
 	if err != nil {
@@ -244,6 +275,15 @@ func generateVideoScenesThumbnail(uploadService *services.UploadService, box ser
 	if !needsVideoScenes(file) {
 		return "", nil
 	}
+	if services.BoxHasTrouble(box) {
+		return "", fmt.Errorf("box is marked as trouble: %s", services.BoxTroubleReason(box))
+	}
+	if file.Processing {
+		return "", fmt.Errorf("file is still processing")
+	}
+	if services.FileHasTrouble(file) {
+		return "", fmt.Errorf("file processing failed: %s", file.ProcessingError)
+	}
 	sceneName := "@scene@" + file.ID + ".jpg"
 	object, err := uploadService.OpenFileObject(context.Background(), box, file)
 	if err != nil {
@@ -263,6 +303,15 @@ func generateArchiveListing(uploadService *services.UploadService, box services.
 	if !needsArchiveListing(file) {
 		return "", nil
 	}
+	if services.BoxHasTrouble(box) {
+		return "", fmt.Errorf("box is marked as trouble: %s", services.BoxTroubleReason(box))
+	}
+	if file.Processing {
+		return "", fmt.Errorf("file is still processing")
+	}
+	if services.FileHasTrouble(file) {
+		return "", fmt.Errorf("file processing failed: %s", file.ProcessingError)
+	}
 	listingName := "@archive@" + file.ID + ".json"
 	object, err := uploadService.OpenFileObject(context.Background(), box, file)
 	if err != nil {

backend/libs/jobs/thumbnails_test.go

@@ -50,6 +50,36 @@ func TestGenerateMissingThumbnailsForBox(t *testing.T) {
 	}
 }
 
+func TestGenerateMissingThumbnailsForTroubleBoxSkipsWork(t *testing.T) {
+	service := newThumbnailTestUploadService(t)
+	result := createThumbnailTestBox(t, service)
+	box, err := service.GetBox(result.BoxID)
+	if err != nil {
+		t.Fatalf("GetBox returned error: %v", err)
+	}
+	box.Trouble = true
+	box.TroubleReason = "storage backend failed"
+	if err := service.SaveBox(box); err != nil {
+		t.Fatalf("SaveBox returned error: %v", err)
+	}
+
+	jobResult, err := generateMissingThumbnailsForBox(service, slog.New(slog.NewTextHandler(io.Discard, nil)), box)
+	if err != nil {
+		t.Fatalf("generateMissingThumbnailsForBox returned error: %v", err)
+	}
+	if jobResult != (ThumbnailJobResult{}) {
+		t.Fatalf("job result = %+v, want no work for trouble box", jobResult)
+	}
+
+	updated, err := service.GetBox(result.BoxID)
+	if err != nil {
+		t.Fatalf("GetBox after job returned error: %v", err)
+	}
+	if updated.Files[0].Thumbnail != "" {
+		t.Fatalf("thumbnail was generated for trouble box: %+v", updated.Files[0])
+	}
+}
+
 func TestCreateTextThumbnailRendersMarkdownAsJPEG(t *testing.T) {
 	data, err := createTextThumbnail(services.File{
 		Name:        "notes.md",

backend/libs/services/resumable.go

@@ -319,7 +319,7 @@ func (s *UploadService) CreateProcessingBoxFromResumable(sessionID string) (Uplo
 		}
 		box.Files = append(box.Files, File{
 			ID:          fileID,
-			Name:        filepath.Base(incoming.Name),
+			Name:        cleanUploadDisplayName(incoming.Name),
 			StoredName:  storedName,
 			Size:        incoming.Size,
 			ContentType: contentType,
@@ -369,19 +369,20 @@ func (s *UploadService) FinalizeProcessingResumableSession(ctx context.Context,
 	}
 	backend, err := s.storage.Backend(box.StorageBackendID)
 	if err != nil {
+		_ = s.markProcessingBoxFailed(box, err)
 		return UploadResult{}, err
 	}
 	for i, incoming := range staged {
 		source, err := incoming.Open()
 		if err != nil {
+			_ = s.markProcessingBoxFailed(box, err)
 			return UploadResult{}, err
 		}
 		file := box.Files[i]
 		if err := s.writeUploadedObject(ctx, backend, file.ObjectKey, source, incoming.Size(), 0, incoming.ContentType()); err != nil {
 			source.Close()
 			_ = backend.Delete(context.Background(), file.ObjectKey)
-			box.Files[i].ProcessingError = err.Error()
-			_ = s.saveBoxRecord(box)
+			_ = s.markProcessingBoxFailed(box, err)
 			return UploadResult{}, err
 		}
 		source.Close()
@@ -406,6 +407,35 @@ func (s *UploadService) FinalizeProcessingResumableSession(ctx context.Context,
 	return s.resultForBox(box, ""), nil
 }
 
+func (s *UploadService) markProcessingBoxFailed(box Box, cause error) error {
+	message := "upload processing failed"
+	if cause != nil && strings.TrimSpace(cause.Error()) != "" {
+		message = cause.Error()
+	}
+	s.logger.Warn("resumable upload box marked failed", "source", "user-upload", "severity", "warn", "code", 4021, "box_id", box.ID, "backend_id", s.BoxStorageBackendID(box), "files", len(box.Files), "error", message)
+	now := time.Now().UTC()
+	box.Trouble = true
+	box.TroubleReason = message
+	for i := range box.Files {
+		if box.Files[i].Processing || box.Files[i].ProcessingError == "" {
+			box.Files[i].Processing = false
+			box.Files[i].ProcessingError = message
+			if box.Files[i].UploadedAt.IsZero() {
+				box.Files[i].UploadedAt = now
+			}
+		}
+	}
+	if err := s.saveBoxRecord(box); err != nil {
+		s.logger.Warn("failed to save failed upload box state", "source", "user-upload", "severity", "warn", "code", 4022, "box_id", box.ID, "backend_id", s.BoxStorageBackendID(box), "error", err.Error())
+		return err
+	}
+	if err := s.writeBoxMetadata(box); err != nil {
+		s.logger.Warn("failed to write failed upload box metadata", "source", "user-upload", "severity", "warn", "code", 4023, "box_id", box.ID, "backend_id", s.BoxStorageBackendID(box), "error", err.Error())
+		return err
+	}
+	return nil
+}
+
 func (s *UploadService) CompleteUploadedResumableSession(ctx context.Context, sessionID string) (UploadResult, ResumableSession, error) {
 	session, err := s.GetResumableSession(sessionID)
 	if err != nil {
@@ -527,7 +557,7 @@ func (s *UploadService) saveResumableSession(session ResumableSession) error {
 func (s *UploadService) resumableFilesFromInput(files []ResumableFileInput, opts UploadOptions, chunkSize int64, existing map[string]bool) ([]ResumableFile, error) {
 	sessionFiles := make([]ResumableFile, 0, len(files))
 	for _, file := range files {
-		file.Name = filepath.Base(strings.TrimSpace(file.Name))
+		file.Name = cleanUploadDisplayName(file.Name)
 		if file.Name == "." || file.Name == "" {
 			return nil, fmt.Errorf("file name is required")
 		}
@@ -564,7 +594,7 @@ func (s *UploadService) resumableFilesFromInput(files []ResumableFileInput, opts
 }
 
 func resumableFileKey(name string, size int64, fingerprint string) string {
-	return strings.TrimSpace(fingerprint) + "|" + filepath.Base(strings.TrimSpace(name)) + "|" + fmt.Sprintf("%d", size)
+	return strings.TrimSpace(fingerprint) + "|" + cleanUploadDisplayName(name) + "|" + fmt.Sprintf("%d", size)
 }
 
 type resumableIncomingFile struct {

backend/libs/services/storage_s3.go

@@ -35,26 +35,35 @@ func (b *s3StorageBackend) ID() string   { return b.cfg.ID }
 func (b *s3StorageBackend) Type() string { return StorageBackendS3 }
 
 func (b *s3StorageBackend) Put(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+	cleanKey := cleanObjectKey(key)
 	opts := minio.PutObjectOptions{ContentType: contentType}
-	_, err := b.client.PutObject(ctx, b.cfg.Bucket, cleanObjectKey(key), body, size, opts)
-	return err
+	_, err := b.client.PutObject(ctx, b.cfg.Bucket, cleanKey, body, size, opts)
+	if err != nil {
+		return fmt.Errorf("s3 put object %q in bucket %q failed: %w", cleanKey, b.cfg.Bucket, err)
+	}
+	return nil
 }
 
 func (b *s3StorageBackend) Get(ctx context.Context, key string) (StorageObject, error) {
-	object, err := b.client.GetObject(ctx, b.cfg.Bucket, cleanObjectKey(key), minio.GetObjectOptions{})
+	cleanKey := cleanObjectKey(key)
+	object, err := b.client.GetObject(ctx, b.cfg.Bucket, cleanKey, minio.GetObjectOptions{})
 	if err != nil {
-		return StorageObject{}, err
+		return StorageObject{}, fmt.Errorf("s3 get object %q from bucket %q failed: %w", cleanKey, b.cfg.Bucket, err)
 	}
 	info, err := object.Stat()
 	if err != nil {
 		object.Close()
-		return StorageObject{}, err
+		return StorageObject{}, fmt.Errorf("s3 stat object %q in bucket %q failed: %w", cleanKey, b.cfg.Bucket, err)
 	}
 	return StorageObject{Key: key, Size: info.Size, ContentType: info.ContentType, ModTime: info.LastModified, Body: object}, nil
 }
 
 func (b *s3StorageBackend) Delete(ctx context.Context, key string) error {
-	return b.client.RemoveObject(ctx, b.cfg.Bucket, cleanObjectKey(key), minio.RemoveObjectOptions{})
+	cleanKey := cleanObjectKey(key)
+	if err := b.client.RemoveObject(ctx, b.cfg.Bucket, cleanKey, minio.RemoveObjectOptions{}); err != nil {
+		return fmt.Errorf("s3 delete object %q from bucket %q failed: %w", cleanKey, b.cfg.Bucket, err)
+	}
+	return nil
 }
 
 func (b *s3StorageBackend) DeletePrefix(ctx context.Context, prefix string) error {
@@ -62,7 +71,7 @@ func (b *s3StorageBackend) DeletePrefix(ctx context.Context, prefix string) erro
 	objects := b.client.ListObjects(ctx, b.cfg.Bucket, minio.ListObjectsOptions{Prefix: prefix, Recursive: true})
 	for object := range objects {
 		if object.Err != nil {
-			return object.Err
+			return fmt.Errorf("s3 list prefix %q in bucket %q failed: %w", prefix, b.cfg.Bucket, object.Err)
 		}
 		if err := b.Delete(ctx, object.Key); err != nil {
 			return err
@@ -75,7 +84,7 @@ func (b *s3StorageBackend) Usage(ctx context.Context) (int64, error) {
 	var total int64
 	for object := range b.client.ListObjects(ctx, b.cfg.Bucket, minio.ListObjectsOptions{Recursive: true}) {
 		if object.Err != nil {
-			return 0, object.Err
+			return 0, fmt.Errorf("s3 usage list bucket %q failed: %w", b.cfg.Bucket, object.Err)
 		}
 		total += object.Size
 	}
@@ -85,7 +94,7 @@ func (b *s3StorageBackend) Usage(ctx context.Context) (int64, error) {
 func (b *s3StorageBackend) Test(ctx context.Context) error {
 	exists, err := b.client.BucketExists(ctx, b.cfg.Bucket)
 	if err != nil {
-		return err
+		return fmt.Errorf("s3 bucket check for %q failed: %w", b.cfg.Bucket, err)
 	}
 	if !exists {
 		return fmt.Errorf("bucket %q does not exist", b.cfg.Bucket)

backend/libs/services/upload.go

@@ -16,6 +16,7 @@ import (
 	"mime/multipart"
 	"net/http"
 	"os"
+	"path"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -117,6 +118,8 @@ type Box struct {
 	Obfuscate        bool      `json:"obfuscate"`
 	CreatorIP        string    `json:"creatorIp,omitempty"`
 	StorageBackendID string    `json:"storageBackendId,omitempty"`
+	Trouble          bool      `json:"trouble,omitempty"`
+	TroubleReason    string    `json:"troubleReason,omitempty"`
 	Files            []File    `json:"files"`
 }
 
@@ -139,6 +142,37 @@ type File struct {
 	UploadedAt              time.Time `json:"uploadedAt"`
 }
 
+func BoxHasTrouble(box Box) bool {
+	if box.Trouble || strings.TrimSpace(box.TroubleReason) != "" {
+		return true
+	}
+	for _, file := range box.Files {
+		if FileHasTrouble(file) {
+			return true
+		}
+	}
+	return false
+}
+
+func BoxTroubleReason(box Box) string {
+	if strings.TrimSpace(box.TroubleReason) != "" {
+		return box.TroubleReason
+	}
+	for _, file := range box.Files {
+		if strings.TrimSpace(file.ProcessingError) != "" {
+			return file.ProcessingError
+		}
+	}
+	if box.Trouble {
+		return "box has failed processing"
+	}
+	return ""
+}
+
+func FileHasTrouble(file File) bool {
+	return strings.TrimSpace(file.ProcessingError) != ""
+}
+
 type UploadResult struct {
 	BoxID        string       `json:"boxId"`
 	BoxURL       string       `json:"boxUrl"`
@@ -419,7 +453,7 @@ func (s *UploadService) writeIncomingFilesToBox(ctx context.Context, box *Box, f
 
 		box.Files = append(box.Files, File{
 			ID:          fileID,
-			Name:        filepath.Base(incoming.Name()),
+			Name:        cleanUploadDisplayName(incoming.Name()),
 			StoredName:  storedName,
 			Size:        incoming.Size(),
 			ContentType: contentType,
@@ -431,6 +465,36 @@ func (s *UploadService) writeIncomingFilesToBox(ctx context.Context, box *Box, f
 	return nil
 }
 
+func cleanUploadDisplayName(name string) string {
+	clean := strings.TrimSpace(strings.ReplaceAll(name, "\\", "/"))
+	clean = strings.TrimLeft(clean, "/")
+	clean = path.Clean(clean)
+	if clean == "." || clean == "/" || clean == "" {
+		return "download"
+	}
+	parts := strings.Split(clean, "/")
+	safeParts := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part == "" || part == "." || part == ".." {
+			continue
+		}
+		part = strings.Map(func(r rune) rune {
+			if r < 0x20 || r == 0x7f || r == '/' || r == '\\' {
+				return -1
+			}
+			return r
+		}, part)
+		if part != "" {
+			safeParts = append(safeParts, part)
+		}
+	}
+	if len(safeParts) == 0 {
+		return "download"
+	}
+	return strings.Join(safeParts, "/")
+}
+
 func (s *UploadService) GetBox(id string) (Box, error) {
 	var box Box
 	err := s.db.View(func(tx *bbolt.Tx) error {

backend/libs/services/upload_test.go

@@ -230,6 +230,47 @@ func TestResumableCompleteRejectsMissingChunks(t *testing.T) {
 	}
 }
 
+func TestProcessingResumableFailureMarksBoxFailed(t *testing.T) {
+	service := newTestUploadService(t)
+	session, err := service.CreateResumableSession([]ResumableFileInput{{
+		Name:        "note.txt",
+		Size:        4,
+		ContentType: "text/plain",
+	}}, UploadOptions{MaxDays: 1, StorageBackendID: "missing"}, 4, time.Hour, "")
+	if err != nil {
+		t.Fatalf("CreateResumableSession returned error: %v", err)
+	}
+	if _, err := service.PutResumableChunk(testContext(), session.ID, session.Files[0].ID, 0, strings.NewReader("note")); err != nil {
+		t.Fatalf("PutResumableChunk returned error: %v", err)
+	}
+	result, processing, err := service.CreateProcessingBoxFromResumable(session.ID)
+	if err != nil {
+		t.Fatalf("CreateProcessingBoxFromResumable returned error: %v", err)
+	}
+	if processing.Status != ResumableStatusProcessing {
+		t.Fatalf("session status = %q, want processing", processing.Status)
+	}
+	if _, err := service.FinalizeProcessingResumableSession(testContext(), session.ID); err == nil {
+		t.Fatalf("FinalizeProcessingResumableSession accepted missing backend")
+	}
+	box := getTestBox(t, service, result.BoxID)
+	if len(box.Files) != 1 {
+		t.Fatalf("box files = %+v", box.Files)
+	}
+	if box.Files[0].Processing {
+		t.Fatalf("failed file is still marked processing: %+v", box.Files[0])
+	}
+	if box.Files[0].ProcessingError == "" {
+		t.Fatalf("failed file did not store processing error: %+v", box.Files[0])
+	}
+	if !box.Trouble {
+		t.Fatalf("failed box was not marked as trouble: %+v", box)
+	}
+	if box.TroubleReason == "" {
+		t.Fatalf("failed box did not store trouble reason: %+v", box)
+	}
+}
+
 func TestResumablePartialCompleteKeepsOnlyFinishedFiles(t *testing.T) {
 	service := newTestUploadService(t)
 	session, err := service.CreateResumableSession([]ResumableFileInput{

backend/static/api/warpbox.ps1

@@ -0,0 +1,81 @@
+#requires -version 5
+<#
+.SYNOPSIS
+  warpbox: command line uploader for Warpbox
+.DESCRIPTION
+  Set the server once, then upload anything:
+    setx WARPBOX_HOST "https://your.warpbox.host"
+    warpbox .\report.pdf
+
+  Install (PowerShell):
+    iwr "$env:WARPBOX_HOST/static/api/warpbox.ps1" -OutFile $HOME\warpbox.ps1
+    # add a function to your $PROFILE:  function warpbox { & "$HOME\warpbox.ps1" @args }
+
+  Auth: set the token once so it never lands in your command history.
+    setx WARPBOX_TOKEN "wbx_your_token"
+  Create a token under Account, Access tokens.
+
+.EXAMPLE
+  .\warpbox.ps1 .\report.pdf
+.EXAMPLE
+  .\warpbox.ps1 -Password 123 -Expiry 2d .\photo.png .\clip.mp4
+#>
+[CmdletBinding()]
+param(
+  [Alias('p')][string]$Password,
+  [Alias('e')][string]$Expiry,
+  [Alias('n')][int]$MaxDownloads,
+  [Alias('o')][switch]$Obfuscate,
+  [string]$Server = $env:WARPBOX_HOST,
+  [string]$Auth = $env:WARPBOX_TOKEN,
+  [string]$AuthFile,
+  [switch]$Json,
+  [switch]$Help,
+  [Parameter(ValueFromRemainingArguments = $true)][string[]]$Files
+)
+
+if ($Help -or -not $Files) {
+  Write-Host 'warpbox: upload files to Warpbox'
+  Write-Host 'USAGE:  warpbox.ps1 [-Password pw] [-Expiry 2d] [-MaxDownloads n] [-Obfuscate] [-Json] <file> [file ...]'
+  Write-Host 'SERVER: set WARPBOX_HOST in your environment (setx WARPBOX_HOST "https://your.host")'
+  Write-Host 'AUTH:   set WARPBOX_TOKEN in your environment (setx WARPBOX_TOKEN "wbx_...")'
+  if (-not $Files -and -not $Help) { exit 2 } else { exit 0 }
+}
+
+if (-not $Server) {
+  Write-Error 'warpbox: no server set. Use -Server <url> or set WARPBOX_HOST'
+  exit 2
+}
+if ($AuthFile) { $Auth = (Get-Content -Raw $AuthFile).Trim() }
+
+function ConvertTo-Minutes($v) {
+  if ($v -match '^(\d+)([mhdw]?)$') {
+    $n = [int]$Matches[1]
+    switch ($Matches[2]) {
+      'h' { return $n * 60 }
+      'd' { return $n * 1440 }
+      'w' { return $n * 10080 }
+      default { return $n }
+    }
+  }
+  return $v
+}
+
+# Expand wildcards (PowerShell does not expand them in arguments).
+$expanded = @()
+foreach ($f in $Files) {
+  $hits = Get-ChildItem -Path $f -File -ErrorAction SilentlyContinue
+  if ($hits) { $expanded += $hits.FullName } else { $expanded += $f }
+}
+
+$curlArgs = @('-fS')
+foreach ($f in $expanded) { $curlArgs += @('-F', "file=@$f") }
+if ($Password) { $curlArgs += @('-F', "password=$Password") }
+if ($Expiry) { $curlArgs += @('-F', "expires_minutes=$(ConvertTo-Minutes $Expiry)") }
+if ($MaxDownloads) { $curlArgs += @('-F', "max_downloads=$MaxDownloads") }
+if ($Obfuscate) { $curlArgs += @('-F', 'obfuscate_metadata=on') }
+if ($Auth) { $curlArgs += @('-H', "Authorization: Bearer $Auth") }
+if ($Json) { $curlArgs += @('-H', 'Accept: application/json') }
+$curlArgs += "$($Server.TrimEnd('/'))/api/v1/upload"
+
+& curl.exe @curlArgs

backend/static/api/warpbox.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# warpbox: command line uploader for Warpbox
+#
+# Set the server once, then upload anything:
+#   export WARPBOX_HOST=https://your.warpbox.host
+#   warpbox ./report.pdf
+#
+# Install:
+#   curl -fsSL "$WARPBOX_HOST/static/api/warpbox.sh" -o ~/.local/bin/warpbox
+#   chmod +x ~/.local/bin/warpbox
+#   # make sure ~/.local/bin is on your PATH
+#
+set -eo pipefail
+
+WARPBOX_HOST="${WARPBOX_HOST:-}"
+AUTH="${WARPBOX_TOKEN:-}"
+PASSWORD=""
+EXPIRY=""
+MAX_DOWNLOADS=""
+OBFUSCATE=""
+AS_JSON=0
+FILES=()
+
+usage() {
+  cat <<'EOF'
+warpbox: upload files to Warpbox from the terminal
+
+USAGE:
+  warpbox [options] <file> [file ...]
+
+OPTIONS:
+  -p, --password <pw>       Require a password to view/download the box
+  -e, --expiry <dur>        Lifetime before expiry: 30m, 6h, 2d, 1w (or bare minutes)
+  -n, --max-downloads <n>   Expire after N downloads
+  -o, --obfuscate           Hide file names/counts until unlocked (needs --password)
+      --host <url>          Warpbox server to upload to (or set WARPBOX_HOST)
+      --auth <token>        API token (prefer the WARPBOX_TOKEN env var, see AUTH)
+      --auth-file <path>    Read the API token from a file (safer than --auth)
+      --json                Print the full JSON response instead of just the URL
+  -h, --help                Show this help
+
+AUTH:
+  Uploads are anonymous unless a token is supplied. The most secure option is the
+  WARPBOX_TOKEN environment variable, so the token never lands in your shell
+  history or the process list:
+
+    export WARPBOX_TOKEN=wbx_your_token
+    warpbox ./photo.png
+
+  Create a token under Account, Access tokens. Avoid --auth on shared machines.
+
+EXAMPLES:
+  warpbox ./report.pdf
+  warpbox --password 123 --expiry 2d ./first_file.zip ./whatever.png ./all_*_photos.jpg
+  warpbox --max-downloads 5 --json ./build.zip
+EOF
+}
+
+expiry_to_minutes() {
+  local v="$1" num unit
+  num="${v%%[mhdw]*}"
+  unit="${v##*[0-9]}"
+  case "$unit" in
+    h) echo $(( num * 60 )) ;;
+    d) echo $(( num * 1440 )) ;;
+    w) echo $(( num * 10080 )) ;;
+    m|"") echo "$num" ;;
+    *) echo "$num" ;;
+  esac
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -p|--password) PASSWORD="$2"; shift 2 ;;
+    -e|--expiry) EXPIRY="$2"; shift 2 ;;
+    -n|--max-downloads) MAX_DOWNLOADS="$2"; shift 2 ;;
+    -o|--obfuscate) OBFUSCATE="on"; shift ;;
+    --host) WARPBOX_HOST="$2"; shift 2 ;;
+    --auth) AUTH="$2"; shift 2 ;;
+    --auth-file) AUTH="$(cat "$2")"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    --) shift; while [ $# -gt 0 ]; do FILES+=("$1"); shift; done ;;
+    -*) echo "warpbox: unknown option $1" >&2; exit 2 ;;
+    *) FILES+=("$1"); shift ;;
+  esac
+done
+
+if [ -z "$WARPBOX_HOST" ]; then
+  echo "warpbox: no server set. Use --host <url> or export WARPBOX_HOST=<url>" >&2
+  exit 2
+fi
+
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "warpbox: no files given" >&2
+  echo >&2
+  usage >&2
+  exit 2
+fi
+
+CURL_ARGS=()
+for f in "${FILES[@]}"; do
+  if [ ! -f "$f" ]; then
+    echo "warpbox: not a file: $f" >&2
+    exit 2
+  fi
+  CURL_ARGS+=(-F "file=@${f}")
+done
+
+[ -n "$PASSWORD" ] && CURL_ARGS+=(-F "password=${PASSWORD}")
+[ -n "$EXPIRY" ] && CURL_ARGS+=(-F "expires_minutes=$(expiry_to_minutes "$EXPIRY")")
+[ -n "$MAX_DOWNLOADS" ] && CURL_ARGS+=(-F "max_downloads=${MAX_DOWNLOADS}")
+[ -n "$OBFUSCATE" ] && CURL_ARGS+=(-F "obfuscate_metadata=on")
+
+HEADERS=()
+[ -n "$AUTH" ] && HEADERS+=(-H "Authorization: Bearer ${AUTH}")
+[ "$AS_JSON" -eq 1 ] && HEADERS+=(-H "Accept: application/json")
+
+exec curl -fS "${HEADERS[@]}" "${CURL_ARGS[@]}" "${WARPBOX_HOST%/}/api/v1/upload"

backend/static/css/04-dialogs.css

@@ -0,0 +1,263 @@
+.warpbox-dialog-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 130;
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  background: color-mix(in srgb, var(--background) 60%, transparent);
+  backdrop-filter: blur(8px);
+  opacity: 0;
+  transition: opacity 160ms ease;
+}
+
+.warpbox-dialog-overlay.is-visible {
+  opacity: 1;
+}
+
+.warpbox-dialog {
+  position: relative;
+  width: min(28rem, 100%);
+  max-height: min(34rem, 90vh);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--card);
+  color: var(--card-foreground);
+  box-shadow: var(--shadow);
+  opacity: 0;
+  transform: translateY(0.6rem) scale(0.98);
+  transition: opacity 160ms ease, transform 160ms ease;
+}
+
+.warpbox-dialog:focus {
+  outline: none;
+}
+
+.warpbox-dialog-overlay.is-visible .warpbox-dialog {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+.warpbox-dialog-head {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 0.85rem;
+  align-items: center;
+  padding: 1.1rem 3.25rem 0 1.1rem;
+}
+
+.warpbox-dialog-icon {
+  width: 1.9rem;
+  height: 1.9rem;
+  display: grid;
+  place-items: center;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--primary) 20%, transparent);
+  color: var(--primary);
+  font-weight: 800;
+  line-height: 1;
+}
+
+.warpbox-dialog-warning .warpbox-dialog-icon {
+  background: color-mix(in srgb, var(--primary) 26%, transparent);
+  color: var(--primary-hover);
+}
+
+.warpbox-dialog-error .warpbox-dialog-icon {
+  background: color-mix(in srgb, var(--danger) 18%, transparent);
+  color: var(--danger);
+}
+
+.warpbox-dialog-title {
+  margin: 0;
+  font-size: 1.1rem;
+  line-height: 1.3;
+}
+
+.warpbox-dialog-close {
+  position: absolute;
+  top: 1.1rem;
+  right: 1.1rem;
+  z-index: 2;
+  min-height: 1.9rem;
+  height: 1.9rem;
+  width: 1.9rem;
+  padding: 0;
+  border-color: var(--border);
+  color: var(--muted-foreground);
+  background: var(--surface-1);
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.warpbox-dialog-close:hover {
+  color: var(--foreground);
+  background: var(--surface-1-hover);
+}
+
+.warpbox-dialog-body {
+  padding: 0.85rem 1.1rem 1.1rem;
+  overflow: auto;
+}
+
+.warpbox-dialog-message {
+  margin: 0 0 0.75rem;
+  color: var(--muted-foreground);
+  font-size: 0.92rem;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+
+.warpbox-dialog-message:last-child {
+  margin-bottom: 0;
+}
+
+.warpbox-dialog-field {
+  width: 100%;
+  border: 1px solid var(--input);
+  border-radius: calc(var(--radius) - 0.35rem);
+  background: var(--surface-1);
+  color: var(--foreground);
+  padding: 0.55rem 0.7rem;
+  font: inherit;
+}
+
+.warpbox-dialog-field:focus {
+  outline: 2px solid var(--ring);
+  outline-offset: 1px;
+}
+
+.warpbox-dialog-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.55rem;
+  padding: 0 1.1rem 1.1rem;
+}
+
+html.warpbox-dialog-open,
+html.warpbox-dialog-open body {
+  overflow: hidden;
+  touch-action: none;
+}
+
+.dialog-file-list {
+  display: grid;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+  max-height: 14rem;
+  overflow: auto;
+  padding-right: 0.25rem;
+}
+
+.dialog-file-row {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.65rem;
+  padding: 0.5rem 0.65rem;
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 0.35rem);
+  background: var(--surface-1);
+}
+
+.dialog-file-icon {
+  width: 1.35rem;
+  height: 1.35rem;
+  color: var(--muted-foreground);
+}
+
+.dialog-file-name {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 0.86rem;
+}
+
+.dialog-file-size {
+  color: var(--muted-foreground);
+  font-size: 0.8rem;
+  white-space: nowrap;
+}
+
+:root[data-theme="retro"] .warpbox-dialog {
+  border: 1px solid #000000;
+  border-radius: 0;
+  background: #c0c0c0;
+  color: #000000;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf, 4px 4px 0 rgba(0, 0, 0, 0.45);
+  font-family: "PixeloidSans", "PixelOperator", "Microsoft Sans Serif", Tahoma, sans-serif;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-head {
+  padding-top: 0.2rem;
+}
+
+:root[data-theme="retro"] .warpbox-dialog::before {
+  content: "Warpbox";
+  display: block;
+  margin: 0.18rem 0.18rem 0;
+  padding: 0.22rem 0.35rem;
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+  color: #ffffff;
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-error::before {
+  content: "Warpbox - Error";
+}
+
+:root[data-theme="retro"] .warpbox-dialog-warning::before {
+  content: "Warpbox - Warning";
+}
+
+:root[data-theme="retro"] .warpbox-dialog-info::before {
+  content: "Warpbox - Info";
+}
+
+:root[data-theme="retro"] .warpbox-dialog-icon {
+  border: 1px solid #000000;
+  background: #ffffff;
+  color: #000078;
+  box-shadow: inset 1px 1px 0 #808080, inset -1px -1px 0 #ffffff;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-warning .warpbox-dialog-icon {
+  color: #9a5b00;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-error .warpbox-dialog-icon {
+  color: #c00000;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-message {
+  color: #000000;
+}
+
+:root[data-theme="retro"] .warpbox-dialog-close {
+  top: 0.36rem;
+  right: 0.3rem;
+  width: 1.1rem;
+  height: 0.95rem;
+  min-height: 0.95rem;
+  background: #c0c0c0;
+  color: #000000;
+  border: 1px solid #000000;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+  font-size: 0.6rem;
+  font-weight: 700;
+}
+
+@media (max-width: 640px) {
+  .warpbox-dialog-overlay {
+    padding: 0.75rem;
+  }
+
+  .warpbox-dialog {
+    width: 100%;
+  }
+}

backend/static/css/16-retro.css

@@ -152,16 +152,16 @@
 
 /* Links: classic blue, underlined, purple when visited. Sidebar links and tabs
    are styled as their own Win98 controls below, so they're excluded here. */
-:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link) {
+:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link):not(.api-nav-link):not(.shortcut-card):not(.link-pill) {
   color: #0000ee;
   text-decoration: underline;
 }
 
-:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link):visited {
+:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link):not(.api-nav-link):not(.shortcut-card):not(.link-pill):visited {
   color: #551a8b;
 }
 
-:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link):hover {
+:root[data-theme="retro"] a:not(.button):not(.brand):not(.sidebar-link):not(.tab):not(.sort-link):not(.api-nav-link):not(.shortcut-card):not(.link-pill):hover {
   color: #ee0000;
 }
 
@@ -655,7 +655,7 @@
   padding: 0;
 }
 
-:root[data-theme="retro"] .view-toolbar .icon-button svg {
+:root[data-theme="retro"] .view-toolbar .icon-button .svg-icon {
   margin: 0;
   display: block;
 }
@@ -741,3 +741,283 @@
 :root[data-theme="retro"] .file-main small {
   color: inherit;
 }
+
+/* ------------------------------------------------------------------------- */
+/* API documentation: sidebar + panels as Win98 windows                      */
+/* The new .api-docs layout uses dark revamp tokens by default, which are     */
+/* unreadable on the black retro desktop. Re-skin it as Win98 chrome: a       */
+/* raised silver sidebar window, plain light section intros on the desktop,   */
+/* and each card a silver window with a navy title bar from its heading.      */
+/* ------------------------------------------------------------------------- */
+
+/* Sidebar = raised silver window with a real title bar from its <h1>. */
+:root[data-theme="retro"] .api-sidebar {
+  background: linear-gradient(to bottom, #ffffff, 4%, #c0c0c0 8%);
+  background-color: #c0c0c0;
+  border: 1px solid #000000;
+  box-shadow: var(--shadow);
+  padding: 0.5rem;
+  gap: 0.5rem;
+}
+
+:root[data-theme="retro"] .api-sidebar > .kicker {
+  display: none;
+}
+
+:root[data-theme="retro"] .api-sidebar-title {
+  margin: -0.5rem -0.5rem 0.5rem;
+  font-size: 0.9rem;
+}
+
+:root[data-theme="retro"] .api-nav {
+  border-left: 0;
+  padding-left: 0;
+  gap: 0.2rem;
+}
+
+/* Nav entries are flat silver list items; the active one is a navy bar. */
+:root[data-theme="retro"] .api-nav-link {
+  color: #000000;
+  font-weight: 700;
+  text-decoration: none;
+  border: 1px solid transparent;
+}
+
+:root[data-theme="retro"] .api-nav-link:hover {
+  background: #d4d0c8;
+  color: #000000;
+}
+
+:root[data-theme="retro"] .api-nav-link.is-active {
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+  color: #ffffff;
+  border-color: #000000;
+}
+
+:root[data-theme="retro"] .api-sidebar-meta {
+  border-top: 1px solid #808080;
+  box-shadow: 0 -1px 0 #ffffff;
+  padding-top: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+/* Section intro becomes a real Win98 window: silver body, the <h2> a navy
+   title bar with a fake close button, and the subtitle as black body text.
+   This fixes the default black-on-black inline code in headings/intros. */
+:root[data-theme="retro"] .panel-head {
+  max-width: none;
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background: linear-gradient(to bottom, #ffffff, 4%, #c0c0c0 8%);
+  background-color: #c0c0c0;
+  border: 1px solid #000000;
+  box-shadow: var(--shadow);
+}
+
+/* The kicker is redundant once the title sits in a title bar; hide it so the
+   bar can hug the top edge (the markup puts the kicker before the h2). */
+:root[data-theme="retro"] .panel-head .kicker {
+  display: none;
+}
+
+:root[data-theme="retro"] .panel-head h2 {
+  position: relative;
+  margin: -1rem -1rem 1rem;
+  padding: 0.35rem 1.8rem 0.35rem 0.5rem;
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+  color: #ffffff;
+  font-size: 1rem;
+  font-weight: 700;
+}
+
+/* Inline code in the title (e.g. "The warpbox CLI") reads white on the bar
+   instead of the default black. */
+:root[data-theme="retro"] .panel-head h2 code {
+  color: #ffffff;
+  background: transparent;
+  padding: 0;
+}
+
+:root[data-theme="retro"] .panel-head h2::after {
+  content: "\2715";
+  position: absolute;
+  top: 50%;
+  right: 0.4rem;
+  transform: translateY(-50%);
+  display: grid;
+  place-items: center;
+  width: 1.15rem;
+  height: 1rem;
+  background: #c0c0c0;
+  color: #000000;
+  font-size: 0.7rem;
+  font-weight: 700;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+}
+
+:root[data-theme="retro"] .panel-head .lead {
+  color: #1a1a1a;
+  margin: 0;
+}
+
+/* Inline code in the subtitle: sunken white field, black text. */
+:root[data-theme="retro"] .panel-head .lead code {
+  color: #000000;
+  background: #ffffff;
+  border: 1px solid #808080;
+  padding: 0 0.2rem;
+}
+
+/* The lone "Quick links" label on the home desktop stays light. */
+:root[data-theme="retro"] .section-label {
+  color: #ffffff;
+}
+
+/* ShareX step lists are light-muted by default; black on the silver window. */
+:root[data-theme="retro"] .docs-steps {
+  color: #1a1a1a;
+}
+
+/* Each card heading becomes a Win98 title bar with a fake close button.
+   Headings bleed to the window edges; only the first hugs the top edge so a
+   multi-step card (e.g. ShareX) reads as stacked group bars, not overlaps. */
+:root[data-theme="retro"] .api-content .card > .card-content > h3 {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  margin: 1.5rem -1.5rem 1rem;
+  padding: 0.35rem 0.5rem;
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+  color: #ffffff;
+  font-size: 1rem;
+  font-weight: 700;
+}
+
+:root[data-theme="retro"] .api-content .card > .card-content > h3:first-child {
+  margin-top: -1.5rem;
+}
+
+/* The upload endpoint card leads with a method + path row; make that the bar. */
+:root[data-theme="retro"] .api-content .endpoint-head {
+  margin: -1.5rem -1.5rem 1rem;
+  padding: 0.3rem 0.5rem;
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+}
+
+:root[data-theme="retro"] .endpoint-head .endpoint-path {
+  color: #ffffff;
+}
+
+:root[data-theme="retro"] .api-content .card > .card-content > h3::after,
+:root[data-theme="retro"] .api-content .endpoint-head::after {
+  content: "\2715";
+  display: grid;
+  place-items: center;
+  width: 1.15rem;
+  height: 1rem;
+  margin-left: auto;
+  background: #c0c0c0;
+  color: #000000;
+  font-size: 0.7rem;
+  font-weight: 700;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+}
+
+/* Body text inside windows reads black, not muted purple. */
+:root[data-theme="retro"] .api-content .card p,
+:root[data-theme="retro"] .api-content .card h4,
+:root[data-theme="retro"] .api-content .field-grid span,
+:root[data-theme="retro"] .endpoint-list div em,
+:root[data-theme="retro"] .faq-item summary,
+:root[data-theme="retro"] .faq-item p {
+  color: #1a1a1a;
+}
+
+/* Sub-labels (Request fields, Example, ...) become small black headers. */
+:root[data-theme="retro"] .api-content .card h4 {
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+/* Endpoint rows are sunken white fields. */
+:root[data-theme="retro"] .endpoint-list div {
+  background: #ffffff;
+  border: 1px solid #000000;
+  box-shadow: inset 1px 1px 0 #808080, inset -1px -1px 0 #ffffff;
+}
+
+/* Home shortcut tiles and quick links: silver windows / sunken white fields. */
+:root[data-theme="retro"] .shortcut-card {
+  background: linear-gradient(to bottom, #ffffff, 6%, #c0c0c0 10%);
+  background-color: #c0c0c0;
+  border: 1px solid #000000;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+}
+
+:root[data-theme="retro"] .shortcut-card:hover {
+  transform: none;
+  background-color: #d4d0c8;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+}
+
+:root[data-theme="retro"] .shortcut-eyebrow {
+  color: #000078;
+}
+
+:root[data-theme="retro"] .shortcut-title,
+:root[data-theme="retro"] .shortcut-sub {
+  color: #1a1a1a;
+}
+
+:root[data-theme="retro"] .link-pill {
+  background: #ffffff;
+  border: 1px solid #000000;
+  box-shadow: inset 1px 1px 0 #808080, inset -1px -1px 0 #ffffff;
+  color: #000000;
+}
+
+:root[data-theme="retro"] .link-pill span {
+  background: #000078;
+  color: #ffffff;
+  border: 1px solid #000000;
+}
+
+/* Colour-coded badges in the classic 16-colour VGA palette, with black
+   borders so they read like little Win98 toolbar icons. */
+:root[data-theme="retro"] .link-pill .tag-get { background: #0000aa; color: #ffffff; }
+:root[data-theme="retro"] .link-pill .tag-post { background: #008000; color: #ffffff; }
+:root[data-theme="retro"] .link-pill .tag-json { background: #aa00aa; color: #ffffff; }
+:root[data-theme="retro"] .link-pill .tag-key { background: #aa5500; color: #ffffff; }
+:root[data-theme="retro"] .link-pill .tag-help { background: #00aaaa; color: #000000; }
+
+/* CLI download cards = silver windows. */
+:root[data-theme="retro"] .download-card {
+  background: linear-gradient(to bottom, #ffffff, 4%, #c0c0c0 8%);
+  background-color: #c0c0c0;
+  border: 1px solid #000000;
+  box-shadow: var(--shadow);
+}
+
+:root[data-theme="retro"] .download-card .download-os,
+:root[data-theme="retro"] .download-card p {
+  color: #1a1a1a;
+}
+
+/* FAQ entries are silver windows; the +/- marker stays. */
+:root[data-theme="retro"] .faq-item {
+  background: linear-gradient(to bottom, #ffffff, 4%, #c0c0c0 8%);
+  background-color: #c0c0c0;
+  border: 1px solid #000000;
+  box-shadow: var(--shadow);
+}
+
+:root[data-theme="retro"] .faq-item summary::after {
+  color: #000000;
+}
+
+/* Copy buttons: stay visible (retro already paints them as silver buttons). */
+:root[data-theme="retro"] .code-block .copy-btn {
+  background: #c0c0c0;
+  opacity: 1;
+}

backend/static/css/19-popups.css

@@ -0,0 +1,173 @@
+.warpbox-popups {
+  position: fixed;
+  z-index: 120;
+  inset-block-start: calc(1rem + env(safe-area-inset-top));
+  inset-inline-end: calc(1rem + env(safe-area-inset-right));
+  width: min(26rem, calc(100vw - 2rem));
+  display: grid;
+  gap: 0.75rem;
+  pointer-events: none;
+}
+
+.warpbox-popup {
+  pointer-events: auto;
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 0.25rem);
+  background: color-mix(in srgb, var(--card) 96%, transparent);
+  color: var(--card-foreground);
+  box-shadow: var(--shadow);
+  opacity: 0;
+  transform: translateY(-0.55rem);
+  transition: opacity 160ms ease, transform 160ms ease;
+  overflow: hidden;
+}
+
+.warpbox-popup.is-visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.warpbox-popup-chrome {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  gap: 0.85rem;
+  align-items: start;
+  padding: 0.95rem;
+}
+
+.warpbox-popup-icon {
+  width: 1.6rem;
+  height: 1.6rem;
+  display: grid;
+  place-items: center;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--primary) 20%, transparent);
+  color: var(--primary);
+  font-weight: 800;
+  line-height: 1;
+}
+
+.warpbox-popup-warning .warpbox-popup-icon {
+  background: color-mix(in srgb, var(--primary) 26%, transparent);
+  color: var(--primary-hover);
+}
+
+.warpbox-popup-error .warpbox-popup-icon {
+  background: color-mix(in srgb, var(--danger) 18%, transparent);
+  color: var(--danger);
+}
+
+.warpbox-popup-title {
+  display: block;
+  margin: 0 0 0.18rem;
+  font-size: 0.92rem;
+  line-height: 1.2;
+}
+
+.warpbox-popup-message {
+  margin: 0;
+  color: var(--muted-foreground);
+  font-size: 0.84rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.warpbox-popup-close {
+  min-height: 1.8rem;
+  width: 1.8rem;
+  padding: 0;
+  border-color: var(--border);
+  color: var(--muted-foreground);
+  background: var(--surface-1);
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.warpbox-popup-close:hover {
+  color: var(--foreground);
+  background: var(--surface-1-hover);
+}
+
+.warpbox-popup-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.55rem;
+  padding: 0 0.95rem 0.95rem;
+}
+
+:root[data-theme="retro"] .warpbox-popups {
+  inset-block-start: 2.65rem;
+  font-family: "PixeloidSans", "PixelOperator", "Microsoft Sans Serif", Tahoma, sans-serif;
+}
+
+:root[data-theme="retro"] .warpbox-popup {
+  border: 1px solid #000000;
+  background: #c0c0c0;
+  color: #000000;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf, 3px 3px 0 rgba(0, 0, 0, 0.45);
+}
+
+:root[data-theme="retro"] .warpbox-popup::before {
+  content: "Warpbox";
+  display: block;
+  margin: 0.18rem 0.18rem 0;
+  padding: 0.22rem 0.35rem;
+  background: linear-gradient(to right, #000078, 80%, #0f80cd);
+  color: #ffffff;
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+
+:root[data-theme="retro"] .warpbox-popup-error::before {
+  content: "Warpbox - Error";
+}
+
+:root[data-theme="retro"] .warpbox-popup-warning::before {
+  content: "Warpbox - Warning";
+}
+
+:root[data-theme="retro"] .warpbox-popup-info::before {
+  content: "Warpbox - Info";
+}
+
+:root[data-theme="retro"] .warpbox-popup-chrome {
+  padding: 0.8rem;
+}
+
+:root[data-theme="retro"] .warpbox-popup-icon {
+  border: 1px solid #000000;
+  background: #ffffff;
+  color: #000078;
+  box-shadow: inset 1px 1px 0 #808080, inset -1px -1px 0 #ffffff;
+}
+
+:root[data-theme="retro"] .warpbox-popup-warning .warpbox-popup-icon {
+  color: #9a5b00;
+}
+
+:root[data-theme="retro"] .warpbox-popup-error .warpbox-popup-icon {
+  color: #c00000;
+}
+
+:root[data-theme="retro"] .warpbox-popup-message {
+  color: #000000;
+}
+
+:root[data-theme="retro"] .warpbox-popup-close {
+  width: 1.45rem;
+  height: 1.25rem;
+  min-height: 1.25rem;
+  background: #c0c0c0;
+  color: #000000;
+  border: 1px solid #000000;
+  box-shadow: inset -1px -1px 0 #404040, inset 1px 1px 0 #ffffff, inset -2px -2px 0 #808080, inset 2px 2px 0 #dfdfdf;
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+
+@media (max-width: 640px) {
+  .warpbox-popups {
+    inset-inline: 1rem;
+    width: auto;
+  }
+}

backend/static/css/20-upload.css

@@ -56,6 +56,10 @@
   display: none !important;
 }
 
+.install-pwa-button[hidden] {
+  display: none !important;
+}
+
 .hero-copy {
   text-align: center;
 }
@@ -395,6 +399,10 @@ button {
   text-align: right;
 }
 
+.upload-file-state-shared {
+  color: var(--primary);
+}
+
 .upload-recovery-overlay {
   position: fixed;
   inset: 0;

backend/static/css/30-download.css

@@ -678,7 +678,54 @@
   color: var(--muted-foreground);
 }
 
-.file-emblem svg {
+.svg-icon {
+  width: 1rem;
+  height: 1rem;
+  display: inline-block;
+  flex: 0 0 auto;
+  background-color: currentColor;
+  vertical-align: -0.125em;
+  mask: var(--svg-icon-url) center / contain no-repeat;
+  -webkit-mask: var(--svg-icon-url) center / contain no-repeat;
+}
+
+.svg-icon-document {
+  --svg-icon-url: url("/static/icons/regular/submit-document.svg");
+}
+
+.svg-icon-share {
+  --svg-icon-url: url("/static/icons/regular/share-android.svg");
+}
+
+.svg-icon-download {
+  --svg-icon-url: url("/static/icons/regular/download.svg");
+}
+
+.svg-icon-list {
+  --svg-icon-url: url("/static/icons/regular/list.svg");
+}
+
+.svg-icon-grid {
+  --svg-icon-url: url("/static/icons/regular/view-grid.svg");
+}
+
+.svg-icon-emoji {
+  --svg-icon-url: url("/static/icons/regular/emoji.svg");
+}
+
+.svg-icon-open {
+  --svg-icon-url: url("/static/icons/regular/open-in-browser.svg");
+}
+
+.svg-icon-copy {
+  --svg-icon-url: url("/static/icons/regular/copy.svg");
+}
+
+.svg-icon-eye {
+  --svg-icon-url: url("/static/icons/regular/eye.svg");
+}
+
+.file-emblem .svg-icon {
   width: 1.75rem;
   height: 1.75rem;
 }
@@ -698,6 +745,17 @@
   text-decoration: none;
 }
 
+.button.is-disabled {
+  opacity: .62;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+.download-share-button {
+  margin-top: 1rem;
+  margin-bottom: 0.65rem;
+}
+
 .upload-processing-alert {
   margin: 1rem 0;
   padding: .85rem 1rem;
@@ -707,6 +765,11 @@
   color: var(--foreground);
 }
 
+.upload-processing-alert-error {
+  border-color: color-mix(in srgb, var(--danger) 55%, transparent);
+  background: color-mix(in srgb, var(--danger) 14%, transparent);
+}
+
 .thumb-link {
   flex: 0 0 4.75rem;
   width: 4.75rem;
@@ -812,7 +875,7 @@
   justify-content: center;
 }
 
-.view-toolbar svg {
+.view-toolbar .svg-icon {
   width: 0.95rem;
   height: 0.95rem;
 }
@@ -870,6 +933,24 @@
   cursor: wait;
 }
 
+.file-card.is-failed {
+  border-color: color-mix(in srgb, var(--danger) 55%, var(--border));
+  background: color-mix(in srgb, var(--danger) 8%, var(--background));
+}
+
+.file-card.is-failed .file-open {
+  cursor: not-allowed;
+}
+
+.file-error {
+  display: block;
+  max-width: 100%;
+  margin-top: 0.18rem;
+  color: var(--danger);
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
 .file-reaction-dock {
   position: static;
   z-index: 2;
@@ -963,14 +1044,9 @@
   pointer-events: auto;
 }
 
-.reaction-button svg {
+.reaction-button .svg-icon {
   width: 1.15rem;
   height: 1.15rem;
-  fill: none;
-  stroke: currentColor;
-  stroke-width: 1.9;
-  stroke-linecap: round;
-  stroke-linejoin: round;
 }
 
 .file-card:hover .reaction-button,

backend/static/css/40-docs.css

@@ -10,6 +10,425 @@
   padding: 2rem 0 3rem;
 }
 
+/* ============================================================
+   API documentation — sidebar layout
+   ============================================================ */
+
+.api-docs {
+  width: min(74rem, calc(100% - 2rem));
+  margin: 0 auto;
+  padding: 2rem 0 3rem;
+  display: grid;
+  grid-template-columns: 13.5rem minmax(0, 1fr);
+  gap: 2rem;
+  align-items: start;
+}
+
+.api-sidebar {
+  position: sticky;
+  top: 1.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+
+.api-sidebar-title {
+  margin: 0 0 0.75rem;
+  font-size: 1.15rem;
+}
+
+.api-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+  border-left: 1px solid var(--border);
+  padding-left: 0.3rem;
+}
+
+.api-nav-link {
+  display: block;
+  padding: 0.45rem 0.7rem;
+  border-radius: calc(var(--radius) - 0.3rem);
+  color: var(--muted-foreground);
+  font-size: 0.9rem;
+  font-weight: 600;
+  text-decoration: none;
+  line-height: 1.2;
+  transition: background 0.12s ease, color 0.12s ease;
+}
+
+.api-nav-link:hover {
+  background: var(--muted);
+  color: var(--foreground);
+}
+
+.api-nav-link.is-active {
+  background: color-mix(in srgb, var(--primary) 16%, transparent);
+  color: var(--foreground);
+}
+
+.api-sidebar-meta {
+  margin-top: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  font-size: 0.8rem;
+}
+
+.api-sidebar-meta a {
+  color: var(--muted-foreground);
+}
+
+/* --- Panels: only one visible at a time --- */
+.api-content {
+  min-width: 0;
+}
+
+.doc-panel {
+  display: none;
+  outline: none;
+}
+
+.doc-panel.is-active {
+  display: block;
+  animation: doc-fade 0.18s ease;
+}
+
+@keyframes doc-fade {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: none; }
+}
+
+.panel-head {
+  max-width: 46rem;
+  margin-bottom: 1.5rem;
+}
+
+.panel-head h2 {
+  margin: 0;
+  font-size: 1.5rem;
+}
+
+.panel-head .lead {
+  margin: 0.6rem 0 0;
+  color: var(--muted-foreground);
+  font-size: 0.95rem;
+  line-height: 1.6;
+}
+
+.api-content .card + .card,
+.api-content .quickstart {
+  margin-top: 1rem;
+}
+
+.api-content h3 {
+  margin: 0;
+  font-size: 1.05rem;
+}
+
+.api-content h4 {
+  margin: 1.4rem 0 0;
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--muted-foreground);
+}
+
+.api-content .card p {
+  margin: 0.65rem 0 0;
+  color: var(--muted-foreground);
+  font-size: 0.9rem;
+  line-height: 1.6;
+}
+
+.api-content code {
+  color: var(--foreground);
+}
+
+.api-content .field-grid p {
+  margin: 0;
+}
+
+.section-label {
+  margin: 1.75rem 0 0.75rem !important;
+  font-size: 0.8rem !important;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--muted-foreground);
+}
+
+/* --- Home shortcuts --- */
+.shortcut-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(13rem, 1fr));
+  gap: 0.75rem;
+  margin-bottom: 1.25rem;
+}
+
+.shortcut-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-left: 3px solid var(--accent-c, var(--border));
+  border-radius: var(--radius);
+  background: color-mix(in srgb, var(--card) 94%, transparent);
+  text-decoration: none;
+  transition: border-color 0.12s ease, transform 0.12s ease, box-shadow 0.12s ease;
+}
+
+.shortcut-card:hover {
+  border-color: var(--accent-c, var(--ring));
+  transform: translateY(-2px);
+  box-shadow: 0 6px 18px color-mix(in srgb, var(--accent-c, var(--ring)) 22%, transparent);
+}
+
+/* Per-card accent. Each home shortcut owns a colour, echoed by its eyebrow,
+   left edge, and hover glow. */
+.accent-blue { --accent-c: #3b82f6; }
+.accent-green { --accent-c: #22c55e; }
+.accent-violet { --accent-c: #8b5cf6; }
+.accent-amber { --accent-c: #f59e0b; }
+
+.shortcut-eyebrow {
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--accent-c, var(--primary));
+}
+
+.shortcut-title {
+  font-size: 1rem;
+  font-weight: 650;
+  color: var(--foreground);
+}
+
+.shortcut-sub {
+  font-size: 0.82rem;
+  color: var(--muted-foreground);
+}
+
+.link-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+  gap: 0.5rem;
+}
+
+.link-pill {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  padding: 0.6rem 0.85rem;
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 0.2rem);
+  background: var(--card);
+  color: var(--foreground);
+  font-size: 0.88rem;
+  text-decoration: none;
+  transition: border-color 0.12s ease;
+}
+
+.link-pill:hover {
+  border-color: var(--ring);
+}
+
+.link-pill span {
+  flex: none;
+  min-width: 2.6rem;
+  text-align: center;
+  padding: 0.15rem 0.35rem;
+  border-radius: 0.3rem;
+  background: var(--muted);
+  color: var(--muted-foreground);
+  font-size: 0.66rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+}
+
+/* Colour-coded tags on the home quick links (and reusable elsewhere). Tinted
+   background plus a saturated label so they read as accents, not loud chips. */
+.link-pill .tag-get { background: color-mix(in srgb, #3b82f6 22%, transparent); color: #93c5fd; }
+.link-pill .tag-post { background: color-mix(in srgb, #22c55e 22%, transparent); color: #86efac; }
+.link-pill .tag-json { background: color-mix(in srgb, #8b5cf6 24%, transparent); color: #c4b5fd; }
+.link-pill .tag-key { background: color-mix(in srgb, #eab308 24%, transparent); color: #fde047; }
+.link-pill .tag-help { background: color-mix(in srgb, #06b6d4 24%, transparent); color: #67e8f9; }
+
+/* --- Code blocks with copy button --- */
+.code-block {
+  position: relative;
+  margin: 0;
+}
+
+.code-block .copy-btn {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  padding: 0.3rem 0.6rem;
+  border: 1px solid var(--border);
+  border-radius: 0.4rem;
+  background: color-mix(in srgb, var(--card) 80%, transparent);
+  color: var(--muted-foreground);
+  font-size: 0.72rem;
+  font-weight: 600;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.12s ease, color 0.12s ease, border-color 0.12s ease;
+}
+
+.code-block:hover .copy-btn,
+.code-block .copy-btn:focus-visible {
+  opacity: 1;
+}
+
+.code-block .copy-btn:hover {
+  color: var(--foreground);
+  border-color: var(--ring);
+}
+
+/* --- Endpoint blocks --- */
+.endpoint-head {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  flex-wrap: wrap;
+}
+
+.endpoint-path {
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+.method {
+  flex: none;
+  display: inline-block;
+  padding: 0.2rem 0.5rem;
+  border-radius: 0.35rem;
+  font-size: 0.68rem;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  color: #fff;
+}
+
+.method-get { background: #2563eb; }
+.method-post { background: #16a34a; }
+.method-put { background: #d97706; }
+
+.endpoint-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin: 1rem 0 0;
+}
+
+.endpoint-list div {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  flex-wrap: wrap;
+  padding: 0.55rem 0.7rem;
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 0.3rem);
+  background: var(--background);
+}
+
+.endpoint-list div code {
+  font-size: 0.82rem;
+  word-break: break-all;
+}
+
+.endpoint-list div em {
+  margin-left: auto;
+  color: var(--muted-foreground);
+  font-size: 0.8rem;
+  font-style: normal;
+}
+
+/* --- CLI download cards --- */
+.download-row {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+  gap: 0.75rem;
+  margin-bottom: 1rem;
+}
+
+.download-card {
+  padding: 1.25rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: color-mix(in srgb, var(--card) 94%, transparent);
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.download-card .download-os {
+  font-size: 1.05rem;
+  font-weight: 650;
+  color: var(--foreground);
+}
+
+.download-card p {
+  margin: 0;
+  color: var(--muted-foreground);
+  font-size: 0.88rem;
+}
+
+.download-card .button {
+  margin-top: auto;
+}
+
+/* --- FAQ --- */
+.faq-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.faq-item {
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) - 0.2rem);
+  background: color-mix(in srgb, var(--card) 94%, transparent);
+  padding: 0 1rem;
+}
+
+.faq-item summary {
+  padding: 0.9rem 0;
+  cursor: pointer;
+  font-weight: 600;
+  color: var(--foreground);
+  list-style: none;
+  position: relative;
+  padding-right: 1.5rem;
+}
+
+.faq-item summary::-webkit-details-marker {
+  display: none;
+}
+
+.faq-item summary::after {
+  content: "+";
+  position: absolute;
+  right: 0.1rem;
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--muted-foreground);
+  font-size: 1.1rem;
+}
+
+.faq-item[open] summary::after {
+  content: "\2212";
+}
+
+.faq-item p {
+  margin: 0 0 0.95rem;
+  color: var(--muted-foreground);
+  font-size: 0.9rem;
+  line-height: 1.6;
+}
+
 .docs-header {
   max-width: 44rem;
 }
@@ -63,42 +482,19 @@
   grid-column: 1 / -1;
 }
 
-.endpoint-list,
 .field-grid {
   display: grid;
   gap: 0.65rem;
   margin: 1rem 0 0;
-}
-
-.endpoint-list div,
-.field-grid {
   min-width: 0;
 }
 
-.endpoint-list div {
-  display: grid;
-  grid-template-columns: 7rem minmax(0, 1fr);
-  gap: 0.75rem;
-  align-items: baseline;
-}
-
-.endpoint-list dt,
-.endpoint-list dd {
-  margin: 0;
-  min-width: 0;
-}
-
-.endpoint-list dt,
 .field-grid span {
   color: var(--muted-foreground);
   font-size: 0.78rem;
   font-weight: 700;
 }
 
-.endpoint-list dd code {
-  display: block;
-}
-
 .docs-steps {
   margin: 0.85rem 0 0;
   padding-left: 1.1rem;

backend/static/css/90-responsive.css

@@ -57,6 +57,44 @@
     grid-template-columns: 1fr;
   }
 
+  .api-docs {
+    grid-template-columns: 1fr;
+    gap: 1.25rem;
+  }
+
+  .api-sidebar {
+    position: static;
+    top: auto;
+  }
+
+  .api-sidebar-title {
+    margin-bottom: 0.5rem;
+  }
+
+  .api-nav {
+    flex-direction: row;
+    flex-wrap: wrap;
+    border-left: 0;
+    padding-left: 0;
+    gap: 0.35rem;
+  }
+
+  .api-nav-link {
+    border: 1px solid var(--border);
+  }
+
+  .api-sidebar-meta {
+    flex-direction: row;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+    margin-top: 0.5rem;
+  }
+
+  .endpoint-list div em {
+    margin-left: 0;
+    width: 100%;
+  }
+
   .app-sidebar {
     position: static;
     width: 100%;

backend/static/js/02-pwa.js

@@ -0,0 +1,43 @@
+(function () {
+  let installPrompt = null;
+
+  if ("serviceWorker" in navigator) {
+    window.addEventListener("load", () => {
+      navigator.serviceWorker.register("/service-worker.js").catch(() => {
+        /* Service workers are progressive enhancement here. */
+      });
+    });
+  }
+
+  window.addEventListener("beforeinstallprompt", (event) => {
+    const button = document.querySelector("[data-install-pwa]");
+    if (!button) {
+      return;
+    }
+    event.preventDefault();
+    installPrompt = event;
+    button.hidden = false;
+    button.addEventListener("click", async () => {
+      if (!installPrompt) {
+        return;
+      }
+      button.disabled = true;
+      try {
+        await installPrompt.prompt();
+        await installPrompt.userChoice;
+      } finally {
+        installPrompt = null;
+        button.hidden = true;
+        button.disabled = false;
+      }
+    }, { once: true });
+  });
+
+  window.addEventListener("appinstalled", () => {
+    const button = document.querySelector("[data-install-pwa]");
+    if (button) {
+      button.hidden = true;
+    }
+    installPrompt = null;
+  });
+})();

backend/static/js/03-popups.js

@@ -0,0 +1,174 @@
+(function () {
+  const DEFAULT_DURATION = 6200;
+  const VARIANTS = ["info", "warning", "error"];
+  const GENERIC_ERROR_MESSAGE = "Something went wrong on this page. Please try again in a moment.";
+
+  window.Warpbox = window.Warpbox || {};
+  let lastGlobalErrorAt = 0;
+
+  function ensureRegion() {
+    let region = document.querySelector("[data-warpbox-popups]");
+    if (region) {
+      return region;
+    }
+    region = document.createElement("div");
+    region.className = "warpbox-popups";
+    region.setAttribute("data-warpbox-popups", "");
+    region.setAttribute("aria-live", "polite");
+    region.setAttribute("aria-atomic", "false");
+    document.body.append(region);
+    return region;
+  }
+
+  function normalizeOptions(options, message) {
+    if (typeof options === "string") {
+      options = { message: options };
+    } else {
+      options = options || {};
+    }
+    if (message) {
+      options.message = message;
+    }
+    const variant = VARIANTS.includes(options.variant) ? options.variant : "info";
+    return {
+      variant,
+      title: options.title || defaultTitle(variant),
+      message: options.message || "",
+      duration: Number.isFinite(options.duration) ? options.duration : DEFAULT_DURATION,
+      actions: Array.isArray(options.actions) ? options.actions : [],
+    };
+  }
+
+  function defaultTitle(variant) {
+    if (variant === "error") {
+      return "Error";
+    }
+    if (variant === "warning") {
+      return "Warning";
+    }
+    return "Info";
+  }
+
+  function notify(options, message) {
+    const config = normalizeOptions(options, message);
+    const region = ensureRegion();
+    const popup = document.createElement("section");
+    popup.className = "warpbox-popup warpbox-popup-" + config.variant;
+    popup.setAttribute("role", config.variant === "error" ? "alert" : "status");
+
+    const chrome = document.createElement("div");
+    chrome.className = "warpbox-popup-chrome";
+
+    const icon = document.createElement("span");
+    icon.className = "warpbox-popup-icon";
+    icon.setAttribute("aria-hidden", "true");
+    icon.textContent = config.variant === "error" ? "!" : config.variant === "warning" ? "?" : "i";
+
+    const body = document.createElement("div");
+    body.className = "warpbox-popup-body";
+
+    const title = document.createElement("strong");
+    title.className = "warpbox-popup-title";
+    title.textContent = config.title;
+
+    const text = document.createElement("p");
+    text.className = "warpbox-popup-message";
+    text.textContent = config.message;
+
+    body.append(title, text);
+
+    const close = document.createElement("button");
+    close.type = "button";
+    close.className = "warpbox-popup-close";
+    close.setAttribute("aria-label", "Dismiss notification");
+    close.textContent = "x";
+    close.addEventListener("click", () => dismiss(popup));
+
+    chrome.append(icon, body, close);
+    popup.append(chrome);
+
+    if (config.actions.length > 0) {
+      const actions = document.createElement("div");
+      actions.className = "warpbox-popup-actions";
+      config.actions.forEach((action) => {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "button " + (action.kind === "primary" ? "button-primary" : "button-outline");
+        button.textContent = action.label || "Action";
+        button.addEventListener("click", () => {
+          if (typeof action.onClick === "function") {
+            action.onClick();
+          }
+          if (action.dismiss !== false) {
+            dismiss(popup);
+          }
+        });
+        actions.append(button);
+      });
+      popup.append(actions);
+    }
+
+    region.append(popup);
+    window.requestAnimationFrame(() => popup.classList.add("is-visible"));
+
+    let timer = null;
+    if (config.duration > 0) {
+      timer = window.setTimeout(() => dismiss(popup), config.duration);
+    }
+
+    return {
+      element: popup,
+      close: function closePopup() {
+        if (timer) {
+          window.clearTimeout(timer);
+        }
+        dismiss(popup);
+      },
+    };
+  }
+
+  function dismiss(popup) {
+    if (!popup || popup.dataset.closing === "true") {
+      return;
+    }
+    popup.dataset.closing = "true";
+    popup.classList.remove("is-visible");
+    window.setTimeout(() => popup.remove(), 180);
+  }
+
+  window.Warpbox.notify = notify;
+  window.Warpbox.info = function info(message, options) {
+    return notify({ ...(options || {}), variant: "info", message });
+  };
+  window.Warpbox.warning = function warning(message, options) {
+    return notify({ ...(options || {}), variant: "warning", message });
+  };
+  window.Warpbox.error = function error(message, options) {
+    return notify({ ...(options || {}), variant: "error", message });
+  };
+
+  function showGlobalError() {
+    const now = Date.now();
+    if (now - lastGlobalErrorAt < 2500) {
+      return;
+    }
+    lastGlobalErrorAt = now;
+    notify({
+      variant: "error",
+      title: "Page error",
+      message: GENERIC_ERROR_MESSAGE,
+      duration: 9000,
+    });
+  }
+
+  window.addEventListener("error", function (event) {
+    if (event && event.target && event.target !== window) {
+      return;
+    }
+    showGlobalError();
+  });
+
+  window.addEventListener("unhandledrejection", function () {
+    showGlobalError();
+  });
+})();

backend/static/js/04-dialogs.js

@@ -0,0 +1,299 @@
+(function () {
+  const VARIANTS = ["info", "warning", "error"];
+  const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  window.Warpbox = window.Warpbox || {};
+  let dialogIdCounter = 0;
+
+  function defaultTitle(variant) {
+    if (variant === "error") {
+      return "Error";
+    }
+    if (variant === "warning") {
+      return "Warning";
+    }
+    return "Info";
+  }
+
+  function normalizeOptions(options, message) {
+    if (typeof options === "string") {
+      options = { message: options };
+    } else {
+      options = options || {};
+    }
+    if (message) {
+      options.message = message;
+    }
+    const variant = VARIANTS.includes(options.variant) ? options.variant : "info";
+    return {
+      variant,
+      title: options.title || defaultTitle(variant),
+      message: options.message || "",
+      body: options.body || null,
+      actions: Array.isArray(options.actions) ? options.actions : [],
+      dismissible: options.dismissible !== false,
+      closable: options.closable !== false,
+      onClose: typeof options.onClose === "function" ? options.onClose : null,
+    };
+  }
+
+  function focusableElements(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetParent !== null);
+  }
+
+  function dialog(options, message) {
+    const config = normalizeOptions(options, message);
+    const previouslyFocused = document.activeElement;
+    dialogIdCounter += 1;
+    const titleId = "warpbox-dialog-title-" + dialogIdCounter;
+
+    const overlay = document.createElement("div");
+    overlay.className = "warpbox-dialog-overlay";
+
+    const card = document.createElement("div");
+    card.className = "warpbox-dialog warpbox-dialog-" + config.variant;
+    card.setAttribute("role", config.variant === "error" ? "alertdialog" : "dialog");
+    card.setAttribute("aria-modal", "true");
+    card.setAttribute("aria-labelledby", titleId);
+    card.setAttribute("tabindex", "-1");
+
+    const head = document.createElement("div");
+    head.className = "warpbox-dialog-head";
+
+    const icon = document.createElement("span");
+    icon.className = "warpbox-dialog-icon";
+    icon.setAttribute("aria-hidden", "true");
+    icon.textContent = config.variant === "error" ? "!" : config.variant === "warning" ? "?" : "i";
+
+    const title = document.createElement("h2");
+    title.id = titleId;
+    title.className = "warpbox-dialog-title";
+    title.textContent = config.title;
+
+    head.append(icon, title);
+
+    if (config.closable) {
+      const close = document.createElement("button");
+      close.type = "button";
+      close.className = "warpbox-dialog-close";
+      close.setAttribute("aria-label", "Close dialog");
+      close.textContent = "x";
+      close.addEventListener("click", () => closeDialog());
+      head.append(close);
+    }
+
+    const body = document.createElement("div");
+    body.className = "warpbox-dialog-body";
+
+    if (config.message) {
+      const text = document.createElement("p");
+      text.className = "warpbox-dialog-message";
+      text.textContent = config.message;
+      body.append(text);
+    }
+
+    if (config.body) {
+      const nodes = Array.isArray(config.body) ? config.body : [config.body];
+      nodes.forEach((node) => {
+        if (node instanceof Node) {
+          body.append(node);
+        }
+      });
+    }
+
+    card.append(head, body);
+
+    let autofocusTarget = null;
+    if (config.actions.length > 0) {
+      const actions = document.createElement("div");
+      actions.className = "warpbox-dialog-actions";
+      config.actions.forEach((action) => {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "button " + (action.kind === "primary" ? "button-primary" : action.kind === "ghost" ? "button-ghost" : "button-outline");
+        button.textContent = action.label || "OK";
+        button.addEventListener("click", () => {
+          if (typeof action.onClick === "function") {
+            action.onClick();
+          }
+          if (action.dismiss !== false) {
+            closeDialog();
+          }
+        });
+        if (action.autofocus) {
+          autofocusTarget = button;
+        }
+        actions.append(button);
+      });
+      card.append(actions);
+    }
+
+    overlay.append(card);
+    document.body.append(overlay);
+    document.documentElement.classList.add("warpbox-dialog-open");
+    window.requestAnimationFrame(() => {
+      overlay.classList.add("is-visible");
+      (autofocusTarget || card).focus();
+    });
+
+    function handleKeydown(event) {
+      if (event.key === "Escape") {
+        if (config.dismissible) {
+          event.preventDefault();
+          closeDialog();
+        }
+        return;
+      }
+      if (event.key !== "Tab") {
+        return;
+      }
+      const focusable = focusableElements(card);
+      if (focusable.length === 0) {
+        event.preventDefault();
+        return;
+      }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+
+    function handleOverlayClick(event) {
+      if (config.dismissible && event.target === overlay) {
+        closeDialog();
+      }
+    }
+
+    document.addEventListener("keydown", handleKeydown, true);
+    overlay.addEventListener("click", handleOverlayClick);
+
+    let closed = false;
+    function closeDialog() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      document.removeEventListener("keydown", handleKeydown, true);
+      overlay.removeEventListener("click", handleOverlayClick);
+      overlay.classList.remove("is-visible");
+      document.documentElement.classList.remove("warpbox-dialog-open");
+      window.setTimeout(() => overlay.remove(), 180);
+      if (previouslyFocused && typeof previouslyFocused.focus === "function") {
+        previouslyFocused.focus();
+      }
+      if (config.onClose) {
+        config.onClose();
+      }
+    }
+
+    return {
+      element: overlay,
+      close: closeDialog,
+    };
+  }
+
+  window.Warpbox.dialog = dialog;
+
+  window.Warpbox.alertDialog = function alertDialog(message, options) {
+    const config = (typeof options === "object" && options) || {};
+    return new Promise((resolve) => {
+      dialog({
+        ...config,
+        message: typeof message === "string" ? message : config.message,
+        actions: [{ label: config.okLabel || "OK", kind: "primary", autofocus: true }],
+        onClose: () => {
+          if (typeof config.onClose === "function") {
+            config.onClose();
+          }
+          resolve();
+        },
+      });
+    });
+  };
+
+  window.Warpbox.confirmDialog = function confirmDialog(message, options) {
+    const config = (typeof options === "object" && options) || {};
+    return new Promise((resolve) => {
+      let settled = false;
+      function settle(value) {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        resolve(value);
+      }
+      dialog({
+        ...config,
+        message: typeof message === "string" ? message : config.message,
+        actions: [
+          { label: config.cancelLabel || "Cancel", kind: "outline", autofocus: true, onClick: () => settle(false) },
+          { label: config.confirmLabel || "Confirm", kind: "primary", onClick: () => settle(true) },
+        ],
+        onClose: () => {
+          if (typeof config.onClose === "function") {
+            config.onClose();
+          }
+          settle(false);
+        },
+      });
+    });
+  };
+
+  window.Warpbox.promptDialog = function promptDialog(message, options) {
+    const config = (typeof options === "object" && options) || {};
+    return new Promise((resolve) => {
+      let settled = false;
+      function settle(value) {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        resolve(value);
+      }
+
+      const field = document.createElement("input");
+      field.type = config.inputType || "text";
+      field.className = "warpbox-dialog-field";
+      if (config.placeholder) {
+        field.placeholder = config.placeholder;
+      }
+      if (typeof config.value === "string") {
+        field.value = config.value;
+      }
+
+      let controller = null;
+      field.addEventListener("keydown", (event) => {
+        if (event.key === "Enter") {
+          event.preventDefault();
+          settle(field.value);
+          if (controller) {
+            controller.close();
+          }
+        }
+      });
+
+      controller = dialog({
+        ...config,
+        message: typeof message === "string" ? message : config.message,
+        body: field,
+        actions: [
+          { label: config.cancelLabel || "Cancel", kind: "outline", onClick: () => settle(null) },
+          { label: config.okLabel || "OK", kind: "primary", onClick: () => settle(field.value) },
+        ],
+        onClose: () => {
+          if (typeof config.onClose === "function") {
+            config.onClose();
+          }
+          settle(null);
+        },
+      });
+
+      window.requestAnimationFrame(() => field.focus());
+    });
+  };
+})();

backend/static/js/13-share.js

@@ -0,0 +1,50 @@
+(function () {
+  const shareButtons = document.querySelectorAll("[data-share-box]");
+  if (shareButtons.length === 0) {
+    return;
+  }
+
+  shareButtons.forEach((button) => {
+    const label = button.querySelector("[data-share-box-label]") || button;
+    const shareData = {
+      title: button.dataset.shareTitle || document.title,
+      text: button.dataset.shareText || "",
+      url: window.Warpbox.absoluteURL(button.dataset.shareUrl || window.location.href),
+    };
+    const canShare = typeof navigator.share === "function" && (!navigator.canShare || navigator.canShare(shareData));
+
+    label.textContent = canShare ? "Share" : "Copy Link";
+    button.setAttribute("aria-label", canShare ? "Share this box" : "Copy box link");
+
+    button.addEventListener("click", async () => {
+      if (canShare) {
+        try {
+          await navigator.share(shareData);
+          return;
+        } catch (error) {
+          if (error && error.name === "AbortError") {
+            return;
+          }
+        }
+      }
+      await copyShareURL(button, label, shareData.url, canShare);
+    });
+  });
+
+  async function copyShareURL(button, label, url, shareMode) {
+    try {
+      await window.Warpbox.writeClipboard(url);
+      const previous = label.textContent;
+      label.textContent = "Copied";
+      window.setTimeout(() => {
+        label.textContent = shareMode ? "Share" : "Copy Link";
+      }, 1400);
+    } catch (error) {
+      if (window.Warpbox && typeof window.Warpbox.error === "function") {
+        window.Warpbox.error("The share link could not be copied.", {
+          title: "Copy failed",
+        });
+      }
+    }
+  }
+})();

backend/static/js/40-upload.js

@@ -14,7 +14,11 @@
   const openBox = document.querySelector("#open-box");
   const manageLink = document.querySelector("#manage-link");
   const newUpload = document.querySelector("#new-upload");
+  const folderPicker = document.querySelector("[data-folder-picker]");
   const RESUMABLE_SESSIONS_KEY = "warpbox-resumable-sessions";
+  const SHARE_CACHE = "warpbox-share-target-v1";
+  const SHARE_LATEST_KEY = "/__warpbox_share_target__/latest";
+  const CELLULAR_WARNING_THRESHOLD_BYTES = 200 * 1024 * 1024;
 
   if (!form || !dropZone || !fileInput) {
     return;
@@ -47,6 +51,9 @@
   let uploadLocked = false;
   let recoveredDraft = null;
   let resumeMode = false;
+  let sharedTargetDraft = null;
+  const maxUploadBytes = parseInt(form.dataset.maxUploadBytes || "-1", 10);
+  const maxUploadLabel = form.dataset.maxUploadLabel || (maxUploadBytes > 0 && window.Warpbox.formatBytes ? window.Warpbox.formatBytes(maxUploadBytes) : "the configured limit");
 
   ["dragenter", "dragover"].forEach((eventName) => {
     dropZone.addEventListener(eventName, (event) => {
@@ -69,18 +76,18 @@
   });
 
   document.addEventListener("drop", (event) => {
-    if (!event.dataTransfer || !event.dataTransfer.files.length) {
+    if (!hasTransferFiles(event.dataTransfer)) {
       return;
     }
     event.preventDefault();
     if (!dropZone.contains(event.target)) {
-      addSelectedFiles(event.dataTransfer.files);
+      addDroppedFiles(event.dataTransfer);
     }
   });
 
   dropZone.addEventListener("drop", (event) => {
-    if (event.dataTransfer && event.dataTransfer.files.length > 0) {
-      addSelectedFiles(event.dataTransfer.files);
+    if (hasTransferFiles(event.dataTransfer)) {
+      addDroppedFiles(event.dataTransfer);
     }
   });
 
@@ -89,15 +96,58 @@
     fileInput.value = "";
   });
 
+  document.addEventListener("paste", (event) => {
+    if (!event.clipboardData || !event.clipboardData.files || event.clipboardData.files.length === 0) {
+      return;
+    }
+    if (isTextEditingTarget(event.target)) {
+      return;
+    }
+    event.preventDefault();
+    addSelectedFiles(event.clipboardData.files, { source: "pasted" });
+  });
+
+  if (folderPicker && typeof window.showDirectoryPicker === "function") {
+    folderPicker.hidden = false;
+    folderPicker.addEventListener("click", async () => {
+      if (uploadLocked) {
+        return;
+      }
+      try {
+        updateStatus("Reading folder...");
+        const directory = await window.showDirectoryPicker();
+        const files = await filesFromDirectoryHandle(directory, directory.name || "");
+        addSelectedFiles(files, { source: "folder" });
+      } catch (error) {
+        if (!error || error.name !== "AbortError") {
+          updateStatus("Folder could not be read.");
+        }
+      }
+    });
+  }
+
   form.addEventListener("submit", async (event) => {
     event.preventDefault();
     if (selectedFiles.length === 0) {
       updateStatus("Choose at least one file first.");
+      notify("warning", "Choose at least one file first.", {
+        title: "No files selected",
+      });
       return;
     }
+    if (!validateSelectedFilesWithinLimit(selectedFiles)) {
+      return;
+    }
+    if (isSlowOrMeteredConnection() && totalSelectedBytes(selectedFiles) >= CELLULAR_WARNING_THRESHOLD_BYTES) {
+      const proceed = await confirmCellularUpload(selectedFiles);
+      if (!proceed) {
+        return;
+      }
+    }
 
     const submit = form.querySelector("button[type='submit']");
     const formData = uploadFormData();
+    await maybeRequestUploadNotificationPermission(selectedFiles);
     if (resumeMode && recoveredDraft) {
       renderResumeQueue(recoveredDraft.session, selectedFiles);
     } else {
@@ -108,8 +158,11 @@
     try {
       const payload = await uploadResumable(form.action, formData, selectedFiles);
       renderResult(payload);
+      showUploadNotification("Warpbox upload complete", `${payload.files.length} file${payload.files.length === 1 ? "" : "s"} uploaded.`, payload.boxUrl);
+      await clearSharedTargetPayload();
       form.reset();
       selectedFiles = [];
+      sharedTargetDraft = null;
       resumeMode = false;
       recoveredDraft = null;
       fileInput.value = "";
@@ -123,6 +176,8 @@
       }
     } catch (error) {
       updateStatus(error.message || "Upload failed");
+      notifyUploadError(error);
+      showUploadNotification("Warpbox upload failed", error.message || "Upload failed");
     } finally {
       setLoading(false, submit);
     }
@@ -136,26 +191,388 @@
 
   if (newUpload) {
     newUpload.addEventListener("click", () => {
+      if (sharedTargetDraft) {
+        clearSharedTargetPayload().finally(() => resetFreshUploadState());
+        return;
+      }
       cancelRecoveredDraft().catch((error) => {
         updateStatus(error.message || "Upload draft could not be deleted");
       });
     });
   }
 
+  if (isShareTargetLaunch()) {
+    loadSharedTargetFiles();
+  } else {
     recoverResumableSessions();
+  }
 
-  function addSelectedFiles(files) {
+  function addSelectedFiles(files, options) {
     if (uploadLocked) {
       return;
     }
+    const rejected = [];
     Array.from(files || []).forEach((file) => {
+      if (fileExceedsUploadLimit(file)) {
+        rejected.push(file);
+        return;
+      }
       if (!selectedFiles.some((existing) => fileIdentity(existing) === fileIdentity(file))) {
         selectedFiles.push(file);
       }
     });
+    if (rejected.length > 0) {
+      notifyRejectedFiles(rejected);
+    }
+    if (options && options.source === "pasted" && files && files.length > 0) {
+      updateStatus(`${files.length} pasted file${files.length === 1 ? "" : "s"} ready.`);
+    }
+    if (options && options.source === "folder" && files && files.length > 0) {
+      updateStatus(`${files.length} folder file${files.length === 1 ? "" : "s"} ready.`);
+    }
     updateSelectedState();
   }
 
+  async function addDroppedFiles(dataTransfer) {
+    if (uploadLocked) {
+      return;
+    }
+    const files = await filesFromDataTransfer(dataTransfer);
+    addSelectedFiles(files, { source: hasDirectoryItems(dataTransfer) ? "folder" : "dropped" });
+  }
+
+  async function filesFromDataTransfer(dataTransfer) {
+    const items = Array.from(dataTransfer.items || []);
+    const entries = items
+      .map((item) => typeof item.webkitGetAsEntry === "function" ? item.webkitGetAsEntry() : null)
+      .filter(Boolean);
+    if (entries.length === 0) {
+      return Array.from(dataTransfer.files || []);
+    }
+    const nested = await Promise.all(entries.map((entry) => filesFromEntry(entry, "")));
+    return nested.flat();
+  }
+
+  function hasDirectoryItems(dataTransfer) {
+    return Array.from(dataTransfer.items || []).some((item) => {
+      const entry = typeof item.webkitGetAsEntry === "function" ? item.webkitGetAsEntry() : null;
+      return entry && entry.isDirectory;
+    });
+  }
+
+  function hasTransferFiles(dataTransfer) {
+    if (!dataTransfer) {
+      return false;
+    }
+    if (dataTransfer.files && dataTransfer.files.length > 0) {
+      return true;
+    }
+    return Array.from(dataTransfer.items || []).some((item) => item.kind === "file");
+  }
+
+  function filesFromEntry(entry, parentPath) {
+    if (!entry) {
+      return Promise.resolve([]);
+    }
+    const relativePath = parentPath ? `${parentPath}/${entry.name}` : entry.name;
+    if (entry.isFile) {
+      return new Promise((resolve) => {
+        entry.file((file) => resolve([withRelativePath(file, relativePath)]), () => resolve([]));
+      });
+    }
+    if (!entry.isDirectory) {
+      return Promise.resolve([]);
+    }
+    const reader = entry.createReader();
+    const children = [];
+    return new Promise((resolve) => {
+      const readBatch = () => {
+        reader.readEntries(async (entries) => {
+          if (!entries.length) {
+            const nested = await Promise.all(children.map((child) => filesFromEntry(child, relativePath)));
+            resolve(nested.flat());
+            return;
+          }
+          children.push(...entries);
+          readBatch();
+        }, () => resolve([]));
+      };
+      readBatch();
+    });
+  }
+
+  async function filesFromDirectoryHandle(directory, parentPath) {
+    const files = [];
+    for await (const [name, handle] of directory.entries()) {
+      const relativePath = parentPath ? `${parentPath}/${name}` : name;
+      if (handle.kind === "file") {
+        const file = await handle.getFile();
+        files.push(withRelativePath(file, relativePath));
+      } else if (handle.kind === "directory") {
+        files.push(...await filesFromDirectoryHandle(handle, relativePath));
+      }
+    }
+    return files;
+  }
+
+  function withRelativePath(file, relativePath) {
+    if (!file || !relativePath) {
+      return file;
+    }
+    try {
+      Object.defineProperty(file, "warpboxRelativePath", {
+        value: normalizeRelativePath(relativePath),
+        configurable: true,
+      });
+    } catch (error) {
+      file.warpboxRelativePath = normalizeRelativePath(relativePath);
+    }
+    return file;
+  }
+
+  function normalizeRelativePath(value) {
+    return String(value || "")
+      .replace(/\\/g, "/")
+      .split("/")
+      .filter((part) => part && part !== "." && part !== "..")
+      .join("/");
+  }
+
+  function uploadName(file) {
+    return normalizeRelativePath(file && (file.warpboxRelativePath || file.webkitRelativePath || file.name)) || (file && file.name) || "file";
+  }
+
+  function isTextEditingTarget(target) {
+    if (!target) {
+      return false;
+    }
+    const tag = (target.tagName || "").toLowerCase();
+    return tag === "input" || tag === "textarea" || target.isContentEditable;
+  }
+
+  function fileExceedsUploadLimit(file) {
+    return Number.isFinite(maxUploadBytes) && maxUploadBytes > 0 && file && file.size > maxUploadBytes;
+  }
+
+  function validateSelectedFilesWithinLimit(files) {
+    const rejected = Array.from(files || []).filter(fileExceedsUploadLimit);
+    if (rejected.length === 0) {
+      return true;
+    }
+    selectedFiles = selectedFiles.filter((file) => !fileExceedsUploadLimit(file));
+    notifyRejectedFiles(rejected);
+    updateSelectedState();
+    return false;
+  }
+
+  function notifyRejectedFiles(files) {
+    const names = files.slice(0, 3).map((file) => `"${file.name}" (${window.Warpbox.formatBytes(file.size)})`).join(", ");
+    const extra = files.length > 3 ? `, and ${files.length - 3} more` : "";
+    const message = `${names}${extra} ${files.length === 1 ? "is" : "are"} over the ${maxUploadLabel} upload limit.`;
+    updateStatus(message);
+    notify("error", message, {
+      title: "Upload limit exceeded",
+      duration: 9000,
+    });
+  }
+
+  function notifyUploadError(error) {
+    const message = error && error.message ? error.message : "Upload failed";
+    const lower = message.toLowerCase();
+    const isLimit = lower.includes("limit") || lower.includes("quota") || lower.includes("too large") || lower.includes("exceeds");
+    notify("error", message, {
+      title: isLimit ? "Upload limit reached" : "Upload failed",
+      duration: isLimit ? 9000 : 7200,
+    });
+  }
+
+  async function maybeRequestUploadNotificationPermission(files) {
+    if (!("Notification" in window) || Notification.permission !== "default" || totalSelectedBytes(files) < CELLULAR_WARNING_THRESHOLD_BYTES) {
+      return;
+    }
+    try {
+      await Notification.requestPermission();
+    } catch (error) {
+      /* notification permission is optional */
+    }
+  }
+
+  async function showUploadNotification(title, body, url) {
+    if (!("Notification" in window) || Notification.permission !== "granted") {
+      return;
+    }
+    if (document.visibilityState === "visible") {
+      return;
+    }
+    const options = {
+      body,
+      icon: "/static/android-chrome-192x192.png",
+      badge: "/static/favicon-32x32.png",
+      data: { url: window.Warpbox.absoluteURL(url || "/") },
+    };
+    try {
+      const registration = navigator.serviceWorker ? await navigator.serviceWorker.ready : null;
+      if (registration && registration.showNotification) {
+        await registration.showNotification(title, options);
+        return;
+      }
+    } catch (error) {
+      /* fall through to page notification */
+    }
+    try {
+      const notification = new Notification(title, options);
+      notification.onclick = () => {
+        window.focus();
+        if (url) {
+          window.location.href = window.Warpbox.absoluteURL(url);
+        }
+        notification.close();
+      };
+    } catch (error) {
+      /* notifications are best-effort */
+    }
+  }
+
+  function notify(variant, message, options) {
+    if (window.Warpbox && typeof window.Warpbox.notify === "function") {
+      window.Warpbox.notify({ ...(options || {}), variant, message });
+    }
+  }
+
+  function isSlowOrMeteredConnection() {
+    const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+    if (!connection) {
+      return false;
+    }
+    if (connection.saveData === true) {
+      return true;
+    }
+    return ["slow-2g", "2g", "3g"].includes(connection.effectiveType);
+  }
+
+  function totalSelectedBytes(files) {
+    return files.reduce((sum, file) => sum + file.size, 0);
+  }
+
+  function confirmCellularUpload(files) {
+    const list = document.createElement("div");
+    list.className = "dialog-file-list";
+    files.forEach((file) => {
+      const icon = document.createElement("span");
+      icon.className = "svg-icon svg-icon-document dialog-file-icon";
+      icon.setAttribute("aria-hidden", "true");
+
+      const name = document.createElement("span");
+      name.className = "dialog-file-name";
+      name.textContent = file.name;
+      name.title = file.name;
+
+      const size = document.createElement("span");
+      size.className = "dialog-file-size";
+      size.textContent = window.Warpbox.formatBytes(file.size);
+
+      const row = document.createElement("div");
+      row.className = "dialog-file-row";
+      row.append(icon, name, size);
+      list.append(row);
+    });
+
+    const totalLabel = window.Warpbox.formatBytes(totalSelectedBytes(files));
+    const message = `You're on a slow or metered connection. You're about to upload ${files.length} file${files.length === 1 ? "" : "s"} (${totalLabel} total) — this could take a while or use up your data plan.`;
+
+    return window.Warpbox.confirmDialog(message, {
+      title: "Slow connection detected",
+      variant: "warning",
+      body: list,
+      confirmLabel: "Upload anyway",
+      cancelLabel: "Cancel",
+    });
+  }
+
+  function isShareTargetLaunch() {
+    const params = new URLSearchParams(window.location.search || "");
+    return params.has("share-target");
+  }
+
+  async function loadSharedTargetFiles() {
+    if (!("caches" in window) || typeof File === "undefined") {
+      updateStatus("Shared files could not be loaded in this browser.");
+      recoverResumableSessions();
+      return;
+    }
+    updateStatus("Loading shared files...");
+    try {
+      const cache = await caches.open(SHARE_CACHE);
+      const metadataResponse = await cache.match(SHARE_LATEST_KEY);
+      if (!metadataResponse) {
+        updateStatus(new URLSearchParams(window.location.search).get("share-target") === "unsupported"
+          ? "Install Warpbox as an app to share files into it from your device."
+          : "No shared files were found.");
+        recoverResumableSessions();
+        return;
+      }
+      const metadata = await metadataResponse.json();
+      if (metadata.error) {
+        updateStatus(metadata.error);
+        recoverResumableSessions();
+        return;
+      }
+      const files = [];
+      for (const item of metadata.files || []) {
+        if (!item.key) {
+          continue;
+        }
+        const response = await cache.match(item.key);
+        if (!response) {
+          continue;
+        }
+        const blob = await response.blob();
+        files.push(new File([blob], item.name || "shared-file", {
+          type: item.type || blob.type || "application/octet-stream",
+          lastModified: item.lastModified || Date.now(),
+        }));
+      }
+      sharedTargetDraft = metadata;
+      selectedFiles = files;
+      resumeMode = false;
+      recoveredDraft = null;
+      validateSelectedFilesWithinLimit(selectedFiles);
+      if (selectedFiles.length > 0) {
+        renderQueue(selectedFiles, "queued", { shared: true });
+        updateStatus("Shared files ready.");
+      } else {
+        updateStatus("No files were included in this share.");
+      }
+      updateSelectedState();
+    } catch (error) {
+      updateStatus(error.message || "Shared files could not be loaded.");
+      recoverResumableSessions();
+    }
+  }
+
+  async function clearSharedTargetPayload() {
+    const draft = sharedTargetDraft;
+    sharedTargetDraft = null;
+    if (!draft || !("caches" in window)) {
+      sharedTargetDraft = null;
+      return;
+    }
+    try {
+      const cache = await caches.open(SHARE_CACHE);
+      for (const item of draft.files || []) {
+        if (item.key) {
+          await cache.delete(item.key);
+        }
+      }
+      if (draft.id) {
+        await cache.delete("/__warpbox_share_target__/meta/" + encodeURIComponent(draft.id));
+      }
+      await cache.delete(SHARE_LATEST_KEY);
+    } catch (error) {
+      /* ignore cache cleanup failures */
+    }
+  }
+
   function removeSelectedFile(index) {
     if (uploadLocked) {
       return;
@@ -175,12 +592,18 @@
         fileSummary.textContent = count === 0
           ? "Reselect missing files to resume, or add extra files to this upload."
           : `${count} local file${count === 1 ? "" : "s"} ready for the recovered upload.`;
+      } else if (sharedTargetDraft) {
+        fileSummary.textContent = count === 0
+          ? "No shared files were received."
+          : `${count} shared file${count === 1 ? "" : "s"} ready. Review options, then upload.`;
       } else {
         fileSummary.textContent = count === 0 ? "Choose one or more files to begin." : `${count} file${count === 1 ? "" : "s"} ready.`;
       }
     }
     if (resumeMode && recoveredDraft) {
       renderResumeQueue(recoveredDraft.session, selectedFiles);
+    } else if (sharedTargetDraft && count > 0) {
+      renderQueue(selectedFiles, "queued", { shared: true });
     } else if (count > 0) {
       renderQueue(selectedFiles, "queued");
     } else if (uploadQueue) {
@@ -194,7 +617,7 @@
     if (!newUpload) {
       return;
     }
-    const visible = Boolean(resumeMode && recoveredDraft);
+    const visible = Boolean((resumeMode && recoveredDraft) || sharedTargetDraft);
     newUpload.hidden = !visible;
     newUpload.style.display = visible ? "" : "none";
   }
@@ -336,7 +759,7 @@
     const fingerprints = await Promise.all(files.map((file) => fileFingerprint(file)));
     const createPayload = {
       files: files.map((file, index) => ({
-        name: file.name,
+        name: uploadName(file),
         size: file.size,
         contentType: file.type || "application/octet-stream",
         fingerprint: fingerprints[index],
@@ -803,6 +1226,7 @@
     selectedFiles = [];
     resumeMode = false;
     recoveredDraft = null;
+    sharedTargetDraft = null;
     fileInput.value = "";
     result.hidden = true;
     if (resultList) {
@@ -862,7 +1286,7 @@
     const rows = [];
     const localByNameSize = new Map();
     (localFiles || []).forEach((file, index) => {
-      localByNameSize.set(`${file.name}:${file.size}`, { file, index });
+      localByNameSize.set(`${uploadName(file)}:${file.size}`, { file, index });
     });
     const usedLocalIndexes = new Set();
     (session.files || []).forEach((file) => {
@@ -873,7 +1297,7 @@
         usedLocalIndexes.add(localMatch.index);
       }
       rows.push({
-        name: file.name,
+        name: uploadName(file),
         size: file.size,
         uploadedBytes,
         meta: complete
@@ -893,7 +1317,7 @@
         return;
       }
       rows.push({
-        name: file.name,
+        name: uploadName(file),
         meta: `${window.Warpbox.formatBytes(file.size)} · new file`,
         progress: 0,
         status: "queued",
@@ -913,20 +1337,22 @@
     return Math.max(0, Math.min(100, Math.round((bytes / total) * 100)));
   }
 
-  function renderQueue(files, status) {
+  function renderQueue(files, status, options) {
     if (!uploadQueue) {
       return;
     }
+    const shared = Boolean(options && options.shared);
     uploadQueue.hidden = files.length === 0;
     uploadQueue.replaceChildren();
     files.forEach((file, index) => {
       uploadQueue.append(createFileRow({
-        name: file.name,
-        meta: window.Warpbox.formatBytes(file.size),
+        name: uploadName(file),
+        meta: shared ? `${window.Warpbox.formatBytes(file.size)} · Shared from device` : window.Warpbox.formatBytes(file.size),
         progress: status === "queued" ? 0 : 100,
         status,
         index,
         removable: status === "queued",
+        shared,
       }));
     });
   }
@@ -965,6 +1391,12 @@
       badge.textContent = "Needs local file";
       side.append(badge);
     }
+    if (file.shared) {
+      const badge = document.createElement("small");
+      badge.className = "upload-file-state upload-file-state-shared";
+      badge.textContent = "Shared from device";
+      side.append(badge);
+    }
     if (file.removable) {
       const remove = document.createElement("button");
       remove.className = "upload-file-remove";
@@ -982,14 +1414,16 @@
   function uploadFormData() {
     const formData = new FormData(form);
     formData.delete("file");
+    formData.delete("file_path");
     selectedFiles.forEach((file) => {
-      formData.append("file", file, file.name);
+      formData.append("file", file, uploadName(file));
+      formData.append("file_path", uploadName(file));
     });
     return formData;
   }
 
   function fileIdentity(file) {
-    return [file.name, file.size, file.lastModified || 0].join(":");
+    return [uploadName(file), file.size, file.lastModified || 0].join(":");
   }
 
   async function fileFingerprint(file) {
@@ -998,7 +1432,7 @@
     }
     const sampleSize = Math.min(file.size, 1024 * 1024);
     const sample = await file.slice(0, sampleSize).arrayBuffer();
-    const metadata = new TextEncoder().encode([file.name, file.size, file.lastModified || 0, sampleSize].join(":"));
+    const metadata = new TextEncoder().encode([uploadName(file), file.size, file.lastModified || 0, sampleSize].join(":"));
     const combined = new Uint8Array(metadata.byteLength + sample.byteLength);
     combined.set(metadata, 0);
     combined.set(new Uint8Array(sample), metadata.byteLength);

backend/static/js/45-preview.js

@@ -66,6 +66,7 @@
   bindLargeGate();
   bindThemeChanges();
   bindRenderFullscreen();
+  configureMediaSession();
   renderTabs();
   selectMode(state.defaultMode);
 
@@ -301,6 +302,32 @@
     document.addEventListener("fullscreenchange", updateRenderFullscreenButton);
   }
 
+  function configureMediaSession() {
+    if (!("mediaSession" in navigator) || typeof window.MediaMetadata !== "function") {
+      return;
+    }
+    if (!fileType.isAudio && !fileType.isVideo) {
+      return;
+    }
+    var artworkURL = "";
+    if (fileType.isVideo && els.videoPane) {
+      artworkURL = els.videoPane.getAttribute("poster") || state.iconURL || "";
+    } else {
+      artworkURL = state.iconURL || "";
+    }
+    var metadata = {
+      title: state.fileName || "Warpbox media",
+      artist: "Warpbox",
+      album: state.sizeLabel || state.contentType || ""
+    };
+    if (artworkURL) {
+      metadata.artwork = [
+        { src: window.Warpbox.absoluteURL(artworkURL), sizes: "512x512", type: "image/png" }
+      ];
+    }
+    navigator.mediaSession.metadata = new MediaMetadata(metadata);
+  }
+
   function ensureTextLoaded() {
     if (state.textLoaded) {
       return Promise.resolve(state.textSource);

backend/static/js/48-api-docs.js

@@ -0,0 +1,94 @@
+(function () {
+  const root = document.querySelector("[data-api-docs]");
+  if (!root) {
+    return;
+  }
+
+  const panels = Array.from(root.querySelectorAll("[data-doc-panel]"));
+  const navLinks = Array.from(root.querySelectorAll("[data-doc-link]"));
+  const DEFAULT = "home";
+
+  function activate(name, focus) {
+    let matched = false;
+    panels.forEach((panel) => {
+      const on = panel.dataset.docPanel === name;
+      panel.classList.toggle("is-active", on);
+      if (on) {
+        matched = true;
+      }
+    });
+    if (!matched) {
+      return false;
+    }
+    root.querySelectorAll(".api-nav-link").forEach((link) => {
+      link.classList.toggle(
+        "is-active",
+        link.getAttribute("href") === "#" + name
+      );
+    });
+    if (focus) {
+      const panel = root.querySelector('[data-doc-panel="' + name + '"]');
+      if (panel) {
+        panel.focus({ preventScroll: true });
+      }
+    }
+    return true;
+  }
+
+  // Resolve the current hash to a panel. The hash can point at a panel id
+  // (e.g. #endpoints) or at any element inside a panel (e.g. #ep-upload),
+  // letting FAQ answers deep-link straight into the reference.
+  function resolveHash(focus) {
+    const id = (location.hash || "").slice(1);
+    if (!id) {
+      activate(DEFAULT, focus);
+      return;
+    }
+    const target = document.getElementById(id);
+    if (!target) {
+      activate(DEFAULT, focus);
+      return;
+    }
+    const panel = target.closest("[data-doc-panel]");
+    const name = panel ? panel.dataset.docPanel : DEFAULT;
+    activate(name, focus && target === panel);
+    if (panel && target !== panel) {
+      // Scroll the deep-linked element into view once its panel is visible.
+      window.requestAnimationFrame(() => {
+        target.scrollIntoView({ block: "start", behavior: "smooth" });
+      });
+    } else {
+      window.scrollTo({ top: 0, behavior: "smooth" });
+    }
+  }
+
+  window.addEventListener("hashchange", () => resolveHash(true));
+
+  navLinks.forEach((link) => {
+    link.addEventListener("click", () => {
+      // hashchange handles activation; this keeps top-level nav clicks snappy.
+      if (link.getAttribute("href") === location.hash) {
+        resolveHash(true);
+      }
+    });
+  });
+
+  // Add a copy button to every code block.
+  root.querySelectorAll(".code-block").forEach((block) => {
+    const pre = block.querySelector("pre");
+    if (!pre) {
+      return;
+    }
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "copy-btn";
+    button.textContent = "Copy";
+    button.setAttribute("aria-label", "Copy code");
+    button.addEventListener("click", () => {
+      window.Warpbox.copyText(pre.innerText.trim(), button, "Copied");
+    });
+    block.appendChild(button);
+  });
+
+  resolveHash(false);
+})();

backend/static/js/service-worker.js

@@ -0,0 +1,130 @@
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  if (event.request.method === "POST" && url.origin === self.location.origin && url.pathname === "/share-target") {
+    event.respondWith(handleShareTarget(event.request));
+  }
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const url = event.notification.data && event.notification.data.url ? event.notification.data.url : "/";
+  event.waitUntil((async () => {
+    const windows = await clients.matchAll({ type: "window", includeUncontrolled: true });
+    for (const client of windows) {
+      if ("focus" in client) {
+        await client.focus();
+        if ("navigate" in client) {
+          await client.navigate(url);
+        }
+        return;
+      }
+    }
+    if (clients.openWindow) {
+      await clients.openWindow(url);
+    }
+  })());
+});
+
+const SHARE_CACHE = "warpbox-share-target-v1";
+const SHARE_PREFIX = "/__warpbox_share_target__/";
+const LATEST_KEY = SHARE_PREFIX + "latest";
+
+async function handleShareTarget(request) {
+  const id = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 10);
+  try {
+    const formData = await request.formData();
+    const files = collectSharedFiles(formData);
+    const cache = await caches.open(SHARE_CACHE);
+    const metadata = {
+      id,
+      title: stringValue(formData.get("title")),
+      text: stringValue(formData.get("text")),
+      url: stringValue(formData.get("url")),
+      createdAt: new Date().toISOString(),
+      files: [],
+    };
+
+    await deletePreviousShare(cache);
+    for (let index = 0; index < files.length; index += 1) {
+      const file = files[index];
+      const key = SHARE_PREFIX + "file/" + encodeURIComponent(id) + "/" + index;
+      metadata.files.push({
+        key,
+        name: file.name || "shared-file",
+        type: file.type || "application/octet-stream",
+        size: file.size || 0,
+        lastModified: file.lastModified || Date.now(),
+      });
+      await cache.put(key, new Response(file, {
+        headers: {
+          "Content-Type": file.type || "application/octet-stream",
+          "Cache-Control": "no-store",
+        },
+      }));
+    }
+
+    await cache.put(LATEST_KEY, jsonResponse(metadata));
+    await cache.put(SHARE_PREFIX + "meta/" + encodeURIComponent(id), jsonResponse(metadata));
+  } catch (error) {
+    await storeShareError(id, error);
+  }
+
+  return Response.redirect("/?share-target=1&share-id=" + encodeURIComponent(id), 303);
+}
+
+function collectSharedFiles(formData) {
+  const files = [];
+  ["files", "file", "sharex"].forEach((name) => {
+    formData.getAll(name).forEach((value) => {
+      if (value instanceof File && value.size > 0) {
+        files.push(value);
+      }
+    });
+  });
+  return files;
+}
+
+function stringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function jsonResponse(payload) {
+  return new Response(JSON.stringify(payload), {
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+async function storeShareError(id, error) {
+  const cache = await caches.open(SHARE_CACHE);
+  await cache.put(LATEST_KEY, jsonResponse({
+    id,
+    error: error && error.message ? error.message : "Shared files could not be staged.",
+    createdAt: new Date().toISOString(),
+    files: [],
+  }));
+}
+
+async function deletePreviousShare(cache) {
+  const previous = await cache.match(LATEST_KEY);
+  if (!previous) {
+    return;
+  }
+  let metadata = null;
+  try {
+    metadata = await previous.json();
+  } catch (error) {
+    metadata = null;
+  }
+  for (const file of metadata && metadata.files ? metadata.files : []) {
+    if (file.key) {
+      await cache.delete(file.key);
+    }
+  }
+  if (metadata && metadata.id) {
+    await cache.delete(SHARE_PREFIX + "meta/" + encodeURIComponent(metadata.id));
+  }
+  await cache.delete(LATEST_KEY);
+}

backend/static/site.webmanifest

@@ -7,6 +7,22 @@
   "display": "standalone",
   "background_color": "#0b0b16",
   "theme_color": "#8b5cf6",
+  "share_target": {
+    "action": "/share-target",
+    "method": "POST",
+    "enctype": "multipart/form-data",
+    "params": {
+      "title": "title",
+      "text": "text",
+      "url": "url",
+      "files": [
+        {
+          "name": "files",
+          "accept": ["*/*"]
+        }
+      ]
+    }
+  },
   "icons": [
     {
       "src": "/static/android-chrome-192x192.png",

backend/templates/layouts/base.html

@@ -4,7 +4,7 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>{{if .Title}}{{.Title}} — {{end}}{{.AppName}}</title>
+  <title>{{if .Title}}{{.Title}} | {{end}}{{.AppName}}</title>
   <meta name="description" content="{{.Description}}">
   {{if .CanonicalURL}}<link rel="canonical" href="{{.CanonicalURL}}">{{end}}
   <meta name="robots" content="{{if .Robots}}{{.Robots}}{{else}}index,follow{{end}}">
@@ -54,11 +54,13 @@
 
   <script src="/static/js/05-theme.js?version={{.AppVersion}}"></script>
   <link rel="stylesheet" href="/static/css/00-base.css?version={{.AppVersion}}">
+  <link rel="stylesheet" href="/static/css/04-dialogs.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/10-layout.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/15-revamp.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/16-retro.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/17-gruvbox.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/18-cyberpunk.css?version={{.AppVersion}}">
+  <link rel="stylesheet" href="/static/css/19-popups.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/20-upload.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/30-download.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/40-docs.css?version={{.AppVersion}}">
@@ -67,14 +69,19 @@
   <link rel="stylesheet" href="/static/css/70-tokens.css?version={{.AppVersion}}">
   <link rel="stylesheet" href="/static/css/90-responsive.css?version={{.AppVersion}}">
   <script defer src="/static/js/00-utils.js?version={{.AppVersion}}"></script>
+  <script defer src="/static/js/02-pwa.js?version={{.AppVersion}}"></script>
+  <script defer src="/static/js/03-popups.js?version={{.AppVersion}}"></script>
+  <script defer src="/static/js/04-dialogs.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/10-file-browser.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/12-reactions.js?version={{.AppVersion}}"></script>
+  <script defer src="/static/js/13-share.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/20-storage-admin.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/25-admin-charts.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/30-token-copy.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/35-pagination.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/40-upload.js?version={{.AppVersion}}"></script>
   <script defer src="/static/js/45-preview.js?version={{.AppVersion}}"></script>
+  <script defer src="/static/js/48-api-docs.js?version={{.AppVersion}}"></script>
 </head>
 <body class="dark">
   <a class="skip-link" href="#main">Skip to content</a>

backend/templates/pages/api.html

@@ -1,68 +1,131 @@
 {{define "api.html"}}{{template "base" .}}{{end}}
 
 {{define "content"}}
-<section class="docs-view" aria-labelledby="api-title">
-  <div class="docs-header">
+<section class="api-docs" aria-labelledby="api-title" data-api-docs>
+  <aside class="api-sidebar">
     <p class="kicker">Developer docs</p>
-    <h1 id="api-title">Warpbox API</h1>
-    <p>Anonymous uploads for curl, scripts, and ShareX. The upload endpoint accepts multipart files and returns either plain text or JSON based on the <code>Accept</code> header.</p>
+    <h1 id="api-title" class="api-sidebar-title">Warpbox API</h1>
+    <nav class="api-nav" aria-label="Documentation sections">
+      <a class="api-nav-link" href="#home" data-doc-link>Home</a>
+      <a class="api-nav-link" href="#endpoints" data-doc-link>Endpoints</a>
+      <a class="api-nav-link" href="#cli" data-doc-link>CLI / Binary</a>
+      <a class="api-nav-link" href="#integrations" data-doc-link>Integrations</a>
+      <a class="api-nav-link" href="#examples" data-doc-link>Examples</a>
+      <a class="api-nav-link" href="#faq" data-doc-link>FAQ</a>
+    </nav>
+    <div class="api-sidebar-meta">
+      <a href="{{.Data.RequestSchemaURL}}">Request schema</a>
+      <a href="{{.Data.ResponseSchemaURL}}">Response schema</a>
+    </div>
+  </aside>
+
+  <div class="api-content">
+
+    <!-- ===================== HOME ===================== -->
+    <section id="home" class="doc-panel" data-doc-panel="home" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Get started</p>
+        <h2>Upload files anywhere, from anything</h2>
+        <p class="lead">Warpbox is a one endpoint upload API. Send a multipart file with <code>curl</code>, a script, ShareX, or the <code>warpbox</code> CLI and get back a shareable box link. Request JSON to also receive private manage and delete URLs.</p>
+      </header>
+
+      <div class="shortcut-grid">
+        <a class="shortcut-card accent-blue" href="#examples" data-doc-link>
+          <span class="shortcut-eyebrow">60-second start</span>
+          <span class="shortcut-title">Copy-paste examples</span>
+          <span class="shortcut-sub">curl, wget, HTTPie, Python &amp; more</span>
+        </a>
+        <a class="shortcut-card accent-green" href="#cli" data-doc-link>
+          <span class="shortcut-eyebrow">Terminal</span>
+          <span class="shortcut-title">Install the CLI</span>
+          <span class="shortcut-sub">One command for macOS, Linux &amp; Windows</span>
+        </a>
+        <a class="shortcut-card accent-violet" href="#endpoints" data-doc-link>
+          <span class="shortcut-eyebrow">Reference</span>
+          <span class="shortcut-title">All endpoints</span>
+          <span class="shortcut-sub">Payloads, responses &amp; status codes</span>
+        </a>
+        <a class="shortcut-card accent-amber" href="#integrations" data-doc-link>
+          <span class="shortcut-eyebrow">Screenshots</span>
+          <span class="shortcut-title">ShareX integration</span>
+          <span class="shortcut-sub">Import once, upload as your account</span>
+        </a>
       </div>
 
-  <div class="docs-grid">
-    <article class="card docs-card">
+      <div class="quickstart card">
         <div class="card-content">
-        <h2>Endpoints</h2>
-        <dl class="endpoint-list">
-          <div><dt>Upload</dt><dd><code>POST /api/v1/upload</code></dd></div>
-          <div><dt>Resumable create</dt><dd><code>POST /api/v1/uploads/resumable</code></dd></div>
-          <div><dt>Resumable status</dt><dd><code>GET /api/v1/uploads/resumable/{sessionID}</code></dd></div>
-          <div><dt>Resumable chunk</dt><dd><code>PUT /api/v1/uploads/resumable/{sessionID}/files/{fileID}/chunks/{index}</code></dd></div>
-          <div><dt>Resumable complete</dt><dd><code>POST /api/v1/uploads/resumable/{sessionID}/complete</code></dd></div>
-          <div><dt>Health</dt><dd><code>GET /health</code></dd></div>
-          <div><dt>Request schema</dt><dd><a href="/api/v1/schemas/upload-request.json"><code>/api/v1/schemas/upload-request.json</code></a></dd></div>
-          <div><dt>Response schema</dt><dd><a href="/api/v1/schemas/upload-response.json"><code>/api/v1/schemas/upload-response.json</code></a></dd></div>
-        </dl>
-      </div>
-    </article>
-
-    <article class="card docs-card docs-card-wide">
-      <div class="card-content">
-        <h2>Resumable uploads</h2>
-        <p>Browser uploads use the resumable API by default. Custom clients can use the same flow: create a session with file metadata, upload exact-sized chunks, then complete the session. Chunks are temporary and are cleaned if the session expires.</p>
-        <pre><code># 1. Create a session.
-curl -s {{.Data.BaseURL}}/api/v1/uploads/resumable \
-  -H 'Accept: application/json' \
-  -H 'Content-Type: application/json' \
-  -d '{"files":[{"name":"report.pdf","size":1048576,"contentType":"application/pdf"}],"expiresMinutes":1440}'
-
-# 2. Upload each chunk using the returned sessionId, file id, and chunkSize.
-dd if=./report.pdf bs=8388608 count=1 skip=0 2>/dev/null | \
-  curl -X PUT --data-binary @- \
-  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/files/FILE_ID/chunks/0
-
-# 3. Complete after all chunks are present. The response is the normal upload JSON.
-curl -X POST -H 'Accept: application/json' \
-  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/complete</code></pre>
-        <p class="muted-copy">For authenticated uploads, send the same <code>Authorization: Bearer &lt;token&gt;</code> header on every resumable request. Incomplete chunks are stored under <code>data/tmp/uploads</code> before finalizing into the selected storage backend.</p>
-      </div>
-    </article>
-
-    <article class="card docs-card">
-      <div class="card-content">
-        <h2>Curl upload</h2>
-        <p>Without a JSON <code>Accept</code> header, Warpbox prints one plain box URL for shell-friendly usage.</p>
+          <h3>Your first upload</h3>
+          <p>No account required. This prints one plain box URL you can share immediately.</p>
+          <figure class="code-block">
             <pre><code>curl -F file=@./report.pdf {{.Data.UploadURL}}</code></pre>
-        <p>For automation, request JSON to get file URLs and the private manage/delete URLs.</p>
+          </figure>
+          <p class="muted-copy">Want file URLs, a manage link, and a delete link back? Add <code>-H 'Accept: application/json'</code>. See <a href="#responses" data-doc-link>the JSON response</a>.</p>
+        </div>
+      </div>
+
+      <h3 class="section-label">Quick links</h3>
+      <div class="link-grid">
+        <a class="link-pill" href="#ep-upload" data-doc-link><span class="link-tag tag-post">POST</span> Upload endpoint</a>
+        <a class="link-pill" href="/static/api/warpbox.sh" download><span class="link-tag tag-get">GET</span> warpbox.sh (macOS/Linux)</a>
+        <a class="link-pill" href="/static/api/warpbox.ps1" download><span class="link-tag tag-get">GET</span> warpbox.ps1 (Windows)</a>
+        <a class="link-pill" href="{{.Data.ShareXDownloadURL}}" download><span class="link-tag tag-get">GET</span> ShareX .sxcu config</a>
+        <a class="link-pill" href="{{.Data.RequestSchemaURL}}"><span class="link-tag tag-json">JSON</span> Request schema</a>
+        <a class="link-pill" href="{{.Data.ResponseSchemaURL}}"><span class="link-tag tag-json">JSON</span> Response schema</a>
+        <a class="link-pill" href="/account/settings"><span class="link-tag tag-key">KEY</span> Create an API token</a>
+        <a class="link-pill" href="#faq" data-doc-link><span class="link-tag tag-help">?</span> FAQ &amp; troubleshooting</a>
+      </div>
+    </section>
+
+    <!-- ===================== ENDPOINTS ===================== -->
+    <section id="endpoints" class="doc-panel" data-doc-panel="endpoints" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Reference</p>
+        <h2>Endpoints</h2>
+        <p class="lead">Base URL <code>{{.Data.BaseURL}}</code>. Authentication is optional: send <code>Authorization: Bearer &lt;token&gt;</code> to upload as your account and use your account limits, or omit it to upload anonymously.</p>
+      </header>
+
+      <article id="ep-upload" class="endpoint card">
+        <div class="card-content">
+          <div class="endpoint-head">
+            <span class="method method-post">POST</span>
+            <code class="endpoint-path">/api/v1/upload</code>
+          </div>
+          <p>The core endpoint. Accepts a <code>multipart/form-data</code> body with one or more files. Returns a plain box URL by default, or the full JSON object when you send <code>Accept: application/json</code>.</p>
+
+          <h4>Request fields</h4>
+          <div class="field-grid">
+            <span><code>file</code></span><p>One or more files. Repeat the field for multiple files. Used by curl, browsers, and the CLI.</p>
+            <span><code>sharex</code></span><p>Alternative file field used by ShareX custom uploader configs. Same behaviour as <code>file</code>.</p>
+            <span><code>max_days</code></span><p>Optional. Days before the box expires. Defaults to 7.</p>
+            <span><code>expires_minutes</code></span><p>Optional. Lifetime in minutes. Takes precedence over <code>max_days</code> when &gt; 0. Use it for expiries under a day (e.g. <code>60</code> = one hour).</p>
+            <span><code>max_downloads</code></span><p>Optional. Auto-expire the box after this many downloads.</p>
+            <span><code>password</code></span><p>Optional. Password required before viewing or downloading.</p>
+            <span><code>obfuscate_metadata</code></span><p>Optional <code>on</code>. Hides file names/counts until unlock (only meaningful with a password).</p>
+          </div>
+
+          <h4>Request headers</h4>
+          <div class="field-grid">
+            <span><code>Accept</code></span><p><code>application/json</code> to receive the JSON body; otherwise a single plain-text URL.</p>
+            <span><code>Authorization</code></span><p>Optional <code>Bearer &lt;token&gt;</code>. Attributes the upload to your account.</p>
+            <span><code>X-Warpbox-Batch</code></span><p>Optional grouping key. Uploads sharing a value within {{.Data.ShareXGroupWindow}} land in the same box. See <a href="#integrations" data-doc-link>Integrations</a>.</p>
+          </div>
+
+          <h4>Example</h4>
+          <figure class="code-block">
             <pre><code>curl -F file=@./report.pdf \
+  -F max_downloads=5 \
+  -F expires_minutes=1440 \
   -H 'Accept: application/json' \
   {{.Data.UploadURL}}</code></pre>
+          </figure>
         </div>
       </article>
 
-    <article class="card docs-card">
+      <article id="responses" class="endpoint card">
         <div class="card-content">
-        <h2>JSON response</h2>
-        <p>The raw delete token is returned only once inside <code>manageUrl</code> and <code>deleteUrl</code>. Keep those links private. On error the body is <code>{ "error": "message" }</code> with a non-2xx status (e.g. rate limited or over a limit).</p>
+          <h3>JSON response</h3>
+          <p>Returned when <code>Accept: application/json</code> is sent. The raw delete token appears <strong>only once</strong>, inside <code>manageUrl</code> and <code>deleteUrl</code>, so store them privately. Full schema: <a href="{{.Data.ResponseSchemaURL}}">upload-response.json</a>.</p>
+          <figure class="code-block">
             <pre><code>{
   "boxId": "abc123",
   "boxUrl": "{{.Data.BaseURL}}/d/abc123",
@@ -81,28 +144,176 @@ curl -X POST -H 'Accept: application/json' \
     }
   ]
 }</code></pre>
+          </figure>
+          <p class="muted-copy">On error the body is <code>{ "error": "message" }</code> with a non-2xx status. Common causes: <code>413</code> over the size limit, <code>429</code> rate limited or over your daily quota, <code>401</code> bad token.</p>
         </div>
       </article>
 
-    <article class="card docs-card">
+      <article id="ep-resumable" class="endpoint card">
         <div class="card-content">
-        <h2>ShareX setup</h2>
-        <p>Import the uploader, then add your API key to upload as your account — with your account's size, daily, and retention limits — instead of as an anonymous guest.</p>
+          <h3>Resumable uploads</h3>
+          <p>For large files. Browser uploads use this by default. Create a session with file metadata, <code>PUT</code> exact-sized chunks, then complete. Chunks are temporary and cleaned if the session expires. Send the same <code>Authorization</code> header on every request for authenticated sessions.</p>
+          <div class="endpoint-list">
+            <div><span class="method method-post">POST</span><code>/api/v1/uploads/resumable</code><em>Create a session</em></div>
+            <div><span class="method method-get">GET</span><code>/api/v1/uploads/resumable/{sessionID}</code><em>Session status</em></div>
+            <div><span class="method method-put">PUT</span><code>/api/v1/uploads/resumable/{sessionID}/files/{fileID}/chunks/{index}</code><em>Upload one chunk</em></div>
+            <div><span class="method method-post">POST</span><code>/api/v1/uploads/resumable/{sessionID}/complete</code><em>Finalize (returns the upload JSON)</em></div>
+          </div>
+          <figure class="code-block">
+            <pre><code># 1. Create a session.
+curl -s {{.Data.BaseURL}}/api/v1/uploads/resumable \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{"files":[{"name":"report.pdf","size":1048576,"contentType":"application/pdf"}],"expiresMinutes":1440}'
 
-        <h3>1 · Import the uploader</h3>
+# 2. Upload each chunk using the returned sessionId, file id, and chunkSize.
+dd if=./report.pdf bs=8388608 count=1 skip=0 2>/dev/null | \
+  curl -X PUT --data-binary @- \
+  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/files/FILE_ID/chunks/0
+
+# 3. Complete after all chunks are present. The response is the normal upload JSON.
+curl -X POST -H 'Accept: application/json' \
+  {{.Data.BaseURL}}/api/v1/uploads/resumable/SESSION_ID/complete</code></pre>
+          </figure>
+          <p class="muted-copy">Incomplete chunks are stored under <code>data/tmp/uploads</code> before finalizing into the selected storage backend.</p>
+        </div>
+      </article>
+
+      <article id="ep-meta" class="endpoint card">
+        <div class="card-content">
+          <h3>Health &amp; schemas</h3>
+          <div class="endpoint-list">
+            <div><span class="method method-get">GET</span><code>/health</code><em>Liveness check</em></div>
+            <div><span class="method method-get">GET</span><code>/api/v1/schemas/upload-request.json</code><em>Request JSON Schema</em></div>
+            <div><span class="method method-get">GET</span><code>/api/v1/schemas/upload-response.json</code><em>Response JSON Schema</em></div>
+          </div>
+        </div>
+      </article>
+    </section>
+
+    <!-- ===================== CLI / BINARY ===================== -->
+    <section id="cli" class="doc-panel" data-doc-panel="cli" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Terminal</p>
+        <h2>The <code>warpbox</code> CLI</h2>
+        <p class="lead">A tiny uploader script that wraps the API. It only needs <code>curl</code> (already on macOS, Linux, and Windows 10+). Point it at this instance once by setting <code>WARPBOX_HOST</code> to <code>{{.Data.BaseURL}}</code>, then upload from anywhere.</p>
+      </header>
+
+      <div class="download-row">
+        <div class="download-card">
+          <div class="download-os">macOS &amp; Linux</div>
+          <p>POSIX shell script (<code>warpbox.sh</code>).</p>
+          <a class="button button-primary" href="/static/api/warpbox.sh" download>Download for macOS / Linux</a>
+        </div>
+        <div class="download-card">
+          <div class="download-os">Windows</div>
+          <p>PowerShell script (<code>warpbox.ps1</code>).</p>
+          <a class="button button-primary" href="/static/api/warpbox.ps1" download>Download for Windows</a>
+        </div>
+      </div>
+
+      <article id="cli-install" class="card">
+        <div class="card-content">
+          <h3>Install &amp; add to PATH</h3>
+
+          <h4>macOS / Linux</h4>
+          <p>Download into a directory on your <code>PATH</code>, then make it executable. <code>~/.local/bin</code> is the recommended location.</p>
+          <figure class="code-block">
+            <pre><code>mkdir -p ~/.local/bin
+curl -fsSL {{.Data.BaseURL}}/static/api/warpbox.sh -o ~/.local/bin/warpbox
+chmod +x ~/.local/bin/warpbox
+
+# Point it at this instance (add to ~/.profile or ~/.zshrc to keep it set)
+echo 'export WARPBOX_HOST={{.Data.BaseURL}}' >> ~/.profile
+
+# If 'warpbox: command not found', add the dir to PATH:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
+# zsh users: use ~/.zshrc, then reload with: source ~/.profile</code></pre>
+          </figure>
+          <p class="muted-copy">Verify with <code>warpbox --help</code>. Prefer a system wide install? Drop it in <code>/usr/local/bin</code> with <code>sudo</code>.</p>
+
+          <h4>Windows (PowerShell)</h4>
+          <p>Save the script, then add a function to your PowerShell profile so <code>warpbox</code> works anywhere.</p>
+          <figure class="code-block">
+            <pre><code># Save it to your home folder
+iwr {{.Data.BaseURL}}/static/api/warpbox.ps1 -OutFile $HOME\warpbox.ps1
+
+# Point it at this instance, and add a 'warpbox' command (run once)
+setx WARPBOX_HOST "{{.Data.BaseURL}}"
+Add-Content $PROFILE 'function warpbox { &amp; "$HOME\warpbox.ps1" @args }'
+. $PROFILE   # reload the profile</code></pre>
+          </figure>
+          <p class="muted-copy">If scripts are blocked, allow local scripts for your user: <code>Set-ExecutionPolicy -Scope CurrentUser RemoteSigned</code>.</p>
+        </div>
+      </article>
+
+      <article id="cli-usage" class="card">
+        <div class="card-content">
+          <h3>Usage</h3>
+          <p>A password, an expiry of two days, and a glob the shell expands for you:</p>
+          <figure class="code-block">
+            <pre><code>warpbox --password 123 --expiry 2d ./first_file.zip ./whatever.png ./all_*_photos.jpg</code></pre>
+          </figure>
+          <div class="field-grid">
+            <span><code>-p, --password</code></span><p>Require a password to open the box.</p>
+            <span><code>-e, --expiry</code></span><p>Lifetime: <code>30m</code>, <code>6h</code>, <code>2d</code>, <code>1w</code> (or bare minutes).</p>
+            <span><code>-n, --max-downloads</code></span><p>Expire after N downloads.</p>
+            <span><code>-o, --obfuscate</code></span><p>Hide names/counts until unlock (needs <code>--password</code>).</p>
+            <span><code>--json</code></span><p>Print the full JSON response instead of just the URL.</p>
+            <span><code>--host</code></span><p>Server to upload to. Defaults to your <code>WARPBOX_HOST</code>.</p>
+          </div>
+          <p class="muted-copy">Windows uses PowerShell flags: <code>warpbox -Password 123 -Expiry 2d .\file.zip</code>.</p>
+        </div>
+      </article>
+
+      <article id="cli-auth" class="card">
+        <div class="card-content">
+          <h3>Secure authentication</h3>
+          <p>To upload as your account (and use your account's size, daily, and retention limits), the CLI needs an API token. <strong>Set it in your environment</strong> so it never appears in your shell history or in the process list that any user on the machine can read:</p>
+          <figure class="code-block">
+            <pre><code># macOS / Linux (add to ~/.profile or ~/.zshrc to persist)
+export WARPBOX_TOKEN=wbx_your_token
+warpbox ./photo.png
+
+# Windows (persist for your user)
+setx WARPBOX_TOKEN "wbx_your_token"</code></pre>
+          </figure>
+          <p>For CI or shared machines, keep the token in a file with locked down permissions and point the CLI at it. This avoids putting the secret on the command line at all:</p>
+          <figure class="code-block">
+            <pre><code>printf '%s' "wbx_your_token" > ~/.warpbox-token
+chmod 600 ~/.warpbox-token
+warpbox --auth-file ~/.warpbox-token ./photo.png</code></pre>
+          </figure>
+          <p class="muted-copy"><code>--auth &lt;token&gt;</code> exists for quick tests but is discouraged: it leaks into shell history and <code>ps</code>. Create or revoke tokens under <a href="/account/settings">Account, Access tokens</a>.</p>
+        </div>
+      </article>
+    </section>
+
+    <!-- ===================== INTEGRATIONS ===================== -->
+    <section id="integrations" class="doc-panel" data-doc-panel="integrations" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Integrations</p>
+        <h2>ShareX setup</h2>
+        <p class="lead">Import the uploader once, then optionally add your API key to upload as your account instead of as an anonymous guest.</p>
+      </header>
+
+      <article id="sharex" class="card">
+        <div class="card-content">
+          <h3>1. Import the uploader</h3>
           <ol class="docs-steps">
-          <li>Download <a href="/api/v1/sharex/warpbox-anonymous.sxcu"><code>warpbox-anonymous.sxcu</code></a>.</li>
+            <li>Download <a href="{{.Data.ShareXDownloadURL}}" download><code>warpbox-anonymous.sxcu</code></a>.</li>
             <li>In ShareX: <code>Destinations → Custom uploader settings → Import → From file</code>, then pick the <code>.sxcu</code>.</li>
           </ol>
 
-        <h3>2 · Add your API key (upload as your account)</h3>
+          <h3>2. Add your API key (optional, upload as your account)</h3>
           <ol class="docs-steps">
-          <li>Create a personal access token under <a href="/account/settings">Account → Access tokens</a> and copy it.</li>
+            <li>Create a personal access token under <a href="/account/settings">Account, Access tokens</a> and copy it.</li>
             <li>In <code>Custom uploader settings</code>, select the Warpbox uploader and open the <code>Headers</code> section.</li>
-          <li>Add a header — Name <code>Authorization</code>, Value <code>Bearer &lt;your token&gt;</code>.</li>
+            <li>Add a header. Name <code>Authorization</code>, Value <code>Bearer &lt;your token&gt;</code>.</li>
           </ol>
           <p class="muted-copy">Without that header, uploads stay anonymous. With it, they're attributed to your account and use your account's limits.</p>
 
+          <figure class="code-block">
             <pre><code>{
   "Version": "1.0.0",
   "Name": "Warpbox (my account)",
@@ -121,27 +332,183 @@ curl -X POST -H 'Accept: application/json' \
   "DeletionURL": "{json:deleteUrl}",
   "ErrorMessage": "{json:error}"
 }</code></pre>
+          </figure>
 
           <h3>Grouping multiple files into one box</h3>
-        <p>Grouping is <strong>opt-in via the <code>X-Warpbox-Batch</code> request header</strong> — without it, every file becomes its own box (the default). When the header is present, uploads sharing the same value (per account, or per IP for anonymous) within {{.Data.ShareXGroupWindow}} of each other are added to the <strong>same</strong> box, so a multi-file ShareX selection produces one shareable link instead of one per file. The shipped config sets <code>X-Warpbox-Batch: sharex</code>; remove that header for one box per file.</p>
+          <p>Grouping is <strong>opt in via the <code>X-Warpbox-Batch</code> request header</strong>. Without it, every file becomes its own box (the default). When the header is present, uploads sharing the same value (per account, or per IP for anonymous) within {{.Data.ShareXGroupWindow}} of each other are added to the <strong>same</strong> box, so a ShareX selection of several files produces one shareable link instead of one per file. The shipped config sets <code>X-Warpbox-Batch: sharex</code>; remove that header for one box per file.</p>
           <p class="muted-copy">The response also exposes <code>{json:thumbnailUrl}</code> for ShareX previews, <code>{json:deleteUrl}</code> for the deletion URL, and <code>{json:error}</code> so ShareX surfaces messages like rate limiting.</p>
         </div>
       </article>
+    </section>
 
-    <article class="card docs-card docs-card-wide">
+    <!-- ===================== EXAMPLES ===================== -->
+    <section id="examples" class="doc-panel" data-doc-panel="examples" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Cookbook</p>
+        <h2>Examples</h2>
+        <p class="lead">Every snippet hits <code>POST {{.Data.UploadURL}}</code>. Add <code>-H 'Authorization: Bearer &lt;token&gt;'</code> to any of them to upload as your account.</p>
+      </header>
+
+      <article id="ex-curl" class="card">
         <div class="card-content">
-        <h2>Multipart fields</h2>
-        <div class="field-grid">
-          <span><code>file</code></span><p>One or more files for curl, browser, and generic multipart clients.</p>
-          <span><code>sharex</code></span><p>One or more files from ShareX custom uploader configs.</p>
-          <span><code>max_days</code></span><p>Optional number of days before expiration. Defaults to 7.</p>
-          <span><code>expires_minutes</code></span><p>Optional lifetime in minutes. Takes precedence over <code>max_days</code> when greater than zero — useful for sub-day expiries (e.g. <code>60</code> for one hour).</p>
-          <span><code>max_downloads</code></span><p>Optional download count limit.</p>
-          <span><code>password</code></span><p>Optional password required before viewing/downloading.</p>
-          <span><code>obfuscate_metadata</code></span><p>Optional <code>on</code>; hides names/counts until unlock when a password is set.</p>
-        </div>
+          <h3>curl</h3>
+          <p>Plain text (one URL) for the shell; JSON for automation.</p>
+          <figure class="code-block">
+            <pre><code># Just the box URL
+curl -F file=@./report.pdf {{.Data.UploadURL}}
+
+# Full JSON with manage + delete URLs, password and 1-hour expiry
+curl -F file=@./report.pdf \
+  -F password=hunter2 \
+  -F expires_minutes=60 \
+  -H 'Accept: application/json' \
+  {{.Data.UploadURL}}</code></pre>
+          </figure>
         </div>
       </article>
+
+      <article id="ex-wget" class="card">
+        <div class="card-content">
+          <h3>wget</h3>
+          <p>The endpoint needs a real <code>multipart/form-data</code> body, which <code>wget</code> can't assemble on its own, so build the body by hand and post it. It also shows the wire format:</p>
+          <figure class="code-block">
+            <pre><code>B=----warpbox$$
+{ printf -- '--%s\r\nContent-Disposition: form-data; name="file"; filename="report.pdf"\r\nContent-Type: application/octet-stream\r\n\r\n' "$B"
+  cat ./report.pdf
+  printf -- '\r\n--%s--\r\n' "$B"; } > /tmp/wb.body
+
+wget --quiet --output-document=- \
+  --header="Content-Type: multipart/form-data; boundary=$B" \
+  --header="Accept: application/json" \
+  --post-file=/tmp/wb.body \
+  {{.Data.UploadURL}}</code></pre>
+          </figure>
+          <p class="muted-copy">Add more form fields (<code>password</code>, <code>expires_minutes</code>, …) by repeating the <code>--%s … Content-Disposition: form-data; name="…"</code> block before the closing boundary. If this feels fiddly, <code>curl</code> or the CLI build the body for you.</p>
+        </div>
+      </article>
+
+      <article id="ex-httpie" class="card">
+        <div class="card-content">
+          <h3>HTTPie</h3>
+          <p>Multipart with form fields:</p>
+          <figure class="code-block">
+            <pre><code>http --multipart POST {{.Data.UploadURL}} \
+  Accept:application/json \
+  file@./report.pdf \
+  max_downloads=3 \
+  expires_minutes=1440</code></pre>
+          </figure>
+        </div>
+      </article>
+
+      <article id="ex-python" class="card">
+        <div class="card-content">
+          <h3>Python (requests)</h3>
+          <figure class="code-block">
+            <pre><code>import requests
+
+with open("report.pdf", "rb") as f:
+    r = requests.post(
+        "{{.Data.UploadURL}}",
+        headers={"Accept": "application/json"},  # add "Authorization": "Bearer <token>"
+        files={"file": f},
+        data={"expires_minutes": 1440, "max_downloads": 5},
+    )
+r.raise_for_status()
+print(r.json()["boxUrl"])</code></pre>
+          </figure>
+        </div>
+      </article>
+
+      <article id="ex-node" class="card">
+        <div class="card-content">
+          <h3>Node.js (fetch)</h3>
+          <figure class="code-block">
+            <pre><code>import { readFile } from "node:fs/promises";
+
+const form = new FormData();
+form.set("file", new Blob([await readFile("report.pdf")]), "report.pdf");
+form.set("expires_minutes", "1440");
+
+const res = await fetch("{{.Data.UploadURL}}", {
+  method: "POST",
+  headers: { Accept: "application/json" }, // add Authorization: "Bearer <token>"
+  body: form,
+});
+const box = await res.json();
+console.log(box.boxUrl);</code></pre>
+          </figure>
+        </div>
+      </article>
+
+      <article id="ex-ps" class="card">
+        <div class="card-content">
+          <h3>PowerShell</h3>
+          <p>PowerShell 7+ has native multipart with <code>-Form</code>:</p>
+          <figure class="code-block">
+            <pre><code>$resp = Invoke-RestMethod -Uri "{{.Data.UploadURL}}" -Method Post -Headers @{ Accept = "application/json" } -Form @{
+  file            = Get-Item ".\report.pdf"
+  expires_minutes = 1440
+}
+$resp.boxUrl</code></pre>
+          </figure>
+          <p class="muted-copy">On Windows PowerShell 5.1, use the bundled <code>curl.exe</code> (the same approach the <a href="#cli" data-doc-link>CLI</a> takes) or the <code>warpbox.ps1</code> script.</p>
+        </div>
+      </article>
+    </section>
+
+    <!-- ===================== FAQ ===================== -->
+    <section id="faq" class="doc-panel" data-doc-panel="faq" tabindex="-1">
+      <header class="panel-head">
+        <p class="kicker">Help</p>
+        <h2>FAQ &amp; troubleshooting</h2>
+        <p class="lead">Quick answers, each linking back to the relevant part of the docs.</p>
+      </header>
+
+      <div class="faq-list">
+        <details class="faq-item">
+          <summary>Do I need an account or API key?</summary>
+          <p>No. Anonymous uploads work without one, see the <a href="#home" data-doc-link>quickstart</a>. Add a token only to upload as your account and use your account's limits; set one up under <a href="/account/settings">Account, Access tokens</a> and pass it as described in <a href="#cli-auth" data-doc-link>CLI authentication</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>How do I send a password, expiry, or download limit?</summary>
+          <p>They're multipart form fields on the upload endpoint: <code>password</code>, <code>expires_minutes</code> (or <code>max_days</code>), and <code>max_downloads</code>. See the full list under <a href="#ep-upload" data-doc-link>Endpoints, request fields</a>, or use the CLI flags in <a href="#cli-usage" data-doc-link>CLI usage</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>How do I get file URLs and a delete link back?</summary>
+          <p>Send <code>Accept: application/json</code>. The response includes <code>boxUrl</code>, per-file <code>url</code>s, and the private <code>manageUrl</code>/<code>deleteUrl</code> (shown only once). See <a href="#responses" data-doc-link>the JSON response</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>How do I upload one big file reliably?</summary>
+          <p>Use the <a href="#ep-resumable" data-doc-link>resumable endpoints</a>: create a session, PUT chunks, then complete. Interrupted uploads can resume from the last chunk.</p>
+        </details>
+        <details class="faq-item">
+          <summary>Can I upload several files into one shareable link?</summary>
+          <p>Yes. Send the <code>X-Warpbox-Batch</code> header with a shared value within {{.Data.ShareXGroupWindow}}. Details in <a href="#integrations" data-doc-link>Integrations, grouping</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>Where's the keep-it-secret way to store my token?</summary>
+          <p>Use the <code>WARPBOX_TOKEN</code> environment variable or <code>--auth-file</code>, not <code>--auth</code> on the command line. Full guidance in <a href="#cli-auth" data-doc-link>CLI authentication</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>My upload returns an error, what do the codes mean?</summary>
+          <p>Errors come back as <code>{ "error": "message" }</code> with a non-2xx status: <code>413</code> too large, <code>429</code> rate limited / over quota, <code>401</code> invalid token. See <a href="#responses" data-doc-link>error responses</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>How do I use Warpbox from ShareX?</summary>
+          <p>Import the <code>.sxcu</code> and (optionally) add your token header. Step by step with the config in <a href="#integrations" data-doc-link>Integrations, ShareX setup</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary><code>warpbox: command not found</code> after install?</summary>
+          <p>The install directory isn't on your <code>PATH</code>. Fix it per your platform in <a href="#cli-install" data-doc-link>Install &amp; add to PATH</a>.</p>
+        </details>
+        <details class="faq-item">
+          <summary>Is there a machine-readable schema?</summary>
+          <p>Yes: <a href="{{.Data.RequestSchemaURL}}">upload-request.json</a> and <a href="{{.Data.ResponseSchemaURL}}">upload-response.json</a> (JSON Schema 2020-12).</p>
+        </details>
+      </div>
+    </section>
+
   </div>
 </section>
 {{end}}

backend/templates/pages/download.html

@@ -5,7 +5,7 @@
   <div class="card download-card">
     <div class="card-content">
       <div class="file-emblem" aria-hidden="true">
-        <svg viewBox="0 0 24 24" role="img" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z" /><path d="M14 2v6h6" /></svg>
+        <span class="svg-icon svg-icon-document"></span>
       </div>
       <h1 id="download-title">{{if .Data.Locked}}Protected box{{else}}Box: {{.Data.Box.ID}} ({{len .Data.Files}} file{{if ne (len .Data.Files) 1}}s{{end}}){{end}}</h1>
       {{if .Data.Locked}}<p class="download-subtitle">Bucket id: {{.Data.Box.ID}}</p>{{end}}
@@ -25,11 +25,17 @@
 
       {{if .Data.Files}}
         {{$processing := false}}{{range .Data.Files}}{{if .Processing}}{{$processing = true}}{{end}}{{end}}
+        {{$failed := false}}{{range .Data.Files}}{{if .Failed}}{{$failed = true}}{{end}}{{end}}
         {{if $processing}}
           <div class="upload-processing-alert" role="status">
             Some files are still processing. You can share this link now, but processing files will become available shortly.
           </div>
         {{end}}
+        {{if $failed}}
+          <div class="upload-processing-alert upload-processing-alert-error" role="alert">
+            Upload processing failed for one or more files. The original upload could not be finalized by the storage backend.
+          </div>
+        {{end}}
         {{$single := eq (len .Data.Files) 1}}
         <div class="badge-row">
           <span class="badge badge-expiry">Expires {{.Data.ExpiresLabel}}</span>
@@ -37,19 +43,29 @@
         </div>
 
         {{if not .Data.Locked}}
+          <button class="button button-outline button-wide download-share-button" type="button" data-share-box data-share-url="/d/{{.Data.Box.ID}}" data-share-title="{{if .Data.Locked}}Protected Warpbox box{{else}}Warpbox box {{.Data.Box.ID}}{{end}}" data-share-text="Shared files on Warpbox">
+            <span class="svg-icon svg-icon-share" aria-hidden="true"></span>
+            <span data-share-box-label>Share</span>
+          </button>
+          {{if or $processing $failed}}
+            <span class="button button-outline button-wide is-disabled" aria-disabled="true">
+              {{if $failed}}Download unavailable{{else}}Files processing{{end}}
+            </span>
+          {{else}}
           {{if $single}}
             {{$first := index .Data.Files 0}}
             <a class="button button-primary button-wide" href="{{$first.DownloadURL}}" download="{{$first.Name}}">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M12 3v12m0 0 4-4m-4 4-4-4M5 21h14" /></svg>
+              <span class="svg-icon svg-icon-download" aria-hidden="true"></span>
               Download
             </a>
           {{else}}
             <a class="button button-primary button-wide" href="{{.Data.ZipURL}}">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M12 3v12m0 0 4-4m-4 4-4-4M5 21h14" /></svg>
+              <span class="svg-icon svg-icon-download" aria-hidden="true"></span>
               Download zip
             </a>
           {{end}}
           {{end}}
+        {{end}}
 
         <div class="file-browser-window" data-file-browser-window>
           <div class="file-browser-titlebar">
@@ -64,11 +80,11 @@
           <div class="file-browser-toolbar" aria-label="File view options">
             <div class="view-toolbar">
               <button class="button button-outline icon-button" type="button" data-view-button="list" aria-pressed="false" aria-label="List view" title="List view">
-                <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" /></svg>
+                <span class="svg-icon svg-icon-list" aria-hidden="true"></span>
                 <span class="sr-only">List view</span>
               </button>
               <button class="button button-outline icon-button is-active" type="button" data-view-button="thumbs" aria-pressed="true" aria-label="Icon view" title="Icon view">
-                <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><rect x="3" y="3" width="7" height="7" rx="1" /><rect x="14" y="3" width="7" height="7" rx="1" /><rect x="3" y="14" width="7" height="7" rx="1" /><rect x="14" y="14" width="7" height="7" rx="1" /></svg>
+                <span class="svg-icon svg-icon-grid" aria-hidden="true"></span>
                 <span class="sr-only">Icon view</span>
               </button>
             </div>
@@ -80,8 +96,8 @@
           </div>
           <div class="download-list file-browser is-thumbs" data-file-browser>
             {{range .Data.Files}}
-              <article class="download-item file-card {{if .Processing}}is-processing{{end}}" data-kind="{{.PreviewKind}}" {{if not .Processing}}data-file-context data-preview-url="{{.URL}}" data-view-url="{{.DownloadURL}}?inline=1" data-download-url="{{.DownloadURL}}"{{end}} data-file-name="{{.Name}}" data-reaction-card data-react-url="{{.ReactURL}}" data-reacted="{{if .Reacted}}true{{else}}false{{end}}">
-                {{if .Processing}}<div class="file-open" aria-label="{{.Name}} is processing">{{else}}<a class="file-open" href="{{.DownloadURL}}?inline=1"{{if not $single}} target="_blank" rel="noopener noreferrer"{{end}} aria-label="Open {{.Name}}">{{end}}
+              <article class="download-item file-card {{if .Processing}}is-processing{{end}} {{if .Failed}}is-failed{{end}}" data-kind="{{.PreviewKind}}" {{if and (not .Processing) (not .Failed)}}data-file-context data-preview-url="{{.URL}}" data-view-url="{{.DownloadURL}}?inline=1" data-download-url="{{.DownloadURL}}"{{end}} data-file-name="{{.Name}}" data-reaction-card data-react-url="{{.ReactURL}}" data-reacted="{{if .Reacted}}true{{else}}false{{end}}">
+                {{if or .Processing .Failed}}<div class="file-open" aria-label="{{.Name}} {{if .Failed}}failed processing{{else}}is processing{{end}}">{{else}}<a class="file-open" href="{{.DownloadURL}}?inline=1"{{if not $single}} target="_blank" rel="noopener noreferrer"{{end}} aria-label="Open {{.Name}}">{{end}}
                   <span class="file-media">
                     {{if .HasThumbnail}}
                       <img class="file-thumb" src="{{.ThumbnailURL}}" alt="" loading="lazy">
@@ -92,11 +108,12 @@
                   </span>
                   <span class="file-main">
                     <strong class="file-name" title="{{.Name}}">{{.Name}}</strong>
-                    <small>{{.Size}} · {{if .Processing}}Processing{{else}}{{.ContentType}}{{end}}</small>
+                    <small>{{.Size}} · {{if .Failed}}Failed{{else if .Processing}}Processing{{else}}{{.ContentType}}{{end}}</small>
+                    {{if .Failed}}<small class="file-error">{{.Error}}</small>{{end}}
                   </span>
-                  <span class="file-type">{{if .Processing}}Processing{{else}}{{.ContentType}}{{end}}</span>
+                  <span class="file-type">{{if .Failed}}Failed{{else if .Processing}}Processing{{else}}{{.ContentType}}{{end}}</span>
                   <span class="file-size">{{.Size}}</span>
-                {{if .Processing}}</div>{{else}}</a>{{end}}
+                {{if or .Processing .Failed}}</div>{{else}}</a>{{end}}
                 {{if not $.Data.Locked}}
                   <div class="file-reaction-dock" data-reaction-dock>
                     <div class="file-reactions" data-reaction-list>
@@ -112,7 +129,7 @@
                     </div>
                     {{if not .Reacted}}
                       <button class="reaction-button" type="button" data-reaction-button data-react-url="{{.ReactURL}}" aria-label="React to {{.Name}}" title="React">
-                        <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M12 21a9 9 0 1 0-9-9 9 9 0 0 0 9 9Z" /><path d="M8 14s1.4 2 4 2 4-2 4-2" /><path d="M9 9h.01M15 9h.01" /></svg>
+                        <span class="svg-icon svg-icon-emoji" aria-hidden="true"></span>
                       </button>
                     {{end}}
                   </div>
@@ -160,35 +177,35 @@
               <small>File actions</small>
               <div class="context-menu-icons" aria-label="Quick actions">
                 <button type="button" role="menuitem" data-context-action="preview" title="Open preview" aria-label="Open preview">
-                  <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M15 3h6v6" /><path d="M10 14 21 3" /><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></svg>
+                  <span class="svg-icon svg-icon-open" aria-hidden="true"></span>
                 </button>
                 <button type="button" role="menuitem" data-context-action="copy-preview" title="Copy preview URL" aria-label="Copy preview URL">
-                  <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>
+                  <span class="svg-icon svg-icon-copy" aria-hidden="true"></span>
                   <span data-context-label class="sr-only">Copy</span>
                 </button>
               </div>
             </div>
             <hr>
             <button type="button" role="menuitem" data-context-action="preview">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6Z" /><circle cx="12" cy="12" r="3" /></svg>
+              <span class="svg-icon svg-icon-eye" aria-hidden="true"></span>
               <span data-context-label>Preview</span>
             </button>
             <button type="button" role="menuitem" data-context-action="view">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M15 3h6v6" /><path d="M10 14 21 3" /><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></svg>
+              <span class="svg-icon svg-icon-open" aria-hidden="true"></span>
               <span data-context-label>View raw file</span>
             </button>
             <hr>
             <button type="button" role="menuitem" data-context-action="copy-preview">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>
+              <span class="svg-icon svg-icon-copy" aria-hidden="true"></span>
               <span data-context-label>Copy Preview</span>
             </button>
             <button type="button" role="menuitem" data-context-action="copy-download">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>
+              <span class="svg-icon svg-icon-copy" aria-hidden="true"></span>
               <span data-context-label>Copy Download</span>
             </button>
             <hr>
             <button type="button" role="menuitem" data-context-action="download">
-              <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M12 3v12m0 0 4-4m-4 4-4-4M5 21h14" /></svg>
+              <span class="svg-icon svg-icon-download" aria-hidden="true"></span>
               <span data-context-label>Download</span>
             </button>
           </div>

backend/templates/pages/home.html

@@ -10,7 +10,7 @@
     {{end}}
   </div>
 
-  <form class="upload-grid" id="upload-form" action="/api/v1/upload" method="post" enctype="multipart/form-data">
+  <form class="upload-grid" id="upload-form" action="/api/v1/upload" method="post" enctype="multipart/form-data" data-max-upload-bytes="{{.Data.MaxUploadBytes}}" data-max-upload-label="{{.Data.MaxUploadSize}}">
     <div class="card upload-main">
       <div class="card-content">
         {{if .CurrentUser}}
@@ -25,7 +25,7 @@
             <svg viewBox="0 0 24 24" role="img" focusable="false" aria-hidden="true"><path d="M12 16V4m0 0 4 4m-4-4-4 4M5 20h14" /></svg>
           </span>
           <span class="drop-title">Drop files to upload</span>
-          <span class="drop-copy">or click to browse</span>
+          <span class="drop-copy">or click to browse, paste files, or drop a folder</span>
           <span class="drop-meta">Max file size: {{.Data.MaxUploadSize}} · {{.Data.LimitSummary}}</span>
           <input id="file-input" name="file" type="file" multiple>
         </label>
@@ -76,6 +76,8 @@
 
         <div class="form-footer">
           <p id="file-summary">Choose one or more files to begin.</p>
+          <button class="button button-outline install-pwa-button" type="button" data-install-pwa hidden>Install Warpbox</button>
+          <button class="button button-outline folder-picker-button" type="button" data-folder-picker hidden>Choose folder</button>
           <button class="button button-primary" type="submit">Upload files</button>
           <button class="button button-danger upload-new-button" type="button" id="new-upload" hidden>New upload</button>
         </div>