Move theme init for page view transitions to critical code path, update tests

Author: webstackdev

src/components/Head/ThemeInit.astro

@@ -38,52 +38,79 @@ const { defaultThemeIdJson, darkThemeIdJson, metaColorsJson } = themeData()
       const darkThemeId = JSON.parse(darkThemeIdJson)
       const themeMetaColors = JSON.parse(metaColorsJson)
 
-      // Read theme preference from localStorage (set by user's previous selection)
+      /** 1. Read theme preference from localStorage (set by user's previous selection) */
       const stored = localStorage.getItem('theme')
 
       if (stored && stored !== defaultThemeId) {
-        // User explicitly chose a theme - apply it immediately
-        // <html> element
+        /** User explicitly chose a theme - apply it immediately */
+        /** <html> element */
         document.documentElement.dataset['theme'] =  stored
       } else if (!stored) {
-        // No stored preference - use system preference
+        /** No stored preference - use system preference */
         const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-        // <html> element
+        /** <html> element */
         document.documentElement.dataset['theme'] =  prefersDark ? darkThemeId : defaultThemeId
       }
 
-      // 2. Turn <body> visible. It's set to hidden in BaseLayout.astro to avoid FOUC. Do
-      // here to make sure it gets turned on, in case the <meta> element selector throws.
+      /** 2. Turn <body> visible. It's set to hidden in BaseLayout.astro to avoid FOUC. Do
+       * here to make sure it gets turned on, in case the <meta> element selector throws.
+       */
       document.body.classList.remove('invisible')
 
-      // 3. Add theme entries from src/content/themes.json to the window.metaColors object
+      /** 3. Add theme entries from src/content/themes.json to the window.metaColors object */
       window.metaColors = window.metaColors || {}
       Object.assign(window.metaColors, themeMetaColors)
 
-      // 4. Update meta theme-color used for PWAs
+      /** 4. Update meta theme-color used for PWAs */
       const metaElement = document.querySelector('meta[name="theme-color"]')
       if (stored && stored !== defaultThemeId && metaElement && window.metaColors) {
-        // User explicitly chose a theme - apply it immediately
+        /** User explicitly chose a theme - apply it immediately */
         metaElement.setAttribute('content', window.metaColors[stored] || '')
       } else if (!stored && metaElement && window.metaColors) {
-        // No stored preference - use system preference
+        /** No stored preference - use system preference */
         const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
         metaElement.setAttribute(
           'content',
           window.metaColors[prefersDark ? darkThemeId : defaultThemeId] || ''
         )
       }
 
-      // 5. If stored === defaultThemeId, BaseLayout.astro already set it on <html> data-theme attribute
-      // and Meta.astro already set it on <meta name="theme-color">, so nothing to do
+      /**
+       * 5. If stored === defaultThemeId, BaseLayout.astro already set it
+       * on <html> data-theme attribute and Meta.astro already set it on
+       * <meta name="theme-color">, so nothing to do
+       */
 
-      // 6. Success!
+      /** 6. Success! */
       console.log('🎨 Theme init on "DOMContentLoaded" executed')
     } catch (error) {
-      // localStorage access can fail (privacy mode, etc.)
-      // Fall back to BaseLayout's data-theme="light", make sure the page is visible
+      /** localStorage access can fail (privacy mode, etc.) */
+      /** Fall back to BaseLayout's data-theme="light", make sure the page is visible */
       document.body.classList.remove('invisible')
       console.error('❌ Theme init on "DOMContentLoaded" failed with errors:', error)
     }
   }, { once: true })
