html-to-markdown 3.4.0 → 3.6.0.pre.rc.23

data/lib/html_to_markdown/native.rb

@@ -1,59 +1,935 @@
 # This file is auto-generated by alef — DO NOT EDIT.
-# alef:hash:b54e7bb2ab55cc6c25c9cac0e62ec66c35fd2d1956ef9ba5e3dc9e7ba5e666a5
+# alef:hash:fbc32dea2062047854006aa7a5d861ef8fc29be3d8b519a3e56646eb14f1b2e9
 # To regenerate: alef generate
 # To verify freshness: alef verify --exit-code
-# Issues & docs: https://github.com/kreuzberg-dev/alef
 # frozen_string_literal: true
 
-require 'json'
-require 'html_to_markdown_rb'
+require "json"
+require "sorbet-runtime"
+require "html_to_markdown_rb"
 module HtmlToMarkdown
-  # Re-export all public module functions from the native extension
-  HtmlToMarkdownRs.methods(false).each do |m|
-    define_singleton_method(m) { |*args, **kwargs, &blk| HtmlToMarkdownRs.public_send(m, *args, **kwargs, &blk) }
+  # Re-export public types from the native extension (curated list, excludes Update/Builder types)
+  ConversionOptions = HtmlToMarkdownRs.const_get(:ConversionOptions)
+  ConversionResult = HtmlToMarkdownRs.const_get(:ConversionResult)
+  DocumentMetadata = HtmlToMarkdownRs.const_get(:DocumentMetadata)
+  DocumentNode = HtmlToMarkdownRs.const_get(:DocumentNode)
+  DocumentStructure = HtmlToMarkdownRs.const_get(:DocumentStructure)
+  GridCell = HtmlToMarkdownRs.const_get(:GridCell)
+  HeaderMetadata = HtmlToMarkdownRs.const_get(:HeaderMetadata)
+  HtmlMetadata = HtmlToMarkdownRs.const_get(:HtmlMetadata)
+  ImageDimensions = HtmlToMarkdownRs.const_get(:ImageDimensions)
+  ImageMetadata = HtmlToMarkdownRs.const_get(:ImageMetadata)
+  LinkMetadata = HtmlToMarkdownRs.const_get(:LinkMetadata)
+  MetadataEntry = HtmlToMarkdownRs.const_get(:MetadataEntry)
+  NodeContext = HtmlToMarkdownRs.const_get(:NodeContext)
+  PreprocessingOptions = HtmlToMarkdownRs.const_get(:PreprocessingOptions)
+  ProcessingWarning = HtmlToMarkdownRs.const_get(:ProcessingWarning)
+  StructuredData = HtmlToMarkdownRs.const_get(:StructuredData)
+  TableData = HtmlToMarkdownRs.const_get(:TableData)
+  TableGrid = HtmlToMarkdownRs.const_get(:TableGrid)
+  TextAnnotation = HtmlToMarkdownRs.const_get(:TextAnnotation)
+  # Re-export public module functions from the native extension (curated list)
+  define_singleton_method(:convert) { |*args, **kwargs, &blk| HtmlToMarkdownRs.public_send(:convert, *args, **kwargs, &blk) }
+end
+module HtmlToMarkdown
+  # The semantic content type of a document node.
+  #
+  # Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
+  module NodeContent
+    extend T::Helpers
+    extend T::Sig
+
+    interface!
+
+    # Dispatch from a Hash to the appropriate variant constructor.
+    # @param hash [Hash] with discriminator field and variant-specific fields
+    # @return [variant_class] an instance of the appropriate variant
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.untyped) }
+    def self.from_hash(hash)
+      discriminator = hash[:node_type] || hash["node_type"]
+      case discriminator
+      when "heading" then NodeContentHeading.from_hash(hash)
+      when "paragraph" then NodeContentParagraph.from_hash(hash)
+      when "list" then NodeContentList.from_hash(hash)
+      when "list_item" then NodeContentListItem.from_hash(hash)
+      when "table" then NodeContentTable.from_hash(hash)
+      when "image" then NodeContentImage.from_hash(hash)
+      when "code" then NodeContentCode.from_hash(hash)
+      when "quote" then NodeContentQuote.from_hash(hash)
+      when "definition_list" then NodeContentDefinitionList.from_hash(hash)
+      when "definition_item" then NodeContentDefinitionItem.from_hash(hash)
+      when "raw_block" then NodeContentRawBlock.from_hash(hash)
+      when "metadata_block" then NodeContentMetadataBlock.from_hash(hash)
+      when "group" then NodeContentGroup.from_hash(hash)
+      else raise "Unknown discriminator: #{discriminator}"
+      end
+    end
+  end
+  ## A heading element (h1-h6).
+  NodeContentHeading = Data.define(:level, :text) do
+    include NodeContent
+    extend T::Sig
+
+    # Heading level (1-6).
+    sig { returns(Integer) }
+    def level = super # rubocop:disable Lint/UselessMethodDefinition
+    # The heading text content.
+    sig { returns(String) }
+    def text = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = true
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(level: hash[:level] || hash["level"], text: hash[:text] || hash["text"])
+    end
+  end
+  ## A paragraph of text.
+  NodeContentParagraph = Data.define(:text) do
+    include NodeContent
+    extend T::Sig
+
+    # The paragraph text content.
+    sig { returns(String) }
+    def text = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = true
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(text: hash[:text] || hash["text"])
+    end
+  end
+  ## A list container (ordered or unordered). Children are `ListItem` nodes.
+  NodeContentList = Data.define(:ordered) do
+    include NodeContent
+    extend T::Sig
+
+    # Whether this is an ordered list.
+    sig { returns(T::Boolean) }
+    def ordered = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = true
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(ordered: hash[:ordered] || hash["ordered"])
+    end
+  end
+  ## A single list item.
+  NodeContentListItem = Data.define(:text) do
+    include NodeContent
+    extend T::Sig
+
+    # The list item text content.
+    sig { returns(String) }
+    def text = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = true
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(text: hash[:text] || hash["text"])
+    end
+  end
+  ## A table with structured cell data.
+  NodeContentTable = Data.define(:grid) do
+    include NodeContent
+    extend T::Sig
+
+    # The table grid structure.
+    sig { returns(TableGrid) }
+    def grid = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = true
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(grid: hash[:grid] || hash["grid"])
+    end
+  end
+  ## An image element.
+  NodeContentImage = Data.define(:description, :src, :image_index) do
+    include NodeContent
+    extend T::Sig
+
+    # Alt text or caption.
+    sig { returns(T.nilable(String)) }
+    def description = super # rubocop:disable Lint/UselessMethodDefinition
+    # Image source URL.
+    sig { returns(T.nilable(String)) }
+    def src = super # rubocop:disable Lint/UselessMethodDefinition
+    # Index into `ConversionResult.images` when image extraction is enabled.
+    sig { returns(T.nilable(Integer)) }
+    def image_index = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = true
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(description: hash[:description] || hash["description"], src: hash[:src] || hash["src"], image_index: hash[:image_index] || hash["image_index"])
+    end
+  end
+  ## A code block or inline code.
+  NodeContentCode = Data.define(:text, :language) do
+    include NodeContent
+    extend T::Sig
+
+    # The code text content.
+    sig { returns(String) }
+    def text = super # rubocop:disable Lint/UselessMethodDefinition
+    # Programming language (from class="language-*" or similar).
+    sig { returns(T.nilable(String)) }
+    def language = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = true
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(text: hash[:text] || hash["text"], language: hash[:language] || hash["language"])
+    end
+  end
+  ## A block quote container.
+  NodeContentQuote = Data.define do
+    include NodeContent
+    extend T::Sig
+
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = true
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## A definition list container.
+  NodeContentDefinitionList = Data.define do
+    include NodeContent
+    extend T::Sig
+
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = true
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
   end
