refactor: Proposal for refactor in SvelteKit with Storybook

[Hazer]

Description

A complete rewrite of the Koko web client from vanilla TypeScript to Svelte 5 (runes) + SvelteKit, along with server-side improvements. This is a draft PR for early review — seeking architecture and approach feedback before finalizing.

Why Svelte 5 + SvelteKit?

The vanilla client is imperative: hand-written string-template HTML, manual addEventListener for every interaction (1395 lines in eventBindings.ts), a custom DOM diffing layer (domPatcher.ts, 290 lines), and a single mutable AppState object that triggers a full re-render on every change. This works but creates maintenance friction: adding a feature means wiring new event listeners, managing DOM updates manually, and ensuring the diff patcher handles the new markup.

Svelte 5 with runes was chosen because it's the closest step from vanilla while gaining reactive state management:

• Compiled, not interpreted. Svelte compiles to vanilla JS at build time — there's no virtual DOM runtime overhead. The output is vanilla DOM manipulation, same as what domPatcher.ts does by hand, but generated correctly by the compiler. This makes it nearly as lightweight as the current vanilla approach, unlike React/Vue which ship a runtime.
• Runes make state explicit. $state, $derived, $effect are compile-time annotations that tell Svelte what to track. No proxy wrapping, no hook rules, no mental model gap. A $state field is just a variable the compiler knows to make reactive. This is conceptually similar to how the vanilla code mutates state and calls render() — but automatic.
• SvelteKit provides routing + build. The vanilla client has a hand-rolled router (routes.ts + hash-based navigation). SvelteKit provides file-based routing, code-splitting, and the adapter-static output (SPA mode) the Rust server already serves. The build output is static HTML/JS/CSS — same as what the server serves today.
• The learning curve is minimal. Svelte templates look like HTML. Stores look like classes with $state fields. There's no JSX, no hooks, no provider tree. A contributor who knows HTML/CSS/JS can read a .svelte file and understand it immediately.

Where it's close to vanilla: the build output is vanilla DOM manipulation. The bundle includes the Svelte runtime (~10KB gzipped) + SvelteKit client (~20KB). The vanilla client's bundle is smaller, but the difference is marginal compared to the maintenance benefit.

What changed

New: crates/client-web-svelte/ — the full rewrite. The vanilla client (crates/client-web/) is untouched.

Server: crates/server/ — transcode streaming now sends X-Content-Duration header + ffmpeg -t flag so fragmented-MP4 streams carry a proper total duration (fixes the growing-duration bug during transcoding).

Architecture: component structure

The vanilla client has ~15 flat render functions. The rewrite organizes into a structured component taxonomy:

src/lib/components/
├── Leaf UI: Button, Icon, CardSurface, MediaCard,
│   PersonCard, MediaExtraCard, CollapsibleText, UserAvatar
├── Section*: page-section members of the item-detail page
│   SectionHero, SectionSupport, SectionPeople,
│   SectionExtras, SectionChildren, SectionBreadcrumbs
├── Sub-components: HeroActions, FactList, SupportFileInfo,
│   SupportMetadata, MetadataSearchPanel
├── Page fragments: BrowseListing (+ Hero/Grid), HomeContent,
│   HomeFeature, HomeNavbar, Rail, Shelf, PersonHero
├── Settings: GeneralForm, UserManagement, LibrarySettings,
│   ProviderSettings, ScheduledTasks, MetadataDashboard,
│   SystemActivities, LogViewer, SettingsShell
└── Player: MediaPlayer, PlayerControls, AudioTrackMenu,
    TrailerPlayer, ThemeSongPlayer, YouTubeIframe, ControlsHelp

Why this matters for maintenance: Section* components are direct children of the item-detail page — their name tells you where they render. Leaf components (Button, Icon, CardSurface) are reusable building blocks. A contributor looking for "the hero section" finds SectionHero.svelte immediately, instead of grepping through itemPersonView.ts for the right render function. Splitting SectionSupport into SupportFileInfo + SupportMetadata means each panel can be tested and modified independently — the two panels share no state.

The naming convention scales: Section* = a <section> in the page stack, unprefixed = a sub-component or leaf, BrowseListing = a routed page (not a Section). Phase 5 Settings added 9 new components following the same convention with zero ambiguity about where each belongs.

Architecture: reactive stores

The vanilla client's AppState is a single mutable object. Any change triggers render(), which re-renders the entire DOM tree (mitigated by domPatcher.ts). The rewrite splits this into 8 domain stores, each a class with $state fields:

stores/
├── auth.svelte.ts     — bootstrap, login, user CRUD
├── catalog.svelte.ts  — home shelves, library items, search
├── item.svelte.ts     — item detail, metadata, playback decision
├── libraries.svelte.ts — library list, scan, refresh
├── settings.svelte.ts  — settings CRUD, providers
├── activities.svelte.ts — activities, logs, polling
├── playback.svelte.ts  — session, player state, seek
└── ui.svelte.ts       — error banner, help modal

Why this improves maintainability: a bug in metadata search only requires reading item.svelte.ts + MetadataSearchPanel.svelte — not the entire eventBindings.ts (1395 lines) to find which listener handles the form submit. Each store is independently testable. State changes are surgical — updating catalog.searchQuery only re-renders the search results, not the entire page. The vanilla domPatcher.ts diff layer (290 lines) is eliminated entirely — the Svelte compiler generates the same surgical updates automatically.

Architecture: the player

