html2rss 0.33.0 → 0.34.0

data/lib/html2rss/request_service/response_caching.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Html2rss
+  class RequestService
+    ##
+    # Opt-in reuse of initial page fetches, e.g. while a person iterates on selectors for one page.
+    # Extended onto {RequestService}; the cache is consulted only for +relation == :initial+ requests,
+    # follow-ups always hit the network.
+    #
+    # The key is a SHA256 digest of the URL, strategy, headers, request options and the policy fields
+    # that shape a response, so credentials never reach the cache and a response fetched under a
+    # permissive {Policy} is never served to a stricter one. Cookie-store state is not part of the key.
+    module ResponseCaching
+      # Mutex guarding the process-wide response cache reference.
+      RESPONSE_CACHE_MUTEX = Mutex.new
+      # Fiber-storage key for the active {#observe_cache_hits} collector.
+      CACHE_HITS_KEY = :html2rss_cache_hits
+      # Fiber-storage key for the cache installed by {#with_response_cache}.
+      SCOPED_CACHE_KEY = :html2rss_scoped_response_cache
+      private_constant :RESPONSE_CACHE_MUTEX, :CACHE_HITS_KEY, :SCOPED_CACHE_KEY
+
+      # @param cache [#fetch, nil] receives +fetch(key) { response }+ and returns the cached or freshly
+      #   built {Response} (tagged with {Response#cache_age} on a hit), e.g. {ResponseCache};
+      #   +nil+ (the default) disables caching. A raising block must not be cached.
+      # @return [void]
+      def response_cache=(cache)
+        RESPONSE_CACHE_MUTEX.synchronize { @response_cache = cache }
+      end
+
+      # @return [#fetch, nil] the scoped cache from {#with_response_cache} if one is active, otherwise
+      #   the globally configured initial-response cache, if any
+      def response_cache
+        scoped = Fiber[SCOPED_CACHE_KEY]
+        return scoped.first if scoped
+
+        RESPONSE_CACHE_MUTEX.synchronize { @response_cache }
+      end
+
+      # Runs the block with +cache+ as the initial-response cache for the current fiber (and fibers or
+      # threads it spawns), taking precedence over {#response_cache=}. The previous scope is restored
+      # when the block exits, even by raising.
+      #
+      # @param cache [#fetch, nil] cache for the block; +nil+ disables caching inside it
+      # @yieldreturn [Object] the block's result
+      # @return [Object] the block's result
+      def with_response_cache(cache)
+        previous = Fiber[SCOPED_CACHE_KEY]
+        Fiber[SCOPED_CACHE_KEY] = [cache]
+        yield
+      ensure
+        Fiber[SCOPED_CACHE_KEY] = previous
+      end
+
+      # Runs the block and reports the cache ages of every initial fetch it served from {#response_cache},
+      # including fetches on threads the block spawns (fiber storage is inherited by reference).
+      #
+      # @yieldreturn [Object] the block's result
+      # @return [Array(Object, Array<Integer>)] the block's result and the served cache ages in seconds
+      def observe_cache_hits
+        hits = Fiber[CACHE_HITS_KEY] = Queue.new
+        result = yield
+        [result, Array.new(hits.size) { hits.pop }]
+      ensure
+        Fiber[CACHE_HITS_KEY] = nil
+      end
+
+      private
+
+      ##
+      # Runs +fetch+ directly, or through {#response_cache} for initial requests.
+      # Callers always receive their own {Response} so parsed documents are never shared.
+      # @param ctx [Context] the request context
+      # @param strategy [Symbol] the resolved strategy name
+      # @yieldreturn [Response] the freshly fetched response
+      # @return [Response]
+      def fetch_initial_through_cache(ctx, strategy, &)
+        cache = response_cache
+        return yield unless cache && ctx.relation == :initial
+
+        cache.fetch(response_cache_key(ctx, strategy), &).replica.tap { |response| record_cache_hit(response) }
+      end
+
+      def record_cache_hit(response)
+        Fiber[CACHE_HITS_KEY]&.push(response.cache_age) if response.cache_age
+      end
+
+      def response_cache_key(ctx, strategy)
+        parts = [ctx.url.to_s, strategy, ctx.headers.sort, ctx.request, ctx.policy.cache_key]
+        Digest::SHA256.hexdigest(parts.inspect)
+      end
+    end
+  end
+end

data/lib/html2rss/request_service/strategy.rb

