From 96c97071136ec81e065def59969a948efb88be6c Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Thu, 25 Sep 2025 16:30:12 -0400
Subject: [PATCH] Document fade-in safeguards

---
 components/sidebar.html |  7 +++++-
 css/style.css           | 46 ++++++++++++++++++++++++++++++++-
 index.html              | 23 +++++++++++++----
 js/app.js               | 13 ++++++++--
 js/index.js             | 56 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 136 insertions(+), 9 deletions(-)

diff --git a/components/sidebar.html b/components/sidebar.html
index 8ecd9cde..beaab150 100644
--- a/components/sidebar.html
+++ b/components/sidebar.html
@@ -1,6 +1,11 @@
+<!--
+  Sidebar fades in once when hydrated on the client. js/index.js removes the
+  helper classes after the initial animation to avoid flashes each time we
+  re-render navigation links.
+-->
 <aside
   id="sidebar"
-  class="bg-gray-900 text-white transition-transform duration-300 ease-in-out fixed top-0 left-0 w-64 h-screen overflow-y-auto"
+  class="bg-gray-900 text-white transition-transform duration-300 ease-in-out fixed top-0 left-0 w-64 h-screen overflow-y-auto fade-in fade-in-delay-100"
 >
   <div class="flex flex-col h-full">
     <!-- Top Navigation Links -->
diff --git a/css/style.css b/css/style.css
index de699c57..380ec497 100644
--- a/css/style.css
+++ b/css/style.css
@@ -90,6 +90,12 @@ header img {
   }
 }
 
+/*
+  Thumbnails start transparent and fade in the first time they finish loading.
+  `data-thumbnail-loaded` is cleared by js/index.js once the animation completes
+  so re-rendering the same element later does not replay the transition and cause
+  a distracting flash.
+*/
 [data-video-thumbnail][data-thumbnail-loaded="true"] {
   animation: video-thumbnail-fade-in 220ms ease-out forwards;
 }
@@ -103,8 +109,46 @@ header img {
   }
 }
 
