html2rss 0.33.0 → 0.34.0

data/lib/html2rss/feed_builder/json_feed/item.rb

@@ -103,7 +103,8 @@ module Html2rss
           {
             url: enclosure.url.to_s,
             mime_type: enclosure.type,
-            size_in_bytes: size&.positive? ? size : nil
+            size_in_bytes: (size if size.positive?),
+            duration_in_seconds: enclosure.duration
           }.compact
         end
       end

data/lib/html2rss/feed_builder/json_feed.rb

@@ -16,7 +16,7 @@ module Html2rss
       # @param user_comment [String] required generator comment (from {Status})
       # @param feed_url [String, nil] optional absolute self URL for the feed (JSON Feed feed_url)
       def initialize(channel:, articles:, user_comment:, feed_url: nil)
-        raise ArgumentError, 'user_comment must be a non-blank String' if blank_string?(user_comment)
+        raise InvalidOption, 'user_comment must be a non-blank String' if blank_string?(user_comment)
 
         @channel = channel
         @articles = articles
@@ -42,7 +42,7 @@ module Html2rss
 
       def normalize_feed_url(value)
         return if value.nil?
-        raise ArgumentError, 'feed_url must be a String or nil' unless value.is_a?(String)
+        raise InvalidOption, 'feed_url must be a String or nil' unless value.is_a?(String)
         return if value.strip.empty?
 
         Url.from_absolute(value).to_s

data/lib/html2rss/feed_builder/rss/stylesheet.rb

@@ -43,9 +43,9 @@ module Html2rss
         # @param type [String] MIME type (`text/css` or `text/xsl`)
         # @param media [String] media query hint for the stylesheet
         def initialize(href:, type:, media: 'all')
-          raise ArgumentError, 'stylesheet.href must be a String' unless href.is_a?(String)
-          raise ArgumentError, 'stylesheet.type invalid' unless TYPES.include?(type)
-          raise ArgumentError, 'stylesheet.media must be a String' unless media.is_a?(String)
+          raise InvalidOption, 'stylesheet.href must be a String' unless href.is_a?(String)
+          raise InvalidOption, 'stylesheet.type invalid' unless TYPES.include?(type)
+          raise InvalidOption, 'stylesheet.media must be a String' unless media.is_a?(String)
 
           @href = href
           @type = type

data/lib/html2rss/feed_builder/rss.rb

@@ -6,7 +6,20 @@ module Html2rss
   module FeedBuilder
     ##
     # Builds an RSS Feed by providing channel, articles and stylesheets.
-    class Rss
+    #
+    # A media feed ({ItemPresentation.media_feed?}) also gets the podcast tags clients play from:
+    # channel +itunes:image+, +itunes:author+, +itunes:category+ (nesting its subcategories) and
+    # +itunes:explicit+ (+true+ or +false+), item +itunes:duration+ (+HH:MM:SS+) and +itunes:image+, each
+    # only when known; categories and the explicit flag only when the followed native feed states them.
+    #
+    # +managingEditor+ carries the channel author only when it is an RSS 2.0 email address
+    # (+editor@example.com+ or +editor@example.com (Name)+); a plain name is no managing editor.
+    class Rss # rubocop:disable Metrics/ClassLength -- channel, item and podcast projections stay co-located
+      # First duration in seconds that +itunes:duration+ cannot spell as +HH:MM:SS+ (100 hours).
+      MAX_CLOCK_DURATION = 100 * 3600
+      # An RSS 2.0 person: an email address, optionally followed by the name in parentheses.
+      EMAIL_PERSON = /\A[^\s@()]+@[^\s@()]+(?: \(.+\))?\z/
+
       class << self
         # @param article [Html2rss::Article] source article
         # @param item_maker [RSS::Maker::RSS20::ItemsBase::ItemBase] RSS item builder
@@ -60,12 +73,13 @@ module Html2rss
       # @param stylesheets [Array<Hash>] An optional array of stylesheet configurations.
       # @param generator [String] required preformatted generator comment (from {Status})
       def initialize(channel:, articles:, generator:, stylesheets: [])
-        raise ArgumentError, 'generator must be a non-blank String' if blank_string?(generator)
+        raise InvalidOption, 'generator must be a non-blank String' if blank_string?(generator)
 
         @channel = channel
         @articles = articles
         @stylesheets = stylesheets
         @generator = generator