+  ## A definition list entry with term and description.
+  NodeContentDefinitionItem = Data.define(:term, :definition) do
+    include NodeContent
+    extend T::Sig
 
-  # Re-export all constants (classes, structs, etc.) from the native extension
-  HtmlToMarkdownRs.constants.each do |c|
-    const_set(c, HtmlToMarkdownRs.const_get(c)) unless const_defined?(c)
+    # The term being defined.
+    sig { returns(String) }
+    def term = super # rubocop:disable Lint/UselessMethodDefinition
+    # The definition text.
+    sig { returns(String) }
+    def definition = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = true
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(term: hash[:term] || hash["term"], definition: hash[:definition] || hash["definition"])
+    end
+  end
+  ## A raw block preserved as-is (e.g. `<script>`, `<style>` content).
+  NodeContentRawBlock = Data.define(:format, :content) do
+    include NodeContent
+    extend T::Sig
+
+    # The format of the raw content (e.g. "html", "css", "javascript").
+    sig { returns(String) }
+    def format = super # rubocop:disable Lint/UselessMethodDefinition
+    # The raw content.
+    sig { returns(String) }
+    def content = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = true
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(format: hash[:format] || hash["format"], content: hash[:content] || hash["content"])
+    end
+  end
+  ## A block of key-value metadata pairs (from `<head>` meta tags).
+  NodeContentMetadataBlock = Data.define(:entries) do
+    include NodeContent
+    extend T::Sig
+
+    # Key-value metadata pairs.
+    sig { returns(T::Array[MetadataEntry]) }
+    def entries = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = true
+    sig { returns(T::Boolean) }
+    def group? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(entries: hash[:entries] || hash["entries"])
+    end
+  end
+  ## A section grouping container (auto-generated from heading hierarchy).
+  NodeContentGroup = Data.define(:label, :heading_level, :heading_text) do
+    include NodeContent
+    extend T::Sig
+
+    # Optional section label.
+    sig { returns(T.nilable(String)) }
+    def label = super # rubocop:disable Lint/UselessMethodDefinition
+    # The heading level that created this group.
+    sig { returns(T.nilable(Integer)) }
+    def heading_level = super # rubocop:disable Lint/UselessMethodDefinition
+    # The heading text that created this group.
+    sig { returns(T.nilable(String)) }
+    def heading_text = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def heading? = false
+    sig { returns(T::Boolean) }
+    def paragraph? = false
+    sig { returns(T::Boolean) }
+    def list? = false
+    sig { returns(T::Boolean) }
+    def list_item? = false
+    sig { returns(T::Boolean) }
+    def table? = false
+    sig { returns(T::Boolean) }
+    def image? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def quote? = false
+    sig { returns(T::Boolean) }
+    def definition_list? = false
+    sig { returns(T::Boolean) }
+    def definition_item? = false
+    sig { returns(T::Boolean) }
+    def raw_block? = false
+    sig { returns(T::Boolean) }
+    def metadata_block? = false
+    sig { returns(T::Boolean) }
+    def group? = true
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(label: hash[:label] || hash["label"], heading_level: hash[:heading_level] || hash["heading_level"], heading_text: hash[:heading_text] || hash["heading_text"])
+    end
   end
 end
 