+
+  /**
+   * Add the fast theme setting logic for Astro View Transition API navigation events.
+   *
+   * The DOMContentLoaded event does not fire on subsequent page transitions (soft loads).
+   */
+  document.addEventListener("astro:before-swap", (event) => {
+    try {
+      /** 1. Read theme preference from localStorage (set by user's previous selection) */
+      const stored = localStorage.getItem('theme')
+      /** 2. <html> element */
+      event.newDocument.documentElement.dataset['theme'] = stored
+      /** 3. Turn <body> visible. It's set to hidden in BaseLayout.astro to avoid FOUC */
+      event.newDocument.body.classList.remove('invisible')
+      /** 4. Success! */
+      console.log('🎨 Theme init on "astro:before-swap" executed')
+    } catch (error) {
+      /** localStorage access can fail (privacy mode, etc.) */
+      /** Fall back to BaseLayout's data-theme="light", make sure the page is visible */
+      event.newDocument.body.classList.remove('invisible')
+      console.error('❌ Theme init on "astro:before-swap" failed with errors:', error)
+    }
+  })
 </script>

src/components/scripts/bootstrap/__tests__/index.spec.ts

@@ -25,7 +25,6 @@ vi.mock('@components/scripts/store', () => ({
   initConsentFromCookies: vi.fn(),
   initConsentSideEffects: vi.fn(),
   initAnimationLifecycle: vi.fn(),
-  addViewTransitionThemeInitListener: vi.fn(),
   exposeStoreActionsForTesting: vi.fn(),
   $hasFunctionalConsent: {
     subscribe: vi.fn(),
@@ -55,7 +54,6 @@ import {
   initConsentFromCookies,
   initConsentSideEffects,
   initAnimationLifecycle,
-  addViewTransitionThemeInitListener,
   exposeStoreActionsForTesting,
 } from '@components/scripts/store'
 import { SentryBootstrap } from '@components/scripts/sentry/client'
@@ -77,7 +75,6 @@ const testWindow = window as TestWindow
 const consoleInfoSpy = vi.spyOn(console, 'info').mockImplementation(() => {})
 
 const mockSuccessfulInit = () => {
-  vi.mocked(addViewTransitionThemeInitListener).mockReturnValue(undefined)
   vi.mocked(initConsentFromCookies).mockReturnValue(undefined)
   vi.mocked(initConsentSideEffects).mockReturnValue(undefined)
   vi.mocked(initAnimationLifecycle).mockReturnValue(undefined)
@@ -105,27 +102,13 @@ describe('AppBootstrap', () => {
   })
 
   describe('Successful initialization', () => {
-    it('should call addViewTransitionThemeInitListener, initConsentFromCookies and initialize side effects', () => {
-      AppBootstrap.init()
-
-      expect(addViewTransitionThemeInitListener).toHaveBeenCalledTimes(1)
-      expect(initAnimationLifecycle).toHaveBeenCalledTimes(1)
-      expect(initConsentFromCookies).toHaveBeenCalledTimes(1)
-      expect(initConsentSideEffects).toHaveBeenCalledTimes(1)
-      expect(exposeStoreActionsForTesting).toHaveBeenCalledTimes(1)
-    })
-
     it('should add breadcrumbs for successful initialization', () => {
       AppBootstrap.init()
 
       expect(addScriptBreadcrumb).toHaveBeenCalledWith({
         scriptName: 'AppBootstrap',
         operation: 'init'
       })
-      expect(addScriptBreadcrumb).toHaveBeenCalledWith({
-        scriptName: 'AppBootstrap',
-        operation: 'addViewTransitionThemeInitListener'
-      })
       expect(addScriptBreadcrumb).toHaveBeenCalledWith({
         scriptName: 'AppBootstrap',
         operation: 'initAnimationLifecycle'
@@ -157,7 +140,6 @@ describe('AppBootstrap', () => {
     })
 
     it('should add breadcrumb before throwing error', () => {
-      vi.mocked(addViewTransitionThemeInitListener).mockReturnValue(undefined)
       const testError = new TestError('Cookie initialization failed')
       vi.mocked(initConsentFromCookies).mockImplementation(() => {
         throw testError
@@ -173,10 +155,6 @@ describe('AppBootstrap', () => {
         scriptName: 'AppBootstrap',
         operation: 'init'
       })
-      expect(addScriptBreadcrumb).toHaveBeenCalledWith({
-        scriptName: 'AppBootstrap',
-        operation: 'addViewTransitionThemeInitListener'
-      })
       expect(addScriptBreadcrumb).toHaveBeenCalledWith({
         scriptName: 'AppBootstrap',
         operation: 'initAnimationLifecycle'
@@ -221,7 +199,6 @@ describe('AppBootstrap', () => {
       AppBootstrap.init()
       AppBootstrap.init()
 
-      expect(addViewTransitionThemeInitListener).toHaveBeenCalledTimes(2)
       expect(initAnimationLifecycle).toHaveBeenCalledTimes(2)
       expect(initConsentFromCookies).toHaveBeenCalledTimes(2)
       expect(initConsentSideEffects).toHaveBeenCalledTimes(2)

src/components/scripts/bootstrap/index.ts

@@ -5,7 +5,6 @@
  */
 import { addScriptBreadcrumb, ClientScriptError } from '@components/scripts/errors'
 import {
-  addViewTransitionThemeInitListener,
   initAnimationLifecycle,
   initConsentFromCookies,
   initConsentSideEffects,
@@ -46,23 +45,19 @@ export class AppBootstrap {
         console.info('🔧 Sentry disabled in development mode')
       }
 
-      // 1. Add event listener to set theme on Astro View Transitions API page navigation
-      addScriptBreadcrumb({ scriptName: 'AppBootstrap', operation: 'addViewTransitionThemeInitListener' })
-      addViewTransitionThemeInitListener()
-
-      // 2. Initialize animation lifecycle listeners
+      // 1. Initialize animation lifecycle listeners
       addScriptBreadcrumb({ scriptName: 'AppBootstrap', operation: 'initAnimationLifecycle' })
       initAnimationLifecycle()
 
-      // 3. Initialize consent from cookies
+      // 2. Initialize consent from cookies
       addScriptBreadcrumb({ scriptName: 'AppBootstrap', operation: 'initConsentFromCookies' })
       initConsentFromCookies()
 
-      // 4. Setup all module-specific side effects (runs once per page load)
+      // 3. Setup all module-specific side effects (runs once per page load)
       addScriptBreadcrumb({ scriptName: 'AppBootstrap', operation: 'initConsentSideEffects' })
       initConsentSideEffects()
 
-      // 5. Expose limited store actions for Playwright-driven E2E tests
+      // 4. Expose limited store actions for Playwright-driven E2E tests
       exposeStoreActionsForTesting()
     } catch (error: unknown) {
       const scriptError = new ClientScriptError(error)

src/components/scripts/store/__tests__/themes.spec.ts

@@ -15,7 +15,6 @@ import {
   closeThemePicker,
   toggleThemePicker,
   themeKeyChangeSideEffectsListener,
-  addViewTransitionThemeInitListener,
   type ThemeId,
 } from '@components/scripts/store/themes'
 import { handleScriptError } from '@components/scripts/errors/handler'
@@ -240,53 +239,3 @@ describe('themeKeyChangeSideEffectsListener', () => {
     document.head.removeChild(meta)
   })
 })
-
-describe('addViewTransitionThemeInitListener', () => {
-  beforeEach(() => {
-    localStorage.clear()
-    document.body.className = ''
-  })
-
-  it('applies stored theme to new documents and reveals the body', () => {
-    localStorage.setItem('theme', 'dark')
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
-    const newDocument = document.implementation.createHTMLDocument('next')
-    newDocument.body.classList.add('invisible')
-
-    addViewTransitionThemeInitListener()
-
-    const event = new CustomEvent('astro:before-swap') as CustomEvent & {
-      newDocument: Document
-    }
-    event.newDocument = newDocument
-    document.dispatchEvent(event)
-
-    expect(newDocument.documentElement.dataset['theme']).toBe('dark')
-    expect(newDocument.body.classList.contains('invisible')).toBe(false)
-    expect(logSpy).toHaveBeenCalledWith('🎨 Theme init on "astro:before-swap" executed')
-  })
-
-  it('falls back gracefully when localStorage access fails', () => {
-    const error = new TestError('denied')
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
-      throw error
-    })
-    const newDocument = document.implementation.createHTMLDocument('fallback')
-    newDocument.body.classList.add('invisible')
-
-    addViewTransitionThemeInitListener()
-
-    const event = new CustomEvent('astro:before-swap') as CustomEvent & {
-      newDocument: Document
-    }
-    event.newDocument = newDocument
-    document.dispatchEvent(event)
-
-    expect(newDocument.body.classList.contains('invisible')).toBe(false)
-    expect(errorSpy).toHaveBeenCalledWith(
-      '❌ Theme init on "astro:before-swap" failed with errors:',
-      error,
-    )
-  })
-})

src/components/scripts/store/index.ts

@@ -72,7 +72,6 @@ export {
 
 // Re-export themes
 export {
-  addViewTransitionThemeInitListener,
   closeThemePicker,
   createThemeController,
   createThemePickerOpenController,

src/components/scripts/store/themes.ts

@@ -237,28 +237,3 @@ export function themeKeyChangeSideEffectsListener(): void {
     }
   })
 }
-
-/**
- * Add the fast theme setting logic for Astro View Transition API navigation events.
- *
- * The DOMContentLoaded event does not fire on subsequent page transitions (soft loads).
- */
-export function addViewTransitionThemeInitListener(): void {
-  document.addEventListener("astro:before-swap", (event) => {
-    try {
-      // 1. Read theme preference from localStorage (set by user's previous selection)
-      const stored = localStorage.getItem('theme')!
-      // <html> element
-      event.newDocument.documentElement.dataset['theme'] = stored
-      // 4. Turn <body> visible. It's set to hidden in BaseLayout.astro to avoid FOUC
-      event.newDocument.body.classList.remove('invisible')
-      // 5. Success!
-      console.log('🎨 Theme init on "astro:before-swap" executed')
-    } catch (error) {
-      // localStorage access can fail (privacy mode, etc.)
-      // Fall back to BaseLayout's data-theme="light", make sure the page is visible
-      event.newDocument.body.classList.remove('invisible')
-      console.error('❌ Theme init on "astro:before-swap" failed with errors:', error)
-    }
-  }, { once: true })
-}

test/e2e/specs/12-component-persistence/body-visibility.spec.ts

@@ -0,0 +1,33 @@
+/**
+ * Regression Tests for Astro View Transitions - Body Visibility
+ *
+ * Ensures the "invisible" class used to prevent FOUC on initial load is removed
+ * from the swapped document's <body> whenever Astro View Transitions performs
+ * client-side navigation. This guards against blank pages during soft reloads.
+ *
+ * Related:
+ * - src/layouts/BaseLayout.astro (initial invisible class)
+ * - src/components/ThemePicker/ThemeInit.astro (runtime theme init logic)
+ */
+
+import { BasePage, expect, test } from '@test/e2e/helpers'
+
+test.describe('View Transitions - body visibility reset', () => {
+  test('removes invisible class from swapped document body', async ({ page: playwrightPage }) => {
+    const page = await BasePage.init(playwrightPage)
+
+    await page.goto('/')
+    await page.waitForLoadState('networkidle')
+
+    const astroBeforeSwapLog = page.consoleMssgPromise('Theme init on "astro:before-swap" executed')
+
+    await page.navigateToPage('/about')
+    await page.waitForPageLoad()
+
+    const logMessage = await astroBeforeSwapLog
+    expect(logMessage.text()).toContain('Theme init on "astro:before-swap" executed')
+
+    const bodyHasInvisibleAfterNav = await page.evaluate(() => document.body.classList.contains('invisible'))
+    expect(bodyHasInvisibleAfterNav).toBe(false)
+  })
+})