+        @media_feed = ItemPresentation.media_feed?(articles)
       end
 
       # @return [RSS::Rss] RSS 2.0 document instance
@@ -80,7 +94,7 @@ module Html2rss
 
       private
 
-      attr_reader :channel, :articles, :generator
+      attr_reader :channel, :articles, :generator, :media_feed
 
       def blank_string?(value)
         !value.is_a?(String) || value.strip.empty?
@@ -98,13 +112,25 @@ module Html2rss
         channel_maker.description = channel.description
         channel_maker.ttl = channel.ttl
 
-        channel_maker.managingEditor = channel.author if channel.author
-        channel_maker.author = channel.author if channel.author
+        channel_maker.managingEditor = channel.author if EMAIL_PERSON.match?(channel.author)
         channel_maker.link = channel.url.to_s
         channel_maker.generator = generator
         channel_maker.updated = channel.last_build_date
 
         make_image(maker.image) if channel.image
+        make_podcast_channel(channel_maker) if media_feed
+      end
+
+      def make_podcast_channel(channel_maker)
+        channel_maker.itunes_image = channel.image
+        channel_maker.itunes_author = channel.author
+        channel_maker.itunes_explicit = channel.explicit&.to_s
+        channel.categories.each { add_itunes_category(channel_maker, *_1) }
+      end
+
+      def add_itunes_category(channel_maker, name, *subcategories)
+        category = channel_maker.new_itunes_category(name)
+        subcategories.each { category.new_category.text = _1 }
       end
 
       def make_image(image_maker)
@@ -114,9 +140,26 @@ module Html2rss
 
       def make_items(maker)
         articles.each do |article|
-          maker.items.new_item { |item_maker| self.class.add_item(article, item_maker) }
+          maker.items.new_item do |item_maker|
+            self.class.add_item(article, item_maker)
+            make_podcast_item(article, item_maker) if media_feed
+          end
         end
       end
+
+      def make_podcast_item(article, item_maker)
+        duration = ItemPresentation.rss_enclosure_for(article)&.duration
+        item_maker.itunes_duration = format_duration(duration) if duration
+        item_maker.itunes_image = article.image
+      end
+
+      # +HH:MM:SS+; plain seconds from 100 hours on, which +HH+ cannot spell.
+      def format_duration(seconds)
+        return seconds.to_s if seconds >= MAX_CLOCK_DURATION
+
+        format('%<hours>02d:%<minutes>02d:%<seconds>02d',
+               hours: seconds / 3600, minutes: seconds % 3600 / 60, seconds: seconds % 60)
+      end
     end
   end
 end

data/lib/html2rss/feed_builder.rb

@@ -8,7 +8,8 @@ module Html2rss
   # FeedResult; +feed_url+ is a render-time JSON Feed-only option.
   #
   # Channel field projection:
-  # - Rss: language, title, description, ttl, link, updated
+  # - Rss: language, title, description, ttl, link, updated, managingEditor (author in email form only)
+  #   (+ itunes:image, itunes:author, itunes:category, itunes:explicit on a media feed)
   # - JsonFeed: title, home_page_url, description, language, icon, authors (+ feed_url)
   module FeedBuilder
   end

data/lib/html2rss/feed_pipeline/README.md

@@ -11,7 +11,7 @@ Use `:auto` when you want `default` (HTTPX) first and a browser-backed hop only
 1. **Default (HTTPX)** — plain HTTP (faster, cheaper).
 2. **Botasaurus** — attempted when default raises a fallback-eligible error (for example `BlockedSurfaceDetected` or timeout) or extracts zero feed items.
 