-# Add accessor methods to Hash-based internally-tagged enum instances
-class Hash
-  # Support internally-tagged enum accessors like format.excel, format.email, etc.
-  # Also support direct field access like format.sheet_count
-  # rubocop:disable Metrics/CyclomaticComplexity
-  def method_missing(method_name, *args, &block)
-    # Try symbol key first (how Magnus converts JSON keys)
-    return self[method_name] if key?(method_name)
+module HtmlToMarkdown
+  # The type of an inline text annotation.
+  #
+  # Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
+  module AnnotationKind
+    extend T::Helpers
+    extend T::Sig
+
+    interface!
+
+    # Dispatch from a Hash to the appropriate variant constructor.
+    # @param hash [Hash] with discriminator field and variant-specific fields
+    # @return [variant_class] an instance of the appropriate variant
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.untyped) }
+    def self.from_hash(hash)
+      discriminator = hash[:annotation_type] || hash["annotation_type"]
+      case discriminator
+      when "bold" then AnnotationKindBold.from_hash(hash)
+      when "italic" then AnnotationKindItalic.from_hash(hash)
+      when "underline" then AnnotationKindUnderline.from_hash(hash)
+      when "strikethrough" then AnnotationKindStrikethrough.from_hash(hash)
+      when "code" then AnnotationKindCode.from_hash(hash)
+      when "subscript" then AnnotationKindSubscript.from_hash(hash)
+      when "superscript" then AnnotationKindSuperscript.from_hash(hash)
+      when "highlight" then AnnotationKindHighlight.from_hash(hash)
+      when "link" then AnnotationKindLink.from_hash(hash)
+      else raise "Unknown discriminator: #{discriminator}"
+      end
+    end
+  end
+  ## Bold / strong emphasis.
+  AnnotationKindBold = Data.define do
+    include AnnotationKind
+    extend T::Sig
+
+    sig { returns(T::Boolean) }
+    def bold? = true
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## Italic / emphasis.
+  AnnotationKindItalic = Data.define do
+    include AnnotationKind
+    extend T::Sig
+
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = true
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## Underline.
+  AnnotationKindUnderline = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-    # Try string key
-    return self[method_name.to_s] if key?(method_name.to_s)
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = true
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## Strikethrough / deleted text.
+  AnnotationKindStrikethrough = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-    # Check if this hash has a 'format_type' field (indicating an internally-tagged enum)
-    format_type = self[:'format_type'] || self['format_type']
-    return super unless format_type
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = true
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## Inline code.
+  AnnotationKindCode = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-    # If the method name matches the format_type (snake_case), extract and return the variant's wrapped data
-    # Internally-tagged enums store variant data in the '_0' field (from alef's struct variant conversion)
-    # This allows format.excel to return the ExcelMetadata hash with sheet_count, sheet_names, etc.
-    snake_case_method = method_name.to_s.downcase
-    if snake_case_method == format_type.to_s.downcase
-      return self[:'_0'] || self['_0'] || self
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = true
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
     end
