From 15e96603324709a3a7860832a5bfd92f824197eb Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 30 Mar 2026 18:08:43 +0100
Subject: [PATCH 1/9] Bump minimum Ruby to 3.2, add rbs dependency, update CI

RBS 4.0 requires Ruby >= 3.2. Bump RDoc's own minimum to match and
add `rbs >= 4.0.0` as a gemspec dependency. Bump prism minimum to
`>= 1.6.0` (required by rbs). Drop JRuby and TruffleRuby from CI
matrix (rbs has a C extension that cannot build on them).
---
 .github/workflows/test.yml | 14 +++-----------
 Gemfile                    |  4 +---
 rdoc.gemspec               |  5 +++--
 3 files changed, 7 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1c6309ea77..70ad37c2cc 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -14,9 +14,9 @@ jobs:
   ruby-versions:
     uses: ruby/actions/.github/workflows/ruby_versions.yml@master
     with:
-      # 2.7 breaks `test_parse_statements_nodoc_identifier_alias_method`
-      min_version: 3.0
+      min_version: 3.2
       versions: '["mswin"]'
+      engine: cruby
 
   test:
     needs: ruby-versions
@@ -26,14 +26,6 @@ jobs:
         ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
         os: [ubuntu-latest, macos-latest, windows-latest]
         exclude:
-          - os: windows-latest
-            ruby: truffleruby
-          - os: windows-latest
-            ruby: truffleruby-head
-          - os: windows-latest
-            ruby: jruby
-          - os: windows-latest
-            ruby: jruby-head
           - os: macos-latest
             ruby: mswin
           - os: ubuntu-latest
@@ -68,7 +60,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        prism_version: ['1.0.0', '1.3.0', '1.7.0', 'head']
+        prism_version: ['1.6.0', '1.7.0', 'head']
     runs-on: ubuntu-latest
     env:
       RUBYOPT: --enable-frozen_string_literal
diff --git a/Gemfile b/Gemfile
index 317623101b..4b2be8f5d5 100644
--- a/Gemfile
+++ b/Gemfile
@@ -18,7 +18,5 @@ elsif ENV['PRISM_VERSION']
 end
 
 platforms :ruby do
-  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
-    gem 'mini_racer' # For testing the searcher.js file
-  end
+  gem 'mini_racer' # For testing the searcher.js file
 end
diff --git a/rdoc.gemspec b/rdoc.gemspec
index 1afe52f7b6..294255d7a1 100644
--- a/rdoc.gemspec
+++ b/rdoc.gemspec
@@ -63,11 +63,12 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
   s.rdoc_options = ["--main", "README.md"]
   s.extra_rdoc_files += s.files.grep(%r[\A[^\/]+\.(?:rdoc|md)\z])
 
-  s.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  s.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
   s.required_rubygems_version = Gem::Requirement.new(">= 2.2")
 
   s.add_dependency 'psych', '>= 4.0.0'
   s.add_dependency 'erb'
   s.add_dependency 'tsort'
-  s.add_dependency 'prism', '>= 1.0.0'
+  s.add_dependency 'prism', '>= 1.6.0'
+  s.add_dependency 'rbs', '>= 4.0.0'
 end

From c7e4cd5541a282eded1f14e8d5b8c57997ce6c0c Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 30 Mar 2026 18:08:57 +0100
Subject: [PATCH 2/9] Extract and display RBS type signatures in documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add `type_signature` accessor to `MethodAttr`. During Prism parsing,
extract `#:` annotation lines from comment blocks and store them on
methods and attributes. Bump Marshal to v4 for RI serialization.

Render type signatures in the aliki theme: below method headings for
methods, inline after the `[RW]` badge for attributes. Arrows use
`→` for consistency with `call_seq`. Validate annotations through
`RBS::Parser` — invalid sigs emit a warning but are still displayed.

Client-side JS highlighter colors type names (blue) and built-in
keywords like `void`/`untyped`/`bool` (purple).
---
 lib/rdoc/code_object/any_method.rb            |   4 +-
 lib/rdoc/code_object/attr.rb                  |   6 +-
 lib/rdoc/code_object/method_attr.rb           |   6 +
 lib/rdoc/generator/template/aliki/_head.rhtml |   5 +
 lib/rdoc/generator/template/aliki/class.rhtml |  13 +-
 .../generator/template/aliki/css/rdoc.css     |  33 ++++
 lib/rdoc/parser/prism_ruby.rb                 |  45 ++++-
 test/rdoc/code_object/any_method_test.rb      |  21 +++
 test/rdoc/code_object/attr_test.rb            |  17 ++
 test/rdoc/parser/prism_ruby_test.rb           | 154 ++++++++++++++++++
 10 files changed, 294 insertions(+), 10 deletions(-)

diff --git a/lib/rdoc/code_object/any_method.rb b/lib/rdoc/code_object/any_method.rb
index f56110ea11..26b42c07cb 100644
--- a/lib/rdoc/code_object/any_method.rb
+++ b/lib/rdoc/code_object/any_method.rb
@@ -14,7 +14,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   #   RDoc 4.1
   #   Added is_alias_for
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -166,6 +166,7 @@ def marshal_dump
       @parent.class,
       @section.title,
       is_alias_for,
+      @type_signature,
     ]
   end
 
@@ -204,6 +205,7 @@ def marshal_load(array)
     @parent_title  = array[13]
     @section_title = array[14]
     @is_alias_for  = array[15]
+    @type_signature = array[16]
 
     array[8].each do |new_name, document|
       add_alias RDoc::Alias.new(nil, @name, new_name, RDoc::Comment.from_document(document), singleton: @singleton)
