docs(set-content): add comment

Author: thetaPC

core/src/utils/test/playwright/page/utils/set-content.ts

@@ -68,16 +68,30 @@ export const setContent = async (page: Page, html: string, testInfo: TestInfo, o
     `;
   }
 
+  /**
+   * This object is CRITICAL for Playwright stability.
+   *
+   * WHY IT'S NEEDED:
+   * 1. Bypasses Dynamic Loading: It avoids the consistent import
+   * failure 'await import(...)' when the global theme needed to be
+   * re-applied after the initial Ionic framework load.
+   * 2. Prevents Incorrect Palettes: It directly initializes with the
+   * required 'enabled: "always"' palette before any scripts run. This guarantees that correct CSS variables are loaded from the start.
+   * Otherwise, it would load the default light palette.
+   *
+   * These issues were only happening in Playwright Firefox tests
+   * that use `setContent`.
+   */
   const customTheme = {
     palette: {
       dark: {
-        enabled: palette === 'dark' ? 'always' : 'never'
+        enabled: palette === 'dark' ? 'always' : 'never',
       },
       highContrast: {
-        enabled: palette === 'high-contrast' ? 'always' : 'never'
+        enabled: palette === 'high-contrast' ? 'always' : 'never',
       },
       highContrastDark: {
-        enabled: palette === 'high-contrast-dark' ? 'always' : 'never'
+        enabled: palette === 'high-contrast-dark' ? 'always' : 'never',
       },
     },
   };