The vanilla playbackController.ts (1385 lines) is imperative DOM: querySelector for every control, addEventListener for every interaction, classList.toggle for state changes, manual render() calls to recreate the <video> element on audio-track switches. The rewrite replaces this with:

• playback.svelte.ts store (~250 lines) — session lifecycle, player element state, seek logic, progress reporting
• 8 player components (~400 lines total) — MediaPlayer, PlayerControls, AudioTrackMenu, TrailerPlayer, ThemeSongPlayer, YouTubeIframe, ControlsHelp, PlayerOverlay

Concrete improvement: when the user switches audio tracks, the vanilla code does state.activeAudioStreamIndex = X; render(false) — a full DOM re-render to recreate the <video> element with a new src. The rewrite changes playback.activeAudioStreamIndex → the derived streamUrl updates → Svelte patches the src attribute → the browser reloads the stream. No DOM re-render, no manual render call, ~50 lines of logic vs ~200.

Player UI improvements

• Gradient fallback for media cards without artwork — the vanilla .media-card-art lacks overflow: hidden, so gradient fallbacks bleed past the 18px border radius. Fixed with overflow: hidden (scoped).
• Hover behavior — vanilla's global button:hover lifts the entire card (including text below the poster) with a blue shadow. Fixed: only the poster tile lifts, not the text block.
• Button spinner centering — vanilla's button.is-busy::after has position: absolute but no centering, so the spinner renders off-center to the right. Fixed with inset: 0; margin: auto (scoped to Button.svelte).
• Slider full-range movement — native <input type="range"> thumbs can't reach true 0/max (the thumb width creates dead zones). Fixed with custom WebKit/Firefox thumb CSS so the progress bar and volume slider fill edge-to-edge.
• Duration pinning during transcoding — the <video> element's reported duration grows as fragmented-MP4 fragments arrive. Fixed by pinning from item metadata (matching vanilla's intended behavior) + server-side X-Content-Duration header + ffmpeg -t flag.

Gamepad + remote navigation

The rewrite includes a full gamepad navigation system for couch/TV use:

Isolated gamepad package (src/lib/gamepad/) — framework-agnostic, designed to be extractable as a standalone library:

• Layout detection — auto-detects the connected controller's button/stick mapping. Supports: standard W3C mapping (Xbox, DualSense, Switch Pro, Steam Deck), and custom layouts for non-standard controllers like the 8BitDo Pro 3 (D-pad on hat axis 9 with neutral value 3.286, Nintendo-style A/B swap, right stick on axes [2,5]).
• Hat-axis parser — pure function that maps 8-position hat values to cardinal directions, handling both standard (neutral=0) and non-standard (neutral=3.286) controllers. 15 unit tests.
• Stick filtering — radial deadzone, hysteresis, direction detection. 14 unit tests.
• rAF polling engine — reads gamepads every frame, normalizes via detected layout, emits a GamepadInput object. Layout results are cached per gamepad index.

Spatial navigation — direction-aware focus management. Unlike the vanilla client's linear focus cycling (±1 in DOM order, where D-pad up/down/left/right all do the same thing), this finds the nearest focusable element in the requested direction using geometric distance.

Declarative navigation regions — each major UI area (sidebar, navbar, content, settings) registers itself as a region with entry points + internal navigation. When a region can't handle a direction (edge reached), the engine transitions to the adjacent region using declared entry points. This makes navigation predictable: "left from shelf" always goes to the Home button, not whichever sidebar element is closest.

Controls help modal — press the Select/Back button on a gamepad (or ? on keyboard) to see a context-aware controls reference showing what each button does in the current mode (browse vs player).

Analog stick debounce — the stick takes only the dominant direction (up/down/left/right), fires once, discards input for 600ms, then repeats at 350ms intervals. The raw magnitude is never used for UI navigation. This prevents the "one tap moves 10 elements" problem.

Current status: functional but still being tuned. Known issues: shelf scroll-up visibility needs refinement, item-detail and settings pages don't have regions wired yet (fallback to spatial search), sometimes the sidebar item nav is not working as expected.

Control mapping:

Input	Browse	Player
D-pad / Left stick	Spatial focus navigation	Seek (escalating)
Right stick	—	Volume (up/down)
A button	Activate / click	Play / pause
B button	Back (history)	Close player
L / R bumper	Switch tabs	—
Select	Controls help	Controls help

Mock API

The vanilla client already had a mock API layer for development without a backend. The rewrite ports and extends this — the same mock endpoints exist, with additions for the new features (playback sessions, settings CRUD, scheduled tasks, dashboard items, metadata search/link). The mock layer is gated by VITE_USE_MOCK_API and fully powers the Storybook stories. The key difference: the rewrite removed the dev-mode silent fallback that would flip to mock mode on any API failure (including auth errors) — this was masking real connection issues during development.

Storybook

98 stories across 30 groups with dark theme, preset dropdown (selectable fixture bundles), and store-driven disclaimers. The vanilla client has no Storybook. Each component can be previewed in isolation with realistic mock data — a MediaCard with artwork, a player controls bar in playing/paused state, a settings library card with scan/refresh actions, etc.

Screenshot

TODO — will add screenshots before marking ready for review.

Issues Fixed or Closed

• Fixes player duration expanding during transcoding (duration pinned from item metadata + server-side X-Content-Duration header + ffmpeg -t)

Roadmap Issues

N/A

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
10 New issues
10.4% Duplication on New Code (required ≤ 2%)
25 Duplicated Blocks on New Code (required ≤ 0)
10 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE