html2rss 0.24.0 → 0.26.0

data/lib/html2rss/cli.rb

@@ -2,6 +2,7 @@
 
 require 'fileutils'
 require 'json'
+require 'yaml'
 require 'thor'
 
 module Html2rss
@@ -79,6 +80,9 @@ module Html2rss
     method_option :max_requests,
                   type: :numeric,
                   desc: 'Maximum requests to allow for this feed build'
+    method_option :limit,
+                  type: :numeric,
+                  desc: 'Maximum number of articles to keep (default: 25)'
     method_option :input,
                   type: :string,
                   desc: 'Local HTML file path to read input from'
@@ -95,6 +99,43 @@ module Html2rss
       puts(format == 'jsonfeed' ? JSON.pretty_generate(result) : result)
     end
 
+    desc 'capture URL', 'Analyze a URL and print a reusable YAML feed config'
+    method_option :strategy,
+                  type: :string,
+                  desc: STRATEGY_OPTION_DESC,
+                  enum: STRATEGY_OPTION_ENUM
+    method_option :items_selector, type: :string, desc: 'CSS selector hint for items (optional)'
+    method_option :max_redirects,
+                  type: :numeric,
+                  desc: 'Maximum redirects to follow per request'
+    method_option :max_requests,
+                  type: :numeric,
+                  desc: 'Maximum requests to allow for this feed build'
+    method_option :limit,
+                  type: :numeric,
+                  desc: 'Maximum number of articles to keep (default: 25)'
+    method_option :input,
+                  type: :string,
+                  desc: 'Local HTML file path to read input from'
+    ##
+    # Captures a URL and prints a reusable YAML config.
+    #
+    # @param url [String, nil] source page URL for capture
+    # @return [void]
+    def capture(url = nil) # rubocop:disable Metrics/MethodLength
+      strategy, local_file_path, url = prepare_auto_inputs(url, options[:input])
+      config = Html2rss.capture(
+        url,
+        strategy:,
+        items_selector: options[:items_selector],
+        limit: options[:limit]&.to_i,
+        max_redirects: options[:max_redirects],
+        max_requests: options[:max_requests],
+        local_file_path:
+      )
+      puts YAML.dump(HashUtil.deep_stringify_keys(config))
+    end
+
     desc 'schema', 'Print the exported config JSON Schema'
     method_option :pretty,
                   type: :boolean,
@@ -120,6 +161,27 @@ module Html2rss
       puts schema_json
     end
 
+    desc 'mcp', 'Start the MCP server for AI client consumption'
+    method_option :transport,
+                  type: :string,
+                  desc: 'MCP transport protocol',
+                  enum: %w[stdio http],
+                  default: 'stdio'
+    method_option :port,
+                  type: :numeric,
+                  desc: 'Port for HTTP transport (binds 127.0.0.1)',
+                  default: 8080
+    ##
+    # Starts the MCP server for AI client consumption.
+    #
+    # @return [void]
+    def mcp
+      Html2rss::MCP.start(
+        transport: options[:transport].to_sym,
+        port: options[:port]
+      )
+    end
+
     desc 'validate YAML_FILE [feed_name]', 'Validate a YAML config with the runtime validator'
     method_option :params,
                   type: :hash,
@@ -180,29 +242,20 @@ module Html2rss
 
       file_path = check_file_exists!(input_option)
       detected_url = url || detect_base_url!(
-        file_path, 'Please specify a URL: html2rss auto [URL] --input <file>'
+        file_path, 'Please specify a URL: html2rss <command> [URL] --input <file>'
       )
 
       [:local_file, file_path, detected_url]
     end
 
     def request_controls
-      Html2rss::Config::RequestControls.new(
-        strategy: options[:strategy]&.to_sym,
+      Html2rss::Config::RequestControls.from_cli_options(
+        strategy: options[:strategy],
         max_redirects: options[:max_redirects],
-        max_requests: options[:max_requests],
-        explicit_keys: explicit_request_control_keys
+        max_requests: options[:max_requests]
       )
     end
 
-    def explicit_request_control_keys
-      keys = []
-      keys << :strategy if options[:strategy]
-      keys << :max_redirects unless options[:max_redirects].nil?
-      keys << :max_requests unless options[:max_requests].nil?
-      keys
-    end
-
     def current_strategy
       options[:strategy]&.to_sym || :auto
     end
@@ -227,15 +280,15 @@ module Html2rss
       yield
     rescue Faraday::FollowRedirects::RedirectLimitReached => error
       raise Thor::Error,
-            "#{error.message}. retry with --max-redirects #{suggested_max_redirects} or use the final URL directly."
+            "#{error.message}. already retried the last redirect hop once; " \
+            "retry with --max-redirects #{suggested_max_redirects} or use the final URL directly."
     rescue Html2rss::RequestService::RequestBudgetExceeded => error
       raise Thor::Error,
             "#{error.message}. retry with --max-requests #{suggested_max_requests} " \
             'or increase request.max_requests in the config.'
-    rescue Html2rss::RequestService::BrowserlessConfigurationError,
-           Html2rss::RequestService::BrowserlessConnectionFailed,
-           Html2rss::RequestService::BotasaurusConfigurationError,
+    rescue Html2rss::RequestService::BotasaurusConfigurationError,
            Html2rss::RequestService::BotasaurusConnectionFailed,
+           Html2rss::RequestService::BotasaurusServiceError,
            Html2rss::RequestService::BlockedSurfaceDetected,
            Html2rss::NoFeedItemsExtracted => error
       raise Thor::Error, error.message
@@ -249,7 +302,8 @@ module Html2rss
         items_selector: options[:items_selector],
         max_redirects: options[:max_redirects],
         max_requests: options[:max_requests],
-        local_file_path:
+        local_file_path:,
+        limit: options[:limit]&.to_i
       )
     end
 

data/lib/html2rss/config/auto_source_contract.rb

@@ -6,6 +6,8 @@ module Html2rss
   class Config
     # Runtime source of truth for validating auto-source config values.
     AutoSourceContract = Dry::Schema.Params do # rubocop:disable Metrics/BlockLength
+      optional(:limit).filled(:integer, gt?: 0)
+
       optional(:scraper).hash do # rubocop:disable Metrics/BlockLength
         optional(:wordpress_api).hash do
           optional(:enabled).filled(:bool)
@@ -27,6 +29,9 @@ module Html2rss
         optional(:json_state).hash do
           optional(:enabled).filled(:bool)
         end
+        optional(:xhr_articles).hash do
+          optional(:enabled).filled(:bool)
+        end
         optional(:meta_oembed).hash do
           optional(:enabled).filled(:bool)
         end
@@ -44,7 +49,6 @@ module Html2rss
 
       optional(:cleanup).hash do
         optional(:keep_different_domain).filled(:bool)
-        optional(:min_words_title).filled(:integer, gt?: 0)
       end
     end
   end

data/lib/html2rss/config/request_controls.rb

@@ -43,6 +43,39 @@ module Html2rss
         request_config.is_a?(Hash) && request_config.key?(key)
       end
 
+      ##
+      # Builds controls for public API shortcuts ({Html2rss.auto_source}, etc.).
+      # Strategy is explicit only when non-nil and not the configured default.
+      #
+      # @param strategy [Symbol, nil]
+      # @param max_redirects [Integer, nil]
+      # @param max_requests [Integer, nil]
+      # @return [RequestControls]
+      def self.from_shortcut(strategy:, max_redirects: nil, max_requests: nil)
+        keys = []
+        keys << :strategy unless strategy.nil? || strategy == Config.default_strategy_name
+        keys << :max_redirects unless max_redirects.nil?
+        keys << :max_requests unless max_requests.nil?
+        new(strategy:, max_redirects:, max_requests:, explicit_keys: keys)
+      end
+
+      ##
+      # Builds controls from CLI option values. Strategy is explicit when the
+      # option was provided (truthy string/symbol), matching Thor option presence.
+      #
+      # @param strategy [Symbol, String, nil]
+      # @param max_redirects [Integer, nil]
+      # @param max_requests [Integer, nil]
+      # @return [RequestControls]
+      def self.from_cli_options(strategy:, max_redirects: nil, max_requests: nil)
+        strategy_sym = strategy&.to_sym
+        keys = []
+        keys << :strategy if strategy
+        keys << :max_redirects unless max_redirects.nil?
+        keys << :max_requests unless max_requests.nil?
+        new(strategy: strategy_sym, max_redirects:, max_requests:, explicit_keys: keys)
+      end
+
       private_class_method :explicit_keys_for, :request_value_for, :request_key?
 
       ##

data/lib/html2rss/config/schema.rb

@@ -48,6 +48,7 @@ module Html2rss
       ##
       # Orchestrates schema assembly from runtime validator contracts plus
       # client-facing overlays.
+      # rubocop:disable Metrics/ClassLength -- overlay assembly stays in one builder
       class Builder
         class << self
           # @return [Hash{String => Object}] fully assembled JSON schema hash
@@ -60,9 +61,10 @@ module Html2rss
         def call
           schema = validator_schema
           apply_top_level(schema)
+          schema[:$defs] = registry_catalog_defs
           schema.fetch(:properties).merge!(overlay)
           schema.fetch(:properties).delete(:dynamic_params_error)
-          DeepStringifier.call(schema)
+          HashUtil.deep_stringify_keys(schema)
         end
 
         private
@@ -77,6 +79,23 @@ module Html2rss
             { 'required' => ['selectors'] },
             { 'required' => ['auto_source'] }
           ]
+
+          topics = schema.dig(:properties, :directory, :properties, :topics)
+          topics[:minItems] = 1 if topics.is_a?(Hash)
+        end
+
+        # @return [Hash{Symbol => Hash}] catalog under $defs.post_processors / $defs.extractors
+        def registry_catalog_defs
+          {
+            post_processors: catalog_from_registry(Selectors::PostProcessors::NAME_TO_CLASS),
+            extractors: catalog_from_registry(Selectors::Extractors::NAME_TO_CLASS)
+          }
+        end
+
+        # @param registry [Hash{Symbol => Class}]
+        # @return [Hash{String => Hash}]
+        def catalog_from_registry(registry)
+          registry.keys.sort.to_h { |name| [name.to_s, registry.fetch(name).schema_doc] }
         end
 
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
@@ -105,6 +124,13 @@ module Html2rss
             ]
           }
 
+          selector_schema = Schema.apply_selector_registry_refs!(
+            Html2rss::Config::SelectorsValidator::Selector.new.schema.json_schema(loose: true)
+          )
+          enclosure_schema = Schema.apply_selector_registry_refs!(
+            Html2rss::Config::SelectorsValidator::Enclosure.new.schema.json_schema(loose: true)
+          )
+
           {
             strategy: {
               type: 'string',
@@ -121,7 +147,7 @@ module Html2rss
               items: Html2rss::Config::Validator::StylesheetConfig.json_schema(loose: true)
             },
             auto_source: Html2rss::Config::AutoSourceContract.json_schema(loose: true).merge(
-              default: DeepStringifier.call(Html2rss::AutoSource::DEFAULT_CONFIG)
+              default: HashUtil.deep_stringify_keys(Html2rss::AutoSource::DEFAULT_CONFIG)
             ),
             selectors: {
               type: 'object',
@@ -130,14 +156,14 @@ module Html2rss
                 items: items_schema.merge(
                   description: 'Defines the items selector and optional enhancement settings.'
                 ),
-                enclosure: Html2rss::Config::SelectorsValidator::Enclosure.new.schema.json_schema(loose: true).merge(
+                enclosure: enclosure_schema.merge(
                   description: 'Describes enclosure extraction settings.'
                 ),
                 guid: reference_array('List of selector keys used to build the GUID. Each entry must reference a sibling selector key; runtime validation enforces those references.'),
                 categories: reference_array('List of selector keys whose values will be used as categories. Each entry must reference a sibling selector key; runtime validation enforces those references.')
               },
               patternProperties: {
-                '^(?!items$|enclosure$|guid$|categories$).+$' => Html2rss::Config::SelectorsValidator::Selector.new.schema.json_schema(loose: true).merge(
+                '^(?!items$|enclosure$|guid$|categories$).+$' => selector_schema.merge(
                   description: 'Dynamic selector definition keyed by attribute name.'
                 )
               },
@@ -159,31 +185,46 @@ module Html2rss
           }
         end
       end
+      # rubocop:enable Metrics/ClassLength
 
       ##
-      # Converts nested hash keys to strings so the resulting schema serializes cleanly.
-      module DeepStringifier
-        module_function
-
-        # @param object [Hash, Array, Object] nested data to normalize
-        # @return [Hash, Array, Object] deep copy with stringified hash keys
-        def call(object)
-          case object
-          when Hash
-            stringify_hash(object)
-          when Array
-            object.map { |value| call(value) }
-          when Symbol
-            object.to_s
-          else
-            object
-          end
-        end
+      # Wires extractor / post_process to thin oneOf $refs into the registry catalog.
+      #
+      # @param schema [Hash] dry-schema JSON schema fragment for a selector
+      # @return [Hash] same schema with registry $ref wiring applied
+      def apply_selector_registry_refs!(schema)
+        properties = schema.fetch(:properties)
+        properties[:extractor] = extractor_wire_schema
+        properties[:post_process] = post_process_wire_schema
+        schema
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def extractor_wire_schema
+        {
+          description: 'Extractor used to pull a value from the selected element.',
+          oneOf: registry_ref_list('extractors', Selectors::Extractors::NAME_TO_CLASS)
+        }
+      end
 
-        # @param object [Hash{Object => Object}] hash whose keys should become strings
-        # @return [Hash{String => Object}] hash with recursively normalized values
-        def stringify_hash(object)
-          object.to_h { |key, value| [key.to_s, call(value)] }
+      # @return [Hash{Symbol => Object}]
+      def post_process_wire_schema
+        {
+          type: 'array',
+          description: 'Ordered transforms applied to the extracted value.',
+          items: {
+            oneOf: registry_ref_list('post_processors', Selectors::PostProcessors::NAME_TO_CLASS)
+          }
+        }
+      end
+
+      ##
+      # @param catalog [String] $defs catalog name (`extractors` or `post_processors`)
+      # @param registry [Hash{Symbol => Class}]
+      # @return [Array<Hash>] oneOf entries of `{ '$ref' => ... }`
+      def registry_ref_list(catalog, registry)
+        registry.keys.sort.map do |name|
+          { '$ref' => "#/$defs/#{catalog}/#{name}" }
         end
       end
     end

data/lib/html2rss/config/selectors_validator.rb

@@ -75,6 +75,9 @@ module Html2rss
       ##
       # Validates the configuration of a single selector.
       class Selector < Dry::Validation::Contract
+        # Extractor Options members supplied at runtime, not from feed YAML.
+        RUNTIME_EXTRACTOR_FIELDS = %i[selector channel].to_set.freeze
+
         params do
           optional(:selector)
           optional(:extractor).filled(:string)
@@ -88,33 +91,69 @@ module Html2rss
         end
 
         rule(:extractor) do
-          # dependent on the extractor, validate required fields, (i.e. static, attribute)
-          case value
-          when 'attribute'
-            key(:attribute).failure('`attribute` must be a string') unless values[:attribute].is_a?(String)
-          when 'static'
-            key(:static).failure('`static` must be a string') unless values[:static].is_a?(String)
+          next unless value
+
+          klass = Selectors::Extractors::NAME_TO_CLASS[value.to_sym]
+          next key(:extractor).failure("unknown extractor: #{value}") unless klass
+
+          klass::Options.members.each do |field|
+            next if RUNTIME_EXTRACTOR_FIELDS.include?(field)
+            next if values[field]
+
+            key(field).failure("`#{field}` is required for extractor `#{value}`")
           end
         end
 
         rule(:post_process).each do
-          case (name = value[:name])
-          when 'gsub'
-            key(:pattern).failure('`pattern` must be a string') unless value[:pattern].is_a?(String)
-            key(:replacement).failure('`replacement` must be a string') unless value[:replacement].is_a?(String)
-          when 'substring'
-            key(:start).failure('`start` must be an integer') unless value[:start].is_a?(Integer)
-            key(:end).failure('`end` must be an integer or omitted') if !value[:end].nil? && !value[:end].is_a?(Integer)
-          when 'template'
-            key(:string).failure('`string` must be a string') unless value[:string].is_a?(String)
-          when 'html_to_markdown', 'markdown_to_html', 'parse_time', 'parse_uri', 'sanitize_html'
-            # nothing to validate
-          when nil
-            key(:post_process).failure('Missing post_processor `name`')
-          else
-            key(:post_process).failure("Unknown post_processor `name`: #{name}")
+          name = value[:name]
+          next key(:post_process).failure('Missing post_processor `name`') if name.nil?
+
+          klass = Selectors::PostProcessors::NAME_TO_CLASS[name.to_sym]
+          next key(:post_process).failure("Unknown post_processor `name`: #{name}") unless klass
+          next unless klass.const_defined?(:Options)
+
+          post_process_option_type_errors(klass, value).each do |field, message|
+            key(field).failure(message)
           end
         end
+
+        private
+
+        def post_process_option_type_errors(klass, value)
+          required_option_type_errors(klass, value) + optional_option_type_errors(klass, value)
+        end
+
+        def required_option_type_errors(klass, value)
+          option_types = klass.const_defined?(:OPTION_TYPES) ? klass::OPTION_TYPES : {}
+
+          klass::Options.members.filter_map do |field|
+            expected = option_types.fetch(field, String)
+            next if value[field].is_a?(expected)
+
+            [field, option_type_failure(field, expected)]
+          end
+        end
+
+        def optional_option_type_errors(klass, value)
+          return [] unless klass.const_defined?(:OPTIONAL_OPTION_TYPES)
+
+          klass::OPTIONAL_OPTION_TYPES.filter_map do |field, expected|
+            actual = value[field]
+            next if actual.nil? || actual.is_a?(expected)
+
+            [field, option_type_failure(field, expected, optional: true)]
+          end
+        end
+
+        def option_type_failure(field, expected, optional: false)
+          label = {
+            Integer => 'an integer',
+            String => 'a string',
+            Hash => 'a hash'
+          }.fetch(expected) { "a #{expected}" }
+          suffix = optional ? ' or omitted' : ''
+          "`#{field}` must be #{label}#{suffix}"
+        end
       end
 
       ##

data/lib/html2rss/config/validator.rb

@@ -15,6 +15,11 @@ module Html2rss
       LANGUAGE_FORMAT_REGEX = /\A[a-z]{2}(-[A-Z]{2})?\z/
       # Baseline strategy-plan enum (:auto plus concrete RequestService strategies).
       BASE_STRATEGY_OPTIONS = Html2rss::FeedPipeline::StrategyPlan.accepted_names.freeze
+      # Controlled vocabulary for catalog-only `directory.topics` (not RSS channel fields).
+      DIRECTORY_TOPICS = %w[
+        sports energy tech science news entertainment jobs finance
+        security travel environment consumer civic product research
+      ].freeze
 
       # Contract for the top-level `channel` section.
       ChannelConfig = Dry::Schema.Params do
@@ -24,6 +29,13 @@ module Html2rss
         optional(:language).maybe(:string, format?: LANGUAGE_FORMAT_REGEX)
         optional(:ttl).maybe(:integer, gt?: 0)
         optional(:time_zone).maybe(:string)
+        optional(:author).maybe(:string)
+        optional(:image).maybe(:string, format?: URI_REGEXP)
+      end
+
+      # Contract for catalog-only `directory` metadata (topics for feed directories).
+      DirectoryConfig = Dry::Schema.Params do
+        optional(:topics).value(:array, min_size?: 1).each(:string, included_in?: DIRECTORY_TOPICS)
       end
 
       # Contract for a stylesheet entry in `stylesheets`.
@@ -33,47 +45,28 @@ module Html2rss
         optional(:media).maybe(:string)
       end
 
-      # Contract for Browserless click-preload options.
-      BrowserlessPreloadClickSelectorConfig = Dry::Schema.Params do
-        required(:selector).filled(:string)
-        optional(:max_clicks).filled(:integer, gt?: 0)
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-      end
-
-      # Contract for Browserless scroll-preload options.
-      BrowserlessPreloadScrollConfig = Dry::Schema.Params do
-        optional(:iterations).filled(:integer, gt?: 0)
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-      end
-
-      # Contract for Browserless preload orchestration options.
-      BrowserlessPreloadConfig = Dry::Schema.Params do
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-        optional(:click_selectors).array(BrowserlessPreloadClickSelectorConfig)
-        optional(:scroll_down).hash(BrowserlessPreloadScrollConfig)
-      end
-
-      # Contract for Browserless-specific request options.
-      BrowserlessRequestConfig = Dry::Schema.Params do
-        optional(:preload).hash(BrowserlessPreloadConfig)
-      end
-
       # Contract for Botasaurus-specific request options.
       BotasaurusRequestConfig = Dry::Schema.Params do
         config.validate_keys = true
 
-        optional(:navigation_mode).filled(:string, included_in?: %w[auto get google_get google_get_bypass])
+        optional(:execution_mode).filled(:string, included_in?: %w[auto request browser])
+        optional(:navigation_mode).filled(:string, included_in?: %w[auto get google_get google_get_bypass organic_get])
         optional(:max_retries).filled(:integer, gteq?: 0, lteq?: 3)
         optional(:wait_for_selector).maybe(:string)
         optional(:wait_timeout_seconds).filled(:integer, gt?: 0)
+        optional(:scroll).filled(:bool)
+        optional(:scroll_to_bottom).filled(:bool)
         optional(:block_images).filled(:bool)
         optional(:block_images_and_css).filled(:bool)
+        optional(:block_trackers).filled(:bool)
         optional(:wait_for_complete_page_load).filled(:bool)
         optional(:headless).filled(:bool)
         optional(:proxy).filled(:string)
         optional(:user_agent).filled(:string)
         optional(:window_size).value(:array, min_size?: 2, max_size?: 2).each(:integer, gt?: 0)
         optional(:lang).filled(:string)
+        optional(:cookies).hash
+        optional(:headers).hash
       end
 
       # Contract for the top-level `request` section.
@@ -81,7 +74,6 @@ module Html2rss
         optional(:max_redirects).filled(:integer, gteq?: 0)
         optional(:max_requests).filled(:integer, gt?: 0)
         optional(:total_timeout_seconds).filled(:integer, gt?: 0)
-        optional(:browserless).hash(BrowserlessRequestConfig)
         optional(:botasaurus).hash(BotasaurusRequestConfig)
         optional(:local_file_path).filled(:string)
       end
@@ -89,6 +81,7 @@ module Html2rss
       params do
         optional(:strategy).filled(:symbol)
         required(:channel).hash(ChannelConfig)
+        optional(:directory).hash(DirectoryConfig)
         optional(:headers).hash
         optional(:stylesheets).array(StylesheetConfig)
         optional(:auto_source).hash(Config::AutoSourceContract)
@@ -132,15 +125,20 @@ module Html2rss
 
       # URL validation delegated to Url class
       rule(:channel) do
-        next unless values[:channel]&.key?(:url)
-
-        url_string = values[:channel][:url]
-        next if url_string.nil? || url_string.empty?
+        if (url_string = values.dig(:channel, :url)) && !url_string.empty?
+          begin
+            Html2rss::Url.for_channel(url_string)
+          rescue ArgumentError => error
+            key(%i[channel url]).failure(error.message)
+          end
+        end
 
-        begin
-          Html2rss::Url.for_channel(url_string)
-        rescue ArgumentError => error
-          key(%i[channel url]).failure(error.message)
+        if (image_string = values.dig(:channel, :image)) && !image_string.empty?
+          begin
+            Html2rss::Url.from_absolute(image_string)
+          rescue ArgumentError => error
+            key(%i[channel image]).failure(error.message)
+          end
         end
       end
     end

data/lib/html2rss/config.rb

@@ -120,11 +120,15 @@ module Html2rss
       # @param url [String] source page URL
       # @param items_selector [String, nil] optional selector hint for item extraction
       # @param request_controls [Html2rss::Config::RequestControls, nil] explicit request controls to write
+      # @param limit [Integer, nil] max articles to keep in the auto-sourced feed
       # @return [Hash{Symbol => Object}] feed config hash ready for {from_hash}
-      def auto_source_config(url:, items_selector: nil, request_controls: nil)
+      def auto_source_config(url:, items_selector: nil, request_controls: nil, limit: nil)
+        auto_source = AutoSource::DEFAULT_CONFIG
+        auto_source = auto_source.merge(limit:) unless limit.nil?
+
         config = {
           channel: default_config[:channel].merge(url:),
-          auto_source: AutoSource::DEFAULT_CONFIG
+          auto_source:
         }
 
         request_controls ||= RequestControls.new

data/lib/html2rss/error.rb

@@ -6,16 +6,24 @@ module Html2rss
 
   # Raised when auto fallback exhausts all concrete tiers and extractors find no feed items.
   class NoFeedItemsExtracted < Error
+    # Categories that append shared surface guidance to the empty-feed message.
+    SURFACE_HINT_CATEGORIES = %i[app_shell blocked_surface].freeze
+
     ##
     # @param attempts [Array<Hash{Symbol => Object}>] tier attempt diagnostics
-    def initialize(attempts:)
+    # @param surface_category [Symbol, nil] optional Scraper surface classification
+    def initialize(attempts:, surface_category: nil)
       @attempts = attempts
+      @surface_category = surface_category
       super(build_message)
     end
 
     # @return [Array<Hash{Symbol => Object}>] tier attempt diagnostics
     attr_reader :attempts
 
+    # @return [Symbol, nil] surface classification when a response body was available
+    attr_reader :surface_category
+
     private
 
     def build_message
@@ -24,8 +32,12 @@ module Html2rss
         "#{attempt[:strategy]} (#{details})"
       end.join(', ')
 
-      "No feed items extracted after auto fallback across strategies: #{summaries}. " \
-        'Try a more specific listing URL or provide explicit selectors.'
+      message = "No feed items extracted after auto fallback across strategies: #{summaries}. " \
+                'Try a more specific listing URL or provide explicit selectors.'
+      return message unless SURFACE_HINT_CATEGORIES.include?(surface_category)
+
+      guidance = AutoSource::Scraper::NoScraperFound::CATEGORY_MESSAGES.fetch(surface_category)
+      "#{message} #{guidance}"
     end
   end
 end