html-to-markdown 3.11.4 → 3.12.0

data/lib/html_to_markdown/native.rb

@@ -1,5 +1,4 @@
 # This file is auto-generated by alef — DO NOT EDIT.
-# alef:hash:d679b59088594adaffae8541ddda37761d2ea48733185dc6d5b1a45f82cf2d54
 # To regenerate: alef generate
 # To verify freshness: alef verify
 # frozen_string_literal: true
@@ -18,7 +17,7 @@ library_candidates = dlexts.flat_map do |dlext|
     File.join(__dir__, "..", extension_name, ruby_abi, "#{extension_name}.#{dlext}"),
     File.join(__dir__, "..", extension_name, ruby_abi, "lib#{extension_name}.#{dlext}"),
     File.join(__dir__, "..", "#{extension_name}.#{dlext}"),
-    File.join(__dir__, "..", "lib#{extension_name}.#{dlext}"),
+    File.join(__dir__, "..", "lib#{extension_name}.#{dlext}")
   ]
 end
 
@@ -34,6 +33,7 @@ unless native_extension
 end
 
 require native_extension
+
 module HtmlToMarkdown
   # Re-export public types from the native extension (curated list, excludes Update/Builder types)
   ConversionOptions = HtmlToMarkdownRs.const_get(:ConversionOptions)
@@ -56,13 +56,16 @@ module HtmlToMarkdown
   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) }
+  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.
+  # The type of an inline text annotation.
   #
-  # Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
-  module NodeContent
+  # Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
+  module AnnotationKind
     extend T::Helpers
     extend T::Sig
 
@@ -73,369 +76,382 @@ module HtmlToMarkdown
     # @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"]
+      discriminator = hash[:annotation_type] || hash["annotation_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}"
+      when "bold"
+        AnnotationKindBold.from_hash(hash)
+      when "italic"
+        AnnotationKindItalic.from_hash(hash)
+      when "underline"
+        AnnotationKindUnderline.from_hash(hash)
+      when "strikethrough"
+        AnnotationKindStrikethrough.from_hash(hash)
+      when "code"
+        AnnotationKindCode.from_hash(hash)
+      when "subscript"
+        AnnotationKindSubscript.from_hash(hash)
+      when "superscript"
+        AnnotationKindSuperscript.from_hash(hash)
+      when "highlight"
+        AnnotationKindHighlight.from_hash(hash)
+      when "link"
+        AnnotationKindLink.from_hash(hash)
+      else
+        raise "Unknown discriminator: #{discriminator}"
       end
     end
   end
-  ## A heading element (h1-h6).
-  NodeContentHeading = Data.define(:level, :text) do
-    include NodeContent
+  ## Bold / strong emphasis.
+  AnnotationKindBold = Data.define do
+    include AnnotationKind
     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
+    def bold? = true
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def strikethrough? = 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
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(level: hash[:level] || hash["level"], text: hash[:text] || hash["text"])
+      new
     end
   end
-  ## A paragraph of text.
-  NodeContentParagraph = Data.define(:text) do
-    include NodeContent
+  ## Italic / emphasis.
+  AnnotationKindItalic = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def italic? = true
     sig { returns(T::Boolean) }
-    def table? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def strikethrough? = 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
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(text: hash[:text] || hash["text"])
+      new
     end
   end
-  ## A list container (ordered or unordered). Children are `ListItem` nodes.
-  NodeContentList = Data.define(:ordered) do
-    include NodeContent
+  ## Underline.
+  AnnotationKindUnderline = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def underline? = true
     sig { returns(T::Boolean) }
-    def image? = false
+    def strikethrough? = 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
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(ordered: hash[:ordered] || hash["ordered"])
+      new
     end
   end
-  ## A single list item.
-  NodeContentListItem = Data.define(:text) do
-    include NodeContent
+  ## Strikethrough / deleted text.
+  AnnotationKindStrikethrough = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def list_item? = true
+    def italic? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def strikethrough? = 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
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(text: hash[:text] || hash["text"])
+      new
     end
   end
-  ## A table with structured cell data.
-  NodeContentTable = Data.define(:grid) do
-    include NodeContent
+  ## Inline code.
+  AnnotationKindCode = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def code? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def quote? = false
+    def strikethrough? = false
     sig { returns(T::Boolean) }
-    def definition_list? = false
+    def code? = true
     sig { returns(T::Boolean) }
-    def definition_item? = false
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(grid: hash[:grid] || hash["grid"])
+      new
     end
   end
-  ## An image element.
-  NodeContentImage = Data.define(:description, :src, :image_index) do
-    include NodeContent
+  ## Subscript text.
+  AnnotationKindSubscript = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def image? = true
+    def strikethrough? = 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
+    def subscript? = true
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(description: hash[:description] || hash["description"], src: hash[:src] || hash["src"], image_index: hash[:image_index] || hash["image_index"])
+      new
     end
   end
-  ## A code block or inline code.
-  NodeContentCode = Data.define(:text, :language) do
-    include NodeContent
+  ## Superscript text.
+  AnnotationKindSuperscript = Data.define do
+    include AnnotationKind
     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
+    def bold? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def code? = true
+    def underline? = false
     sig { returns(T::Boolean) }
-    def quote? = false
+    def strikethrough? = false
     sig { returns(T::Boolean) }
-    def definition_list? = false
+    def code? = false
     sig { returns(T::Boolean) }
-    def definition_item? = false
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def superscript? = true
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def highlight? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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(text: hash[:text] || hash["text"], language: hash[:language] || hash["language"])
+      new
     end
   end
-  ## A block quote container.
-  NodeContentQuote = Data.define do
-    include NodeContent
+  ## Highlighted / marked text.
+  AnnotationKindHighlight = Data.define do
+    include AnnotationKind
     extend T::Sig
 
     sig { returns(T::Boolean) }
-    def heading? = false
+    def bold? = false
     sig { returns(T::Boolean) }
-    def paragraph? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def list? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def strikethrough? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def code? = false
     sig { returns(T::Boolean) }
-    def image? = false
+    def subscript? = false
     sig { returns(T::Boolean) }
-    def code? = false
+    def superscript? = false
     sig { returns(T::Boolean) }
-    def quote? = true
+    def highlight? = true
     sig { returns(T::Boolean) }
-    def definition_list? = false
+    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
+
+    # 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) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def url = super
+    # 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)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def title = super
     sig { returns(T::Boolean) }
-    def definition_item? = false
+    def bold? = false
     sig { returns(T::Boolean) }
-    def raw_block? = false
+    def italic? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = false
+    def underline? = false
     sig { returns(T::Boolean) }
-    def group? = false
+    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
+      new(url: hash[:url] || hash["url"], title: hash[:title] || hash["title"])
     end
   end
-  ## A definition list container.
-  NodeContentDefinitionList = Data.define do
+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"
+        NodeContentHeading.from_hash(hash)
+      when "paragraph"
+        NodeContentParagraph.from_hash(hash)
+      when "list"
+        NodeContentList.from_hash(hash)
+      when "list_item"
+        NodeContentListItem.from_hash(hash)
+      when "table"
+        NodeContentTable.from_hash(hash)
+      when "image"
+        NodeContentImage.from_hash(hash)
+      when "code"
+        NodeContentCode.from_hash(hash)
+      when "quote"
+        NodeContentQuote.from_hash(hash)
+      when "definition_list"
+        NodeContentDefinitionList.from_hash(hash)
+      when "definition_item"
+        NodeContentDefinitionItem.from_hash(hash)
+      when "raw_block"
+        NodeContentRawBlock.from_hash(hash)
+      when "metadata_block"
+        NodeContentMetadataBlock.from_hash(hash)
+      when "group"
+        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) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def level = super
+    # The heading text content.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def text = super
     sig { returns(T::Boolean) }
-    def heading? = false
+    def heading? = true
     sig { returns(T::Boolean) }
     def paragraph? = false
     sig { returns(T::Boolean) }
