Extract and display RBS type signatures in documentation

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).

Author: st0012

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 |

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)

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
 

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
 
   ##

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

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 %>

lib/rdoc/generator/template/aliki/css/rdoc.css

@@ -1075,6 +1075,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);
@@ -1334,6 +1346,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 {
   position: absolute;
   top: var(--space-3);

lib/rdoc/generator/template/aliki/js/rbs_highlighter.js

@@ -0,0 +1,106 @@
+/**
+ * Client-side RBS type signature linker for RDoc
+ *
+ * Links type names in RBS annotations 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 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;
+        var short = entry.name;
+        if (!lookup[short]) lookup[short] = entry.path;
+      }
+    });
+    return lookup;
+  }
+
+  function escapeHtml(text) {
+    return text
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  function isIdentChar(ch) {
+    return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+           (ch >= '0' && ch <= '9') || ch === '_';
+  }
+
+  function linkTypes(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++;
+        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(escapeHtml(name));
+        }
+        i = end;
+        continue;
+      }
+
+      // Any other identifier — pass through
+      if ((ch >= 'a' && ch <= 'z') || ch === '_') {
+        var end = i + 1;
+        while (end < len && isIdentChar(text[end])) end++;
+        tokens.push(escapeHtml(text.substring(i, end)));
+        i = end;
+        continue;
+      }
+
+      tokens.push(escapeHtml(ch));
+      i++;
+    }
+
+    return tokens.join('');
+  }
+
+  function initLinking() {
+    var elements = document.querySelectorAll('.method-type-signature code');
+    if (elements.length === 0) return;
+
+    typeLookup = buildTypeLookup();
+
+    elements.forEach(function(el) {
+      if (el.getAttribute('data-linked') === 'true') return;
+      el.innerHTML = linkTypes(el.textContent); // eslint-disable-line no-unsanitized/property
+      el.setAttribute('data-linked', 'true');
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initLinking);
+  } else {
+    initLinking();
+  }
+})();

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,14 +626,15 @@ 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
 
     names.each do |symbol|
       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|