-Before escalating default → Botasaurus on a **weak** auto-source extract (empty / below floor / high-entropy / app-shell / unsupported — not blocked), `FeedResolution` may probe up to five same-origin listing or native-feed candidates and rewrite the effective scrape URL via {ScrapeTarget}. Botasaurus then uses the resolved URL. Direct RSS/Atom entry URLs are parsed via `Syndication::Parser` without HTML AutoSource.
+Before escalating default → Botasaurus on a **weak** auto-source extract (empty / below floor / high-entropy / app-shell / unsupported — not blocked), `FeedResolution` may probe up to five same-origin listing or native-feed candidates and rewrite the effective scrape URL via {ScrapeTarget}. Botasaurus then uses the resolved URL. Direct RSS/Atom/RDF entry URLs are parsed via `Syndication::Parser` without HTML AutoSource.
 
 There is no Browserless / Puppeteer-in-gem tier. Pin `botasaurus` when you want browser rendering without default first. Botasaurus needs `BOTASAURUS_SCRAPER_URL`.
 

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -108,26 +108,15 @@ module Html2rss
         end
 
         # @param response [RequestService::Response] successful response
-        # @param articles [Array] extracted articles
-        # @param dedup_dropped [Integer] articles removed by deduplication
+        # @param extraction [Html2rss::FeedPipeline::Extraction] its articles, drops and feed channel facts
         # @param selected_strategy [Symbol] concrete strategy that produced items
         # @param attempt_count [Integer] number of attempts recorded for this chain
-        # @param admission_drops [Hash{String => Integer}] Cleanup drop tallies
         # @param scrape_target [Html2rss::ScrapeTarget]
         # @return [void]
-        # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- PipelineOutcome kwargs stay co-located
-        def succeed!(response:, articles:, dedup_dropped:, selected_strategy:, attempt_count:,
-                     scrape_target:, admission_drops: {})
+        def succeed!(response:, extraction:, selected_strategy:, attempt_count:, scrape_target:)
           @result = PipelineOutcome.new(
-            response:,
-            articles:,
-            dedup_dropped:,
-            selected_strategy:,
-            attempt_count:,
-            strategy_attempts: attempts,
-            admission_drops:,
-            scrape_target:,
-            entry_resolution:
+            response:, selected_strategy:, attempt_count:, strategy_attempts: attempts,
+            scrape_target:, entry_resolution:, **extraction.to_h
           )
         end
 
@@ -215,6 +204,8 @@ module Html2rss
       rescue *NON_FALLBACK_ERRORS => error
         state.record_error(strategy:, error:, elapsed_ms: monotonic_ms - started_ms)
         state.abort!
+      rescue Html2rss::ContractError
+        raise
       rescue Html2rss::Error => error
         state.record_error(strategy:, error:, elapsed_ms: monotonic_ms - started_ms)
         log_fallback_error(strategy:, next_strategy:, error:, request_session:) if next_strategy && request_session
@@ -222,11 +213,9 @@ module Html2rss
 
       # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize, Metrics/ParameterLists -- extract + resolution delegate
       def process_response(response:, strategy:, next_strategy:, request_session:, state:, elapsed_ms: nil)
-        articles, dedup_dropped, admission_drops = pipeline.deduplicated_articles(
-          config:, response:, request_session:
-        )
+        extraction = pipeline.extract(config:, response:, request_session:)
         state.remember_response(response)
-        items_count = articles.size
+        items_count = extraction.articles.size
         state.record_items(strategy:, items_count:, transport_meta: response.transport_meta, elapsed_ms:)
         Log.debug("#{self.class}: strategy=#{strategy} items=#{items_count} " \
                   "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
@@ -234,16 +223,13 @@ module Html2rss
 
         if (outcome = FeedResolution.try_apply!(
           pipeline:, config:, response:, session: request_session, strategy:, resources:,
-          articles:, scrape_target:, state:, budget:
+          articles: extraction.articles, scrape_target:, state:, budget:
         ))
           @scrape_target = outcome.scrape_target
           return
         end
 
-        if items_count.positive?
-          return record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:,
-                                state:)
-        end
+        return record_success(response:, strategy:, extraction:, state:) if items_count.positive?
 
         if DETERMINISTIC_HTTP_STATUSES.member?(response&.status)
           state.abort!
@@ -254,14 +240,10 @@ module Html2rss
         log_info_fallback_zero_items(strategy:, next_strategy:, response:) if next_strategy
       end
 
-      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- success kwargs + structured selected log
-      def record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:, state:)
+      # rubocop:disable-next Metrics/MethodLength -- success + structured selected log
+      def record_success(response:, strategy:, extraction:, state:)
         attempt_count = state.attempts.size
-        state.succeed!(
-          response:, articles:, dedup_dropped:, selected_strategy: strategy,
-          attempt_count:, admission_drops:,
-          scrape_target:
-        )
+        state.succeed!(response:, extraction:, selected_strategy: strategy, attempt_count:, scrape_target:)
         return unless attempt_count > 1
 
         Log.info({

data/lib/html2rss/feed_pipeline/strategy_plan.rb

@@ -33,13 +33,13 @@ module Html2rss
         ##
         # @param name [Symbol, String] config or configure strategy value
         # @return [Auto, Concrete] resolved feed-level plan
-        # @raise [ArgumentError] when +name+ is neither +:auto+ nor a registered strategy
+        # @raise [InvalidOption] when +name+ is neither +:auto+ nor a registered strategy
         def resolve(name)
           normalized = name.to_sym
           return Auto.new if normalized == AUTO_NAME
 
           unless RequestService.strategy_registered?(normalized)
-            raise ArgumentError, "unknown strategy plan: #{name.inspect}"
+            raise InvalidOption, "unknown strategy plan: #{name.inspect}"
           end
 
           Concrete.new(strategy: normalized)
@@ -64,7 +64,7 @@ module Html2rss
 
           resolve(name)
           true
-        rescue ArgumentError
+        rescue InvalidOption
           false
         end
 

data/lib/html2rss/feed_pipeline.rb

@@ -10,11 +10,19 @@ module Html2rss
     # selected_strategy: set on :auto success; nil otherwise.
     # attempt_count: auto attempts attempted; 0 outside :auto.
     # strategy_attempts: auto attempt hashes (with optional transport_meta); empty outside :auto.
+    # feed_channel: channel facts of the native feed followed ({Syndication::ChannelFacts}); nil without one.
     PipelineOutcome = Data.define(
       :response, :articles, :dedup_dropped, :selected_strategy, :attempt_count, :strategy_attempts,
-      :admission_drops, :scrape_target, :entry_resolution
+      :admission_drops, :scrape_target, :entry_resolution, :feed_channel
     )
 
+    # What one response yields after extraction and dedup ({#extract}); its fields are the
+    # {PipelineOutcome} fields of the same names.
+    # articles: unique articles. dedup_dropped: articles removed by deduplication.
+    # admission_drops: Cleanup drop tallies. feed_channel: the followed native feed's channel facts
+    # ({Syndication::ChannelFacts}); nil without one.
+    Extraction = Data.define(:articles, :dedup_dropped, :admission_drops, :feed_channel)
+
     ##
     # @param raw_config [Hash{Symbol => Object}] user-provided feed config
     def initialize(raw_config)
@@ -71,11 +79,11 @@ module Html2rss
     # @param config [Html2rss::Config]
     # @param response [Html2rss::RequestService::Response]
     # @param request_session [Html2rss::RequestSession]
-    # @return [Array(Array<Html2rss::Article>, Integer, Hash)] unique articles, dedup drops, admission drops
-    def deduplicated_articles(config:, response:, request_session:)
-      collected, admission_drops = collect_articles(config:, response:, request_session:)
+    # @return [Extraction] unique articles with their dedup and admission drops and feed channel facts
+    def extract(config:, response:, request_session:)
+      collected, admission_drops, feed_channel = collect_articles(config:, response:, request_session:)
       unique = Article::Deduplicator.new(collected).call
-      [unique, collected.size - unique.size, admission_drops]
+      Extraction.new(articles: unique, dedup_dropped: collected.size - unique.size, admission_drops:, feed_channel:)
     end
 
     private
@@ -95,13 +103,12 @@ module Html2rss
     def run_pipeline_for_strategy(config, strategy:, resources:)
       request_session = request_session_for(config, strategy:, resources:)
       response = request_session.fetch_initial_response
-      articles, dedup_dropped, admission_drops = deduplicated_articles(config:, response:, request_session:)
-      raise_empty_auto_source!(strategy:, response:) if config.auto_source && articles.empty?
+      extraction = extract(config:, response:, request_session:)
+      raise_empty_auto_source!(strategy:, response:) if config.auto_source && extraction.articles.empty?
 
       PipelineOutcome.new(
-        response:, articles:, dedup_dropped:, selected_strategy: nil, attempt_count: 0,
-        strategy_attempts: [], admission_drops:,
-        scrape_target: ScrapeTarget.from_config(config), entry_resolution: nil
+        response:, selected_strategy: nil, attempt_count: 0, strategy_attempts: [],
+        scrape_target: ScrapeTarget.from_config(config), entry_resolution: nil, **extraction.to_h
       )
     end
 
@@ -127,49 +134,55 @@ module Html2rss
     end
 
     def collect_articles(config:, response:, request_session:)
-      selector = selector_articles(config:, response:, request_session:)
-      auto, admission_drops = auto_source_articles(config:, response:, request_session:)
-      [selector + auto, admission_drops]
+      selector, selector_drops = selector_articles(config:, response:, request_session:)
+      auto, auto_drops, feed_channel = auto_source_articles(config:, response:, request_session:)
+      [selector + auto, selector_drops.merge(auto_drops) { |_reason, left, right| left + right }, feed_channel]
     end
 
-    # rubocop:disable-next Metrics/MethodLength
+    # @return [Array(Array<Html2rss::Article>, Hash{String => Integer})] articles and unlinked-item drop tallies
     def selector_articles(config:, response:, request_session:)
-      return [] unless (selectors = config.selectors)
-      return [] if response.feed_response?
+      return [[], {}] unless (selectors = config.selectors)
+      return [[], {}] if response.feed_response?
 
       page_responses = request_session.page_responses(
         response,
         pagination_config: selectors.dig(:items, :pagination)
       )
+      engines = page_responses.lazy.map { |page| Selectors.new(page, selectors:, time_zone: config.time_zone) }
+      collect_selector_pages(engines)
+    end
 
+    # Stops at the first empty page after articles were found; drop tallies sum over the pages read.
+    def collect_selector_pages(engines)
       articles = []
-      page_responses.each do |page_response|
-        page_articles = Selectors.new(page_response, selectors:, time_zone: config.time_zone).articles
+      drops = Hash.new(0)
+      engines.each do |engine|
+        page_articles = engine.articles
+        engine.admission_drops.each { |reason, count| drops[reason] += count }
         break if page_articles.empty? && articles.any?
 
         articles.concat(page_articles)
       end
-      articles
+      [articles, drops]
     end
 
-    # @return [Array(Array<Html2rss::Article>, Hash{String => Integer})]
+    # @return [Array(Array<Html2rss::Article>, Hash{String => Integer}, Html2rss::Syndication::ChannelFacts)]
     def auto_source_articles(config:, response:, request_session:)
-      return [[], {}] unless (auto_source = config.auto_source)
+      return [[], {}, nil] unless (auto_source = config.auto_source)
       return syndication_articles(response) if response.feed_response?
 
       source = AutoSource.new(response, auto_source, request_session:)
-      [source.articles, source.admission_drops]
+      [source.articles, source.admission_drops, source.feed_channel]
     end
 
     def syndication_articles(response)
-      articles = Syndication::Parser.parse_response(response).map do |hash|
-        Article.new(**hash, scraper: AutoSource::Scraper::NativeFeed)
-      end
-      [articles, {}]
+      feed = Syndication::Parser.parse_response(response)
+      articles = feed.articles.map { |hash| Article.new(**hash, scraper: AutoSource::Scraper::NativeFeed) }
+      [articles, {}, feed.channel]
     end
 
     def feed_result_for(config, outcome) # rubocop:disable Metrics/MethodLength
-      channel = Channel.from_response(outcome.response, overrides: config.channel)
+      channel = Channel.from_response(outcome.response, overrides: config.channel, feed: outcome.feed_channel)
       status = Status.build(
         articles: outcome.articles,
         dedup_dropped: outcome.dedup_dropped,

data/lib/html2rss/feed_resolution/README.md

@@ -24,7 +24,7 @@ tournament on item count (feed-as-means) — intentional.
 
 ### CandidateGenerator mix
 
-- **Feed slot:** first `Syndication::Discovery.candidate_urls` only (alternates precede path guesses).
+- **Feed slot:** first same-domain `Syndication::Discovery.candidate_urls` entry. Alternates precede path guesses, except audio-hinted ones on a page without podcast signals. An alternate on another domain is skipped.
 - **Listing fill** (cap = `max - 1` when `max > 1`; `max == 1` → feed only): nav (`taxonomy_path +3`, `content_path +1`) → segment first-wins (`:list` → `:cluster` → `:semantic`, ≥2 same-origin primary links) → `LISTING_PATHS`.
 - Same-page / same-registrable-domain filters; feed never pads into listing slots.
 

data/lib/html2rss/feed_resolution/candidate_generator.rb

@@ -46,13 +46,12 @@ module Html2rss
 
       def listing_cap = max > 1 ? max - 1 : 0
 
+      # First eligible Discovery candidate: an alternate on another domain (Discovery ranks
+      # audio-hinted ones first on a podcast page) must not displace a same-domain feed or path guess.
       def feed_slot
         return unless parsed_html
 
-        url = Syndication::Discovery.candidate_urls(page_url: entry_url, parsed_body: parsed_html).first
-        return unless eligible_url?(url)
-
-        url
+        Syndication::Discovery.candidate_urls(page_url: entry_url, parsed_body: parsed_html).find { eligible_url?(_1) }
       end
 
       def listing_urls

data/lib/html2rss/feed_resolution/policy.rb

@@ -15,7 +15,7 @@ module Html2rss
         # @param surface_category [Html2rss::SurfaceCategory, Symbol]
         # @return [Boolean]
         def resolve?(config:, articles:, surface_category:)
-          raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
+          raise InvalidError, 'articles must be an Array' unless articles.is_a?(Array)
           return false unless eligible_config?(config)
 
           category = SurfaceCategory[surface_category]

data/lib/html2rss/feed_resolution/probe.rb

@@ -29,6 +29,8 @@ module Html2rss
           origin_url:
         )
         score_response(response)
+      rescue Html2rss::ContractError
+        raise
       rescue Html2rss::Error
         nil
       end
@@ -39,7 +41,7 @@ module Html2rss
 
       def score_response(response) # rubocop:disable Metrics/MethodLength -- feed vs HTML branches
         if response.feed_response?
-          count = Syndication::Parser.parse_response(response).size
+          count = Syndication::Parser.parse_response(response).articles.size
           return Scored.new(
             url: response.url,
             score: Scorer.score_feed(articles_count: count),

data/lib/html2rss/feed_resolution.rb

@@ -8,6 +8,9 @@ module Html2rss
   #
   # {include:file:lib/html2rss/feed_resolution/README.md}
   module FeedResolution
+    # Raised when the tournament or its policy is handed articles that are not an Array.
+    class InvalidError < Html2rss::ContractError; end
+
     # Default entry-resolution options merged into AutoSource::DEFAULT_CONFIG.
     DEFAULT_CONFIG = {
       enabled: true,
@@ -120,7 +123,7 @@ module Html2rss
       rescue RequestService::RequestBudgetExceeded
         log_budget_exhausted
         nil
-      rescue *NON_FALLBACK_ERRORS
+      rescue *NON_FALLBACK_ERRORS, Html2rss::ContractError
         raise
       rescue Html2rss::Error => error
         log_retry_failed(error)
@@ -185,19 +188,15 @@ module Html2rss
           config, strategy:, resources:, scrape_url: effective.effective_url
         )
         retry_response = retry_session.fetch_initial_response
-        retry_articles, dedup_dropped, admission_drops = pipeline.deduplicated_articles(
-          config:, response: retry_response, request_session: retry_session
-        )
+        extraction = pipeline.extract(config:, response: retry_response, request_session: retry_session)
+        items_count = extraction.articles.size
         state.remember_response(retry_response)
-        state.record_items(
-          strategy:, items_count: retry_articles.size, transport_meta: retry_response.transport_meta
-        )
-        return unless retry_articles.size.positive?
+        state.record_items(strategy:, items_count:, transport_meta: retry_response.transport_meta)
+        return unless items_count.positive?
 
         state.succeed!(
-          response: retry_response, articles: retry_articles, dedup_dropped:,
-          selected_strategy: strategy, attempt_count: state.attempts.size, admission_drops:,
-          scrape_target: effective
+          response: retry_response, extraction:, selected_strategy: strategy,
+          attempt_count: state.attempts.size, scrape_target: effective
         )
         true
       end
@@ -214,7 +213,7 @@ module Html2rss
       # @param surface_category [Symbol, nil]
       # rubocop:disable-next Metrics/ParameterLists -- tournament context stays co-located
       def initialize(entry_url:, response:, session:, config:, articles:, surface_category: nil)
-        raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
+        raise InvalidError, 'articles must be an Array' unless articles.is_a?(Array)
 
         @entry_url = Url.from_absolute(entry_url)
         @response = response

data/lib/html2rss/feed_result.rb

@@ -15,16 +15,20 @@ module Html2rss
   #   are re-frozen via private {#marshal_load}. For trusted cache reads only,
   #   +Marshal.load(payload, freeze: true)+ is also safe.
   class FeedResult
+    # Raised when the scrape handle is built from invalid parts.
+    class InvalidError < Html2rss::ContractError; end
+
     ##
     # @param channel [Html2rss::Channel] channel metadata (internal; not exposed on the public API)
     # @param articles [Array<Html2rss::Article>] extracted articles (deduplicated; not exposed)
     # @param status [Html2rss::Status] pipeline telemetry
     # @param stylesheets [Array<Hash>] optional RSS stylesheet configs
+    # @raise [InvalidError] when a part has the wrong type
     def initialize(channel:, articles:, status:, stylesheets: [])
-      raise ArgumentError, 'channel must be a Html2rss::Channel' unless channel.is_a?(Channel)
-      raise ArgumentError, 'status must be a Html2rss::Status' unless status.is_a?(Status)
-      raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
-      raise ArgumentError, 'articles must all be Html2rss::Article' unless articles.all?(Article)
+      raise InvalidError, 'channel must be a Html2rss::Channel' unless channel.is_a?(Channel)
+      raise InvalidError, 'status must be a Html2rss::Status' unless status.is_a?(Status)
+      raise InvalidError, 'articles must be an Array' unless articles.is_a?(Array)
+      raise InvalidError, 'articles must all be Html2rss::Article' unless articles.all?(Article)
 
       @channel = channel
       @articles = articles.dup.freeze
@@ -81,7 +85,7 @@ module Html2rss
     end
 
     def freeze_stylesheets(stylesheets)
-      raise ArgumentError, 'stylesheets must be an Array' unless stylesheets.is_a?(Array)
+      raise InvalidError, 'stylesheets must be an Array' unless stylesheets.is_a?(Array)
 
       stylesheets.map do |sheet|
         sheet.to_h.transform_keys(&:to_sym).transform_values do |value|

data/lib/html2rss/hash_util.rb

@@ -81,7 +81,7 @@ module Html2rss
 
         unless value.each_key.all?(Symbol)
           invalid_key = value.keys.find { _1.class != Symbol }
-          raise ArgumentError, "#{context} must use symbol keys (found #{invalid_key.inspect})"
+          raise InvalidOption, "#{context} must use symbol keys (found #{invalid_key.inspect})"
         end
 
         value.each_value { assert_symbol_keys!(_1, context:, deep:) } if deep
@@ -98,7 +98,7 @@ module Html2rss
 
         unless value.each_key.all?(String)
           invalid_key = value.keys.find { _1.class != String }
-          raise ArgumentError, "#{context} must use string keys (found #{invalid_key.inspect})"
+          raise InvalidOption, "#{context} must use string keys (found #{invalid_key.inspect})"
         end
 
         value.each_value { assert_string_keys!(_1, context:, deep:) } if deep
@@ -111,7 +111,7 @@ module Html2rss
         in Symbol then key
         in String then key.to_sym
         else
-          raise ArgumentError, "#{context} must use string or symbol keys (found #{key.inspect})"
+          raise InvalidOption, "#{context} must use string or symbol keys (found #{key.inspect})"
         end
       end
     end

data/lib/html2rss/html/article_extractor/category_extractor.rb

@@ -42,7 +42,7 @@ module Html2rss
           Set.new.tap do |categories|
             extract_element_data_categories!(categories, article_tag, title:)
             article_tag.css(CATEGORY_SELECTORS.join(',')).each do |element|
-              if ArticleRules::Category.class_match?(element['class'])
+              if ArticleRules::Category.class_match?(element['class'].to_s.split)
                 extract_text_categories!(categories, element, title:)
               end
               extract_element_data_categories!(categories, element, title:)