About TidyTube

Inspiration

YouTube is arguably the world's greatest open repository of human knowledge. Whether you are learning full-stack development, mastering complex mathematics, studying university lectures, or picking up a new craft, world-class instruction is available for free at your fingertips.

However, the modern YouTube experience is heavily optimized for algorithmic engagement rather than intentional learning. The second you open the homepage, you are greeted by sensational thumbnails, algorithmic rabbit holes, and infinite feeds engineered to capture and hold your attention. A quick search for a 5-minute code snippet often spirals into hours of wasted time.

Even worse, the rise of vertical YouTube Shorts introduced an aggressive infinite-scroll loop directly into the desktop experience—stripping away essential learning tools like seek bars, precise scrubbing, playback speed adjustment, and keyboard navigation.

We built TidyTube to solve this problem. Our goal was simple: transform YouTube from a noisy attention casino back into a calm, focused, and intentional workspace. We wanted a lightweight, cross-browser tool that silences algorithmic distractions without breaking page layouts, respects user agency, and makes studying long-form content enjoyable again.

What it does

TidyTube is a route-aware, distraction-free browser extension for Chromium and Firefox that cleans up YouTube's UI and gives users complete control over their viewing environment via a clean toolbar popup.

• 🏠 Homepage Decluttering:

  • Hide Algorithmic Feed: Replaces the endless recommendations grid on the homepage with a clean, calm space, allowing you to open YouTube with clear intent.
  • Hide Shorts Shelves: Completely removes vertical Shorts carousels from the homepage.

• 🔍 Search Results Focus:

  • Strip Shorts Shelves: Filters out vertical Shorts reels and carousels from search results so you only see the relevant, long-form tutorials and lectures you actually searched for.

• 🎬 Distraction-Free Watch Page (/watch):

  • Master Focus Switch: Silence all watch page distractions with a single click.
  • Sidebar Recommendations: Removes the addictive "Up Next" / related videos column.
  • Comments & Live Chat: Hides comment sections and live chat streams to eliminate endless discussions and arguments.
  • End-Screen Video Cards: Prevents suggestion tiles from popping up over the final seconds of a video.
  • Info Cards: Suppresses in-player teaser cards and drawer prompts during playback.

• 🔀 Shorts to Standard Player Redirect:

  • Automatically intercepts /shorts/:id links and reroutes them to the standard /watch?v=:id player.
  • Restores all standard video controls: timeline scrubbing, playback speed toggles, theater mode, and keyboard shortcuts—while eliminating the vertical doomscroll trap.

• ⏱️ Playlist Total Duration Calculator (/playlist):

  • Displays cumulative runtime directly in the left sidebar metadata block beneath video and view counts (e.g., 14h 25m).
  • Features dynamic on-scroll calculation for large playlists, skips deleted/private videos, and gracefully handles continuous radio mixes (list=RD...) with an infinity symbol (∞).

• ⚡ Instant Zero-Flicker Reactivity:

  • Changes made in the popup update all open YouTube tabs in real time without requiring page refreshes or causing visual flicker. Settings persist locally in browser storage.

How we built it

TidyTube was built from the ground up using a modern web extension architecture:

• Framework & Build System: Built on WXT (Next-Gen Web Extension Framework) powered by Vite, generating clean Manifest V3 (MV3) bundles for both Chromium browsers (Chrome, Brave, Edge) and Firefox.
• Popup User Interface: Designed with React 18, TypeScript, and Tailwind CSS 3.4. We used semantic design tokens (bg-primary, text-onPrimary, border-border, accent-accent) aligned with YouTube's dark aesthetic (#0f0f0f background, #272727 borders, and YouTube red #FF0000 accents).
• Dynamic CSS Injection Engine (style-injector.ts): Rather than performing heavy, flickering JavaScript DOM removal that causes layout shifts, TidyTube compiles active user settings into scoped CSS rules injected directly into a <style id="tidytube-styles"> tag. An in-memory cache ensures zero-latency application across page transitions.
• Client-Side Shorts Redirector (shorts-redirector.ts): Listens to YouTube's internal SPA navigation events (yt-navigate-finish, popstate) and intercepts click events across the Shadow DOM boundary using event.composedPath() to seamlessly reroute /shorts/ URLs to /watch?v= via window.location.replace.
• High-Performance Playlist Calculator (playlist-timer.ts): Scans playlist video duration badges and caches parsed durations in an $O(\Delta N)$ Map<string, number> keyed by video ID. A 300ms debounce ensures that lazy-loaded batches update the total duration smoothly without dropping frames or triggering unnecessary recalculations.
• Typed Storage Manager (storage.ts): Cross-browser abstraction over browser.storage.local with full TypeScript schemas and reactive listeners for real-time state synchronization.