+/*
+  Generic fade-in utility for chrome elements (sidebar, header controls, etc.).
+  js/index.js listens for the `interface-fade-in` animation finishing and removes
+  the temporary classes so that once an element has gracefully appeared it stays
+  opaque even if the DOM is re-used or re-parented later.
+*/
+.fade-in {
+  opacity: 0;
+  animation: interface-fade-in 280ms ease-out forwards;
+  animation-delay: var(--fade-in-delay, 0ms);
+}
+
+.fade-in-delay-100 {
+  --fade-in-delay: 100ms;
+}
+
+.fade-in-delay-200 {
+  --fade-in-delay: 200ms;
+}
+
+.fade-in-delay-300 {
+  --fade-in-delay: 300ms;
+}
+
+.fade-in-delay-400 {
+  --fade-in-delay: 400ms;
+}
+
+@keyframes interface-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
-  .video-card--enter {
+  .video-card--enter,
+  .fade-in {
     opacity: 1;
     animation: none;
   }
diff --git a/index.html b/index.html
index 8ee91fbe..b9c9f100 100644
--- a/index.html
+++ b/index.html
@@ -59,14 +59,24 @@
       md:ml-64 ensures content is shifted on desktop so the pinned sidebar doesn't overlap.
       On mobile, we also toggle .sidebar-open to shift the entire content.
     -->
-    <div id="app" class="md:ml-64 px-4 py-8 min-h-screen flex flex-col">
+    <!--
+      `fade-in` is scrubbed by js/index.js after the first animation so that
+      re-rendering views does not cause the shell to flicker. Only apply it to
+      elements that should animate exactly once on initial paint.
+    -->
+    <div id="app" class="md:ml-64 px-4 py-8 min-h-screen flex flex-col fade-in">
       <!-- Header -->
       <header class="mb-8 flex items-center w-full">
         <!-- Mobile hamburger button (hidden on md+) -->
         <!-- New button -->
+        <!--
+          Mobile menu button: uses `fade-in` to match the rest of the chrome.
+          The JS animation cleanup removes the helper classes once the entrance
+          finishes to prevent flashes on future sidebar toggles.
+        -->
         <button
           id="mobileMenuBtn"
-          class="md:hidden ml-2 mr-4 flex items-center justify-center w-10 h-10 rounded-full bg-transparent hover:bg-transparent focus:outline-none focus:ring-2 focus:ring-[#0f172a] z-[60]"
+          class="md:hidden ml-2 mr-4 flex items-center justify-center w-10 h-10 rounded-full bg-transparent hover:bg-transparent focus:outline-none focus:ring-2 focus:ring-[#0f172a] z-[60] fade-in"
         >
           <img
             src="assets/svg/mobile-sidebar-menu-icon.svg"
@@ -75,14 +85,16 @@
           />
         </button>
         <!-- Logo -->
+        <!-- Logo fades in once on initial load. -->
         <img
           src="assets/svg/bitvid-logo-light-mode.svg"
           alt="BitVid Logo"
-          class="h-16"
+          class="h-16 fade-in fade-in-delay-100"
         />
 
         <!-- Buttons on the far right -->
-        <div class="ml-auto flex items-center space-x-4">
+        <!-- Header action buttons share the fade-in treatment for consistency. -->
+        <div class="ml-auto flex items-center space-x-4 fade-in fade-in-delay-200">
           <!-- Login Button -->
           <button
             id="loginButton"
@@ -141,7 +153,8 @@
       <div id="modalContainer"></div>
 
       <!-- Tagline / Slogan -->
-      <div class="text-center mb-8">
+      <!-- Tagline fade matches the cards. -->
+      <div class="text-center mb-8 fade-in fade-in-delay-300">
         <h2 class="text-2xl font-bold text-gray-500 tracking-wide">
           seed. zap. subscribe.
         </h2>
diff --git a/js/app.js b/js/app.js
index 49cac9d1..839d0e59 100644
--- a/js/app.js
+++ b/js/app.js
@@ -2476,6 +2476,8 @@ class bitvidApp {
         this.loadedThumbnails.get(video.id) || "";
       const shouldLazyLoadThumbnail =
         escapedThumbnail && previouslyLoadedThumbnail !== escapedThumbnail;
+      const shouldAnimateThumbnail =
+        !!escapedThumbnail && previouslyLoadedThumbnail !== escapedThumbnail;
       const thumbnailAttrLines = ["data-video-thumbnail=\"true\""];
       if (shouldLazyLoadThumbnail) {
         thumbnailAttrLines.push(
@@ -2567,8 +2569,15 @@ class bitvidApp {
               return;
             }
 
-            if (thumbnailEl.dataset.thumbnailLoaded !== "true") {
-              thumbnailEl.dataset.thumbnailLoaded = "true";
+            if (shouldAnimateThumbnail) {
+              // Flag the element so CSS runs a one-time fade. js/index.js scrubs
+              // this attribute in the `animationend` handler so reusing the same
+              // DOM node later will not re-trigger the animation and flash.
+              if (thumbnailEl.dataset.thumbnailLoaded !== "true") {
+                thumbnailEl.dataset.thumbnailLoaded = "true";
+              }
+            } else if (thumbnailEl.dataset.thumbnailLoaded) {
+              delete thumbnailEl.dataset.thumbnailLoaded;
             }
 
             this.loadedThumbnails.set(video.id, escapedThumbnail);
diff --git a/js/index.js b/js/index.js
index a26695be..d3c062d0 100644
--- a/js/index.js
+++ b/js/index.js
@@ -2,6 +2,62 @@
 
 import { trackPageView } from "./analytics.js";
 
+const INTERFACE_FADE_IN_ANIMATION = "interface-fade-in";
+const VIDEO_THUMBNAIL_FADE_IN_ANIMATION = "video-thumbnail-fade-in";
+
+//
+// Centralized animation cleanup
+// ------------------------------
+// We attach a single capture-phase listener for animation events so that any
+// chrome element or thumbnail using our fade-in helpers can automatically shed
+// the temporary classes/data attributes that trigger the transition. This is
+// critical because these DOM nodes frequently persist while the surrounding
+// lists re-render; if the classes stick around, future layout shuffles would
+// replay the fade and make the UI flicker. Clearing the hooks immediately after
+// the first animation keeps the graceful entrance without introducing future
+// flashes.
+const handleFadeInAnimationComplete = (event) => {
+  const { animationName, target } = event;
+
+  if (!(target instanceof HTMLElement)) {
+    return;
+  }
+
+  if (animationName === INTERFACE_FADE_IN_ANIMATION) {
+    if (!target.classList.contains("fade-in")) {
+      return;
+    }
+
+    // Remove the transient fade-in class so future renders keep the element
+    // visible. The delays piggyback on `fade-in`, so we strip those too.
+    target.classList.remove("fade-in");
+    Array.from(target.classList).forEach((className) => {
+      if (className.startsWith("fade-in-delay-")) {
+        target.classList.remove(className);
+      }
+    });
+    return;
+  }
+
+  if (animationName !== VIDEO_THUMBNAIL_FADE_IN_ANIMATION) {
+    return;
+  }
+
+  if (
+    target.dataset &&
+    target.dataset.videoThumbnail === "true" &&
+    target.dataset.thumbnailLoaded === "true"
+  ) {
+    // Thumbnails use the same pattern: once the fade finishes we clear the flag
+    // so a later `load` event (or template reuse) does not restart the
+    // animation.
+    delete target.dataset.thumbnailLoaded;
+  }
+};
+
+document.addEventListener("animationend", handleFadeInAnimationComplete, true);
+document.addEventListener("animationcancel", handleFadeInAnimationComplete, true);
+
 // 1) Load modals (login, application, etc.)
 async function loadModal(url) {
   try {