# Settings Modal Redesign — Design Document

**Date:** 2026-02-18
**Version:** PulseJT 3.3.0 -> 3.4.0
**Scope:** Settings modal visual redesign, new tabs, responsiveness

---

## Goals

1. **Add new settings** — Playback controls and background customization that scale well within the existing tab architecture
2. **Visual redesign** — Glassmorphism treatment (frosted glass, blur, theme-matched glows)
3. **Responsiveness** — Adapt gracefully to narrow CEP panel widths

## Approach

**Enhanced Tab System** — Add 2 new tabs (Playback, Background), merge Help into Info, redesign all tabs with glassmorphism styling. Each tab's content scrolls independently.

---

## Tab Structure

| Tab | Icon | Content |
|-----|------|---------|
| General | gear | Theme grid, rounded corners toggle, error suppression, performance mode |
| Playback | play | Video volume (moved from General), playback speed, loop toggle, autoplay toggle |
| Background | image | Background type selector, solid color picker, checkerboard, custom image upload |
| History | folder | Recent 12 items grid (unchanged) |
| Info | info | Version, authors, license status, terms, Discord link, quick tips, debug logs (merged from Help) |

Help/Contact content merges into Info tab footer to free the tab slot without overcrowding the tab bar.

---

## Visual Style — Glassmorphism

### Modal Card
- Semi-transparent background with `backdrop-filter: blur(16px)`
- Subtle border glow matching active theme accent color
- 12px border radius

### Tab Bar
- Frosted glass strip along the top
- Active tab: soft underline glow in theme accent color
- Inactive tabs: muted text with subtle hover glow

### Setting Rows
- Each `.settingRow` gets frosted glass card treatment
- Slightly lighter bg than modal, 1px border at ~10% white opacity, 8px border radius
- 8px gap between cards

### Theme Grid Cards
- Existing gradient previews stay
- Glass border treatment, pronounced selection state (glow ring)

### Scrollbar
- Custom thin scrollbar matching theme accent (existing, refined)

### Transitions
- 200ms smooth transitions on tab switches (fade/slide), hover states, toggle interactions

---

## New Settings — Playback Tab

### Video Volume (relocated from General)
- Mute button + slider + percentage display (existing implementation, moved)

### Playback Speed
- Segmented control or dropdown: 0.25x, 0.5x, 0.75x, **1x** (default), 1.5x, 2x
- Applies to video and GIF playback
- Storage key: `gifPreview.playbackSpeed`

### Loop Behavior
- Toggle: Loop On/Off (default: On)
- When Off, media plays once and stops on last frame
- Storage key: `gifPreview.loopEnabled`

### Autoplay
- Toggle: Autoplay On/Off (default: On)
- When Off, media loads paused, user clicks to play
- Storage key: `gifPreview.autoplay`

### GIF Frame Stepping (deferred)
- Requires canvas-based GIF rendering — planned for future version

---

## New Settings — Background Tab

### Background Type Selector
Segmented control with 4 options:

1. **Default** — Uses current theme background (existing behavior)
2. **Solid Color** — Custom backdrop color
3. **Checkerboard** — Transparency grid pattern
4. **Custom Image** — Uploaded background image

### Solid Color
- Native `<input type="color">` with hex text display
- Storage key: `gifPreview.bgColor`

### Checkerboard
- Two preset sizes: Small (8px), Large (16px)
- Light/Dark variant toggle
- Storage keys: `gifPreview.bgCheckerSize`, `gifPreview.bgCheckerVariant`

### Custom Image
- File input accepting image formats
- Fit mode: Cover / Tile
- Opacity slider (0-100%)
- Stored as data URL in localStorage (with size warning if >1MB)
- Storage keys: `gifPreview.bgImage`, `gifPreview.bgImageFit`, `gifPreview.bgImageOpacity`

---

## Responsiveness

### Breakpoints

| Width | Behavior |
|-------|----------|
| 400px+ (normal) | Full layout: icon + label tabs, 4-column theme grid |
| 300-399px (narrow) | Icon-only tabs, 3-column theme grid, tighter padding |
| <300px (very narrow) | Icon-only tabs, 2-column theme grid, stacked volume control |

### Height Handling
- Each tab page scrolls independently
- Sticky tab bar (top) and footer (bottom)
- Content area: `flex: 1; overflow-y: auto`

### Modal Sizing
- `max-height: calc(100vh - 24px)` — always fits panel
- `min-height: 300px` — prevents unusable collapsed state

---

## Storage Keys Summary

New keys (all prefixed `gifPreview.`):

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `playbackSpeed` | number | 1 | Video/GIF playback rate |
| `loopEnabled` | boolean | true | Loop media playback |
| `autoplay` | boolean | true | Auto-start media on load |
| `bgType` | string | "default" | Background type: default/color/checker/image |
| `bgColor` | string | "#000000" | Solid background color |
| `bgCheckerSize` | string | "small" | Checkerboard size: small/large |
| `bgCheckerVariant` | string | "dark" | Checkerboard variant: light/dark |
| `bgImage` | string | "" | Background image data URL |
| `bgImageFit` | string | "cover" | Background image fit: cover/tile |
| `bgImageOpacity` | number | 1 | Background image opacity (0-1) |

---

## Files to Modify

- `index.html` — New tab buttons, Playback tab content, Background tab content, merge Help into Info
- `style.css` — Glassmorphism styles, new component styles, responsive breakpoints
- `JS/bundle.js` — New settings initialization, localStorage read/write, playback speed/loop/autoplay logic, background rendering
- `assets/index.html` — Mirror changes (asset copy)
- `assets/style.css` — Mirror changes (asset copy)
