docs: add 0.4.0 frontend hardening sprint section

Document the frontend security and UX hardening sprint that landed
just before 0.4.0 ships:

CHANGELOG.md:
  * Added new Security section under [0.4.0] covering FOAC fix,
    centralized user state cleanup, session-scoped AbortController,
    bfcache invalidation, toast cross-session leak fix, Keycloak
    URL validation, DOMPurify sanitization across 8 {@html} render
    sites, bypassable regex sanitizer replacement, and production
    sourcemap disable.
  * Added new Upload Modal Redesign, Skeleton Loaders, and Collection
    & Share Modal Polish subsections under Added.
  * Extended Fixed with websocket notification leak, upload queue
    persistence leak, dropdown clipping fix, double-card visual fix,
    debug console.log removal, dead code removal, and avatar
    lazy-loading.
  * Added hard-reload note to Upgrade Notes.

docs-site/blog/2026-02-07-v0.4.0-release.md:
  * Added 'The Final Polish: Frontend Hardening Sprint' section
    between 'Everything Else' and 'Lessons from 1,400 Podcasts'.
  * Six subsections: Session Security (FOAC, clearUserState, request
    cancellation, bfcache), XSS Hardening (DOMPurify, regex sanitizer
    replacement, sourcemap disable), Upload Modal Redesign (stepper
    flow, decomposition, unified across upload sources), Skeleton
    Loaders Replace Spinners (research-backed perceived performance),
    Gallery Click Feedback (press state, prefetch, double-click
    guard), and Collection & Share Modal Polish (help text, empty
    states, permission guide).

Verified docusaurus build succeeds before committing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: davidamacey

CHANGELOG.md