@@ -451,7 +467,7 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def quote? = false
     sig { returns(T::Boolean) }
-    def definition_list? = true
+    def definition_list? = false
     sig { returns(T::Boolean) }
     def definition_item? = false
     sig { returns(T::Boolean) }
@@ -464,24 +480,22 @@ module HtmlToMarkdown
     # @return [self]
     sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
     def self.from_hash(hash)
-      new
+      new(level: hash[:level] || hash["level"], text: hash[:text] || hash["text"])
     end
   end
-  ## A definition list entry with term and description.
-  NodeContentDefinitionItem = Data.define(:term, :definition) do
+  ## A paragraph of text.
+  NodeContentParagraph = Data.define(:text) do
     include NodeContent
     extend T::Sig
 
-    # The term being defined.
-    sig { returns(String) }
-    def term = super # rubocop:disable Lint/UselessMethodDefinition
-    # The definition text.
+    # The paragraph text content.
     sig { returns(String) }
-    def definition = super # rubocop:disable Lint/UselessMethodDefinition
+    # rubocop:disable Lint/UselessMethodDefinition
+    def text = super
     sig { returns(T::Boolean) }
     def heading? = false
     sig { returns(T::Boolean) }
-    def paragraph? = false
+    def paragraph? = true
     sig { returns(T::Boolean) }
     def list? = false
     sig { returns(T::Boolean) }
@@ -497,7 +511,7 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def definition_list? = false
     sig { returns(T::Boolean) }
-    def definition_item? = true
+    def definition_item? = false
     sig { returns(T::Boolean) }
     def raw_block? = false
     sig { returns(T::Boolean) }
@@ -508,26 +522,24 @@ module HtmlToMarkdown
     # @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"])
+      new(text: hash[:text] || hash["text"])
     end
   end