+  end
+  ## Subscript text.
+  AnnotationKindSubscript = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-    super
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = true
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
   end
-  # rubocop:enable Metrics/CyclomaticComplexity
+  ## Superscript text.
+  AnnotationKindSuperscript = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-  def respond_to_missing?(method_name, include_private = false)
-    return true if key?(method_name) || key?(method_name.to_s)
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = true
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## Highlighted / marked text.
+  AnnotationKindHighlight = Data.define do
+    include AnnotationKind
+    extend T::Sig
 
-    format_type = self[:'format_type'] || self['format_type']
-    return false unless format_type
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = true
+    sig { returns(T::Boolean) }
+    def link? = false
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new
+    end
+  end
+  ## A hyperlink sourced from an `<a href="...">` element.
+  AnnotationKindLink = Data.define(:url, :title) do
+    include AnnotationKind
+    extend T::Sig
 
-    snake_case_method = method_name.to_s.downcase
-    snake_case_method == format_type.to_s.downcase || super
+    # The URL from the `href` attribute, copied verbatim from the source HTML.
+    #
+    # No URL decoding or normalization is performed: percent-encoded sequences, relative
+    # paths, and protocol-relative URLs (`//example.com`) are all preserved exactly as
+    # written in the source. Callers that need an absolute URL must resolve it against the
+    # document base URL themselves.
+    sig { returns(String) }
+    def url = super # rubocop:disable Lint/UselessMethodDefinition
+    # The `title` attribute of the `<a>` element, if present.
+    #
+    # `None` when the `<a>` tag has no `title="..."` attribute. When present, the value
+    # is copied verbatim — HTML entities within the title are not decoded.
+    sig { returns(T.nilable(String)) }
+    def title = super # rubocop:disable Lint/UselessMethodDefinition
+    sig { returns(T::Boolean) }
+    def bold? = false
+    sig { returns(T::Boolean) }
+    def italic? = false
+    sig { returns(T::Boolean) }
+    def underline? = false
+    sig { returns(T::Boolean) }
+    def strikethrough? = false
+    sig { returns(T::Boolean) }
+    def code? = false
+    sig { returns(T::Boolean) }
+    def subscript? = false
+    sig { returns(T::Boolean) }
+    def superscript? = false
+    sig { returns(T::Boolean) }
+    def highlight? = false
+    sig { returns(T::Boolean) }
+    def link? = true
+    # @param hash [Hash] deserialized from the native extension
+    # @return [self]
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash)
+      new(url: hash[:url] || hash["url"], title: hash[:title] || hash["title"])
+    end
   end
 end