@@ -18,12 +18,13 @@ module Html2rss
       # Executes the request through the shared preflight/postflight path.
       #
       # @return [Response] the response from the strategy
-      # @raise [NotImplementedError] if the subclass does not implement `#fetch`
       def execute
         check_timeout!
         response = perform_execute
         postflight!(response)
         response
+      rescue Html2rss::ContractError
+        raise
       rescue StandardError => error
         handle_error(error)
       end
@@ -42,15 +43,6 @@ module Html2rss
         fetch
       end
 
-      ##
-      # Adapter hook: perform the transport-specific fetch after preflight.
-      #
-      # @return [Response] normalized response
-      # @raise [NotImplementedError] when a subclass omits the hook
-      def fetch
-        raise NotImplementedError, 'Subclass must implement #fetch'
-      end
-
       ##
       # Consumes a request slot and validates the destination before transport work.
       #
@@ -60,7 +52,9 @@ module Html2rss
         return if skip_preflight?
 
         ctx.budget.consume! if consume_budget
-        ctx.policy.validate_request!(url: ctx.url, origin_url: ctx.origin_url, relation: ctx.relation)
+        ctx.policy.validate_request!(
+          url: ctx.url, origin_url: ctx.origin_url, relation: ctx.relation, advertisement: ctx.advertisement
+        )
       end
 
       ##

data/lib/html2rss/request_service.rb

@@ -8,28 +8,67 @@ module Html2rss
   # Feed-level +:auto+ is not registered here — {FeedPipeline::StrategyPlan} resolves
   # it to a concrete strategy (or {FeedPipeline::AutoFallback} chain) before execute.
   class RequestService
+    extend ResponseCaching
+
     # Raised when an unknown request strategy is requested.
     class UnknownStrategy < Html2rss::Error; end
+
     # Raised when a URL cannot be parsed or validated.
-    class InvalidUrl < Html2rss::Error; end
+    class InvalidUrl < Html2rss::Error
+      # @return [Symbol]
+      def kind = :invalid_url
+    end
+
     # Raised when a URL uses an unsupported scheme.
-    class UnsupportedUrlScheme < Html2rss::Error; end
+    class UnsupportedUrlScheme < Html2rss::Error
+      # @return [Symbol]
+      def kind = :invalid_url
+    end
+
     # Raised when a response type cannot be parsed.
     class UnsupportedResponseContentType < Html2rss::Error; end
+
     # Raised when HTTP request slot limits are exceeded.
-    class RequestBudgetExceeded < Html2rss::Error; end
+    class RequestBudgetExceeded < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when policy denies private-network access.
-    class PrivateNetworkDenied < Html2rss::Error; end
+    class PrivateNetworkDenied < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when cross-origin follow-up requests are denied.
-    class CrossOriginFollowUpDenied < Html2rss::Error; end
+    class CrossOriginFollowUpDenied < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when a response exceeds configured size limits.
-    class ResponseTooLarge < Html2rss::Error; end
+    class ResponseTooLarge < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when HTTP redirect limits are exceeded.
-    class RedirectLimitReached < Html2rss::Error; end
+    class RedirectLimitReached < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when blocked content surfaces are detected.
-    class BlockedSurfaceDetected < Html2rss::Error; end
+    class BlockedSurfaceDetected < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when the target connection fails before a response document exists.
-    class ConnectionFailed < Html2rss::Error; end
+    class ConnectionFailed < Html2rss::Error
+      # @return [Symbol]
+      def kind = :connection
+    end
 
     # Raised when a request times out.
     class RequestTimedOut < Html2rss::Error
@@ -43,6 +82,9 @@ module Html2rss
 
       # @return [String, nil] scrape-api timeout stage, or nil for transport/budget timeouts
       attr_reader :timeout_phase
+
+      # @return [Symbol]
+      def kind = :timeout
     end
 
     # Raised when Botasaurus configuration is missing or invalid.
@@ -52,7 +94,11 @@ module Html2rss
     end
 
     # Raised when the Botasaurus service cannot be reached (network / DNS / SSL).
-    class BotasaurusConnectionFailed < Html2rss::Error; end
+    class BotasaurusConnectionFailed < Html2rss::Error
+      # @return [Symbol]
+      def kind = :connection
+    end
+
     # Raised when Botasaurus responds but the scrape fails (upstream error, bad payload).
     class BotasaurusServiceError < Html2rss::Error; end
 
@@ -82,9 +128,22 @@ module Html2rss
     MAX_DEPRECATION_WARNINGS = 256
     # Mutex guarding process-local deprecation warning deduplication.
     DEPRECATION_MUTEX = Mutex.new
-    private_constant :DEPRECATION_MUTEX
+    # Mutex guarding the process-wide cookie store reference.
+    COOKIE_STORE_MUTEX = Mutex.new
+    private_constant :DEPRECATION_MUTEX, :COOKIE_STORE_MUTEX
 
     class << self
+      # @param store [#fetch, #write, #evict, nil] replacement cookie store (nil restores the in-memory default)
+      # @return [void]
+      def cookie_store=(store)
+        COOKIE_STORE_MUTEX.synchronize { @cookie_store = store }
+      end
+
+      # @return [#fetch, #write, #evict] the configured cookie store (in-memory by default)
+      def cookie_store
+        COOKIE_STORE_MUTEX.synchronize { @cookie_store ||= CookieStore.new }
+      end
+
       # @return [Symbol] the default strategy name
       def default_strategy_name = DEFAULT_STRATEGY_NAME
 
@@ -112,7 +171,7 @@ module Html2rss
                 "The strategy '#{strategy}' is not known. Available strategies: #{strategy_names.join(', ')}"
         end
 
-        strategy_class.new(ctx).execute
+        fetch_initial_through_cache(ctx, strategy_sym) { strategy_class.new(ctx).execute }
       end
 
       ##

data/lib/html2rss/request_session/pager/base.rb

@@ -70,13 +70,6 @@ module Html2rss
           )
           nil
         end
-
-        # @param page_response [RequestService::Response]
-        # @param page_number [Integer] 1-based target page number (e.g. 2 for second page)
-        # @return [Html2rss::Url, String, nil]
-        def next_page_url(page_response, page_number:)
-          raise NotImplementedError, "#{self.class}#next_page_url must be implemented by subclass"
-        end
       end
     end
   end

data/lib/html2rss/request_session/pager.rb

@@ -47,7 +47,7 @@ module Html2rss
         strategy_name = normalized_config.fetch(:strategy, :rel_next).to_sym
 
         klass = STRATEGIES.fetch(strategy_name) do
-          raise ArgumentError, "Unknown pagination strategy: #{strategy_name}"
+          raise InvalidOption, "Unknown pagination strategy: #{strategy_name}"
         end
 
         klass.new(session:, initial_response:, config: normalized_config)

data/lib/html2rss/request_session.rb

@@ -65,9 +65,13 @@ module Html2rss
     # @param url [String, Html2rss::Url] follow-up request url
     # @param relation [Symbol] why the follow-up is being made
     # @param origin_url [String, Html2rss::Url] effective origin for same-origin checks
+    # @param advertisement [RequestService::FeedAdvertisement, nil] the origin page's advertised feeds;
+    #   with relation +:advertised_feed+, {RequestService::Policy} lets a listed feed leave the origin
     # @return [RequestService::Response] follow-up response
-    def follow_up(url:, relation:, origin_url:)
-      execute(context.follow_up(url:, relation:, origin_url:)).tap { |response| remember!(response.url) }
+    def follow_up(url:, relation:, origin_url:, advertisement: nil)
+      execute(context.follow_up(url:, relation:, origin_url:, advertisement:)).tap do |response|
+        remember!(response.url)
+      end
     end
 
     ##

data/lib/html2rss/scoring/cluster_scorer.rb

@@ -72,7 +72,7 @@ module Html2rss
       end
 
       def text_words(node)
-        @text_words[node] ||= node.word_count
+        @text_words[node] ||= node.run_count
       end
 
       def date?(node)

data/lib/html2rss/scoring/container_assessor.rb

@@ -7,6 +7,8 @@ module Html2rss
     class ContainerAssessor
       # Microdata itemprop values treated as publish/update markers.
       PUBLISH_ITEMPROPS = %w[datePublished dateModified].freeze
+      # Letter/digit runs ({WordCount.runs}) beyond the title that make a container descriptive.
+      DESCRIPTIVE_RUNS = 8
 
       # @param text_classifier [LinkDestination::TextClassifier]
       # @param content_token_regexp [Regexp]
@@ -25,11 +27,12 @@ module Html2rss
       # @param destination_facts [LinkDestination::DestinationFacts, nil]
       # @return [Observation]
       def call(container, selected_anchor, destination_facts:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        title = entry_title(container, selected_anchor)
+        source = container.find(&:heading?) || selected_anchor
+        title = source ? source.visible_text.to_s.strip : ''
         tokens = "#{container.attrs.class_attr} #{container.attrs.id}"
 
         Observation.new(
-          title_word_count: word_count(title),
+          title_runs: source ? source.run_count : 0,
           path_length: destination_facts&.url&.path.to_s.length,
           content_path: destination_facts&.content_path,
           publish_marker: publish_marker?(container),
@@ -59,20 +62,16 @@ module Html2rss
       end
 
       def descriptive_context?(container_text, title)
-        snippet = container_text.to_s.sub(/\A#{Regexp.escape(title.to_s)}/i, '')
-        snippet.length > 30 && word_count(snippet) >= 8
+        snippet = without_title_prefix(container_text.to_s, title)
+        snippet.length > 30 && WordCount.runs(snippet, ceiling: DESCRIPTIVE_RUNS) == DESCRIPTIVE_RUNS
       end
 
-      def entry_title(container, selected_anchor)
-        heading = container.find(&:heading?)
-        source = heading || selected_anchor
-        source ? source.visible_text.to_s.strip : ''
-      end
+      # Case-insensitive prefix strip compared by character count, so multi-character
+      # case folds (e.g. "ß" vs "ss") do not match; the title is then left in the snippet.
+      def without_title_prefix(text, title)
+        return text unless text[0, title.length].casecmp?(title)
 
-      def word_count(text)
-        count = 0
-        text.to_s.scan(/\p{Alnum}+/) { count += 1 }
-        count
+        text[title.length..]
       end
     end
   end

data/lib/html2rss/scoring/engine.rb

@@ -11,7 +11,7 @@ module Html2rss
       SCORE_FLOOR = 0.0
 
       FEATURE_IDS = Set[
-        :title_word_count_ge3, :title_word_count_ge7, :path_length_gt6, :content_path,
+        :title_runs_ge3, :title_runs_ge7, :path_length_gt6, :content_path,
         :publish_marker, :descriptive_context, :article_container, :content_tokens,
         :non_content_utility_path, :utility_prefix_title_short, :shallow, :weak_container,
         :recommended_title_non_content, :high_confidence_junk_path, :junk_tokens,
@@ -22,8 +22,8 @@ module Html2rss
 
       # Quality feature triples: [feature_id, predicate, weight].
       QUALITY_RULES = [
-        [:title_word_count_ge3, ->(o) { o.title_word_count >= 3 }, 40],
-        [:title_word_count_ge7, ->(o) { o.title_word_count >= 7 }, 15],
+        [:title_runs_ge3, ->(o) { o.title_runs >= 3 }, 40],
+        [:title_runs_ge7, ->(o) { o.title_runs >= 7 }, 15],
         [:path_length_gt6, ->(o) { o.path_length > 6 }, 20],
         [:content_path, lambda(&:content_path), 15],
         [:publish_marker, lambda(&:publish_marker), 15],
@@ -35,7 +35,7 @@ module Html2rss
       # Junk feature triples: [feature_id, predicate, weight].
       JUNK_RULES = [
         [:non_content_utility_path, ->(o) { o.utility_path && !o.content_path && !o.strong_post_suffix }, 25],
-        [:utility_prefix_title_short, ->(o) { o.utility_prefix_title && o.title_word_count <= 6 }, 15],
+        [:utility_prefix_title_short, ->(o) { o.utility_prefix_title && o.title_runs <= 6 }, 15],
         [:shallow, lambda(&:shallow), 10],
         [:weak_container, ->(o) { !o.publish_marker && !o.descriptive_context }, 10],
         [:recommended_title_non_content, ->(o) { o.recommended_title && !o.content_path }, 10],
@@ -46,9 +46,9 @@ module Html2rss
       ##
       # @param id [Symbol]
       # @return [Symbol]
-      # @raise [ArgumentError] when id is not in the closed set
+      # @raise [InvalidOption] when id is not in the closed set
       def self.assert_feature_id!(id)
-        raise ArgumentError, "unknown feature: #{id.inspect}" unless FEATURE_IDS.include?(id)
+        raise InvalidOption, "unknown feature: #{id.inspect}" unless FEATURE_IDS.include?(id)
 
         id
       end

data/lib/html2rss/scoring/observation.rb

@@ -3,7 +3,7 @@
 module Html2rss
   module Scoring
     Observation = Data.define(
-      :title_word_count,
+      :title_runs,
       :path_length,
       :content_path,
       :publish_marker,
@@ -40,7 +40,7 @@ module Html2rss
         when :lenient
           (high_confidence_junk_path && weak_signals?) || chrome_title_junk?
         else
-          raise ArgumentError, "unknown hard_junk mode: #{mode.inspect}"
+          raise InvalidOption, "unknown hard_junk mode: #{mode.inspect}"
         end
       end
 

data/lib/html2rss/selector_candidates.rb

@@ -8,7 +8,12 @@ module Html2rss
   # Does not emit the default +a[href]+ fallback — that remains Capture's YAML path only.
   class SelectorCandidates # rubocop:disable Metrics/ClassLength -- ranking + field CSS stay co-located
     # Empty candidate buckets (no discovered evidence).
-    EMPTY = { items: [].freeze, title: [].freeze, link: [].freeze, published: [].freeze }.freeze
+    EMPTY = {
+      items: [].freeze, title: [].freeze, link: [].freeze, published: [].freeze, candidates_by_item: [].freeze
+    }.freeze
+
+    # How many top-ranked item candidates get their own field buckets in +:candidates_by_item+.
+    BY_ITEM_LIMIT = 5
 
     # Ranking preference for items selector derivation kind (lower is better).
     KIND_RANK = { shared_class: 0, unique_tag: 1, path: 2 }.freeze
@@ -22,8 +27,8 @@ module Html2rss
     DEFAULT_MIN_MATCHES = 2
     private_constant :DEFAULT_MIN_MATCHES
 
-    # Class token that identifies a non-heading title node. Same pattern title_node matches.
-    TITLE_CLASS_PATTERN = /title|font-bold|font-semibold/
+    # Class token that identifies a non-heading title node. Owned by the extractor so both match the same nodes.
+    TITLE_CLASS_PATTERN = Html::SstArticleExtractor::TITLE_CLASS_PATTERN
     private_constant :TITLE_CLASS_PATTERN
 
     class << self
@@ -37,7 +42,8 @@ module Html2rss
       # @param items_evidence [Array<Hash>] each with +:selector+, +:enhance+, +:strategy+,
       #   +:kind+, +:match_count+, and +:roots+ (SST nodes under the items selector)
       # @param min_matches [Integer] minimum repeated field evidence across roots
-      # @return [Hash{Symbol=>Array<Hash>}] +:items+, +:title+, +:link+, +:published+
+      # @return [Hash{Symbol=>Array<Hash>}] +:items+, +:title+, +:link+, +:published+ (buckets for the
+      #   top item) and +:candidates_by_item+ (per-item buckets for the top {BY_ITEM_LIMIT} items)
       def call(items_evidence:, min_matches: DEFAULT_MIN_MATCHES)
         new(items_evidence:, min_matches:).call
       end
@@ -57,17 +63,22 @@ module Html2rss
       items = rank_items(@items_evidence)
       return EMPTY if items.empty?
 
-      roots = roots_for(items.first, @items_evidence)
+      by_item = items.first(BY_ITEM_LIMIT).map { |item| item_buckets(item) }
+      { items:, **by_item.first.slice(:title, :link, :published), candidates_by_item: by_item }
+    end
+
+    private
+
+    def item_buckets(item)
+      roots = roots_for(item, @items_evidence)
       {
-        items:,
+        selector: item.fetch(:selector),
         title: field_bucket(roots, :title),
         link: field_bucket(roots, :link),
         published: field_bucket(roots, :published)
       }
     end
 
-    private
-
     def rank_items(evidence)
       evidence
         .sort_by { |entry| item_rank_key(entry) }

data/lib/html2rss/selectors/README.md

@@ -11,7 +11,7 @@ YAML / MCP wire vocabulary is unchanged (`selectors`, `extractor`, `post_process
 ## Live flow
 
 1. **Parse** — HTML stays on `Response#parsed_body`. JSON responses are converted once via `JsonXml` into an HTML5 fragment so CSS selectors still run.
-2. **Items** — `items.selector` finds each card/node. Omitted, blank, and `Selectors::DEFAULT_ITEMS_SELECTOR` expand to `Html::Navigator::MAIN_ANCHOR_SELECTOR` (permalink anchors). Any other selector, including `a` and `.card`, is used as written. `Config.prepare_defaults` fills that default, with `enhance: true`, only when `selectors:` is present. `enhance: true` fills missing fields via `Html::ArticleExtractor` (list-card enrichment). Enhancement is skipped when title, url, description, published_at, enclosures, and categories are already populated.
+2. **Items** — `items.selector` finds each card/node. Omitted, blank, and `Selectors::DEFAULT_ITEMS_SELECTOR` expand to `Html::Navigator::MAIN_ANCHOR_SELECTOR` (permalink anchors). Any other selector, including `a` and `.card`, is used as written. `Config.prepare_defaults` fills that default, with `enhance: true`, only when `selectors:` is present. `enhance: true` fills missing fields via `Html::ArticleExtractor` (list-card enrichment); an item with no link of its own gets no `url`, never a `page#id` fragment, and is left out of the feed (`Article#linked?`, the rule auto-source applies too). An item needs a resolvable link: configure a `url` selector when the items are not anchors or do not contain one. Enhancement is skipped when title, url, description, published_at, enclosures, and categories are already populated.
 3. **Field dispatch** (private on `Selectors`) — for each selectable key (`title`, `url`, `enclosure`, `categories`, …):
    - Regular fields → `Extractors.call` → optional `PostProcessors.call` chain
    - Special keys → enclosure wrap, guid fan-out, multi-node categories

data/lib/html2rss/selectors/option_spec.rb

@@ -11,6 +11,9 @@ module Html2rss
     # introspection SoT (+for+ / +expectation_for+); {SchemaExport} maps Ruby
     # types to JSON Schema only.
     class OptionSpec
+      # Raised when an extractor/post-processor +OPTIONS+ declares a type with no JSON Schema mapping.
+      class InvalidError < Html2rss::ContractError; end
+
       # Maps Ruby option types to JSON Schema +type+ strings.
       RUBY_TO_JSON_TYPE = {
         String => 'string',
@@ -83,7 +86,7 @@ module Html2rss
           when Array then ruby_type.map { |t| json_type_for(t) }
           else
             RUBY_TO_JSON_TYPE.fetch(ruby_type) do
-              raise ArgumentError, "unsupported OPTIONS type mapping for #{ruby_type}"
+              raise InvalidError, "unsupported OPTIONS type mapping for #{ruby_type}"
             end
           end
         end

data/lib/html2rss/selectors/post_processors/base.rb

@@ -114,14 +114,6 @@ module Html2rss
         end
 
         attr_reader :value, :context
-
-        # Abstract method to be implemented by subclasses
-        #
-        # @return [Object] transformed value
-        # @raise [NotImplementedError] if not implemented in subclass
-        def call
-          raise NotImplementedError, 'You must implement the `call` method in the post processor'
-        end
       end
     end
   end

data/lib/html2rss/selectors/post_processors/gsub.rb

@@ -70,7 +70,7 @@ module Html2rss
         #
         # @param string [String]
         # @return [Regexp]
-        # @raise [ArgumentError] when +string+ is not a String, exceeds the character cap,
+        # @raise [InvalidOption] when +string+ is not a String, exceeds the character cap,
         #   contains nested quantifiers, or does not parse
         def self.compiled_pattern(string)
           compiled_patterns[string] ||= compile_regexp_string(string)
@@ -88,25 +88,25 @@ module Html2rss
         # to maintain backwards compatibility before building the Regexp.
         # Length is the character count of the authored string (the JSON Schema
         # +maxLength+ unit), then the AST is walked for nested quantifiers,
-        # then +to_re+. Parser errors are re-raised as ArgumentError so
+        # then +to_re+. Parser errors are re-raised as InvalidOption so
         # validation and execution share one path.
         #
         # @param string [String]
         # @return [Regexp]
-        # @raise [ArgumentError] when +string+ is not a String, exceeds {MAX_PATTERN_LENGTH},
+        # @raise [InvalidOption] when +string+ is not a String, exceeds {MAX_PATTERN_LENGTH},
         #   contains nested quantifiers, or does not parse
         def self.compile_regexp_string(string)
-          raise ArgumentError, 'must be a string!' unless string.is_a?(String)
-          raise ArgumentError, "pattern exceeds #{MAX_PATTERN_LENGTH} characters" if string.length > MAX_PATTERN_LENGTH
+          raise InvalidOption, 'must be a string!' unless string.is_a?(String)
+          raise InvalidOption, "pattern exceeds #{MAX_PATTERN_LENGTH} characters" if string.length > MAX_PATTERN_LENGTH
 
           source = regexp_source(string)
 
           expression = Regexp::Parser.parse(source)
-          raise ArgumentError, 'pattern contains nested quantifiers' if nested_quantifiers?(expression)
+          raise InvalidOption, 'pattern contains nested quantifiers' if nested_quantifiers?(expression)
 
           expression.to_re
         rescue Regexp::Parser::Error => error
-          raise ArgumentError, error.message, [], cause: nil
+          raise InvalidOption, error.message, [], cause: nil
         end
         private_class_method :compile_regexp_string
 

data/lib/html2rss/selectors/post_processors/html_transformers/keep_playable_media.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Html2rss
+  class Selectors
+    module PostProcessors
+      module HtmlTransformers
+        ##
+        # Transformer that keeps only media a reader can play: an +http(s)+ +src+ on +<audio>+, +<video>+
+        # and +<source>+, made absolute; any other +src+ (missing, blank, +javascript:+, +data:+, unparsable)
+        # is removed. A +<source>+ left without one is dropped, and so is an +<audio>+ or +<video>+ with no
+        # playable +src+ of its own or on a child +<source>+ (no empty player shell).
+        class KeepPlayableMedia
+          # Elements that play a file named by +src+ (theirs or a child +<source>+).
+          PLAYERS = %w[audio video].freeze
+
+          # @param base_url [String, Html2rss::Url] base URL used to resolve relative sources
+          def initialize(base_url)
+            @base_url = base_url
+          end
+
+          ##
+          # @param node_name [String] node name currently being transformed
+          # @param node [Nokogiri::XML::Node] node currently being transformed
+          # @param _env [Hash] transformer context
+          # @option _env [Object] :_reserved reserved for transformer pipeline context
+          # @return [void]
+          def call(node_name:, node:, **_env)
+            if node_name == 'source'
+              node.unlink unless absolutize_src(node)
+            elsif PLAYERS.include?(node_name)
+              # Children are transformed after their parent, so child sources are only checked here.
+              playable = absolutize_src(node) || node.css('source').any? { Url.resolve_web(_1['src'], @base_url) }
+              node.unlink unless playable
+            end
+          end
+
+          private
+
+          # Rewrites +src+ to its absolute playable URL (Nokogiri stores its +to_s+) or removes it;
+          # returns the URL kept, if any.
+          def absolutize_src(node)
+            url = Url.resolve_web(node['src'], @base_url)
+            url ? node['src'] = url : node.remove_attribute('src')
+            url
+          end
+        end
+      end
+    end
+  end
+end

data/lib/html2rss/selectors/post_processors/html_transformers/transform_urls_to_absolute_ones.rb

@@ -12,9 +12,7 @@ module Html2rss
           URL_ELEMENTS_WITH_URL_ATTRIBUTE = {
             'a' => :href, # Visible link
             'img' => :src, # Visible image
-            'iframe' => :src, # Embedded frame (visible content)
-            'audio' => :src, # Can show controls, so potentially visible
-            'video' => :src # Video player is visible
+            'iframe' => :src # Embedded frame (visible content)
           }.freeze
 
           # @param base_url [String, Html2rss::Url] base URL used to resolve relative links

data/lib/html2rss/selectors/post_processors/parse_time.rb

@@ -63,14 +63,14 @@ module Html2rss
         # @param _value [String] extracted time string (unused; type-checked via VALUE_TYPE)
         # @param context [Selectors::StepEnv] must carry a usable +time_zone+
         # @return [void]
-        # @raise [ArgumentError] when time_zone is nil or empty
+        # @raise [MissingOption] when time_zone is nil or empty
         def self.validate_args!(_value, context)
           time_zone_value = context.time_zone
 
-          raise ArgumentError, 'time_zone cannot be nil or empty', [], cause: nil if time_zone_value.nil?
+          raise MissingOption, 'time_zone cannot be nil or empty', [], cause: nil if time_zone_value.nil?
 
           assert_type(time_zone_value, String, :time_zone, context:)
-          raise ArgumentError, 'time_zone cannot be nil or empty', [], cause: nil if time_zone_value.empty?
+          raise MissingOption, 'time_zone cannot be nil or empty', [], cause: nil if time_zone_value.empty?
         end
 
         ##