-  ## A raw block preserved as-is (e.g. `<script>`, `<style>` content).
-  NodeContentRawBlock = Data.define(:format, :content) do
+  ## A list container (ordered or unordered). Children are `ListItem` nodes.
+  NodeContentList = Data.define(:ordered) 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
+    # Whether this is an ordered list.
+    sig { returns(T::Boolean) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def ordered = super
     sig { returns(T::Boolean) }
     def heading? = false
     sig { returns(T::Boolean) }
     def paragraph? = false
     sig { returns(T::Boolean) }
-    def list? = false
+    def list? = true
     sig { returns(T::Boolean) }
     def list_item? = false
     sig { returns(T::Boolean) }
@@ -543,7 +555,7 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def definition_item? = false
     sig { returns(T::Boolean) }
-    def raw_block? = true
+    def raw_block? = false
     sig { returns(T::Boolean) }
     def metadata_block? = false
     sig { returns(T::Boolean) }
@@ -552,17 +564,18 @@ module HtmlToMarkdown
     # @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"])
+      new(ordered: hash[:ordered] || hash["ordered"])
     end
   end
-  ## A block of key-value metadata pairs (from `<head>` meta tags).
-  NodeContentMetadataBlock = Data.define(:entries) do
+  ## A single list item.
+  NodeContentListItem = Data.define(:text) do
     include NodeContent
     extend T::Sig
 
-    # Key-value metadata pairs.
-    sig { returns(T::Array[MetadataEntry]) }
-    def entries = super # rubocop:disable Lint/UselessMethodDefinition
+    # The list item text content.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def text = super
     sig { returns(T::Boolean) }
     def heading? = false
     sig { returns(T::Boolean) }
@@ -570,7 +583,7 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def list? = false
     sig { returns(T::Boolean) }
-    def list_item? = false
+    def list_item? = true
     sig { returns(T::Boolean) }
     def table? = false
     sig { returns(T::Boolean) }
@@ -586,30 +599,25 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def raw_block? = false
     sig { returns(T::Boolean) }
-    def metadata_block? = true
+    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(entries: hash[:entries] || hash["entries"])
+      new(text: hash[:text] || hash["text"])
     end
   end
-  ## A section grouping container (auto-generated from heading hierarchy).
-  NodeContentGroup = Data.define(:label, :heading_level, :heading_text) do
+  ## A table with structured cell data.
+  NodeContentTable = Data.define(:grid) 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
+    # The table grid structure.
+    sig { returns(TableGrid) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def grid = super
     sig { returns(T::Boolean) }
     def heading? = false
     sig { returns(T::Boolean) }
@@ -619,7 +627,7 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def list_item? = false
     sig { returns(T::Boolean) }
-    def table? = false
+    def table? = true
     sig { returns(T::Boolean) }
     def image? = false
     sig { returns(T::Boolean) }
@@ -635,159 +643,145 @@ module HtmlToMarkdown
     sig { returns(T::Boolean) }
     def metadata_block? = false
     sig { returns(T::Boolean) }
-    def group? = true
+    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(label: hash[:label] || hash["label"], heading_level: hash[:heading_level] || hash["heading_level"], heading_text: hash[:heading_text] || hash["heading_text"])
-    end
-  end
-end
-
-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
+      new(grid: hash[:grid] || hash["grid"])
     end
   end
-  ## Bold / strong emphasis.
-  AnnotationKindBold = Data.define do
-    include AnnotationKind
+  ## 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)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def description = super
+    # Image source URL.
+    sig { returns(T.nilable(String)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def src = super
+    # Index into `ConversionResult.images` when image extraction is enabled.
+    sig { returns(T.nilable(Integer)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def image_index = super
     sig { returns(T::Boolean) }
-    def bold? = true
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    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 subscript? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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
+      new(
+        description: hash[:description] || hash["description"],
+        src: hash[:src] || hash["src"],
+        image_index: hash[:image_index] || hash["image_index"]
+      )
     end
   end
-  ## Italic / emphasis.
-  AnnotationKindItalic = Data.define do
-    include AnnotationKind
+  ## A code block or inline code.
+  NodeContentCode = Data.define(:text, :language) do
+    include NodeContent
     extend T::Sig
 
+    # The code text content.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def text = super
+    # Programming language (from class="language-*" or similar).
+    sig { returns(T.nilable(String)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def language = super
     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
+    def heading? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def list? = 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
-
+    def list_item? = false
     sig { returns(T::Boolean) }
-    def bold? = false
+    def table? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def image? = false
     sig { returns(T::Boolean) }
-    def underline? = true
+    def code? = true
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def code? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def subscript? = false
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def raw_block? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def metadata_block? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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
+      new(text: hash[:text] || hash["text"], language: hash[:language] || hash["language"])
     end
   end
-  ## Strikethrough / deleted text.
-  AnnotationKindStrikethrough = Data.define do
-    include AnnotationKind
+  ## A block quote container.
+  NodeContentQuote = Data.define do
+    include NodeContent
     extend T::Sig
 
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = true
+    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 subscript? = false
+    def quote? = true
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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) }
@@ -795,29 +789,37 @@ module HtmlToMarkdown
       new
     end
   end
-  ## Inline code.
-  AnnotationKindCode = Data.define do
-    include AnnotationKind
+  ## A definition list container.
+  NodeContentDefinitionList = Data.define do
+    include NodeContent
     extend T::Sig
 
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    def list_item? = false
     sig { returns(T::Boolean) }
-    def code? = true
+    def table? = false
     sig { returns(T::Boolean) }
-    def subscript? = false
+    def image? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def code? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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) }
@@ -825,138 +827,192 @@ module HtmlToMarkdown
       new
     end
   end
-  ## Subscript text.
-  AnnotationKindSubscript = Data.define do
-    include AnnotationKind
+  ## A definition list entry with term and description.
+  NodeContentDefinitionItem = Data.define(:term, :definition) do
+    include NodeContent
     extend T::Sig
 
+    # The term being defined.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def term = super
+    # The definition text.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def definition = super
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    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 subscript? = true
+    def quote? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def definition_item? = true
     sig { returns(T::Boolean) }
-    def link? = false
+    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
+      new(term: hash[:term] || hash["term"], definition: hash[:definition] || hash["definition"])
     end
   end
-  ## Superscript text.
-  AnnotationKindSuperscript = Data.define do
-    include AnnotationKind
+  ## 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) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def format = super
+    # The raw content.
+    sig { returns(String) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def content = super
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    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 subscript? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def superscript? = true
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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
+      new(format: hash[:format] || hash["format"], content: hash[:content] || hash["content"])
     end
   end
-  ## Highlighted / marked text.
-  AnnotationKindHighlight = Data.define do
-    include AnnotationKind
+  ## 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]) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def entries = super
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    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 subscript? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = true
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def link? = false
+    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
+      new(entries: hash[:entries] || hash["entries"])
     end
   end
-  ## A hyperlink sourced from an `<a href="...">` element.
-  AnnotationKindLink = Data.define(:url, :title) do
-    include AnnotationKind
+  ## A section grouping container (auto-generated from heading hierarchy).
+  NodeContentGroup = Data.define(:label, :heading_level, :heading_text) do
+    include NodeContent
     extend T::Sig
 
-    # 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.
+    # Optional section label.
+    sig { returns(T.nilable(String)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def label = super
+    # The heading level that created this group.
+    sig { returns(T.nilable(Integer)) }
+    # rubocop:disable Lint/UselessMethodDefinition
+    def heading_level = super
+    # The heading text that created this group.
     sig { returns(T.nilable(String)) }
-    def title = super # rubocop:disable Lint/UselessMethodDefinition
+    # rubocop:disable Lint/UselessMethodDefinition
+    def heading_text = super
     sig { returns(T::Boolean) }
-    def bold? = false
+    def heading? = false
     sig { returns(T::Boolean) }
-    def italic? = false
+    def paragraph? = false
     sig { returns(T::Boolean) }
-    def underline? = false
+    def list? = false
     sig { returns(T::Boolean) }
-    def strikethrough? = false
+    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 subscript? = false
+    def quote? = false
     sig { returns(T::Boolean) }
-    def superscript? = false
+    def definition_list? = false
     sig { returns(T::Boolean) }
-    def highlight? = false
+    def definition_item? = false
     sig { returns(T::Boolean) }
-    def link? = true
+    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(url: hash[:url] || hash["url"], title: hash[:title] || hash["title"])
+      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
@@ -980,12 +1036,18 @@ module HtmlToMarkdown
     def self.from_hash(hash)
       discriminator = hash[:type] || hash["type"]
       case discriminator
-      when "continue" then VisitResultContinue.from_hash(hash)
-      when "custom" then VisitResultCustom.from_hash(hash)
-      when "skip" then VisitResultSkip.from_hash(hash)
-      when "preserve_html" then VisitResultPreserveHtml.from_hash(hash)
-      when "error" then VisitResultError.from_hash(hash)
-      else raise "Unknown discriminator: #{discriminator}"
+      when "continue"
+        VisitResultContinue.from_hash(hash)
+      when "custom"
+        VisitResultCustom.from_hash(hash)
+      when "skip"
+        VisitResultSkip.from_hash(hash)
+      when "preserve_html"
+        VisitResultPreserveHtml.from_hash(hash)
+      when "error"
+        VisitResultError.from_hash(hash)
+      else
+        raise "Unknown discriminator: #{discriminator}"
       end
     end
   end
@@ -1021,7 +1083,8 @@ module HtmlToMarkdown
 
     # @return [String]
     sig { returns(String) }
-    def value = super # rubocop:disable Lint/UselessMethodDefinition
+    # rubocop:disable Lint/UselessMethodDefinition
+    def value = super
     sig { returns(T::Boolean) }
     def continue? = false
     sig { returns(T::Boolean) }
@@ -1096,7 +1159,8 @@ module HtmlToMarkdown
 
     # @return [String]
     sig { returns(String) }
-    def value = super # rubocop:disable Lint/UselessMethodDefinition
+    # rubocop:disable Lint/UselessMethodDefinition
+    def value = super
     sig { returns(T::Boolean) }
     def continue? = false
     sig { returns(T::Boolean) }