diff --git a/lib/rdoc/code_object/attr.rb b/lib/rdoc/code_object/attr.rb
index bfc981f7e8..3895121854 100644
--- a/lib/rdoc/code_object/attr.rb
+++ b/lib/rdoc/code_object/attr.rb
@@ -11,7 +11,7 @@ class RDoc::Attr < RDoc::MethodAttr
   #    Added parent name and class
   #    Added section title
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -108,7 +108,8 @@ def marshal_dump
       @file.relative_name,
       @parent.full_name,
       @parent.class,
-      @section.title
+      @section.title,
+      @type_signature,
     ]
   end
 
@@ -140,6 +141,7 @@ def marshal_load(array)
     @parent_name   = array[8]
     @parent_class  = array[9]
     @section_title = array[10]
+    @type_signature = array[11]
 
     @file = RDoc::TopLevel.new array[7] if version > 1
 
diff --git a/lib/rdoc/code_object/method_attr.rb b/lib/rdoc/code_object/method_attr.rb
index 3169640982..f968543bdd 100644
--- a/lib/rdoc/code_object/method_attr.rb
+++ b/lib/rdoc/code_object/method_attr.rb
@@ -58,6 +58,11 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_accessor :call_seq
 
+  ##
+  # RBS type signature from inline #: annotations
+
+  attr_accessor :type_signature
+
   ##
   # The call_seq or the param_seq with method name, if there is no call_seq.
 
@@ -86,6 +91,7 @@ def initialize(text, name, singleton: false)
     @block_params = nil
     @call_seq     = nil
     @params       = nil
+    @type_signature = nil
   end
 
   ##
diff --git a/lib/rdoc/generator/template/aliki/_head.rhtml b/lib/rdoc/generator/template/aliki/_head.rhtml
index c6c238d26c..4d05606e58 100644
--- a/lib/rdoc/generator/template/aliki/_head.rhtml
+++ b/lib/rdoc/generator/template/aliki/_head.rhtml
@@ -145,6 +145,11 @@
   defer
 ></script>
 
+<script
+  src="<%= h asset_rel_prefix %>/js/rbs_highlighter.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
 <script
   src="<%= h asset_rel_prefix %>/js/aliki.js?v=<%= h RDoc::VERSION %>"
   defer
diff --git a/lib/rdoc/generator/template/aliki/class.rhtml b/lib/rdoc/generator/template/aliki/class.rhtml
index ba1238b9e9..a1d55c282d 100644
--- a/lib/rdoc/generator/template/aliki/class.rhtml
+++ b/lib/rdoc/generator/template/aliki/class.rhtml
@@ -91,8 +91,9 @@
         <div class="method-heading attribute-method-heading">
           <a href="#<%= attrib.aref %>" title="Link to this attribute">
             <span class="method-name"><%= h attrib.name %></span>
-            <span class="attribute-access-type">[<%= attrib.rw %>]</span>
-          </a>
+            <span class="attribute-access-type">[<%= attrib.rw %>]</span></a><%- if attrib.type_signature %>
+          <span class="method-type-signature"><code><%= h attrib.type_signature %></code></span>
+          <%- end %>
         </div>
 
         <div class="method-description">
@@ -150,6 +151,14 @@
               </a>
             </div>
           <%- end %>
+
+          <%- if method.type_signature %>
+          <div class="method-type-signature">
+            <%- method.type_signature.split("\n").each do |sig| %>
+            <code><%= h(sig).gsub('-&gt;', '&rarr;') %></code>
+            <%- end %>
+          </div>
+          <%- end %>
         </div>
 
         <%- if method.token_stream %>
diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index 25a3f43076..6d420705d5 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -1071,6 +1071,18 @@ main h6 a:hover {
   font-style: italic;
 }
 
+/* RBS Type Signature Highlighting — only types and builtins get color */
+.rbs-type    { color: var(--code-blue); }
+.rbs-builtin { color: var(--code-purple); }
+
+a.rbs-type {
+  text-decoration: none;
+}
+
+a.rbs-type:hover {
+  text-decoration: underline;
+}
+
 /* Emphasis */
 em {
   text-decoration-color: var(--color-emphasis-decoration);
@@ -1312,6 +1324,27 @@ main .method-heading .method-args {
   font-weight: var(--font-weight-normal);
 }
 
+/* Type signatures — method overloads stack vertically under the name */
+main .method-header .method-type-signature {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-1);
+}
+
+main .method-type-signature code {
+  font-family: var(--font-code);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-secondary);
+  background: transparent;
+}
+
+/* Attribute type sigs render inline after the [RW] badge */
+main .method-heading > .method-type-signature {
+  display: inline;
+  margin-left: var(--space-2);
+}
+
 main .method-controls {
   float: right;
 }
diff --git a/lib/rdoc/parser/prism_ruby.rb b/lib/rdoc/parser/prism_ruby.rb
index e8dedd5c18..9d97458cab 100644
--- a/lib/rdoc/parser/prism_ruby.rb
+++ b/lib/rdoc/parser/prism_ruby.rb
@@ -461,7 +461,39 @@ def skip_comments_until(line_no_until)
   def consecutive_comment(line_no)
     return unless @unprocessed_comments.first&.first == line_no
     _line_no, start_line, text = @unprocessed_comments.shift
