source_monitor 0.7.1 → 0.8.0

data/app/assets/javascripts/source_monitor/application.js

@@ -1,6 +1,7 @@
 import { Application } from "@hotwired/stimulus";
 import AsyncSubmitController from "./controllers/async_submit_controller";
 import NotificationController from "./controllers/notification_controller";
+import NotificationContainerController from "./controllers/notification_container_controller";
 import DropdownController from "./controllers/dropdown_controller";
 import ModalController from "./controllers/modal_controller";
 import ConfirmNavigationController from "./controllers/confirm_navigation_controller";
@@ -15,6 +16,7 @@ if (!existingApplication) {
 }
 
 application.register("notification", NotificationController);
+application.register("notification-container", NotificationContainerController);
 application.register("async-submit", AsyncSubmitController);
 application.register("dropdown", DropdownController);
 application.register("modal", ModalController);

data/app/assets/javascripts/source_monitor/controllers/notification_container_controller.js

@@ -0,0 +1,138 @@
+/* global MutationObserver, requestAnimationFrame, cancelAnimationFrame */
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static values = {
+    maxVisible: { default: 3, type: Number },
+    expanded: { default: false, type: Boolean }
+  };
+
+  static targets = ["list", "badge", "badgeCount", "clearAll"];
+
+  connect() {
+    this.rafId = null;
+    this.boundHandleClickOutside = this.handleClickOutside.bind(this);
+    this.boundScheduleRecalculate = () => this.scheduleRecalculate();
+
+    this.observer = new MutationObserver(this.boundScheduleRecalculate);
+    this.observer.observe(this.listTarget, { childList: true });
+
+    this.listTarget.addEventListener(
+      "notification:dismissed",
+      this.boundScheduleRecalculate
+    );
+
+    this.recalculateVisibility();
+  }
+
+  disconnect() {
+    if (this.observer) {
+      this.observer.disconnect();
+      this.observer = null;
+    }
+
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+
+    this.listTarget.removeEventListener(
+      "notification:dismissed",
+      this.boundScheduleRecalculate
+    );
+    document.removeEventListener("click", this.boundHandleClickOutside);
+  }
+
+  scheduleRecalculate() {
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+    }
+    this.rafId = requestAnimationFrame(() => {
+      this.rafId = null;
+      this.recalculateVisibility();
+    });
+  }
+
+  recalculateVisibility() {
+    const toasts = Array.from(this.listTarget.children);
+    const total = toasts.length;
+
+    if (this.expandedValue) {
+      toasts.forEach((toast) => {
+        toast.classList.remove("hidden");
+        toast.removeAttribute("aria-hidden");
+        toast.removeAttribute("inert");
+      });
+    } else {
+      toasts.forEach((toast, index) => {
+        if (index < this.maxVisibleValue) {
+          toast.classList.remove("hidden");
+          toast.removeAttribute("aria-hidden");
+          toast.removeAttribute("inert");
+        } else {
+          toast.classList.add("hidden");
+          toast.setAttribute("aria-hidden", "true");
+          toast.setAttribute("inert", "");
+        }
+      });
+    }
+
+    const hiddenCount = this.expandedValue
+      ? 0
+      : Math.max(0, total - this.maxVisibleValue);
+
+    if (this.hasBadgeTarget) {
+      if (this.hasBadgeCountTarget) {
+        this.badgeCountTarget.textContent = `+${hiddenCount} more`;
+      }
+      if (hiddenCount > 0) {
+        this.badgeTarget.classList.remove("hidden");
+      } else {
+        this.badgeTarget.classList.add("hidden");
+      }
+    }
+
+    if (this.hasClearAllTarget) {
+      const showClearAll = total > 0 && (hiddenCount > 0 || this.expandedValue);
+      if (showClearAll) {
+        this.clearAllTarget.classList.remove("hidden");
+      } else {
+        this.clearAllTarget.classList.add("hidden");
+      }
+    }
+  }
+
+  toggleExpand(event) {
+    event.preventDefault();
+    if (this.expandedValue) {
+      this.collapseStack();
+    } else {
+      this.expandStack();
+    }
+  }
+
+  expandStack() {
+    this.expandedValue = true;
+    this.recalculateVisibility();
+    document.addEventListener("click", this.boundHandleClickOutside);
+  }
+
+  collapseStack() {
+    this.expandedValue = false;
+    document.removeEventListener("click", this.boundHandleClickOutside);
+    this.recalculateVisibility();
+  }
+
+  handleClickOutside(event) {
+    if (!this.element.contains(event.target)) {
+      this.collapseStack();
+    }
+  }
+
+  clearAll(event) {
+    event.preventDefault();
+    const toasts = Array.from(this.listTarget.children);
+    toasts.forEach((toast) => toast.remove());
+    this.collapseStack();
+  }
+}