Challenges we ran into

1. Navigating YouTube's Single-Page App (SPA) Architecture: YouTube does not perform standard full-page reloads when navigating between Home, Search, Watch, or Playlist pages. Standard DOMContentLoaded or load events fire only once. We had to hook deeply into YouTube's internal event lifecycle (yt-navigate-finish, yt-page-data-updated, and popstate) to guarantee that route-specific rules and observers re-evaluate instantly.

2. Shadow DOM & Lit Web Components: Modern YouTube increasingly renders UI elements using Lit Web Components (shorts-lockup-view-model, grid-shelf-view-model) and encapsulated Shadow DOM trees. Standard click listeners on window or document failed to catch link clicks because the event targets were retargeted. We solved this by inspecting event.composedPath() to identify Shorts navigation before YouTube's internal router executed.

3. Preventing Visual Flicker (FOUC) and Layout Thrashing: Hiding elements via JavaScript after they mount causes a jarring "flash of unstyled content" where recommendations appear for a split second before vanishing. We eliminated this by relying on dynamic, in-memory cached CSS injection, ensuring that hidden sections are suppressed before the browser paints them.

4. Shorts Redirection Loops & History Pollution: Naively redirecting /shorts/ to /watch?v= using window.location.href pushed extra entries onto the browser history stack, trapping users in infinite redirect loops when hitting the browser "Back" button. We overcame this by using window.location.replace and coordinating tightly with YouTube's SPA router.

5. Dynamic Lazy Loading in Playlists: YouTube only renders the first ~100 videos of a playlist, rendering additional batches as the user scrolls. Recalculating hundreds of DOM nodes on every scroll event caused noticeable stutter. We designed an incremental caching layer that only parses newly added nodes in $O(\Delta N)$ time, keeping performance silky smooth.

Accomplishments that we're proud of

• Silky-Smooth, Native User Experience: TidyTube blends seamlessly into YouTube. There are no sluggish delays, no page reload requirements, and no jarring UI pops. It looks and feels like an official YouTube Pro setting.
• Instant Cross-Tab Synchronization: Toggling any setting in the popup instantly reflects across all open YouTube tabs simultaneously through reactive storage events.
• Reclaiming Control from Shorts: Transforming addictive, swipe-based vertical Shorts back into full-featured video players restores time scrubbing, custom playback speeds, and theater mode.
• Robust Playlist Duration Engine: Creating a rock-solid playlist calculator that effortlessly handles lazy loading, skips unlisted/deleted videos, and accounts for infinite continuous mixes (∞).
• Cross-Browser Manifest V3 Ready: Built fully compliant with modern Manifest V3 standards for Chrome, Brave, Edge, and Firefox with strict TypeScript type safety.
• Clean Stepwise Engineering: Breaking a complex, multi-surface browser extension into well-defined, independently verifiable vertical slices from plan to release.

What we learned

• Advanced Browser Extension Patterns: Gained deep experience with Manifest V3 service workers, content script sandboxing, and unified cross-browser storage APIs.
• Single-Page Application Internals: Learned how to safely observe and intercept client-side routing, custom element lifecycles, and Shadow DOM event propagation on one of the world's largest web applications.
• Performance-First Extension Design: Discovered that declarative CSS injection paired with in-memory caching provides a vastly superior user experience compared to heavy JavaScript DOM manipulation.
• The Value of Structured Planning: Following a plan-first discipline—progressing through scoping, product requirements, technical specifications, and bite-sized vertical slices—prevented feature bloat and made development fast, focused, and enjoyable.

What's next for TidyTube

• 🖥️ Full-Width Theater Mode: An optional cinema mode toggle that expands the primary video player to fill the entire viewport width for an immersive lecture experience.
• ⌨️ Customizable Keyboard Shortcuts: Fast hotkeys to quickly toggle comments or sidebar recommendations on the fly without clicking into the toolbar popup.
• ✨ Playlist Study Planner with Speed Multipliers: An interactive calculator in the playlist sidebar showing estimated completion times at different playback speeds (1.25x, 1.5x, 1.75x, 2x) to help students schedule their study sessions.
• 🎯 Creator & Channel Whitelisting: The ability to selectively allow comments or recommendations on specific educational channels while keeping the rest of YouTube quiet.
• 🚀 Official Store Distribution: Packaging and publishing TidyTube to the Chrome Web Store and Firefox Add-ons repository so learners and developers everywhere can reclaim their focus.

Built With

• react
• typscript
• wxt