-    parse_comment_text_to_directives(text, start_line)
+    type_signature = extract_type_signature!(text)
+    result = parse_comment_text_to_directives(text, start_line)
+    return unless result
+    comment, directives = result
+    [comment, directives, type_signature]
+  end
+
+  # Extracts RBS type signature lines (#: ...) from raw comment text.
+  # Mutates the input text to remove the extracted lines.
+  # Returns the type signature string, or nil if none found.
+  private def extract_type_signature!(text)
+    return nil unless text.include?('#:')
+
+    lines = text.lines
+    sig_lines, doc_lines = lines.partition { |l| l.match?(/\A#:\s/) }
+    return nil if sig_lines.empty?
+
+    text.replace(doc_lines.join)
+    type_sig = sig_lines.map { |l| l.sub(/\A#:\s?/, '').chomp }.join("\n")
+    validate_type_signature(type_sig)
+    type_sig
+  end
+
+  private def validate_type_signature(sig)
+    sig.split("\n").each do |line|
+      # Method types contain ->, plain types (for attributes) don't
+      error = if line.include?('->')
+        RDoc::RbsSupport.validate_method_type(line)
+      else
+        RDoc::RbsSupport.validate_type(line)
+      end
+      @options.warn "Invalid RBS type signature: #{line.inspect}" if error
+    end
   end
 
   # Parses comment text and retuns a pair of RDoc::Comment and directives
@@ -594,7 +626,7 @@ def add_alias_method(old_name, new_name, line_no)
   # Handles `attr :a, :b`, `attr_reader :a, :b`, `attr_writer :a, :b` and `attr_accessor :a, :b`
 
   def add_attributes(names, rw, line_no)
-    comment, directives = consecutive_comment(line_no)
+    comment, directives, type_signature = consecutive_comment(line_no)
     handle_code_object_directives(@container, directives) if directives
     return unless @container.document_children
 
@@ -602,6 +634,7 @@ def add_attributes(names, rw, line_no)
       a = RDoc::Attr.new(nil, symbol.to_s, rw, comment, singleton: @singleton)
       a.store = @store
       a.line = line_no
+      a.type_signature = type_signature
       record_location(a)
       handle_modifier_directive(a, line_no)
       @container.add_attribute(a) if should_document?(a)
@@ -640,7 +673,7 @@ def add_extends(names, line_no) # :nodoc:
 
   def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, start_line:, args_end_line:, end_line:)
     receiver = receiver_name ? find_or_create_module_path(receiver_name, receiver_fallback_type) : @container
-    comment, directives = consecutive_comment(start_line)
+    comment, directives, type_signature = consecutive_comment(start_line)
     handle_code_object_directives(@container, directives) if directives
 
     internal_add_method(
@@ -655,11 +688,12 @@ def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:
       params: params,
       calls_super: calls_super,
       block_params: block_params,
-      tokens: tokens
+      tokens: tokens,
+      type_signature: type_signature
     )
   end
 
-  private def internal_add_method(method_name, container, comment:, dont_rename_initialize: false, directives:, modifier_comment_lines: nil, line_no:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:) # :nodoc:
+  private def internal_add_method(method_name, container, comment:, dont_rename_initialize: false, directives:, modifier_comment_lines: nil, line_no:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, type_signature: nil) # :nodoc:
     meth = RDoc::AnyMethod.new(nil, method_name, singleton: singleton)
     meth.comment = comment
     handle_code_object_directives(meth, directives) if directives
@@ -680,6 +714,7 @@ def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:
     meth.params ||= params || '()'
     meth.calls_super = calls_super
     meth.block_params ||= block_params if block_params
+    meth.type_signature = type_signature
     record_location(meth)
     meth.start_collecting_tokens(:ruby)
     tokens.each do |token|
diff --git a/test/rdoc/code_object/any_method_test.rb b/test/rdoc/code_object/any_method_test.rb
index 43dc679d95..eb97257d5a 100644
--- a/test/rdoc/code_object/any_method_test.rb
+++ b/test/rdoc/code_object/any_method_test.rb
@@ -242,6 +242,27 @@ def test_marshal_dump
     assert_equal section,        loaded.section
   end
 
+  def test_marshal_dump_with_type_signature
+    @store.path = Dir.tmpdir
+    top_level = @store.add_file 'file.rb'
+
+    m = RDoc::AnyMethod.new nil, 'method'
+    m.block_params   = 'some_block'
+    m.call_seq        = 'call_seq'
+    m.comment         = 'this is a comment'
+    m.params          = 'param'
+    m.type_signature  = '(String) -> Integer'
+    m.record_location top_level
+
+    cm = top_level.add_class RDoc::ClassModule, 'Klass'
+    cm.add_method m
+
+    loaded = Marshal.load Marshal.dump m
+    loaded.store = @store
+
+    assert_equal '(String) -> Integer', loaded.type_signature
+  end
+
   def test_marshal_load_aliased_method
     aliased_method = Marshal.load Marshal.dump(@c2_a)
 
diff --git a/test/rdoc/code_object/attr_test.rb b/test/rdoc/code_object/attr_test.rb
index 3588743694..a226ffa5cd 100644
--- a/test/rdoc/code_object/attr_test.rb
+++ b/test/rdoc/code_object/attr_test.rb
@@ -74,6 +74,23 @@ def test_marshal_dump
     assert_equal section,      loaded.section
   end
 
+  def test_marshal_dump_with_type_signature
+    @store.path = Dir.tmpdir
+    top_level = @store.add_file 'file.rb'
+
+    a = RDoc::Attr.new nil, 'name', 'R', 'a comment'
+    a.type_signature = 'String'
+    a.record_location top_level
+
+    cm = top_level.add_class RDoc::ClassModule, 'Klass'
+    cm.add_attribute a
+
+    loaded = Marshal.load Marshal.dump a
+    loaded.store = @store
+
+    assert_equal 'String', loaded.type_signature
+  end
+
   def test_marshal_dump_singleton
     tl = @store.add_file 'file.rb'
 
diff --git a/test/rdoc/parser/prism_ruby_test.rb b/test/rdoc/parser/prism_ruby_test.rb
index f018123f7b..dca28c2bd8 100644
--- a/test/rdoc/parser/prism_ruby_test.rb
+++ b/test/rdoc/parser/prism_ruby_test.rb
@@ -2374,6 +2374,160 @@ def m2; end
     assert_equal "foo1\nbar1", m1.call_seq.chomp
     assert_equal "ARGF.readlines(a)\nARGF.readlines(b)\nARGF.readlines(c)\nARGF.readlines(d)", m2.call_seq.chomp
   end
+
+  # Type signature tests — Prism parser only (Ripper doesn't extract #: annotations)
+
+  def test_method_type_signature
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        # A greeting method
+        #: (String, Integer) -> void
+        def greet(name, count); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    greet = klass.method_list.first
+    assert_equal 'greet', greet.name
+    assert_equal '(String, Integer) -> void', greet.type_signature
+    assert_equal 'A greeting method', greet.comment.text.strip
+  end
+
+  def test_attribute_type_signature
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        #: String
+        attr_reader :name
+
+        #: Integer
+        attr_accessor :count
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    attrs = klass.attributes.sort_by(&:name)
+    assert_equal 'count', attrs[0].name
+    assert_equal 'Integer', attrs[0].type_signature
+    assert_equal 'name', attrs[1].name
+    assert_equal 'String', attrs[1].type_signature
+  end
+
+  def test_method_type_signature_multiple_overloads
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        # Convert a value
+        #: (String) -> Integer
+        #: (Integer) -> String
+        def convert(value); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    convert = klass.method_list.first
+    assert_equal "(String) -> Integer\n(Integer) -> String", convert.type_signature
+    assert_equal 'Convert a value', convert.comment.text.strip
+  end
+
+  def test_method_without_type_signature
+    util_parser <<~RUBY
+      class Foo
+        # A plain method
+        def plain; end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    plain = klass.method_list.first
+    assert_nil plain.type_signature
+    assert_equal 'A plain method', plain.comment.text.strip
+  end
+
+  def test_method_type_signature_only
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        #: (Integer) -> void
+        def bar(x); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    bar = klass.method_list.first
+    assert_equal '(Integer) -> void', bar.type_signature
+  end
+
+  def test_method_type_signature_with_blank_line_separation
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        # Documentation here
+        #
+        #: (String) -> void
+        def bar(x); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    bar = klass.method_list.first
+    assert_equal '(String) -> void', bar.type_signature
+    assert_includes bar.comment.text, 'Documentation here'
+  end
+
+  def test_method_type_signature_with_override_comment
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        # @override
+        #: (untyped) -> void
+        def accept(visitor); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    accept = klass.method_list.first
+    assert_equal '(untyped) -> void', accept.type_signature
+    assert_includes accept.comment.text, '@override'
+  end
+
+  def test_type_signature_real_file
+    content = File.read(File.expand_path('../../../lib/rdoc/markup/heading.rb', __dir__))
+    top_level = @store.add_file 'lib/rdoc/markup/heading.rb'
+    parser = RDoc::Parser::PrismRuby.new(top_level, content, @options, @stats)
+    parser.scan
+
+    heading_class = @store.find_class_named('RDoc::Markup::Heading')
+    assert heading_class, 'RDoc::Markup::Heading should be found'
+
+    label_method = heading_class.method_list.find { |m| m.name == 'label' }
+    assert label_method, 'label method should be found'
+    assert_equal '(RDoc::Context?) -> String', label_method.type_signature
+
+    aref_method = heading_class.method_list.find { |m| m.name == 'aref' }
+    assert aref_method, 'aref method should be found'
+    assert_equal '() -> String', aref_method.type_signature
+
+    accept_method = heading_class.method_list.find { |m| m.name == 'accept' }
+    assert accept_method, 'accept method should be found'
+    assert_equal '(untyped) -> void', accept_method.type_signature
+  end
+
+  def test_type_signature_invalid_still_stored
+    omit 'Prism parser only' if accept_legacy_bug?
+    util_parser <<~RUBY
+      class Foo
+        #: (String ->
+        def bar(x); end
+      end
+    RUBY
+
+    klass = @store.find_class_named 'Foo'
+    bar = klass.method_list.first
+    # Invalid sigs are still stored (don't block display)
+    assert_equal '(String ->', bar.type_signature
+  end
 end
 
 class RDocParserPrismRubyTest < RDoc::TestCase

From c3a8a620423111ca3bdb48053f2195734a3997b9 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 30 Mar 2026 18:09:18 +0100
Subject: [PATCH 3/9] Add RBS support module for sig/ loading and validation

`RDoc::RbsSupport` provides:
- `load_signatures` to load types from .rbs files via
  `RBS::EnvironmentLoader`
- `merge_into_store` to attach sig/ types to code objects
  (inline `#:` annotations take priority)
- `validate_method_type`/`validate_type` for syntax checking

Auto-detects `sig/` directory during generation and merges types
after `store.complete`.
---
 lib/rdoc/rbs_support.rb       | 88 +++++++++++++++++++++++++++++++++++
 lib/rdoc/rdoc.rb              |  8 ++++
 test/rdoc/rbs_support_test.rb | 83 +++++++++++++++++++++++++++++++++
 3 files changed, 179 insertions(+)
 create mode 100644 lib/rdoc/rbs_support.rb
 create mode 100644 test/rdoc/rbs_support_test.rb

diff --git a/lib/rdoc/rbs_support.rb b/lib/rdoc/rbs_support.rb
new file mode 100644
index 0000000000..bc3a989c58
--- /dev/null
+++ b/lib/rdoc/rbs_support.rb
@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+##
+# RBS type signature support.
+# Loads type information from .rbs files and validates inline annotations.
+
+module RDoc::RbsSupport
+
+  ##
+  # Validates an RBS method type signature string.
+  # Returns nil if valid, or an error message string if invalid.
+
+  def self.validate_method_type(sig)
+    RBS::Parser.parse_method_type(sig, require_eof: true)
+    nil
+  rescue RBS::ParsingError => e
+    e.message
+  end
+
+  ##
+  # Validates an RBS type signature string.
+  # Returns nil if valid, or an error message string if invalid.
+
+  def self.validate_type(sig)
+    RBS::Parser.parse_type(sig, require_eof: true)
+    nil
+  rescue RBS::ParsingError => e
+    e.message
+  end
+
+  ##
+  # Loads RBS signatures from the given directories.
+  # Returns a Hash mapping "ClassName#method_name" => "type sig string".
+
+  def self.load_signatures(*dirs)
+    loader = RBS::EnvironmentLoader.new(core_root: nil)
+    dirs.each { |dir| loader.add(path: Pathname(dir)) }
+
+    env = RBS::Environment.new
+    loader.load(env: env)
+
+    signatures = {}
+
+    env.class_decls.each do |type_name, entry|
+      class_name = type_name.to_s.delete_prefix('::')
+
+      entry.each_decl do |decl|
+        decl.members.each do |member|
+          case member
+          when RBS::AST::Members::MethodDefinition
+            key = member.singleton? ? "#{class_name}::#{member.name}" : "#{class_name}##{member.name}"
+            sigs = member.overloads.map { |o| o.method_type.to_s }
+            signatures[key] = sigs.join("\n")
+          when RBS::AST::Members::AttrReader, RBS::AST::Members::AttrWriter, RBS::AST::Members::AttrAccessor
+            key = "#{class_name}.#{member.name}"
+            signatures[key] = member.type.to_s
+          end
+        end
+      end
+    end
+
+    signatures
+  end
+
+  ##
+  # Merges loaded RBS signatures into the store's code objects.
+  # Inline #: annotations take priority and are not overwritten.
+
+  def self.merge_into_store(store, signatures)
+    store.all_classes_and_modules.each do |cm|
+      cm.method_list.each do |method|
+        next if method.type_signature
+
+        key = method.singleton ? "#{cm.full_name}::#{method.name}" : "#{cm.full_name}##{method.name}"
+        method.type_signature = signatures[key] if signatures[key]
+      end
+
+      cm.attributes.each do |attr|
+        next if attr.type_signature
+
+        key = "#{cm.full_name}.#{attr.name}"
+        attr.type_signature = signatures[key] if signatures[key]
+      end
+    end
+  end
+end
diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index 195bd21421..9de808e321 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -5,6 +5,7 @@
 require 'fileutils'
 require 'pathname'
 require 'time'
+require_relative 'rbs_support'
 
 ##
 # This is the driver for generating RDoc output.  It handles file parsing and
@@ -492,6 +493,13 @@ def document(options)
 
     @store.complete @options.visibility
 
+    # Load RBS signatures from sig/ directory
+    sig_dir = File.join(@options.root.to_s, 'sig')
+    if File.directory?(sig_dir)
+      signatures = RDoc::RbsSupport.load_signatures(sig_dir)
+      RDoc::RbsSupport.merge_into_store(@store, signatures) unless signatures.empty?
+    end
+
     @stats.coverage_level = @options.coverage_report
 
     if @options.coverage_report then
diff --git a/test/rdoc/rbs_support_test.rb b/test/rdoc/rbs_support_test.rb
new file mode 100644
index 0000000000..b5545dd933
--- /dev/null
+++ b/test/rdoc/rbs_support_test.rb
@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'helper'
+require 'rdoc/rbs_support'
+
+class RDocRbsSupportTest < RDoc::TestCase
+  def test_validate_method_type_valid
+    assert_nil RDoc::RbsSupport.validate_method_type('(String) -> void')
+    assert_nil RDoc::RbsSupport.validate_method_type('(Integer, ?String) -> bool')
+    assert_nil RDoc::RbsSupport.validate_method_type('() -> Array[String]')
+  end
+
+  def test_validate_method_type_invalid
+    error = RDoc::RbsSupport.validate_method_type('(String ->')
+    assert_kind_of String, error
+  end
+
+  def test_validate_type_valid
+    assert_nil RDoc::RbsSupport.validate_type('String')
+    assert_nil RDoc::RbsSupport.validate_type('Array[Integer]')
+    assert_nil RDoc::RbsSupport.validate_type('String?')
+  end
+
+  def test_validate_type_invalid
+    error = RDoc::RbsSupport.validate_type('String[')
+    assert_kind_of String, error
+  end
+
+  def test_load_signatures_from_directory
+    Dir.mktmpdir do |dir|
+      File.write(File.join(dir, 'test.rbs'), <<~RBS)
+        class Greeter
+          def greet: (String name) -> void
+          attr_reader language: String
+        end
+      RBS
+
+      sigs = RDoc::RbsSupport.load_signatures(dir)
+      assert_equal '(String name) -> void', sigs['Greeter#greet']
+      assert_equal 'String', sigs['Greeter.language']
+    end
+  end
+
+  def test_merge_into_store
+    top_level = @store.add_file 'test.rb'
+    cm = top_level.add_class RDoc::NormalClass, 'Greeter'
+
+    m = RDoc::AnyMethod.new(nil, 'greet')
+    m.params = '(name)'
+    cm.add_method m
+
+    a = RDoc::Attr.new(nil, 'language', 'R', '')
+    cm.add_attribute a
+
+    signatures = {
+      'Greeter#greet' => '(String name) -> void',
+      'Greeter.language' => 'String'
+    }
+
+    RDoc::RbsSupport.merge_into_store(@store, signatures)
+
+    assert_equal '(String name) -> void', m.type_signature
+    assert_equal 'String', a.type_signature
+  end
+
+  def test_merge_does_not_overwrite_inline_annotations
+    top_level = @store.add_file 'test.rb'
+    cm = top_level.add_class RDoc::NormalClass, 'Greeter'
+
+    m = RDoc::AnyMethod.new(nil, 'greet')
+    m.params = '(name)'
+    m.type_signature = '(String) -> void'
+    cm.add_method m
+
+    signatures = {
+      'Greeter#greet' => '(String name, ?Integer count) -> void'
+    }
+
+    RDoc::RbsSupport.merge_into_store(@store, signatures)
+
+    assert_equal '(String) -> void', m.type_signature
+  end
+end

From bcec636281f7c1ce2353c0f9520dd05ca5cebefa Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 30 Mar 2026 18:09:27 +0100
Subject: [PATCH 4/9] Link type names in RBS signatures to documentation pages

The JS highlighter resolves type names against the search index and
wraps matches in <a> tags. Qualified names like Foo::Bar::Baz are
collected as single linked units. Types not found in the index
remain as unlinked <span> elements.
---
 .../template/aliki/js/rbs_highlighter.js      | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 lib/rdoc/generator/template/aliki/js/rbs_highlighter.js

diff --git a/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js b/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js
new file mode 100644
index 0000000000..92ccb32a55
--- /dev/null
+++ b/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js
@@ -0,0 +1,116 @@
+/**
+ * Client-side RBS type signature highlighter for RDoc
+ *
+ * Highlights type names and built-in keywords in inline RBS annotations.
+ * Links type names to their documentation pages using the search index.
+ *
+ * NOTE: innerHTML usage is safe here — input is the element's own textContent
+ * (not user-supplied) and all output is escaped through escapeHtml(). This
+ * follows the same pattern as c_highlighter.js and bash_highlighter.js.
+ */
+
+(function() {
+  'use strict';
+
+  var BUILTIN_TYPES = new Set([
+    'void', 'untyped', 'nil', 'bool', 'self', 'top', 'bot',
+    'instance', 'class', 'true', 'false'
+  ]);
+
+  var typeLookup = null;
+
+  function buildTypeLookup() {
+    var lookup = {};
+    if (!window.search_data || !window.search_data.index) return lookup;
+
+    window.search_data.index.forEach(function(entry) {
+      if (entry.type === 'class' || entry.type === 'module') {
+        lookup[entry.full_name] = entry.path;
+        // Also map short name if not already taken
+        var short = entry.name;
+        if (!lookup[short]) lookup[short] = entry.path;
+      }
+    });
+    return lookup;
+  }
+
+  function escapeHtml(text) {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  function isIdentChar(ch) {
+    return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+           (ch >= '0' && ch <= '9') || ch === '_';
+  }
+
+  function highlightRbs(text) {
+    var tokens = [];
+    var i = 0;
+    var len = text.length;
+    var prefix = typeof rdoc_rel_prefix !== 'undefined' ? rdoc_rel_prefix : '';
+
+    while (i < len) {
+      var ch = text[i];
+
+      // Uppercase identifier — possibly a type name, collect qualified name (Foo::Bar)
+      if (ch >= 'A' && ch <= 'Z') {
+        var end = i + 1;
+        while (end < len && isIdentChar(text[end])) end++;
+        // Collect :: continuations
+        while (end + 1 < len && text[end] === ':' && text[end + 1] === ':') {
+          end += 2;
+          while (end < len && isIdentChar(text[end])) end++;
+        }
+        var name = text.substring(i, end);
+        var href = typeLookup ? typeLookup[name] : null;
+
+        if (href) {
+          tokens.push('<a href="' + prefix + href + '" class="rbs-type">' + escapeHtml(name) + '</a>');
+        } else {
+          tokens.push('<span class="rbs-type">' + escapeHtml(name) + '</span>');
+        }
+        i = end;
+        continue;
+      }
+
+      // Lowercase identifier — check for builtin keywords
+      if ((ch >= 'a' && ch <= 'z') || ch === '_') {
+        var end = i + 1;
+        while (end < len && isIdentChar(text[end])) end++;
+        var word = text.substring(i, end);
+
+        if (BUILTIN_TYPES.has(word)) {
+          tokens.push('<span class="rbs-builtin">' + escapeHtml(word) + '</span>');
+        } else {
+          tokens.push(escapeHtml(word));
+        }
+        i = end;
+        continue;
+      }
+
+      tokens.push(escapeHtml(ch));
+      i++;
+    }
+
+    return tokens.join('');
+  }
+
+  function initHighlighting() {
+    typeLookup = buildTypeLookup();
+
+    document.querySelectorAll('.method-type-signature code').forEach(function(el) {
+      if (el.getAttribute('data-highlighted') === 'true') return;
+      el.innerHTML = highlightRbs(el.textContent); // eslint-disable-line no-unsanitized/property
+      el.setAttribute('data-highlighted', 'true');
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initHighlighting);
+  } else {
+    initHighlighting();
+  }
+})();

From 2fecc0186063f00d72da6c88ef149cfe34020e69 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Mon, 30 Mar 2026 18:09:36 +0100
Subject: [PATCH 5/9] Add design context to CLAUDE.md

---
 CLAUDE.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 164dc8bcfe..23decc096d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,3 +10,30 @@ Please refer to `AGENTS.md` for comprehensive project documentation, including:
 - CI/CD information
 
 All project-specific instructions and guidelines are maintained in `AGENTS.md`.
+
+## Design Context
+
+**Personality:** Minimal, focused, fast. A well-organized reference tool — never decorative, never in the way.
+
+**References:** Elixir HexDocs, Tailwind CSS v2 docs. **Anti-references:** busy enterprise docs, heavy drop shadows, ornamental borders.
+
+### Design Principles
+
+1. **Types are equal partners** — Type signatures are as important as method names. Immediately visible, not hidden metadata.
+2. **Hierarchy through typography, not decoration** — Font size, weight, color. No badges, pills, or ornamental borders for structural info. Let whitespace do the heavy lifting.
+3. **Code is the content** — Method names, params, and types all use `--font-code`. Don't mix prose typography into code contexts.
+4. **Scan-first design** — Method entries parseable at a glance: name → type → description. Each layer visually distinct.
+5. **Respect the design system** — Use CSS custom properties exclusively. No hardcoded values. Dark mode and themes must work automatically.
+
+### Design Tokens (Aliki Theme)
+
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| `--color-text-primary` | `#1c1917` | `#fafaf9` | Method names, headings |
+| `--color-text-secondary` | `#57534e` | `#e7e5e4` | Type signatures, descriptions |
+| `--color-text-tertiary` | `#78716c` | `#a8a29e` | De-emphasized metadata |
+| `--font-code` | ui-monospace stack | same | All code: names, params, types |
+| `--font-size-lg` | 18px | same | Method headings |
+| `--font-size-sm` | 14px | same | Type signatures |
+| `--font-size-xs` | 12px | same | Metadata, labels |
+| `--space-1` to `--space-6` | 4px–24px | same | All spacing |

From d26eef5c865381735dca7d3038e21cd47fdc4fcc Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Tue, 31 Mar 2026 22:55:39 +0100
Subject: [PATCH 6/9] Display RBS type signatures in ri output

---
 lib/rdoc/ri/driver.rb       |  9 +++++++++
 test/rdoc/ri/driver_test.rb | 14 ++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/lib/rdoc/ri/driver.rb b/lib/rdoc/ri/driver.rb
index 014c5be4fb..670be70783 100644
--- a/lib/rdoc/ri/driver.rb
+++ b/lib/rdoc/ri/driver.rb
@@ -1415,6 +1415,7 @@ def render_method(out, store, method, name) # :nodoc:
     out << RDoc::Markup::Rule.new(1)
 
     render_method_arguments out, method.arglists
+    render_method_type_signature out, method.type_signature
     render_method_superclass out, method
     if method.is_alias_for
       al = method.is_alias_for
@@ -1452,6 +1453,14 @@ def render_method_comment(out, method, alias_for = nil)# :nodoc:
     end
   end
 
+  def render_method_type_signature(out, type_signature) # :nodoc:
+    return unless type_signature
+
+    sigs = type_signature.split("\n").map { |s| s + "\n" }
+    out << RDoc::Markup::Verbatim.new(*sigs)
+    out << RDoc::Markup::BlankLine.new
+  end
+
   def render_method_superclass(out, method) # :nodoc:
     return unless
       method.respond_to?(:superclass_method) and method.superclass_method
diff --git a/test/rdoc/ri/driver_test.rb b/test/rdoc/ri/driver_test.rb
index 2d1a2ce741..ec6a1c8475 100644
--- a/test/rdoc/ri/driver_test.rb
+++ b/test/rdoc/ri/driver_test.rb
@@ -737,6 +737,20 @@ def test_display_method
     assert_match %r%blah.6%,        out
   end
 
+  def test_display_method_with_type_signature
+    util_store
+
+    @blah.type_signature = '(Integer) -> String'
+    @store1.save
+
+    out, = capture_output do
+      @driver.display_method 'Foo::Bar#blah'
+    end
+
+    assert_match %r%Foo::Bar#blah%, out
+    assert_match %r%\(Integer\) -> String%, out
+  end
+
   def test_display_method_attribute
     util_store
 

From 7326f84a372ba998a7b8e30798b21af6103abbba Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Wed, 1 Apr 2026 16:56:32 +0100
Subject: [PATCH 7/9] Improve multi-signature display with stacked code block

---
 lib/rdoc/generator/template/aliki/class.rhtml |  6 +---
 .../generator/template/aliki/css/rdoc.css     | 28 +++++++++++++------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/lib/rdoc/generator/template/aliki/class.rhtml b/lib/rdoc/generator/template/aliki/class.rhtml
index a1d55c282d..02b8e0f12d 100644
--- a/lib/rdoc/generator/template/aliki/class.rhtml
+++ b/lib/rdoc/generator/template/aliki/class.rhtml
@@ -153,11 +153,7 @@
           <%- end %>
 
           <%- if method.type_signature %>
-          <div class="method-type-signature">
-            <%- method.type_signature.split("\n").each do |sig| %>
-            <code><%= h(sig).gsub('-&gt;', '&rarr;') %></code>
-            <%- end %>
-          </div>
+          <pre class="method-type-signature"><code><%= method.type_signature.split("\n").map { |sig| h(sig).gsub('-&gt;', '&rarr;') }.join("\n") %></code></pre>
           <%- end %>
         </div>
 
diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index 6d420705d5..3b92318891 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -1324,25 +1324,35 @@ main .method-heading .method-args {
   font-weight: var(--font-weight-normal);
 }
 
-/* Type signatures — method overloads stack vertically under the name */
-main .method-header .method-type-signature {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-1);
-}
-
-main .method-type-signature code {
+/* Type signatures — overloads stack as a code block under the method name */
+pre.method-type-signature {
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  border: none;
   font-family: var(--font-code);
   font-size: var(--font-size-sm);
-  font-weight: var(--font-weight-normal);
   color: var(--color-text-secondary);
+  line-height: var(--line-height-normal);
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+pre.method-type-signature code {
+  font-family: inherit;
+  font-size: inherit;
+  color: inherit;
   background: transparent;
+  padding: 0;
 }
 
 /* Attribute type sigs render inline after the [RW] badge */
 main .method-heading > .method-type-signature {
   display: inline;
   margin-left: var(--space-2);
+  font-family: var(--font-code);
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
 }
 
 main .method-controls {

From df1587ca66c1b84bb6e048c4dde419307b838127 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Wed, 1 Apr 2026 16:57:03 +0100
Subject: [PATCH 8/9] Load RBS core types automatically

---
 lib/rdoc/generator/template/aliki/js/aliki.js |  2 +-
 lib/rdoc/rbs_support.rb                       |  2 +-
 lib/rdoc/rdoc.rb                              | 10 +++++-----
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/lib/rdoc/generator/template/aliki/js/aliki.js b/lib/rdoc/generator/template/aliki/js/aliki.js
index 7883132b00..2324b311c9 100644
--- a/lib/rdoc/generator/template/aliki/js/aliki.js
+++ b/lib/rdoc/generator/template/aliki/js/aliki.js
@@ -436,7 +436,7 @@ function wrapCodeBlocksWithCopyButton() {
   // - Modifying the formatter would require extending RDoc's core internals
 
   // Find all pre elements that are not already wrapped
-  const preElements = document.querySelectorAll('main pre:not(.code-block-wrapper pre)');
+  const preElements = document.querySelectorAll('main pre:not(.code-block-wrapper pre):not(.method-type-signature)');
 
   preElements.forEach((pre) => {
     // Skip if already wrapped
diff --git a/lib/rdoc/rbs_support.rb b/lib/rdoc/rbs_support.rb
index bc3a989c58..d7a73894f3 100644
--- a/lib/rdoc/rbs_support.rb
+++ b/lib/rdoc/rbs_support.rb
@@ -35,7 +35,7 @@ def self.validate_type(sig)
   # Returns a Hash mapping "ClassName#method_name" => "type sig string".
 
   def self.load_signatures(*dirs)
-    loader = RBS::EnvironmentLoader.new(core_root: nil)
+    loader = RBS::EnvironmentLoader.new
     dirs.each { |dir| loader.add(path: Pathname(dir)) }
 
     env = RBS::Environment.new
diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index 9de808e321..8637916982 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -493,12 +493,12 @@ def document(options)
 
     @store.complete @options.visibility
 
-    # Load RBS signatures from sig/ directory
+    # Load RBS type signatures from core types and sig/ directory
+    sig_dirs = []
     sig_dir = File.join(@options.root.to_s, 'sig')
-    if File.directory?(sig_dir)
-      signatures = RDoc::RbsSupport.load_signatures(sig_dir)
-      RDoc::RbsSupport.merge_into_store(@store, signatures) unless signatures.empty?
-    end
+    sig_dirs << sig_dir if File.directory?(sig_dir)
+    signatures = RDoc::RbsSupport.load_signatures(*sig_dirs)
+    RDoc::RbsSupport.merge_into_store(@store, signatures) unless signatures.empty?
 
     @stats.coverage_level = @options.coverage_report
 

From 9c63b369022dbd5ddaffb4c2aa9f6eaa8fe22c5c Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Wed, 1 Apr 2026 18:29:50 +0100
Subject: [PATCH 9/9] Style linked types with consistent underline

---
 lib/rdoc/generator/template/aliki/css/rdoc.css          | 7 +++++--
 lib/rdoc/generator/template/aliki/js/rbs_highlighter.js | 5 ++++-
 lib/rdoc/parser/prism_ruby.rb                           | 1 -
 lib/rdoc/rbs_support.rb                                 | 9 ++++++---
 4 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index 3b92318891..d7886ae339 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -1076,11 +1076,14 @@ main h6 a:hover {
 .rbs-builtin { color: var(--code-purple); }
 
 a.rbs-type {
-  text-decoration: none;
+  text-decoration: underline;
+  text-decoration-color: var(--color-border-default);
+  text-underline-offset: 0.2em;
+  transition: text-decoration-color var(--transition-fast);
 }
 
 a.rbs-type:hover {
-  text-decoration: underline;
+  text-decoration-color: currentColor;
 }
 
 /* Emphasis */
diff --git a/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js b/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js
index 92ccb32a55..63dd3f07bd 100644
--- a/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js
+++ b/lib/rdoc/generator/template/aliki/js/rbs_highlighter.js
@@ -99,9 +99,12 @@
   }
 
   function initHighlighting() {
+    var elements = document.querySelectorAll('.method-type-signature code');
+    if (elements.length === 0) return;
+
     typeLookup = buildTypeLookup();
 
-    document.querySelectorAll('.method-type-signature code').forEach(function(el) {
+    elements.forEach(function(el) {
       if (el.getAttribute('data-highlighted') === 'true') return;
       el.innerHTML = highlightRbs(el.textContent); // eslint-disable-line no-unsanitized/property
       el.setAttribute('data-highlighted', 'true');
diff --git a/lib/rdoc/parser/prism_ruby.rb b/lib/rdoc/parser/prism_ruby.rb
index 9d97458cab..a281cd7d3e 100644
--- a/lib/rdoc/parser/prism_ruby.rb
+++ b/lib/rdoc/parser/prism_ruby.rb
@@ -486,7 +486,6 @@ def consecutive_comment(line_no)
 
   private def validate_type_signature(sig)
     sig.split("\n").each do |line|
-      # Method types contain ->, plain types (for attributes) don't
       error = if line.include?('->')
         RDoc::RbsSupport.validate_method_type(line)
       else
diff --git a/lib/rdoc/rbs_support.rb b/lib/rdoc/rbs_support.rb
index d7a73894f3..8c139b4d1f 100644
--- a/lib/rdoc/rbs_support.rb
+++ b/lib/rdoc/rbs_support.rb
@@ -74,14 +74,17 @@ def self.merge_into_store(store, signatures)
         next if method.type_signature
 
         key = method.singleton ? "#{cm.full_name}::#{method.name}" : "#{cm.full_name}##{method.name}"
-        method.type_signature = signatures[key] if signatures[key]
+        if (sig = signatures[key])
+          method.type_signature = sig
+        end
       end
 
       cm.attributes.each do |attr|
         next if attr.type_signature
 
-        key = "#{cm.full_name}.#{attr.name}"
-        attr.type_signature = signatures[key] if signatures[key]
+        if (sig = signatures["#{cm.full_name}.#{attr.name}"])
+          attr.type_signature = sig
+        end
       end
     end
   end