fix(theme): clean favicon settings persistence

Author: Callin Mullaney

config/schema/emulsify.schema.yml

@@ -14,7 +14,7 @@ emulsify.settings:
         type: integer
     favicon_source_svg:
       type: text
-      label: 'Exportable SVG source markup'
+      label: 'Portable SVG source markup'
     favicon_source_filename:
       type: string
       label: 'Source SVG filename'

src/Favicon/FaviconPackageGenerator.php

@@ -168,7 +168,7 @@ public function generate(string $theme_name, File $source_file, array $settings)
   }
 
   /**
-   * Generates a full favicon package from exportable SVG source markup.
+   * Generates a full favicon package from portable SVG source markup.
    *
    * @param array<string, mixed> $source
    *   Optional source metadata such as file ID or filename.
@@ -430,6 +430,8 @@ private function encodeJson(mixed $data, int $options = 0): string {
    */
   private function buildPackageHash(array $settings, string $source_hash): string {
     $hash_settings = $settings;
+    // File IDs, stored source copies, and human-facing labels do not change the
+    // rendered package output, so exclude them from the deterministic hash.
     unset(
       $hash_settings['favicon_source_fid'],
       $hash_settings['favicon_source_svg'],
@@ -506,7 +508,7 @@ private function sanitizeSvg(string $source_data): string {
    * Inspects and sanitizes SVG markup.
    *
    * @return array<string, mixed>
-   *   Source analysis including the sanitized SVG.
+   *   Source analysis including sanitized markup and non-fatal warnings.
    */
   private function inspectSvgMarkup(string $source_data): array {
     $document = $this->loadSvgDocument($source_data);
@@ -808,6 +810,8 @@ private function renderPng(string $mime_type, string $source_data, int $size, st
     $background = imagecolorallocatealpha($canvas, $red, $green, $blue, 0);
     imagefilledrectangle($canvas, 0, 0, $size, $size, $background);
 
+    // All raster outputs share the same centering and padding rules so the
+    // browser, iOS, and Android assets stay visually aligned.
     $inner_size = max(1, $size - (2 * (int) round($size * ($padding / 100))));
     $scale = min($inner_size / $source_width, $inner_size / $source_height);
     $target_width = max(1, (int) round($source_width * $scale));

src/Favicon/FaviconPreviewBuilder.php

@@ -172,8 +172,8 @@ private function resolvePreviewSourceUrl(string $platform, array $settings, ?Fil
       return $this->fileUrlGenerator->generateString($source_file->getFileUri());
     }
 
-    if (FaviconSettings::hasExportableSource($settings)) {
-      return 'data:image/svg+xml;base64,' . base64_encode(FaviconSettings::getSourceSvg($settings));
+    if (FaviconSettings::hasPortableSource($settings)) {
+      return 'data:image/svg+xml;base64,' . base64_encode(FaviconSettings::getPortableSourceSvg($settings));
     }
 
     $package_path = $settings['favicon_package_path'] ?? '';

src/Favicon/FaviconSettings.php

@@ -121,17 +121,35 @@ public static function getSourceFileId(array $settings): ?int {
   }
 
   /**
-   * Returns the exportable SVG source stored in config.
+   * Returns the portable SVG source stored in config.
    */
-  public static function getSourceSvg(array $settings): string {
+  public static function getPortableSourceSvg(array $settings): string {
     return trim((string) ($settings['favicon_source_svg'] ?? ''));
   }
 
   /**
-   * Indicates whether an exportable SVG source is available.
+   * Indicates whether a portable SVG source is available.
+   */
+  public static function hasPortableSource(array $settings): bool {
+    return self::getPortableSourceSvg($settings) !== '';
+  }
+
+  /**
+   * Returns the portable SVG source stored in config.
+   *
+   * @todo Remove in Emulsify 8.x after callers move to getPortableSourceSvg().
+   */
+  public static function getSourceSvg(array $settings): string {
+    return self::getPortableSourceSvg($settings);
+  }
+
+  /**
+   * Indicates whether a portable SVG source is available.
+   *
+   * @todo Remove in Emulsify 8.x after callers move to hasPortableSource().
    */
   public static function hasExportableSource(array $settings): bool {
-    return self::getSourceSvg($settings) !== '';
+    return self::hasPortableSource($settings);
   }
 
   /**

src/Hook/FaviconHooks.php

@@ -106,7 +106,7 @@ private function resolveRuntimePackageSettings(string $theme_name, array $settin
    * Resolves package settings when a portable SVG source is available.
    */
   private function doResolveRuntimePackageSettings(string $theme_name, array $settings): ?array {
-    $source_svg = FaviconSettings::getSourceSvg($settings);
+    $source_svg = FaviconSettings::getPortableSourceSvg($settings);
     $source_metadata = [
       'filename' => (string) ($settings['favicon_source_filename'] ?? 'favicon.svg'),
     ];

src/Hook/ThemeSettingsHooks.php

@@ -27,6 +27,26 @@ final class ThemeSettingsHooks {
 
   use StringTranslationTrait;
 
+  /**
+   * Theme settings UI keys that should never be persisted to config.
+   *
+   * ThemeSettingsForm saves arbitrary submitted values unless they are marked
+   * as clean, so all helper-only UI keys live here.
+   */
+  private const NON_CONFIG_THEME_SETTING_KEYS = [
+    'portable_source',
+    'portable_source_notice',
+    'diagnostics',
+    'source_diagnostics_notice',
+    'status',
+    'package_status_notice',
+    'maskable_info',
+    'maskable_icon_notice',
+    'generation_hint',
+    'dirty_state',
+    'emulsify_tools_apply_admin_theme_favicon',
+  ];
+
   /**
    * Generates favicon packages from uploaded theme assets.
    */
@@ -115,6 +135,7 @@ public function formSystemThemeSettingsAlter(array &$form, FormStateInterface $f
     $form['#attached']['library'][] = 'emulsify/favicon_admin';
     $form['#validate'][] = [self::class, 'validateFaviconSettings'];
     $form['#submit'][] = [self::class, 'submitFaviconSettings'];
+    $this->registerCleanValueKeys($form_state);
 
     $form['favicon_package_hash'] = [
       '#type' => 'hidden',
@@ -189,7 +210,7 @@ public function formSystemThemeSettingsAlter(array &$form, FormStateInterface $f
       ],
       '#description' => $this->t('Use a square SVG with a square viewBox. Embedded base64 raster image data is allowed, but it may scale less cleanly than a pure vector source.'),
     ];
-    $form['emulsify_favicon']['source']['portable_source'] = [
+    $form['emulsify_favicon']['source']['portable_source_notice'] = [
       '#type' => 'item',
       '#title' => $this->t('Portable source config'),
       '#markup' => '<span class="description">' . $this->buildPortableSourceDescription($package_status) . '</span>',
@@ -211,14 +232,14 @@ public function formSystemThemeSettingsAlter(array &$form, FormStateInterface $f
       ];
     }
     if ($package_status['source_diagnostics'] !== '') {
-      $form['emulsify_favicon']['source']['diagnostics'] = [
+      $form['emulsify_favicon']['source']['source_diagnostics_notice'] = [
         '#type' => 'item',
         '#title' => $this->t('Source diagnostics'),
         '#markup' => $package_status['source_diagnostics'],
       ];
     }
 
-    $form['emulsify_favicon']['status'] = [
+    $form['emulsify_favicon']['package_status_notice'] = [
       '#type' => 'item',
       '#title' => $this->t('Current generated package'),
       '#markup' => $package_status['status_markup'],
@@ -304,7 +325,7 @@ public function formSystemThemeSettingsAlter(array &$form, FormStateInterface $f
       '#max' => 40,
       '#description' => $this->t('The maskable icon keeps at least 20% padding to protect the safe area.'),
     ];
-    $form['emulsify_favicon']['android']['maskable_info'] = [
+    $form['emulsify_favicon']['android']['maskable_icon_notice'] = [
       '#type' => 'item',
       '#title' => $this->t('Maskable Android Icon'),
       '#markup' => '<span class="description">' . $this->t('Emulsify always generates a dedicated maskable Android icon with extra safe-area padding so launchers can crop the outer edges into circles or squircles without cutting into the logo.') . '</span>',
@@ -335,8 +356,8 @@ public function formSystemThemeSettingsAlter(array &$form, FormStateInterface $f
 
         $form['emulsify_favicon']['actions']['regenerate_package'] = [
           '#type' => 'submit',
+		'#name' => 'regenerate_package',
           '#value' => $default_label,
-          '#submit' => [[self::class, 'requestFaviconRegeneration']],
           '#button_type' => $package_status['state'] === 'current' ? 'secondary' : 'primary',
           '#attributes' => [
             'data-favicon-regenerate-button' => 'true',
@@ -381,13 +402,6 @@ public static function submitFaviconSettings(array &$form, FormStateInterface $f
     self::service()->doSubmitFaviconSettings($form_state);
   }
 
-  /**
-   * Static generate button callback.
-   */
-  public static function requestFaviconRegeneration(array &$form, FormStateInterface $form_state): void {
-    self::service()->doRequestFaviconRegeneration($form_state);
-  }
-
   /**
    * Static reset button callback.
    */
@@ -396,10 +410,12 @@ public static function resetFaviconSettings(array &$form, FormStateInterface $fo
   }
 
   /**
-   * Flags the form submit as an explicit regeneration request.
+   * Marks helper-only values so ThemeSettingsForm does not export them.
    */
-  private function doRequestFaviconRegeneration(FormStateInterface $form_state): void {
-    $form_state->set('emulsify_favicon_force_generate', TRUE);
+  private function registerCleanValueKeys(FormStateInterface $form_state): void {
+    foreach (self::NON_CONFIG_THEME_SETTING_KEYS as $key) {
+      $form_state->addCleanValueKey($key);
+    }
   }
 
   /**
@@ -479,7 +495,7 @@ private function doSubmitFaviconSettings(FormStateInterface $form_state): void {
         $source_context['source_svg'],
       );
       $metadata = $this->packageGenerator->readPackageMetadata($definition['path']);
-      $should_generate = (bool) $form_state->get('emulsify_favicon_force_generate')
+      $should_generate = $this->isRegenerationRequest($form_state)
         || $settings['favicon_package_hash'] !== $definition['hash']
         || $settings['favicon_package_path'] !== $definition['path']
         || !$this->packageGenerator->packageExists($definition['path']);
@@ -554,6 +570,14 @@ private function doResetFaviconSettings(FormStateInterface $form_state): void {
     $this->messenger->addStatus($this->t('Reset the generated favicon package and restored the theme default favicon behavior.'));
   }
 
+  /**
+   * Returns whether the current submit was an explicit regeneration request.
+   */
+  private function isRegenerationRequest(FormStateInterface $form_state): bool {
+    $trigger = $form_state->getTriggeringElement();
+    return is_array($trigger) && ($trigger['#name'] ?? '') === 'regenerate_package';
+  }
+
   /**
    * Resolves a stored managed file source when it still exists.
    */
@@ -574,7 +598,7 @@ private function resolveStoredSourceFile(array $settings): ?File {
    *   The resolved source context, or an empty array if no source exists.
    */
   private function resolveSourceContext(array $settings, bool $requires_rasterization): array {
-    $source_svg = FaviconSettings::getSourceSvg($settings);
+    $source_svg = FaviconSettings::getPortableSourceSvg($settings);
     $source_filename = (string) ($settings['favicon_source_filename'] ?: 'favicon.svg');
     $source_fid = FaviconSettings::getSourceFileId($settings);
     $source_file = $source_fid ? File::load($source_fid) : NULL;
@@ -638,7 +662,7 @@ private function buildPackageStatus(string $theme_name, array $settings, ?File $
       'package_exists' => !empty($settings['favicon_package_path']) && $this->packageGenerator->packageExists($settings['favicon_package_path']),
       'source_available' => FALSE,
       'portable_source_missing' => FALSE,
-      'exportable_source' => FaviconSettings::hasExportableSource($settings),
+      'portable_source_available' => FaviconSettings::hasPortableSource($settings),
       'source_diagnostics' => '',
       'status_markup' => '',
     ];
@@ -647,9 +671,9 @@ private function buildPackageStatus(string $theme_name, array $settings, ?File $
       $source_context = [];
       if ($source_file) {
         $source_context = $this->resolveSourceContext($settings, FALSE);
-        $status['portable_source_missing'] = !$status['exportable_source'];
+		$status['portable_source_missing'] = !$status['portable_source_available'];
       }
-      elseif ($status['exportable_source']) {
+      elseif ($status['portable_source_available']) {
         $source_context = $this->resolveSourceContext($settings, FALSE);
       }
 
@@ -696,7 +720,7 @@ private function buildPackageStatus(string $theme_name, array $settings, ?File $
    * Describes whether the current source is portable through config.
    */
   private function buildPortableSourceDescription(array $package_status): string {
-    if ($package_status['exportable_source']) {
+    if ($package_status['portable_source_available']) {
       return (string) $this->t('The sanitized SVG source is saved in theme config and can be regenerated after configuration import.');
     }
 

whisk/config/schema/whisk.schema.yml

@@ -14,7 +14,7 @@ whisk.settings:
         type: integer
     favicon_source_svg:
       type: text
-      label: 'Exportable SVG source markup'
+      label: 'Portable SVG source markup'
     favicon_source_filename:
       type: string
       label: 'Source SVG filename'