data/app/assets/javascripts/source_monitor/controllers/notification_controller.js

@@ -12,6 +12,7 @@ export default class extends Controller {
 
     this.clearTimeout();
     this.registerController();
+    this.applyLevelDelay();
     this.startTimer();
   }
 
@@ -34,8 +35,18 @@ export default class extends Controller {
     this.timeoutId = window.setTimeout(() => this.dismiss(), this.delayValue);
   }
 
+  applyLevelDelay() {
+    const level = this.element.dataset.level;
+    if (level === "error" && this.delayValue === 5000) {
+      this.delayValue = 10000;
+    }
+  }
+
   dismiss() {
     if (!this.element) return;
+    this.element.dispatchEvent(
+      new CustomEvent("notification:dismissed", { bubbles: true })
+    );
     this.element.classList.add("opacity-0", "translate-y-2");
     window.setTimeout(() => {
       if (this.element && this.element.remove) {

data/app/controllers/source_monitor/source_favicon_fetches_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SourceMonitor
+  class SourceFaviconFetchesController < ApplicationController
+    include SourceMonitor::SourceTurboResponses
+
+    before_action :set_source
+
+    def create
+      unless defined?(ActiveStorage) && SourceMonitor.config.favicons.enabled?
+        return render_fetch_enqueue_response("Favicon fetching is not enabled.", toast_level: :warning)
+      end
+
+      if @source.respond_to?(:favicon) && @source.favicon.attached?
+        @source.favicon.purge
+      end
+
+      # Clear cooldown so the job doesn't skip this attempt
+      clear_favicon_cooldown(@source)
+
+      SourceMonitor::FaviconFetchJob.perform_later(@source.id)
+      render_fetch_enqueue_response("Favicon fetch has been enqueued.")
+    rescue StandardError => error
+      handle_fetch_failure(error, prefix: "Favicon fetch")
+    end
+
+    private
+
+    def set_source
+      @source = Source.find(params[:source_id])
+    end
+
+    def clear_favicon_cooldown(source)
+      metadata = (source.metadata || {}).except("favicon_last_attempted_at")
+      source.update_column(:metadata, metadata)
+    end
+  end
+end

data/app/controllers/source_monitor/sources_controller.rb

@@ -55,6 +55,7 @@ module SourceMonitor
       @source = Source.new(source_params)
 
       if @source.save
+        enqueue_favicon_fetch(@source)
         redirect_to source_monitor.source_path(@source), notice: "Source created successfully"
       else
         render :new, status: :unprocessable_entity
@@ -130,5 +131,15 @@ module SourceMonitor
       sanitized = SourceMonitor::Security::ParameterSanitizer.sanitize(raw_value.to_s)
       sanitized.start_with?("/") ? sanitized : nil
     end
+
+    def enqueue_favicon_fetch(source)
+      return unless defined?(ActiveStorage)
+      return unless SourceMonitor.config.favicons.enabled?
+      return if source.website_url.blank?
+
+      SourceMonitor::FaviconFetchJob.perform_later(source.id)
+    rescue StandardError => error
+      Rails.logger.warn("[SourceMonitor] Failed to enqueue favicon fetch: #{error.message}") if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+    end
   end
 end

data/app/helpers/source_monitor/application_helper.rb

@@ -232,6 +232,23 @@ module SourceMonitor
       nil
     end
 
+    # Renders the source favicon as an <img> tag or a colored-circle initials
+    # placeholder when no favicon is attached.  Handles the case where
+    # ActiveStorage is not loaded (host app without AS).
+    #
+    # Options:
+    #   size: pixel dimension for width/height (default: 24)
+    #   class: additional CSS classes
+    def source_favicon_tag(source, size: 24, **options)
+      css = options.delete(:class) || ""
+
+      if favicon_attached?(source)
+        favicon_image_tag(source, size: size, css: css)
+      else
+        favicon_placeholder_tag(source, size: size, css: css)
+      end
+    end
+
     private
 
     def external_link_icon
@@ -270,5 +287,39 @@ module SourceMonitor
 
       Rails.logger.debug("[SourceMonitor] Skipping #{kind} bundle include: #{error.message}")
     end
+
+    def favicon_attached?(source)
+      defined?(ActiveStorage) &&
+        source.respond_to?(:favicon) &&
+        source.favicon.attached?
+    end
+
+    def favicon_image_tag(source, size:, css:)
+      blob = source.favicon.blob
+      url = Rails.application.routes.url_helpers.rails_blob_path(blob, only_path: true)
+
+      image_tag(url,
+        alt: "#{source.name} favicon",
+        width: size,
+        height: size,
+        class: "rounded object-contain #{css}".strip,
+        style: "max-width: #{size}px; max-height: #{size}px;",
+        loading: "lazy")
+    rescue StandardError
+      favicon_placeholder_tag(source, size: size, css: css)
+    end
+
+    def favicon_placeholder_tag(source, size:, css:)
+      initial = source.name.to_s.strip.first.presence&.upcase || "?"
+      hue = source.name.to_s.bytes.sum % 360
+      bg_color = "hsl(#{hue}, 45%, 65%)"
+
+      content_tag(:span,
+        initial,
+        class: "inline-flex items-center justify-center rounded-full text-white font-semibold #{css}".strip,
+        style: "width: #{size}px; height: #{size}px; background-color: #{bg_color}; font-size: #{(size * 0.5).round}px; line-height: #{size}px;",
+        title: source.name,
+        "aria-hidden": "true")
+    end
   end
 end

data/app/jobs/source_monitor/favicon_fetch_job.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SourceMonitor
+  class FaviconFetchJob < ApplicationJob
+    source_monitor_queue :fetch
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(source_id)
+      return unless defined?(ActiveStorage)
+
+      source = SourceMonitor::Source.find_by(id: source_id)
+      return unless source
+      return unless SourceMonitor.config.favicons.enabled?
+      return if source.website_url.blank?
+      return if source.favicon.attached?
+      return if within_cooldown?(source)
+
+      result = SourceMonitor::Favicons::Discoverer.new(source.website_url).call
+
+      if result
+        attach_favicon(source, result)
+      else
+        record_failed_attempt(source)
+      end
+    rescue StandardError => error
+      record_failed_attempt(source) if source
+      log_error(source, error)
+    end
+
+    private
+
+    def within_cooldown?(source)
+      last_attempt = source.metadata&.dig("favicon_last_attempted_at")
+      return false if last_attempt.blank?
+
+      cooldown_days = SourceMonitor.config.favicons.retry_cooldown_days
+      Time.parse(last_attempt) > cooldown_days.days.ago
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def attach_favicon(source, result)
+      blob = ActiveStorage::Blob.create_and_upload!(
+        io: result.io,
+        filename: result.filename,
+        content_type: result.content_type
+      )
+      source.favicon.attach(blob)
+    end
+
+    def record_failed_attempt(source)
+      metadata = (source.metadata || {}).merge(
+        "favicon_last_attempted_at" => Time.current.iso8601
+      )
+      source.update_column(:metadata, metadata)
+    rescue StandardError
+      nil
+    end
+
+    def log_error(source, error)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.warn(
+        "[SourceMonitor::FaviconFetchJob] Failed for source #{source&.id}: #{error.class} - #{error.message}"
+      )
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/jobs/source_monitor/import_opml_job.rb

@@ -72,6 +72,7 @@ module SourceMonitor
 
       if source.save
         imported_sources << { id: source.id, feed_url: source.feed_url, name: source.name }
+        SourceMonitor::FaviconFetchJob.perform_later(source.id) if should_fetch_favicon?(source)
         processed << normalized_url
       else
         failed_sources << failure_payload(feed_url, "ValidationFailed", source.errors.full_messages.to_sentence)
@@ -130,6 +131,14 @@ module SourceMonitor
       }
     end
 
+    def should_fetch_favicon?(source)
+      defined?(ActiveStorage) &&
+        SourceMonitor.config.favicons.enabled? &&
+        source.website_url.present?
+    rescue StandardError
+      false
+    end
+
     def broadcast_completion(history)
       return unless defined?(Turbo::StreamsChannel)
 

data/app/jobs/source_monitor/source_health_check_job.rb

@@ -12,6 +12,7 @@ module SourceMonitor
 
       result = SourceMonitor::Health::SourceHealthCheck.new(source: source).call
       broadcast_outcome(source, result)
+      trigger_fetch_if_degraded(source, result)
       result
     rescue StandardError => error
       Rails.logger&.error(
@@ -23,8 +24,17 @@ module SourceMonitor
       nil
     end
 
+    DEGRADED_STATUSES = %w[declining critical warning].freeze
+
     private
 
+    def trigger_fetch_if_degraded(source, result)
+      return unless result&.success?
+      return unless DEGRADED_STATUSES.include?(source.health_status.to_s)
+
+      SourceMonitor::FetchFeedJob.perform_later(source.id, force: true)
+    end
+
     def record_unexpected_failure(source, error)
       SourceMonitor::HealthCheckLog.create!(
         source: source,

data/app/models/source_monitor/source.rb

@@ -8,6 +8,8 @@ module SourceMonitor
     include SourceMonitor::Models::Sanitizable
     include SourceMonitor::Models::UrlNormalizable
 
+    has_one_attached :favicon if defined?(ActiveStorage)
+
     FETCH_STATUS_VALUES = %w[idle queued fetching failed].freeze
 
     has_many :all_items, class_name: "SourceMonitor::Item", inverse_of: :source, dependent: :destroy

data/app/views/layouts/source_monitor/application.html.erb

@@ -13,8 +13,29 @@
 </head>
 <body class="fm-admin">
   <%= turbo_stream_from "source_monitor_notifications" %>
-  <div class="pointer-events-none fixed inset-x-0 top-4 z-50 flex justify-end px-6">
-    <div id="source_monitor_notifications" class="flex w-full max-w-sm flex-col gap-3"></div>
+  <div class="pointer-events-none fixed inset-x-0 top-4 z-50 flex justify-end px-6"
+       data-controller="notification-container">
+    <div class="flex w-full max-w-sm flex-col items-end gap-3">
+      <div id="source_monitor_notifications"
+           data-notification-container-target="list"
+           class="flex w-full flex-col gap-3">
+      </div>
+      <div data-notification-container-target="badge"
+           class="pointer-events-auto hidden">
+        <button type="button"
+                data-action="notification-container#toggleExpand"
+                class="inline-flex items-center gap-1.5 rounded-full bg-slate-700 px-3 py-1 text-xs font-medium text-white shadow-lg transition hover:bg-slate-600"
+                aria-live="polite">
+          <span data-notification-container-target="badgeCount">+0 more</span>
+        </button>
+      </div>
+      <button type="button"
+              data-action="notification-container#clearAll"
+              data-notification-container-target="clearAll"
+              class="pointer-events-auto hidden text-xs font-medium text-slate-400 underline transition hover:text-white">
+        Clear all
+      </button>
+    </div>
   </div>
   <div id="source_monitor_redirects" class="hidden" aria-hidden="true"></div>
   <div class="flex min-h-screen flex-col">

data/app/views/source_monitor/shared/_toast.html.erb

@@ -13,6 +13,7 @@
 <div
   data-controller="notification"
   data-notification-delay-value="<%= delay_ms %>"
+  data-level="<%= level_key %>"
   class="pointer-events-auto w-full max-w-md rounded-lg border px-4 py-3 shadow-lg transition duration-300 <%= classes %>"
 >
   <div class="flex items-start justify-between gap-3">

data/app/views/source_monitor/sources/_details.html.erb

@@ -8,13 +8,40 @@
 
 <div class="space-y-8">
   <div class="flex items-start justify-between">
-    <div>
-      <h1 class="text-3xl font-semibold text-slate-900"><%= source.name %></h1>
-      <div class="mt-2 flex flex-wrap items-center gap-2 text-xs">
-        <span data-testid="fetch-status-badge" class="inline-flex items-center rounded-full px-3 py-1 font-semibold <%= fetch_status[:classes] %>">
+    <div class="flex items-start gap-4">
+      <div class="flex flex-col items-center">
+        <div class="group relative">
+          <%= source_favicon_tag(source, size: 40) %>
+          <% if defined?(ActiveStorage) && SourceMonitor.config.favicons.enabled? %>
+            <%= button_to source_monitor.source_favicon_fetch_path(source),
+                  method: :post,
+                  class: "absolute -bottom-1 -right-1 hidden group-hover:inline-flex items-center justify-center rounded-full bg-white border border-slate-200 shadow-sm p-0.5 hover:bg-slate-50",
+                  title: "Fetch favicon",
+                  data: {
+                    "async-submit-target": "button",
+                    turbo_confirm: source.respond_to?(:favicon) && source.favicon.attached? ? "Replace existing favicon?" : nil
+                  }.compact,
+                  form: {
+                    class: "inline",
+                    data: {
+                      controller: "async-submit",
+                      action: "turbo:submit-start->async-submit#start turbo:submit-end->async-submit#finish"
+                    }
+                  } do %>
+              <svg class="h-4 w-4 text-slate-500" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99" />
+              </svg>
+            <% end %>
+          <% end %>
+        </div>
+        <span data-testid="fetch-status-badge" class="mt-2 inline-flex items-center rounded-full px-3 py-1 text-xs font-semibold <%= fetch_status[:classes] %>">
           <%= loading_spinner_svg if fetch_status[:show_spinner] %>
           <%= fetch_status[:label] %>
         </span>
+      </div>
+      <div>
+        <h1 class="text-3xl font-semibold text-slate-900"><%= source.name %></h1>
+      <div class="mt-2 flex flex-wrap items-center gap-2 text-xs">
         <% if source.last_fetch_started_at.present? %>
           <span class="rounded-full bg-slate-100 px-3 py-1 font-semibold text-slate-600">
             Started <%= time_ago_in_words(source.last_fetch_started_at) %> ago
@@ -24,8 +51,10 @@
             Last fetched <%= time_ago_in_words(source.last_fetched_at) %> ago
           </span>
         <% end %>
+        <span class="text-slate-400">&middot;</span>
+        <%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %>
+      </div>
       </div>
-      <p class="mt-2 text-sm text-slate-500">Feed URL: <%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %></p>
     </div>
     <div class="flex flex-wrap items-center justify-end gap-3">
       <% fetch_disabled = %w[queued fetching].include?(source.fetch_status) %>

data/app/views/source_monitor/sources/_row.html.erb

@@ -23,13 +23,18 @@
 
 <tr id="<%= dom_id(source, :row) %>" class="hover:bg-slate-50">
   <td class="px-6 py-4">
-    <div class="font-medium text-slate-900">
-      <%= link_to source.name,
-            source_monitor.source_path(source),
-            class: "text-slate-900 hover:text-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2",
-            data: { turbo_frame: "_top" } %>
+    <div class="flex items-center gap-3">
+      <%= source_favicon_tag(source, size: 24) %>
+      <div>
+        <div class="font-medium text-slate-900">
+          <%= link_to source.name,
+                source_monitor.source_path(source),
+                class: "text-slate-900 hover:text-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2",
+                data: { turbo_frame: "_top" } %>
+        </div>
+        <div class="text-xs text-slate-500 truncate max-w-xs"><%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %></div>
+      </div>
     </div>
-    <div class="text-xs text-slate-500 truncate max-w-xs"><%= external_link_to source.feed_url, source.feed_url, class: "text-slate-500 hover:text-blue-500" %></div>
   </td>
   <td class="px-6 py-4">
     <div class="flex flex-col gap-2 text-xs">

data/config/routes.rb

@@ -22,5 +22,6 @@ SourceMonitor::Engine.routes.draw do
     resource :bulk_scrape, only: :create, controller: "source_bulk_scrapes"
     resource :health_check, only: :create, controller: "source_health_checks"
     resource :health_reset, only: :create, controller: "source_health_resets"
+    resource :favicon_fetch, only: :create, controller: "source_favicon_fetches"
   end
 end

data/docs/configuration.md

@@ -46,7 +46,7 @@ The helper `SourceMonitor.mission_control_dashboard_path` performs a routing che
 - `timeout` – total request timeout in seconds (default `15`)
 - `open_timeout` – connection open timeout in seconds (`5`)
 - `max_redirects` – maximum redirects to follow (`5`)
-- `user_agent` – defaults to `SourceMonitor/<version>`
+- `user_agent` – defaults to `Mozilla/5.0 (compatible; SourceMonitor/<version>)` (browser-like to avoid bot-blocking)
 - `proxy` – hash or URL to configure proxy usage
 - `headers` – hash (or callables) merged into every request
 - `retry_max`, `retry_interval`, `retry_interval_randomness`, `retry_backoff_factor`, `retry_statuses` – mapped to `faraday-retry`

data/docs/upgrade.md

@@ -46,6 +46,28 @@ If a removed option raises an error (`SourceMonitor::DeprecatedOptionError`), yo
 
 ## Version-Specific Notes
 
+### Upgrading to 0.8.0 (from 0.7.x)
+
+**What changed:**
+- Default HTTP User-Agent changed from `SourceMonitor/<version>` to a browser-like string (`Mozilla/5.0 (compatible; SourceMonitor/<version>)`) with Accept-Language, DNT, and Referer headers. This prevents bot-blocking by feed servers.
+- Default `max_in_flight_per_source` changed from `25` to `nil` (unlimited). If you relied on the previous default, add `config.scraping.max_in_flight_per_source = 25` to your initializer.
+- Successful manual health checks on degraded sources now trigger a feed fetch to allow faster recovery.
+- Automatic source favicons via Active Storage (see `config.favicons` section).
+- Toast notifications capped at 3 visible with "+N more" overflow badge and "Clear all" button.
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/rails source_monitor:upgrade
+bin/rails db:migrate
+```
+
+**Notes:**
+- No breaking changes for most users. The User-Agent and `max_in_flight_per_source` defaults changed, but both are backward-compatible.
+- If you explicitly set `config.http.user_agent` in your initializer, your custom value is preserved.
+- If your scraping workload requires per-source rate limiting, set `config.scraping.max_in_flight_per_source` explicitly.
+- Favicons require Active Storage in the host app; apps without it see placeholder initials with no errors.
+
 ### Upgrading to 0.4.0 (from 0.3.x)
 
 **Released:** 2026-02-12

data/lib/generators/source_monitor/install/templates/source_monitor.rb.tt

@@ -70,7 +70,7 @@ SourceMonitor.configure do |config|
   # config.http.retry_interval = 0.5
   # config.http.retry_backoff_factor = 2
   # config.http.retry_statuses = [429, 500, 502, 503, 504]
-  # Merge extra default headers (User-Agent defaults to SourceMonitor/version).
+  # Merge extra default headers (User-Agent defaults to a browser-like string).
   # config.http.headers = { "X-Request-ID" => -> { SecureRandom.uuid } }
 
   # ---- Adaptive fetch scheduling ----------------------------------------
@@ -141,6 +141,20 @@ SourceMonitor.configure do |config|
   # config.models.source.validate :enforce_custom_rules
   # config.models.source.validate ->(record) { record.errors.add(:base, "custom error") }
 
+  # ---- Favicons ----------------------------------------------------------
+  # Automatically fetch and store source favicons via Active Storage.
+  # Requires Active Storage in the host app (rails active_storage:install).
+  # Without Active Storage, favicons are silently disabled and colored
+  # initials placeholders are shown instead.
+  # config.favicons.enabled = true                    # default: true
+  # config.favicons.fetch_timeout = 5                 # seconds
+  # config.favicons.max_download_size = 1_048_576     # 1 MB
+  # config.favicons.retry_cooldown_days = 7
+  # config.favicons.allowed_content_types = %w[
+  #   image/x-icon image/vnd.microsoft.icon image/png
+  #   image/jpeg image/gif image/svg+xml image/webp
+  # ]
+
   # ---- Realtime adapter -------------------------------------------------
   # Choose the Action Cable backend powering Turbo Streams. Solid Cable keeps
   # everything in the primary database so Redis is no longer required. Switch