# TutorialVault — 15 UI Enhancements Design

**Goal:** Add 15 real, polished enhancements to the TutorialVault frontend — all WCAG 2.2 AAA compliant.

**Architecture:** All changes are frontend-only (TypeScript + CSS). No Rust/backend changes needed. Each enhancement is independent — no cross-dependencies between them.

**Tech Stack:** TypeScript, CSS, HTML (Tauri v2 webview frontend)

---

## Enhancement 1: Mute Toggle (M key + volume icon click)

**What:** Press `M` to toggle mute. Click the volume icon to toggle mute. Muted state shows `fa-volume-xmark`, grays out the slider. Unmuting restores previous volume.

**Files:** `main.ts`, `player.ts`, `player.css`

**Behavior:**
- Store `lastVolume` before muting. Set volume to 0 on mute.
- On unmute, restore `lastVolume` (default 1.0 if none stored).
- Volume icon dynamically swaps: `fa-volume-high` (>50%), `fa-volume-low` (>0%), `fa-volume-xmark` (0/muted).
- Dragging the volume slider while muted unmutes automatically.

**WCAG:** Volume icon gets `aria-label="Mute"/"Unmute"` dynamically. Muted visual uses icon change + reduced opacity (not color alone).

---

## Enhancement 2: Fullscreen Shortcut (F key)

**What:** Press `F` to toggle fullscreen. Mirrors the existing fullscreen button behavior.

**Files:** `main.ts`

**Behavior:** Add `case 'f':` to the keyboard switch. Calls the same fullscreen toggle as `fsBtn.onclick`.

**WCAG:** No visual changes needed.

---

## Enhancement 3: Seek Feedback Overlay

**What:** Flash `−5s` / `+5s` text in the video overlay when seeking via arrow keys. Fades after 600ms.

**Files:** `main.ts`, `player.ts`, `player.css`

**Behavior:**
- New `showSeekFeedback(delta: number)` function in player.ts.
- Reuses the existing video overlay area. Shows text like "−5s" or "+5s" centered.
- Uses a CSS class `.seekFeedback` that fades in/out.
- Consecutive presses accumulate: pressing ArrowRight 3 times quickly shows "+15s".

**WCAG:** Overlay area has `aria-live="assertive"` so screen readers announce "Seeked forward 5 seconds". Text meets 7:1 contrast (white on semi-transparent dark).

---

## Enhancement 4: Playlist Search/Filter

**What:** Search input above the playlist. Typing filters by video name or relative path in real-time. Shows "X of Y" while filtering. Clear button (x) resets.

**Files:** `index.html`, `playlist.ts`, `playlist.css`

**Behavior:**
- Add `<input id="plistSearch">` in the playlist `.panelHeader`.
- `renderList()` checks the filter value and skips non-matching items.
- Filter is case-insensitive, matches against `it.title`, `it.name`, `it.relpath`.
- Clear button appears only when input has text.
- Pressing Escape in the search input clears it.

**WCAG:** `aria-label="Search playlist"`. Filtered count via `aria-live="polite"` region. Clear button has 44x44 target and `aria-label="Clear search"`.

---

## Enhancement 5: Scroll-to-Current Button

**What:** Button in playlist header that scrolls the active item into view. Only visible when the active item is off-screen.

**Files:** `index.html`, `playlist.ts`, `playlist.css`

**Behavior:**
- Uses `IntersectionObserver` on the `.row.active` element.
- Button appears (fades in) when active row is not visible.
- Clicking calls `activeRow.scrollIntoView({ block: 'center', behavior: 'smooth' })`.
- Icon: `fa-crosshairs` or `fa-location-dot`.

**WCAG:** `aria-label="Scroll to current video"`. 44x44 touch target. Hidden with `display:none` when not actionable (removed from a11y tree).

---

## Enhancement 6: Picture-in-Picture Button

**What:** PiP toggle button next to the fullscreen button. Uses native `requestPictureInPicture()` API.

**Files:** `index.html`, `player.ts`

**Behavior:**
- New `iconBtn` after fsBtn: `<button class="iconBtn" id="pipBtn">`.
- Icon swaps: `fa-up-right-from-square` (enter PiP) / `fa-down-left-and-up-right-to-center` (exit PiP).
- Listen to `enterpictureinpicture` / `leavepictureinpicture` events to update icon.
- Feature-detect: hide button if `document.pictureInPictureEnabled` is false.

**WCAG:** Dynamic `aria-label="Enter picture-in-picture"/"Exit picture-in-picture"`. Same focus-visible ring as all icon buttons.

---

## Enhancement 7: Timestamp Insertion in Notes

**What:** Button in the notes dock header that inserts `[MM:SS] ` at the textarea cursor position using the current video time.

**Files:** `index.html`, `ui.ts`, `panels.css`

**Behavior:**
- Small button in `#notesHeader`: `<button id="insertTimestamp" aria-label="Insert timestamp">`.
- Icon: `fa-clock` or `fa-stopwatch`.
- On click: read `player.currentTime`, format as `[M:SS]`, insert at `notesBox.selectionStart`.
- After insert, focus the textarea and place cursor after the inserted text.

**WCAG:** `aria-label="Insert timestamp"`. 44x44 target via `::before` expansion. `data-tooltip` for hover discoverability.

---

## Enhancement 8: Keyboard Shortcut Help Panel

**What:** Press `?` to open a help overlay listing all keyboard shortcuts. Press `?` or `Escape` to close.

**Files:** `index.html`, `main.ts`, `main.css` or `components.css`