@@ -126,6 +126,45 @@ Major release combining enterprise-grade authentication, native transcription pi
 - **Keycloak Federated Logout** - Session termination propagates to Keycloak OIDC end-session endpoint (#125)
 - **Super Admin PKI + Local Password Fallback** - PKI-authenticated super admins can retain local password as fallback (#127)
 
+#### Upload Modal Redesign
+- **6-Step Stepper Flow** - Replaced the accordion-inside-modal upload UX with a linear stepper: Media → Tags → Collections → Speakers → Options → Submit. Conditional Extract step appears automatically for large video files
+- **Unified Across All Upload Sources** - File, URL, and recording uploads now share steps 2-6, so URL downloads and recordings gain full access to tags/collections/speaker settings (previously file-only)
+- **Remember Previous Values** - Upload modal pre-fills tags, collections, speaker settings, whisper model, and skip-summary from the last upload. One-click "Review with defaults" shortcut lets power users jump straight to submit
+- **Clickable Stepper Navigation** - Users can click any previously-visited step to go back and edit. Dot + label is a single clickable button per step (Fitts's Law / Apple HIG 44×44pt touch-target compliance)
+- **Decomposed Monolith** - The 4,603-line `FileUploader.svelte` split into a 1,294-line coordinator plus 9 focused components under `frontend/src/components/upload/` (each under ~470 lines). New `upload-shared.css` provides a unified chip/dropdown pattern reused across tags and collections
+- **Conditional Extraction Step** - Large video files (>100MB by default) trigger an inline Extract step with radio-button choice (Extract Audio Only vs Upload Full Video). Extraction runs on final Submit, not at selection time, so users can still change their mind while stepping through tags/collections
+- **Backdrop-Click No Longer Closes** - Modal only closes via X button or Escape key, preventing data loss from stray clicks on in-progress upload state
+
+#### Skeleton Loaders on Major Pages
+- **Structural Loading States** - Replaced generic `<Spinner size="large">` on home gallery, search results, file detail page, and speaker clusters/profiles/inbox with skeleton components that mirror the final layout. Perceived load time ~20% faster per Nielsen Norman research
+- **Reusable Skeleton Components** - New `FileDetailSkeleton.svelte` (full 2-column layout with header/video/transcript), `ui/CardGridSkeleton.svelte` (parametric with media/profile/search variants), and `ui/ListRowSkeleton.svelte` (avatar + title + actions rows)
+- **Gallery Click Feedback** - Clicking a file card now dims + scales it instantly (opacity 0.72, scale 0.985) with `pointer-events: none` to prevent double-clicks. Prefetch kicks off on `mousedown` ~50-100ms before the click handler runs
+
+#### Collection & Share Modal Polish
+- **Help Text and Empty States** - Create/Edit Collection modals gained intro banners explaining what collections are, field hints with `maxlength` indicators, and proper `aria-labelledby` wiring
+- **Universal Content Analyzer Default** - New collections auto-select the system-default prompt (via `is_system_default` lookup), matching the behavior users typically want without requiring manual selection
+- **Share Modal Intro and Permission Guide** - Share Collection modal now includes an introductory explanation, a collection name banner with folder icon, and a visible permission-level reference card showing Viewer/Editor labels inline with descriptions (previously only in tooltips). Empty state added for collections with no existing shares
+- **Manage Collections Visual Fix** - Fixed nested-card glitch where the inner `.collections-panel` had its own surface background inside the outer modal container, producing a visible "card in a card" look
+
+### Security
+
+#### Frontend Session Hardening
+- **Flash of Authenticated Content (FOAC) fix** - `+layout.svelte` now gates all protected content behind `authReady && isAuthenticated && !isPublicPath`, showing a loading screen in route-mismatch states while async redirects are in flight. Previously, unauthenticated users hitting `/` briefly saw the gallery slot render before the redirect fired, leaking ~1-2 frames of protected UI and triggering `/files` API calls
+- **Centralized User State Cleanup** - New `frontend/src/lib/session/clearUserState.ts` is the single source of truth for session teardown. Clears 17+ subsystems on every login/logout transition: toast, websocket, uploads, gallery filters, search results, sharing, LLM status, settings modal, transcript, groups, downloads, notifications, recording (with media track cleanup), thumbnail cache, media URL cache, speaker colors, plus user-scoped localStorage keys. Preferences (theme, locale, view mode, recording settings) are explicitly preserved. Replaces ad-hoc cleanup previously scattered across `auth.ts`
+- **Session-Scoped Request Cancellation** - Session-scoped `AbortController` in `lib/axios.ts` attached to every request via interceptor (except `/auth/login`, `/auth/logout`, `/auth/token/refresh` which must always complete). `logout()` now calls `abortAllRequests()` before `clearUserState()`, closing the race window where a late API response could repopulate a cleared store with stale data from the previous session. New `isRequestCancelled()` helper exported for catch blocks to suppress error toasts on cancelled requests
+- **bfcache Invalidation on Back Button** - `+layout.svelte` now listens for `pageshow` events with `event.persisted === true` and forces `window.location.reload()` to discard the restored DOM/JS snapshot. Prevents users from hitting the back button after logout and seeing the previously-protected page restored from memory on shared devices
+- **Toast Cross-Session Leak Fixed** - `toastStore.clear()` is called from every login success path (local, Keycloak callback, PKI, MFA) and from `logout()` via `clearUserState()`. Previously, notifications from User A's session could persist into User B's login screen or the next user's session
+- **Keycloak Redirect URL Validation** - `loginWithKeycloak()` now parses and validates the `authorization_url` returned by `/auth/keycloak/login` (requires `http:` or `https:` protocol) before calling `window.location.href`. Prevents open-redirect or `javascript:`/`data:` URL injection if upstream config drifts
+
+#### XSS Hardening
+- **DOMPurify-Backed HTML Sanitization** - New `lib/utils/sanitizeHtml.ts` provides `sanitizeHighlightHtml()` (whitelist allows `mark`, `span`, `br`, `ul`, `li`, `em`, `strong`, `div`, `p` with `class` and `data-match-index` attributes) and `sanitizeToPlainText()`. Added `dompurify` and `@types/dompurify` as dependencies
+- **Defense-in-Depth Across 8 Render Sites** - Wrapped every `{@html}` directive that renders API-sourced or LLM-generated content with `sanitizeHighlightHtml()`: TopicsList, TranscriptDisplay, TranscriptModal, SearchTranscriptModal, SearchOccurrence, SearchResultCard, SummaryDisplay
+- **Bypassable Regex Sanitizer Replaced** - `SearchOccurrence.svelte` and `SearchResultCard.svelte` previously used `html.replace(/<(?!\/?mark[\s>])[^>]*>/g, '')` which was bypassable via `</mark><script>alert(1)</script><mark>` payloads (the regex only matched opening tags). Now uses DOMPurify with a strict tag whitelist
+
+#### Build & Configuration Hardening
+- **Production Source Maps Disabled** - `vite.config.ts` now uses `sourcemap: mode !== 'production'`, ensuring `.js.map` files are only generated for dev/preview builds. Previously, production builds shipped source maps exposing variable names, API endpoint URIs, error messages, and full business logic to any visitor via DevTools or automated crawlers
+- **Defense-in-Depth Home Page Guard** - `routes/+page.svelte` `onMount` now early-returns if `!get(isAuthenticated)`, preventing `fetchFiles()` and WebSocket subscriptions from running if the component is somehow mounted unauthenticated (belt-and-suspenders beyond the layout-level route guard)
+
 ### Changed
 
 - **Default Whisper Model** - Changed from `large-v2` to `large-v3-turbo` for significantly faster transcription with maintained accuracy
@@ -171,6 +210,13 @@ Major release combining enterprise-grade authentication, native transcription pi
 - Admin bypass and shared editor access across all API endpoints
 - Alembic migration chain linearized after branch merges
 - LDAP user bcrypt crash when verifying non-local passwords
+- **WebSocket notification queue leak** - `clearAll()` now called on logout; previously persisted in localStorage across sessions, exposing User A's notification history to User B on shared devices
+- **Upload queue persistence leak** - `localStorage['upload_queue']` is now cleared on logout via new `uploadsStore.reset()`; previously leaked file UUIDs, metadata, and processing status across sessions
+- **Dropdown clipping in upload modal** - Removed nested `overflow-y: auto` on the stepper body that was clipping tag and collection dropdowns. Primary modal container now handles all scrolling with `z-index: 200` on the dropdown list
+- **Double-card visual in Manage Collections** - `.collections-panel` previously had its own `surface-color` background + border inside the outer modal container, producing a visible "card in a card" look. Root set to `background: transparent` when rendered inside the modal
+- **Debug console.logs removed** - `AuthenticationSettings.svelte` no longer logs full auth config on every load; `files/[id]/+page.svelte` no longer logs every 5 minutes on video URL refresh
+- **Dead code removed** - Deleted unused `routes/Tasks.svelte.old` (868 lines) and the unused `AudioExtractionModal.svelte` (replaced by inline stepper step)
+- **Avatar lazy-loading** - Profile and cluster avatars on the Speakers page now use `loading="lazy"` and `decoding="async"`, preventing synchronous load-block on page init
 
 ### Upgrade Notes
 
@@ -184,6 +230,8 @@ docker compose pull
 docker compose up -d
 ```
 
+After upgrading, users should **hard-reload the frontend** (Ctrl+Shift+R / Cmd+Shift+R) to pick up the new service worker and clear any stale cached assets. The service worker will automatically cache the new build on next visit.
+
 The system will automatically detect the authentication configuration mode and function correctly. To use new authentication features:
 
 1. Log in as super admin

docs-site/blog/2026-02-07-v0.4.0-release.md

@@ -130,6 +130,71 @@ There's too much to list exhaustively, but here are the highlights:
 - **Russian UI language** -- 8th supported interface language (added in v0.3.3)
 - **Protected media auth** -- Plugin architecture for downloading from password-protected corporate video portals (v0.3.3)
 
+## The Final Polish: Frontend Hardening Sprint
+
+After the backend and pipeline work stabilized, we took a hard look at the frontend and found that two months of feature sprints had accumulated technical debt and security gaps that needed attention before shipping. A dedicated audit sprint closed those gaps.
+
+### Session Security
+
+The biggest finding: **Svelte stores persisted across logout**. Logging out as User A and logging in as User B on the same device leaked data from the previous session — toasts, search queries, gallery filters, upload queues, WebSocket notifications, transcript segments, speaker colors, and a dozen other pieces of state remained in memory. The auth cookie was invalidated on the backend, but the frontend kept showing User A's data until the next page reload.
+
+We fixed this with a **single source of truth for session teardown**: `frontend/src/lib/session/clearUserState.ts`. It clears 17+ subsystems in parallel on every login/logout transition, plus the user-scoped localStorage keys (notification queue, upload queue, remembered upload values). Preferences like theme, locale, and view mode are explicitly preserved — those are user choices, not user data.
+
+While we were in there, we also found and fixed three more session-level leaks:
+
+- **Flash of Authenticated Content (FOAC)** on fresh page loads. The layout's `{:else}` branch rendered the protected page slot for ~1-2 frames while the async `goto('/login')` was in flight. Unauthenticated users briefly saw the gallery UI AND triggered `/files` API calls. Fixed by gating all rendering behind `authReady && isAuthenticated && !isPublicPath`, showing a loading screen in the route-mismatch state.
+
+- **In-flight request race**. When a user clicks a file and immediately logs out, the `GET /files/{uuid}` response can still resolve after `clearUserState()` and repopulate the store. Fixed with a session-scoped `AbortController` in `lib/axios.ts` that cancels all pending requests on logout (except auth endpoints like `/auth/logout`, which must always complete).
+
+- **Back-button (bfcache) after logout**. Modern browsers restore pages from in-memory snapshots when users navigate back, bypassing all our auth guards and store clearing because the DOM is served from the cached snapshot. Fixed with a `pageshow` event listener that detects `event.persisted === true` and forces `window.location.reload()` to discard the snapshot.
+
+### XSS Hardening
+
+Audit turned up a **bypassable regex sanitizer** in the search result highlighting utility. The regex `/<(?!\/?mark[\s>])[^>]*>/g` only matched opening `<` characters, so a payload like `</mark><script>alert(1)</script><mark>` would pass through unscathed. Replaced with **DOMPurify**, using a strict tag whitelist that allows only the specific markup produced by the highlight pipeline (`mark`, `span`, `br`, `ul`, `li`, `em`, `strong`, `div`, `p` with `class` and `data-match-index` attributes).
+
+As defense-in-depth, we wrapped every other `{@html}` render site — 8 in total — with the same sanitizer: transcript segments, search highlights, LLM-generated topic summaries, AI summary sections. The underlying escape pipeline was already correct, but running everything through DOMPurify as a final pass means a future code change that forgets to escape can't introduce an XSS.
+
+And one config fix: **production source maps were enabled**. `.js.map` files exposed variable names, API endpoints, error messages, and the entire business logic to any visitor via DevTools. Disabled with a one-line `sourcemap: mode !== 'production'` change to `vite.config.ts`.
+
+### Upload Modal Redesign
+
+The old upload modal was a 4,603-line monolith with accordion sections that didn't scroll. We redesigned it as a **6-step linear stepper**:
+
+  Media → Tags → Collections → Speakers → Options → Submit
+
+Plus a conditional Extract step for large video files. The new flow decomposes the monolith into a 1,294-line coordinator plus 9 focused components (each under ~470 lines). All three upload sources (file, URL, recording) share steps 2-6, so URL downloads and recordings now get full tag/collection/speaker configuration — previously file-only.
+
+The stepper has a "Review with defaults" shortcut for power users who want to skip the middle, a "Remember previous values" feature that pre-fills from the last upload, and clickable step dots that let users jump back to any visited step. The backdrop no longer closes the modal (prevents data loss), and dropdowns for tags/collections were converted from auto-open search boxes to clean checkbox lists that don't visually explode on focus.
+
+### Skeleton Loaders Replace Spinners
+
+Research shows skeleton screens feel **~20% faster** than spinners for the same actual load time (Nielsen Norman). We replaced generic `<Spinner size="large"/>` loading states on four high-traffic pages with skeleton components that mirror the final layout:
+
+- **File detail page** — full 2-column skeleton with header/video/transcript shapes
+- **Home gallery** — card grid skeleton matching the media file layout
+- **Search results** — horizontal search-card skeleton with thumbnail + snippet shape
+- **Speaker clusters/profiles/inbox** — list row and profile card skeletons
+
+The new `FileDetailSkeleton`, `CardGridSkeleton`, and `ListRowSkeleton` components live in `frontend/src/components/` and `frontend/src/components/ui/` and are reusable across any page with a predictable layout. Loading feels structured and anticipatory instead of "waiting."
+
+### Gallery Click Feedback
+
+Clicking a file card used to have a visible delay before the detail page appeared, leading users to click twice (and briefly see the same file loaded twice). Fixed with a three-layer approach:
+
+1. **Instant press state** — dims the clicked card (opacity 0.72, scale 0.985) and disables `pointer-events` on click
+2. **Double-click guard** — the `navigatingTo` state variable prevents the second click from firing
+3. **Prefetch on mousedown** — kicks off `/files/{uuid}` ~50-100ms before the click handler runs, giving the browser a head start
+
+Users now get immediate visual feedback (~16ms) plus a shorter actual wait.
+
+### Collection & Share Modal Polish
+
+The Create/Edit Collection modals were bare forms with no explanation. Added intro banners, field hints with `maxlength` indicators, and pre-selected the Universal Content Analyzer prompt (the system default) so new collections work out of the box.
+
+The Share Collection modal got the biggest facelift: an introductory sentence explaining what sharing does, a collection name banner with a folder icon, and a permission-level reference card showing Viewer/Editor labels inline with descriptions (previously those descriptions only appeared in tooltips, invisible to most users). Empty state added for collections with no existing shares so the modal doesn't look broken on first open.
+
+Also fixed a long-standing visual glitch where the Manage Collections modal showed a gray "card within a card" — the inner panel had its own surface background that duplicated the outer modal container.
+
 ## Lessons from 1,400 Podcasts
 
 Processing real data at scale taught us things that unit tests never would: