seo_geo 0.1.0

data/lib/seo_geo/json_ld.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "json"
+require "date"
+require "time"
+
+module SeoGeo
+  # Builds one schema.org +@graph+ document. Nodes get stable +@id+ anchors so they can reference
+  # each other (+{ "@id" => "https://www.example.com/#organization" }+) and so the same node added
+  # twice (layout + view) is emitted once — the later call wins.
+  #
+  # Anchors: site-wide nodes hang off the origin (+/#website+, +/#organization+); page nodes hang
+  # off the page URL (+<url>#faq+, +#article+, +#breadcrumb+, +#video+, +#product+, +#profile+, +#app+).
+  #
+  # Keyword arguments are snake_case and become camelCase properties (+same_as+ -> +sameAs+);
+  # nested +type:+/+id:+ become +@type+/+@id+; Date/Time values become ISO 8601; nil values are dropped;
+  # root-relative URLs (+"/logo.png"+) in URL-like properties are made absolute against the origin.
+  #
+  # Each typed method checks the properties Google requires for that type and raises {InvalidNode}
+  # listing every missing one. FAQPage is built for AI answers and Bing; Google shows FAQ rich results
+  # only for government and health sites, so no rich result is promised.
+  #
+  # @example
+  #   ld = SeoGeo::JsonLd.new
+  #   ld.website.organization
+  #   ld.article(headline: post.title, url: post_url(post), date_published: post.published_at)
+  #   ld.to_json
+  class JsonLd
+    # Raised when a node lacks a property its type requires.
+    class InvalidNode < ArgumentError; end
+
+    CONTEXT = "https://schema.org"
+
+    # @return [Hash{String => Array<String>}] required properties per +@type+ (Google structured data docs)
+    REQUIRED = {
+      "WebSite" => %w[name url],
+      "Organization" => %w[name url],
+      "SoftwareApplication" => %w[name],
+      "WebApplication" => %w[name],
+      "MobileApplication" => %w[name],
+      "Article" => %w[headline],
+      "BlogPosting" => %w[headline],
+      "NewsArticle" => %w[headline],
+      "BreadcrumbList" => %w[itemListElement],
+      "VideoObject" => %w[name thumbnailUrl uploadDate],
+      "Product" => %w[name],
+      "ProfilePage" => %w[mainEntity],
+      "FAQPage" => %w[mainEntity]
+    }.freeze
+
+    URL_KEYS = %w[url logo image thumbnailUrl contentUrl embedUrl item].freeze
+    private_constant :URL_KEYS
+
+    # @return [String] origin used for +@id+ anchors and absolute URLs
+    attr_reader :origin
+
+    # @param origin [String, nil] defaults to config.canonical_origin
+    # @param config [Configuration]
+    def initialize(origin: nil, config: SeoGeo.config)
+      @config = config
+      @origin = (origin || config.canonical_origin).to_s.chomp("/")
+      @nodes = []
+    end
+
+    # @return [Array<Hash>] the graph nodes, in insertion order
+    def nodes
+      @nodes.dup
+    end
+
+    # @return [Boolean]
+    def empty?
+      @nodes.empty?
+    end
+
+    # Adds a raw node (string or symbol keys) or every node of another {JsonLd} / +@graph+ document.
+    # Raw nodes of a known +@type+ are validated like the typed methods.
+    # @param node [Hash, JsonLd, Array]
+    # @return [self]
+    def add(node)
+      case node
+      when JsonLd then node.nodes.each { |inner| push(inner) }
+      when Array then node.each { |inner| add(inner) }
+      when Hash
+        normalized = normalize(node)
+        graph = normalized["@graph"]
+        graph ? graph.each { |inner| push(inner) } : push(normalized.except("@context"))
+      when nil then nil
+      else raise ArgumentError, "JSON-LD node must be a Hash or SeoGeo::JsonLd (got #{node.class})"
+      end
+      self
+    end
+    alias << add
+
+    # @return [self]
+    def website(name: @config.site.name, url: "#{origin}/", description: @config.site.description, **attrs)
+      node("WebSite", "#{origin}/#website", name: name, url: url, description: description, **attrs)
+    end
+
+    # @return [self]
+    def organization(name: @config.site.name, url: "#{origin}/", logo: @config.site.logo_url,
+                     same_as: @config.site.same_as, **attrs)
+      same_as = Array(same_as)
+      node("Organization", "#{origin}/#organization", name: name, url: url, logo: logo,
+                                                      same_as: same_as.empty? ? nil : same_as, **attrs)
+    end
+
+    # @param type [String] "SoftwareApplication", "WebApplication" or "MobileApplication"
+    # @return [self]
+    def software_application(name:, url: "#{origin}/", type: "SoftwareApplication", **attrs)
+      node(type, anchor(url, "app"), name: name, url: url, **attrs)
+    end
+
+    # @return [self]
+    def web_application(name:, **attrs)
+      software_application(name: name, type: "WebApplication", **attrs)
+    end
+
+    # @param type [String] "Article", "BlogPosting" or "NewsArticle"
+    # @return [self]
+    def article(headline:, url: "#{origin}/", type: "Article", **attrs)
+      node(type, anchor(url, "article"), headline: headline, url: url, main_entity_of_page: url, **attrs)
+    end
+
+    # @param items [Array<Array(String, String)>, Array<Hash>] +[name, url]+ pairs or +{name:, url:}+;
+    #   the last item may omit its URL (the current page)
+    # @return [self]
+    def breadcrumb_list(items, url: "#{origin}/")
+      elements = Array(items).each_with_index.map do |item, index|
+        name, item_url = item.is_a?(Hash) ? [item[:name] || item["name"], item[:url] || item["url"]] : item
+        raise InvalidNode, "BreadcrumbList item #{index + 1} needs a name" if blank?(name)
+
+        { type: "ListItem", position: index + 1, name: name, item: item_url }
+      end
+      node("BreadcrumbList", anchor(url, "breadcrumb"), item_list_element: elements.empty? ? nil : elements)
+    end
+
+    # @return [self]
+    def video_object(name:, thumbnail_url:, upload_date:, url: "#{origin}/", **attrs)
+      node("VideoObject", anchor(url, "video"), name: name, thumbnail_url: thumbnail_url,
+                                                upload_date: upload_date, **attrs)
+    end
+
+    # Google requires one of +offers+, +review+ or +aggregate_rating+ for product snippets.
+    # @return [self]
+    def product(name:, url: "#{origin}/", **attrs)
+      unless %i[offers review aggregate_rating].any? { |key| attrs[key] }
+        raise InvalidNode, "Product #{name.inspect} needs offers, review or aggregate_rating"
+      end
+
+      node("Product", anchor(url, "product"), name: name, url: url, **attrs)
+    end
+
+    # @param main_entity [Hash] the Person or Organization the page is about (+name:+ required)
+    # @return [self]
+    def profile_page(main_entity:, url: "#{origin}/", **attrs)
+      entity = { type: "Person" }.merge(main_entity.transform_keys(&:to_sym))
+      raise InvalidNode, "ProfilePage main_entity needs a name" if blank?(entity[:name])
+
+      node("ProfilePage", anchor(url, "profile"), url: url, main_entity: entity, **attrs)
+    end
+
+    # @param faq [Array<Hash>] +{question:, answer:}+ items, e.g. {Page#faq}
+    # @return [self]
+    def faq_page(faq, url: "#{origin}/", **attrs)
+      questions = Array(faq).each_with_index.map do |item, index|
+        question = item[:question] || item["question"]
+        answer = item[:answer] || item["answer"]
+        raise InvalidNode, "FAQPage item #{index + 1} needs a question and an answer" if blank?(question) || blank?(answer)
+
+        { type: "Question", name: question, accepted_answer: { type: "Answer", text: answer } }
+      end
+      node("FAQPage", anchor(url, "faq"), main_entity: questions.empty? ? nil : questions, **attrs)
+    end
+
+    # @return [Hash{String => Object}] +{"@context" => ..., "@graph" => [...]}+
+    def to_h
+      { "@context" => CONTEXT, "@graph" => nodes }
+    end
+    alias as_json to_h
+
+    # Plain JSON. Use {SeoGeo::Meta::Helper#seo_geo_json_ld_tag} (or +ERB::Util.json_escape+) to put it in HTML.
+    # @return [String]
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+
+    # @param type [String] schema.org type
+    # @param id [String, nil] +@id+
+    # @return [self]
+    def node(type, id, **attrs)
+      push(normalize({ type: type, id: id }.merge(attrs)))
+      self
+    end
+
+    private
+
+    def push(hash)
+      validate!(hash)
+      @nodes.reject! { |existing| hash["@id"] && existing["@id"] == hash["@id"] }
+      @nodes << hash
+    end
+
+    def validate!(hash)
+      missing = REQUIRED.fetch(hash["@type"].to_s, []).select { |key| blank?(hash[key]) }
+      return if missing.empty?
+
+      raise InvalidNode, "#{hash["@type"]} #{hash["@id"]} is missing #{missing.join(", ")}"
+    end
+
+    def anchor(url, name)
+      "#{absolute(url.to_s).sub(/#.*\z/, "")}##{name}"
+    end
+
+    def normalize(value, key = nil)
+      case value
+      when Hash
+        value.each_with_object({}) do |(name, inner), out|
+          property = property_name(name)
+          normalized = normalize(inner, property)
+          out[property] = normalized unless normalized.nil?
+        end
+      when Array then value.map { |inner| normalize(inner, key) }
+      when Time, DateTime then value.iso8601
+      when Date then value.iso8601
+      when Symbol then value.to_s
+      when String then URL_KEYS.include?(key) ? absolute(value) : value
+      else value.respond_to?(:iso8601) ? value.iso8601 : value
+      end
+    end
+
+    def property_name(name)
+      return name if name.is_a?(String)
+      return "@#{name}" if %i[type id context graph].include?(name)
+
+      name.to_s.gsub(/_([a-z\d])/) { Regexp.last_match(1).upcase }
+    end
+
+    def absolute(value)
+      value.start_with?("/") && !value.start_with?("//") ? "#{origin}#{value}" : value
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+
+  # JSON-LD built from the page copy, so FAQPage always matches the visible FAQ.
+  class Page
+    # @param url [String, nil] absolute page URL used for +@id+ anchors; defaults to the canonical origin root
+    # @param config [Configuration]
+    # @return [JsonLd] a document holding the FAQPage node (empty when the page has no FAQ)
+    def json_ld(url: nil, config: SeoGeo.config)
+      document = JsonLd.new(config: config)
+      return document if faq.empty?
+
+      document.faq_page(faq, url: url || "#{document.origin}/")
+    end
+  end
+end

data/lib/seo_geo/llms_txt.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "uri"
+require "set"
+
+module SeoGeo
+  # Builds /llms.txt (https://llmstxt.org/) and /llms-full.txt for one request host.
+  #
+  # llms.txt: +# site.name+, +> site.description+, optional {LlmsTxtOptions#details}, then one H2 per
+  # section with +- [title](url): description+ lines and +## Optional+ last. Page links point at the
+  # page's Markdown (+.md+) when {MarkdownOptions#enabled}. Links come from {Configuration#llms_txt};
+  # when none are declared, the host's static sitemap paths are listed.
+  #
+  # llms-full.txt (community convention, not in the llmstxt.org text): the same header followed by
+  # every listed page's {Page#to_markdown}, headings demoted one level under one H1.
+  #
+  # Both are served only for hosts whose sitemap is on ({HostPolicy#sitemap}); otherwise nil (=> 404).
+  class LlmsTxt
+    OPTIONAL_SECTION = "Optional"
+
+    # @param config [Configuration]
+    # @param host [String] request host
+    # @param pages [PageRegistry]
+    # @param sitemap [Sitemap::Registry] fallback link source
+    def initialize(config, host, pages: SeoGeo.pages, sitemap: SeoGeo.sitemap)
+      @config = config
+      @host = host
+      @pages = pages
+      @sitemap = sitemap
+      @options = config.llms_txt
+      @policy = config.host_policy(host)
+    end
+
+    # @return [String, nil] llms.txt body, nil when not served on this host
+    def to_s
+      return nil unless served?
+
+      parts = header
+      sections.each do |name, lines|
+        parts << "## #{name}\n\n#{lines.join("\n")}"
+      end
+      "#{parts.join("\n\n")}\n"
+    end
+
+    # @return [String, nil] llms-full.txt body, nil when not served or no page is listed
+    def full
+      return nil unless served? && @options.full
+
+      page_links = links.select(&:page)
+      return nil if page_links.empty?
+
+      parts = header
+      page_links.each do |item|
+        markdown = page_for(item).to_markdown.gsub(/^(#+) /) { "##{Regexp.last_match(1)} " }
+        parts << "---\n\nSource: #{absolute(item.path)}\n\n#{markdown.strip}"
+      end
+      "#{parts.join("\n\n")}\n"
+    end
+
+    private
+
+    def served?
+      @options.enabled && @policy.sitemap
+    end
+
+    def header
+      name = present(@config.site.name) || @config.canonical_host || @policy.host
+      parts = ["# #{name}"]
+      description = present(@config.site.description)
+      parts << "> #{description.gsub(/\s+/, " ")}" if description
+      details = present(@options.details)
+      parts << details_markdown(details) if details
+      parts
+    end
+
+    # @return [Array<Array(String, Array<String>)>] section name => link lines, Optional last
+    def sections
+      grouped = links.group_by { |item| item.optional ? OPTIONAL_SECTION : (item.section || @options.default_section) }
+      optional = grouped.delete(OPTIONAL_SECTION)
+      grouped = grouped.to_a
+      grouped << [OPTIONAL_SECTION, optional] if optional
+      grouped.map { |name, items| [name, items.map { |item| line(item) }] }
+    end
+
+    def line(item)
+      page = item.page && page_for(item)
+      title = item.title || page&.title || page&.heading || item.path
+      description = item.description || page&.description
+      url = absolute(item.path)
+      url = markdown_url(url) if item.markdown_link?(@config) && same_origin?(URI.parse(url))
+      text = "- [#{title.to_s.gsub(/[\[\]]/) { |char| "\\#{char}" }}](#{url})"
+      description ? "#{text}: #{description.to_s.gsub(/\s+/, " ").strip}" : text
+    end
+
+    def links
+      @links ||= begin
+        declared = @options.links.select { |item| for_host?(item.hosts) }
+        (@options.links.empty? ? sitemap_links : declared).select { |item| publishable?(item.path) }
+      end
+    end
+
+    def sitemap_links
+      @sitemap.entries.select { |entry| entry.static? && entry.for_host?(@host, @config) && !@sitemap.excluded?(entry.source) }
+              .map do |entry|
+        LlmsTxtOptions::Link.new(page: nil, title: nil, path: entry.source, description: nil, section: nil,
+                                 optional: false, hosts: nil, markdown: entry.markdown)
+      end
+    end
+
+    # llms.txt and llms-full.txt list only what {SeoGeo::Publication} allows (the sitemap.xml and
+    # head rule: robots disallow, exclusions, noindex declarations, default_noindex). Links to other
+    # origins are not ours to judge and pass through.
+    def publishable?(path)
+      if path.match?(%r{\Ahttps?://}i)
+        return true unless same_origin?(URI.parse(path))
+      end
+      # /x.md (also /x.md?q) is the Markdown form of /x (Markdown::PathSuffix), so it is published only when /x is.
+      # The query stays for robots rules (Disallow: /x?preview=1); declarations drop it themselves.
+      page_path = RobotsPath.html_target(path, markdown: @config.markdown.suffix_urls?)
+      Publication.publishable?(@host, page_path, config: @config, sitemap: @sitemap, check_host: false,
+                                                 declared_index: indexed_by_sitemap?(page_path))
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def same_origin?(uri)
+      origin = URI.parse(@config.origin_for(@host))
+      uri.host && uri.host.casecmp?(origin.host) && uri.scheme.casecmp?(origin.scheme) && uri.port == origin.port
+    end
+
+    # Under default_noindex, records of a collection added with index: true are declared indexable too;
+    # only sitemap.xml knows their paths, so ask it (enumerated once per llms.txt render).
+    def indexed_by_sitemap?(path)
+      return false unless @config.default_noindex
+
+      @indexed_paths ||= Sitemap::Xml.new(@config, @sitemap, @host).urls
+                                     .to_set { |url| RobotsPath.path(url.loc) }
+      @indexed_paths.include?(RobotsPath.path(path))
+    end
+
+    def for_host?(hosts)
+      wanted = hosts ? hosts.map(&:downcase) : [@config.canonical_host]
+      wanted.include?(@policy.host)
+    end
+
+    def page_for(item)
+      @pages.fetch(item.page, locale: @config.site.default_locale)
+    end
+
+    def absolute(path)
+      return path if path.match?(%r{\Ahttps?://})
+
+      @config.canonical_url("#{@config.origin_for(@host)}#{path}")
+    end
+
+    # "/" => "/index.md", "/pricing" => "/pricing.md" (llmstxt.org convention); query dropped.
+    def markdown_url(url)
+      uri = URI.parse(url)
+      path = uri.path.to_s
+      path = path.empty? || path.end_with?("/") ? "#{path.chomp("/")}/index.md" : "#{path}.md"
+      uri.path = path
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
+    end
+
+    # Details are free Markdown (paragraphs, lists, headings). In llms.txt the single H1 is the site name and H2s are
+    # link sections, so H1/H2 headings in details are demoted to H3 (outside fenced code); H3+ stay as written.
+    def details_markdown(text)
+      fenced = false
+      text.strip.lines.map do |line|
+        fenced = !fenced if line.start_with?("```", "~~~")
+        fenced ? line : line.sub(/\A\#{1,2}(?=\s)/, "###")
+      end.join
+    end
+
+    def present(value)
+      value.nil? || value.to_s.strip.empty? ? nil : value.to_s
+    end
+  end
+end

data/lib/seo_geo/markdown/document.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "nokogiri"
+
+module SeoGeo
+  module Markdown
+    # Turns a rendered HTML page into a Markdown document for agents:
+    #
+    #   ---
+    #   title: ...          # <title>, else page copy
+    #   description: ...    # meta description
+    #   canonical: ...      # link rel=canonical, else config.canonical_url(request URL)
+    #   image: ...          # og:image
+    #   locale: ...         # <html lang>
+    #   ---
+    #
+    #   <main content converted to Markdown>
+    #
+    #   ```json
+    #   <each JSON-LD block>
+    #   ```
+    #
+    # When the HTML has no main content (an Inertia/SPA mount point) and a {SeoGeo::Page} is given, the
+    # body comes from {SeoGeo::Page#to_markdown}, so agents see the same copy as the crawler fallback.
+    class Document
+      # Removed before conversion wherever they appear.
+      NOISE = %w[script style noscript template iframe svg canvas nav form button dialog].freeze
+      # Removed as well when no main element exists and the whole body is converted.
+      CHROME = %w[header footer aside].freeze
+
+      # @return [String]
+      attr_reader :html
+
+      # @param html [String] the rendered HTML response body
+      # @param config [Configuration]
+      # @param url [String, nil] request URL, used for the canonical fallback
+      # @param page [Page, nil] page copy for client-rendered pages
+      # @param selector [String, nil] main-content selector; nil uses +config.markdown.selector+
+      def initialize(html, config: SeoGeo.config, url: nil, page: nil, selector: nil)
+        @html = html.to_s
+        @config = config
+        @url = url
+        @page = page
+        @selector = selector || config.markdown.selector
+      end
+
+      # @return [String] the full Markdown document
+      def to_s
+        body = body_markdown
+        parts = [frontmatter, body.strip]
+        json_ld.each { |block| parts << "```json\n#{block}\n```" }
+        "#{parts.reject(&:empty?).join("\n\n")}\n"
+      end
+
+      # @return [Hash{String => String}] frontmatter fields that have a value
+      def metadata
+        {
+          "title" => text_at("head > title") || @page&.title,
+          "description" => attribute_at('meta[name="description"]', "content") || @page&.description,
+          "canonical" => attribute_at('link[rel="canonical"]', "href") || canonical_fallback,
+          "image" => attribute_at('meta[property="og:image"]', "content"),
+          "locale" => attribute_at("html", "lang") || @page&.locale&.to_s
+        }.reject { |_name, value| value.nil? || value.to_s.strip.empty? }
+      end
+
+      # @return [RobotsDirectives] every robots and crawler-specific meta of the HTML
+      def robots
+        @robots ||= RobotsDirectives.from_html(doc)
+      end
+
+      # Global directives (every +<meta name="robots">+), lower-cased, +none+ expanded to +noindex, nofollow+.
+      # @return [Array<String>]
+      def robots_directives
+        robots.global.to_a
+      end
+
+      # @return [Boolean] true when the HTML asks every robot not to index the page
+      def noindex?
+        robots.noindex?
+      end
+
+      # @return [Array<String>] pretty-printed JSON-LD blocks
+      def json_ld
+        doc.css('script[type="application/ld+json"]').filter_map do |node|
+          raw = node.text.strip
+          next if raw.empty?
+
+          begin
+            JSON.pretty_generate(JSON.parse(raw))
+          rescue JSON::ParserError
+            raw
+          end
+        end
+      end
+
+      private
+
+      def doc
+        @doc ||= if defined?(Nokogiri::HTML5) then Nokogiri::HTML5(@html)
+                 else Nokogiri::HTML(@html)
+                 end
+      end
+
+      def frontmatter
+        data = metadata
+        return "" if data.empty?
+
+        "#{YAML.dump(data).sub(/\A---\s*\n/, "---\n")}---"
+      end
+
+      def body_markdown
+        from_html = convert(main_html)
+        return from_html unless from_html.strip.empty? && @page
+
+        @page.to_markdown
+      end
+
+      # HTML of the main content with noise removed. Works on a copy so metadata/JSON-LD stay readable.
+      def main_html
+        copy = doc.dup
+        main = copy.at_css(@selector)
+        root = main || copy.at_css("body")
+        return "" if root.nil?
+
+        removable = main ? NOISE : NOISE + CHROME
+        root.css(removable.join(",")).each(&:remove)
+        root.inner_html
+      end
+
+      def convert(fragment)
+        return "" if fragment.strip.empty?
+
+        converter = @config.markdown.converter
+        markdown = if converter.respond_to?(:call)
+                     converter.call(fragment)
+                   else
+                     require "reverse_markdown"
+                     ReverseMarkdown.convert(fragment, unknown_tags: :bypass, github_flavored: true)
+                   end
+        markdown.to_s.gsub(/\n{3,}/, "\n\n")
+      end
+
+      def text_at(selector)
+        node = doc.at_css(selector)
+        value = node&.text&.strip
+        value unless value.nil? || value.empty?
+      end
+
+      def attribute_at(selector, name)
+        value = doc.at_css(selector)&.[](name)&.strip
+        value unless value.nil? || value.empty?
+      end
+
+      def canonical_fallback
+        return nil if @url.nil? || @config.canonical_origin.nil?
+
+        @config.canonical_url(@url)
+      end
+    end
+  end
+end

data/lib/seo_geo/markdown/negotiation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SeoGeo
+  module Markdown
+    # Decides whether an +Accept+ header asks for Markdown.
+    #
+    # Markdown wins only when +text/markdown+ is named explicitly (wildcards never select it) with a
+    # q-value above zero that is higher than the one +text/html+ gets, or equal to it and listed first.
+    # Agents send +text/markdown, text/html;q=0.9+ or +text/markdown, text/html, *\/*+; browsers never
+    # name text/markdown, so they keep getting HTML.
+    module Negotiation
+      module_function
+
+      # @param accept [String, nil] raw Accept header
+      # @return [Boolean]
+      def markdown?(accept)
+        ranges = parse(accept)
+        markdown = ranges.find { |range| range[:type] == "text/markdown" }
+        return false if markdown.nil? || markdown[:q] <= 0
+
+        html = quality_for_html(ranges)
+        return true if html.nil?
+
+        markdown[:q] > html[:q] || (markdown[:q] == html[:q] && markdown[:index] < html[:index])
+      end
+
+      # @param accept [String, nil]
+      # @return [Array<Hash>] +{type:, q:, index:}+ in header order
+      def parse(accept)
+        accept.to_s.split(",").each_with_index.filter_map do |part, index|
+          type, *params = part.split(";").map(&:strip)
+          next if type.nil? || type.empty?
+
+          q = params.filter_map { |param| param[/\Aq\s*=\s*([0-9.]+)\z/i, 1] }.first
+          { type: type.downcase, q: q ? q.to_f.clamp(0.0, 1.0) : 1.0, index: index }
+        end
+      end
+
+      # The most specific range matching text/html (RFC 9110 §12.5.1).
+      def quality_for_html(ranges)
+        %w[text/html text/* */*].each do |type|
+          found = ranges.find { |range| range[:type] == type }
+          return found if found
+        end
+        nil
+      end
+    end
+  end
+end