**Behavior:**
- Hidden `<div id="shortcutHelp" role="dialog" aria-label="Keyboard shortcuts">` in HTML.
- Two-column grid showing key + description pairs.
- Shortcuts shown: Space (play/pause), Left/Right (seek ±5s), Up/Down (volume), M (mute), F (fullscreen), [ / ] (speed), Alt+Arrow (reorder playlist), ? (this help).
- Focus trap inside the dialog while open.
- Semi-transparent dark backdrop.

**WCAG:** `role="dialog"` with `aria-label`. Focus trapped. Escape closes. All text 7:1 contrast. Backdrop doesn't remove background content from a11y tree (uses `aria-hidden="true"` on app root while dialog is open).

---

## Enhancement 9: Playback Speed Shortcuts ([ and ])

**What:** Press `[` to decrease speed one step, `]` to increase speed one step through the SPEEDS array.

**Files:** `main.ts`, `player.ts`

**Behavior:**
- New `cycleSpeed(delta: number)` exported from player.ts.
- Finds current speed in SPEEDS array, moves by delta (clamped to bounds).
- Updates speed button text, gauge icon, and saves to backend.
- Shows toast notification: "Speed: 1.25x".

**WCAG:** Speed change announced via toast (existing `aria-live="polite"` region).

---

## Enhancement 10: Reset Progress Confirmation

**What:** Two-click confirmation before resetting progress. First click changes button to "Confirm?" state with red tint. Second click within 3 seconds actually resets. Timeout or click-away cancels.

**Files:** `ui.ts`, `main.css`

**Behavior:**
- First click: add `.confirming` class, change icon to `fa-exclamation-triangle`, start 3s timer.
- Second click while `.confirming`: execute the actual reset.
- Timer expiry or blur: remove `.confirming`, restore original icon.
- `.confirming` state: red-tinted background (`rgba(255,70,70,.14)`).

**WCAG:** `aria-label` changes to "Confirm reset progress" in confirm state. Visual change uses both color AND icon change (not color alone).

---

## Enhancement 11: Video Load Error State

**What:** When the `<video>` fires an error event, show a centered overlay with warning icon, error message, and "Try next" button.

**Files:** `player.ts`, `player.css`

**Behavior:**
- Listen to `player.addEventListener('error', ...)`.
- Create/show error overlay inside `.videoWrap` with `fa-triangle-exclamation` icon.
- Message: "This file format may not be supported. Try MP4 (H.264/AAC) or WebM."
- "Try next" button calls `nextPrev(+1)`.
- Overlay clears on next successful `loadedmetadata`.

**WCAG:** `role="alert"` for screen reader announcement. "Try next" button has 44x44 target. Error text meets 7:1 contrast.

---

## Enhancement 12: Double-Click to Fullscreen

**What:** Double-clicking the video toggles fullscreen. Single click still toggles play/pause.

**Files:** `player.ts`

**Behavior:**
- Replace simple click handler with a click/double-click discriminator.
- On click: set a 300ms timer. If no second click arrives, toggle play/pause.
- On double-click: cancel the timer, toggle fullscreen instead.
- `dblclick` event on the video overlay area.

**WCAG:** Mouse/touch enhancement only. Fullscreen remains keyboard-accessible via F key and button.

---

## Enhancement 13: Playlist Stats in Header

**What:** Show video count and completion info next to "Playlist" header. E.g., "24 videos  ·  8 done".

**Files:** `index.html`, `playlist.ts`

**Behavior:**
- Add `<span class="plistStats" id="plistStats"></span>` in the panelHeader.
- In `renderList()`: compute total count, done count, update the span.
- Styled as `--textMuted`, smaller font (11px), monospace.

**WCAG:** Stats text meets 7:1 contrast. Updated via DOM so screen readers can read it on demand.

---

## Enhancement 14: Mini Progress Bars Per Playlist Item

**What:** Thin 2px progress bar at the bottom of each playlist row showing watched/total. Green for done, accent blue for in-progress.

**Files:** `playlist.ts`, `playlist.css`

**Behavior:**
- For each row in `renderList()`, create a `.rowProgress` div.
- Width: `(watched / duration) * 100%`. If duration is null, hide.
- Color: `--success` for done items, `--accent` for in-progress.
- Positioned absolutely at bottom of the row.

**WCAG:** `aria-hidden="true"` — numeric info already in the row's `aria-label`. Colors pass 3:1 minimum for non-text contrast per WCAG 2.2.

---

## Enhancement 15: Collapsible Dock Panes

**What:** Clicking a dock header collapses that pane, giving the other pane full height. Collapsed state shows just the header with a chevron. Persisted via prefs.

**Files:** `ui.ts`, `panels.css`, `index.html`

**Behavior:**
- Click on `.dockHeader` toggles `.collapsed` on the parent `.dockPane`.
- Collapsed: `flex:0 0 auto`, content inside has `display:none`.
- Chevron icon in header rotates to indicate collapsed/expanded.
- Collapsing one pane doesn't collapse the other.
- State saved in prefs as `notes_collapsed` / `info_collapsed` booleans.

**WCAG:** Headers get `aria-expanded="true"/"false"`. Chevron is `aria-hidden="true"`. Enter/Space on header toggles. Collapsed content is `display:none` (removed from a11y tree).

---

## Approach

**Single-pass, all frontend:** Every enhancement modifies only TypeScript and CSS files. No backend/Rust changes. Each enhancement is independent and can be implemented in any order.

**Implementation strategy:** Direct edits to existing files using Edit/Write tools. No subagents for file editing. Each enhancement touches 1-3 files. Build verification after each enhancement or batch.

**Testing:** `npm run build` (TypeScript compilation + Vite build) after each enhancement to catch errors immediately.