@kreuzberg/html-to-markdown-node 3.4.0 → 3.5.0-rc.1

package/index.d.ts

@@ -1,250 +1,553 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
-export declare class JsConversionOptionsBuilder {
-  stripTags(tags: Array<string>): JsConversionOptionsBuilder
-  preserveTags(tags: Array<string>): JsConversionOptionsBuilder
-  keepInlineImagesIn(tags: Array<string>): JsConversionOptionsBuilder
-  excludeSelectors(selectors: Array<string>): JsConversionOptionsBuilder
-  preprocessing(preprocessing: JsPreprocessingOptions): JsConversionOptionsBuilder
-  build(): JsConversionOptions
-}
-
-export declare class JsVisitorHandle {
-
-}
-
-export declare function convert(html: string, options?: JsConversionOptions | undefined | null): JsConversionResult
-
-export interface JsAnnotationKind {
+/**
+ * Shareable, thread-safe handle to a user-provided HTML visitor implementation.
+ *
+ * Pass an instance wrapped in this handle to `ConversionOptions` to
+ * customise how the HTML document is traversed and converted to Markdown.
+ * The handle may be cloned and shared across threads without additional
+ * synchronisation on the caller's side.
+ */
+export declare class VisitorHandle {
+
+}
+export type JsVisitorHandle = VisitorHandle
+
+/**
+ * The type of an inline text annotation.
+ *
+ * Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
+ */
+export interface AnnotationKind {
   annotation_type: string
   url?: string
   title?: string
 }
 
-export declare const enum JsCodeBlockStyle {
+/**
+ * Code block fence style in Markdown output.
+ *
+ * Determines how code blocks (`<pre><code>`) are rendered in Markdown.
+ */
+export declare const enum CodeBlockStyle {
+  /** Indented code blocks (4 spaces). `CommonMark` standard. */
   Indented = 'Indented',
+  /** Fenced code blocks with backticks (```). Default (GFM). Supports language hints. */
   Backticks = 'Backticks',
+  /** Fenced code blocks with tildes (~~~). Supports language hints. */
   Tildes = 'Tildes'
 }
 
-export interface JsConversionOptions {
+/**
+ * Main conversion options for HTML to Markdown conversion.
+ *
+ * Use `ConversionOptions.builder()` to construct, or `Default.default()` for defaults.
+ *
+ * # Example
+ */
+export interface ConversionOptions {
+  /** Heading style to use in Markdown output (ATX `#` or Setext underline). */
   headingStyle?: JsHeadingStyle
+  /** How to indent nested list items (spaces or tab). */
   listIndentType?: JsListIndentType
+  /** Number of spaces (or tabs) to use for each level of list indentation. */
   listIndentWidth?: number
+  /** Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). */
   bullets?: string
+  /** Character used for bold/italic emphasis markers (`*` or `_`). */
   strongEmSymbol?: string
+  /** Escape `*` characters in plain text to avoid unintended bold/italic. */
   escapeAsterisks?: boolean
+  /** Escape `_` characters in plain text to avoid unintended bold/italic. */
   escapeUnderscores?: boolean
+  /** Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. */
   escapeMisc?: boolean
+  /** Escape ASCII characters that have special meaning in certain Markdown dialects. */
   escapeAscii?: boolean
+  /** Default language annotation for fenced code blocks that have no language hint. */
   codeLanguage?: string
+  /** Automatically convert bare URLs into Markdown autolinks. */
   autolinks?: boolean
+  /** Emit a default title when no `<title>` tag is present. */
   defaultTitle?: boolean
+  /** Render `<br>` elements inside table cells as literal line breaks. */
   brInTables?: boolean
+  /**
+   * Emit tables without column padding (compact GFM format).
+   *
+   * When `true`, column widths are not computed and cells are emitted with
+   * no trailing spaces. Separator rows use exactly `---` per column.
+   * Produces token-efficient output suitable for RAG / LLM contexts.
+   *
+   * Default `false` (aligned padding preserved).
+   */
+  compactTables?: boolean
+  /** Style used for `<mark>` / highlighted text (e.g. `==text==`). */
   highlightStyle?: JsHighlightStyle
+  /**
+   * Populate `result.metadata` with `<head>` / `<meta>` extraction
+   * (title, description, Open Graph, Twitter Card, JSON-LD, …).
+   *
+   * Default `true`. Disabling skips the metadata pass only — table
+   * extraction into `result.tables` runs unconditionally.
+   */
   extractMetadata?: boolean
+  /**
+   * Controls how whitespace sequences are normalised in the converted output.
+   *
+   * - [`WhitespaceMode::Normalized`] (default) — collapses consecutive whitespace characters
+   *   (spaces, tabs, newlines) to a single space, matching browser rendering behaviour.
+   * - [`WhitespaceMode::Strict`] — preserves all whitespace exactly as it appears in the
+   *   source HTML, including runs of spaces and embedded newlines.
+   *
+   * Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted
+   * content outside `<pre>` tags). For most documents `Normalized` produces cleaner output.
+   */
   whitespaceMode?: JsWhitespaceMode
+  /** Strip all newlines from the output, producing a single-line result. */
   stripNewlines?: boolean
+  /** Wrap long lines at [`wrap_width`](Self::wrap_width) characters. */
   wrap?: boolean
+  /**
+   * Maximum output line width in characters when [`wrap`](Self::wrap) is `true` (default `80`).
+   *
+   * Lines are broken at word boundaries so that no line exceeds this length. A value of `0`
+   * is treated as "no limit" — equivalent to leaving [`wrap`](Self::wrap) disabled. Has no
+   * effect when `wrap` is `false`.
+   */
   wrapWidth?: number
+  /** Treat the entire document as inline content (no block-level wrappers). */
   convertAsInline?: boolean
+  /** Markdown notation for subscript text (e.g. `"~"`). */
   subSymbol?: string
+  /** Markdown notation for superscript text (e.g. `"^"`). */
   supSymbol?: string
+  /** How to encode hard line breaks (`<br>`) in Markdown. */
   newlineStyle?: JsNewlineStyle
+  /** Style used for fenced code blocks (backticks or tilde). */
   codeBlockStyle?: JsCodeBlockStyle
+  /** HTML tag names whose `<img>` children are kept inline instead of block. */
   keepInlineImagesIn?: Array<string>
+  /**
+   * Options for the HTML pre-processing pass applied before conversion begins.
+   *
+   * Pre-processing runs before the HTML is handed to the converter and can perform operations
+   * such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising
+   * vendor-specific markup. See [`PreprocessingOptions`] for the full set of knobs.
+   *
+   * Defaults to [`PreprocessingOptions::default()`], which enables the standard cleaning
+   * passes. Set individual fields on [`PreprocessingOptions`] (or construct via
+   * [`ConversionOptions::builder`]) to opt in or out of specific passes.
+   */
   preprocessing?: JsPreprocessingOptions
+  /** Expected character encoding of the input HTML (default `"utf-8"`). */
   encoding?: string
+  /** Emit debug information during conversion. */
   debug?: boolean
+  /** HTML tag names whose content is stripped from the output entirely. */
   stripTags?: Array<string>
+  /** HTML tag names that are preserved verbatim in the output. */
   preserveTags?: Array<string>
+  /** Skip conversion of `<img>` elements (omit images from output). */
   skipImages?: boolean
+  /** Link rendering style (inline or reference). */
   linkStyle?: JsLinkStyle
+  /** Target output format (Markdown, plain text, etc.). */
   outputFormat?: JsOutputFormat
+  /** Include structured document tree in result. */
   includeDocumentStructure?: boolean
+  /** Extract inline images from data URIs and SVGs. */
   extractImages?: boolean
+  /** Maximum decoded image size in bytes (default 5MB). */
   maxImageSize?: number
+  /** Capture SVG elements as images. */
   captureSvg?: boolean
+  /** Infer image dimensions from data. */
   inferDimensions?: boolean
+  /**
+   * Maximum DOM traversal depth. `None` means unlimited.
+   * When set, subtrees beyond this depth are silently truncated.
+   */
   maxDepth?: number
+  /**
+   * CSS selectors for elements to exclude entirely (element + all content).
+   *
+   * Unlike `strip_tags` (which removes the tag wrapper but keeps children),
+   * excluded elements and all their descendants are dropped from the output.
+   * Supports any CSS selector that `tl` supports: tag names, `.class`,
+   * `#id`, `[attribute]`, etc.
+   *
+   * Invalid selectors are silently skipped at conversion time.
+   *
+   * Example: `vec![".cookie-banner".into(), "#ad-container".into(), "[role='complementary']".into()]`
+   */
   excludeSelectors?: Array<string>
+  /**
+   * Optional visitor for custom traversal logic.
+   *
+   * When set, the visitor's callbacks are invoked for matching HTML elements
+   * during conversion, allowing custom output, skipping, or HTML preservation.
+   * See `HtmlVisitor`.
+   */
   visitor?: object
 }
 
-export interface JsConversionOptionsUpdate {
-  headingStyle?: JsHeadingStyle
-  listIndentType?: JsListIndentType
-  listIndentWidth?: number
-  bullets?: string
-  strongEmSymbol?: string
-  escapeAsterisks?: boolean
-  escapeUnderscores?: boolean
-  escapeMisc?: boolean
-  escapeAscii?: boolean
-  codeLanguage?: string
-  autolinks?: boolean
-  defaultTitle?: boolean
-  brInTables?: boolean
-  highlightStyle?: JsHighlightStyle
-  extractMetadata?: boolean
-  whitespaceMode?: JsWhitespaceMode
-  stripNewlines?: boolean
-  wrap?: boolean
-  wrapWidth?: number
-  convertAsInline?: boolean
-  subSymbol?: string
-  supSymbol?: string
-  newlineStyle?: JsNewlineStyle
-  codeBlockStyle?: JsCodeBlockStyle
-  keepInlineImagesIn?: Array<string>
-  preprocessing?: JsPreprocessingOptionsUpdate
-  encoding?: string
-  debug?: boolean
-  stripTags?: Array<string>
-  preserveTags?: Array<string>
-  skipImages?: boolean
-  linkStyle?: JsLinkStyle
-  outputFormat?: JsOutputFormat
-  includeDocumentStructure?: boolean
-  extractImages?: boolean
-  maxImageSize?: number
-  captureSvg?: boolean
-  inferDimensions?: boolean
-  maxDepth?: number
-  excludeSelectors?: Array<string>
-  visitor?: object
-}
-
-export interface JsConversionResult {
+export declare function conversionOptionsDefault(): ConversionOptions
+
+/**
+ * The primary result of HTML conversion and extraction.
+ *
+ * Contains the converted text output, optional structured document tree,
+ * metadata, extracted tables, images, and processing warnings.
+ *
+ * # Example
+ *
+ * ```text
+ * use html_to_markdown_rs::{convert, ConversionOptions};
+ *
+ * let result = convert("<h1>Hello</h1><p>World</p>", None)?;
+ * assert!(result.content.is_some());
+ * assert!(result.warnings.is_empty());
+ * ```
+ */
+export interface ConversionResult {
+  /**
+   * Converted text output (markdown, djot, or plain text).
+   *
+   * `None` when `output_format` is set to `OutputFormat::None`,
+   * indicating extraction-only mode.
+   */
   content?: string
-  document?: JsDocumentStructure
-  metadata?: JsHtmlMetadata
+  /**
+   * Structured document tree with semantic elements.
+   *
+   * Populated when `ConversionOptions::include_document_structure` is `true`. `None`
+   * otherwise (the default), which avoids the overhead of building the tree.
+   *
+   * When present, the tree mirrors the converted document: headings open
+   * `Group` sections, paragraphs and list items carry
+   * inline `TextAnnotation`s, and tables reference the same
+   * `TableGrid` data exposed in [`Self::tables`].
+   *
+   * Note: this field is independent of the `metadata` feature flag. Document structure
+   * collection is always available at runtime; it is gated only by the runtime option, not
+   * by a compile-time feature.
+   */
+  document?: DocumentStructure
+  /** Extracted HTML metadata (title, OG, links, images, structured data). */
+  metadata?: HtmlMetadata
+  /** Extracted tables with structured cell data and markdown representation. */
   tables?: Array<JsTableData>
+  /**
+   * Extracted inline images (data URIs and SVGs).
+   *
+   * Populated when `extract_images` is `true` in options.
+   */
   images?: Array<string>
+  /** Non-fatal processing warnings. */
   warnings?: Array<JsProcessingWarning>
 }
 
-export interface JsDocumentMetadata {
+export declare function convert(html: string, options?: ConversionOptions | undefined | null, visitor?: object | undefined | null): ConversionResult
+
+/**
+ * Document-level metadata extracted from `<head>` and top-level elements.
+ *
+ * Contains all metadata typically used by search engines, social media platforms,
+ * and browsers for document indexing and presentation.
+ *
+ * # Examples
+ */
+export interface DocumentMetadata {
+  /** Document title from `<title>` tag */
   title?: string
+  /** Document description from `<meta name="description">` tag */
   description?: string
+  /** Document keywords from `<meta name="keywords">` tag, split on commas */
   keywords?: Array<string>
+  /** Document author from `<meta name="author">` tag */
   author?: string
+  /** Canonical URL from `<link rel="canonical">` tag */
   canonicalUrl?: string
+  /** Base URL from `<base href="">` tag for resolving relative URLs */
   baseHref?: string
+  /** Document language from `lang` attribute */
   language?: string
+  /** Document text direction from `dir` attribute */
   textDirection?: JsTextDirection
+  /**
+   * Open Graph metadata (og:* properties) for social media
+   * Keys like "title", "description", "image", "url", etc.
+   */
   openGraph?: Record<string, string>
+  /**
+   * Twitter Card metadata (twitter:* properties)
+   * Keys like "card", "site", "creator", "title", "description", "image", etc.
+   */
   twitterCard?: Record<string, string>
+  /**
+   * Additional meta tags not covered by specific fields
+   * Keys are meta name/property attributes, values are content
+   */
   metaTags?: Record<string, string>
 }
 
-export interface JsDocumentNode {
+/** A single node in the document tree. */
+export interface DocumentNode {
+  /** Deterministic node identifier. */
   id: string
+  /** The semantic content of this node. */
   content: JsNodeContent
+  /** Index of the parent node (None for root nodes). */
   parent?: number
+  /** Indices of child nodes in reading order. */
   children: Array<number>
+  /** Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. */
   annotations: Array<JsTextAnnotation>
+  /**
+   * Format-specific attributes preserved from the source HTML element.
+   *
+   * Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`,
+   * `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source —
+   * no HTML entity decoding is applied here.
+   *
+   * The map is `None` when no attributes are present (omitted entirely in serialized output).
+   * Not every HTML attribute is preserved: only attributes that carry semantic or structural
+   * significance for the node type are collected. For example, heading nodes capture the `"id"`
+   * attribute for anchor linking; other element-level attributes may be silently dropped.
+   */
   attributes?: Record<string, string>
 }
 
-export interface JsDocumentStructure {
+/**
+ * A structured document tree representing the semantic content of an HTML document.
+ *
+ * Uses a flat node array with index-based parent/child references for efficient traversal.
+ */
+export interface DocumentStructure {
+  /** All nodes in document reading order. */
   nodes: Array<JsDocumentNode>
+  /** The source format (always "html" for this crate). */
   sourceFormat?: string
 }
 
-export interface JsGridCell {
+/** A single cell in a table grid. */
+export interface GridCell {
+  /** The text content of the cell. */
   content: string
+  /** 0-indexed row position. */
   row: number
+  /** 0-indexed column position. */
   col: number
+  /** Number of rows this cell spans (default 1). */
   rowSpan: number
+  /** Number of columns this cell spans (default 1). */
   colSpan: number
+  /** Whether this is a header cell (`<th>`). */
   isHeader: boolean
 }
 
-export interface JsHeaderMetadata {
+/**
+ * Header element metadata with hierarchy tracking.
+ *
+ * Captures heading elements (h1-h6) with their text content, identifiers,
+ * and position in the document structure.
+ *
+ * # Examples
+ */
+export interface HeaderMetadata {
+  /** Header level: 1 (h1) through 6 (h6) */
   level: number
+  /** Normalized text content of the header */
   text: string
+  /** HTML id attribute if present */
   id?: string
+  /** Document tree depth at the header element */
   depth: number
+  /** Byte offset in original HTML document */
   htmlOffset: number
 }
 
-export declare const enum JsHeadingStyle {
+/**
+ * Heading style options for Markdown output.
+ *
+ * Controls how headings (h1-h6) are rendered in the output Markdown.
+ */
+export declare const enum HeadingStyle {
+  /** Underlined style (=== for h1, --- for h2). */
   Underlined = 'Underlined',
+  /** ATX style (# for h1, ## for h2, etc.). Default. */
   Atx = 'Atx',
+  /** ATX closed style (# title #, with closing hashes). */
   AtxClosed = 'AtxClosed'
 }
 
-export declare const enum JsHighlightStyle {
+/**
+ * Highlight rendering style for `<mark>` elements.
+ *
+ * Controls how highlighted text is rendered in Markdown output.
+ */
+export declare const enum HighlightStyle {
+  /** Double equals syntax (==text==). Default. Pandoc-compatible. */
   DoubleEqual = 'DoubleEqual',
+  /** Preserve as HTML (==text==). Original HTML tag. */
   Html = 'Html',
+  /** Render as bold (**text**). Uses strong emphasis. */
   Bold = 'Bold',
+  /** Strip formatting, render as plain text. No markup. */
   None = 'None'
 }
 
-export interface JsHtmlMetadata {
-  document?: JsDocumentMetadata
-  headers?: Array<JsHeaderMetadata>
-  links?: Array<JsLinkMetadata>
-  images?: Array<JsImageMetadata>
-  structuredData?: Array<JsStructuredData>
-}
-
-export interface JsImageMetadata {
+/**
+ * Comprehensive metadata extraction result from HTML document.
+ *
+ * Contains all extracted metadata types in a single structure,
+ * suitable for serialization and transmission across language boundaries.
+ *
+ * # Examples
+ */
+export interface HtmlMetadata {
+  /** Document-level metadata (title, description, canonical, etc.) */
+  document?: DocumentMetadata
+  /** Extracted header elements with hierarchy */
+  headers?: Array<HeaderMetadata>
+  /** Extracted hyperlinks with type classification */
+  links?: Array<LinkMetadata>
+  /** Extracted images with source and dimensions */
+  images?: Array<ImageMetadata>
+  /** Extracted structured data blocks */
+  structuredData?: Array<StructuredData>
+}
+
+/**
+ * Image metadata with source and dimensions.
+ *
+ * Captures `<img>` elements and inline `<svg>` elements with metadata
+ * for image analysis and optimization.
+ *
+ * # Examples
+ */
+export interface ImageMetadata {
+  /** Image source (URL, data URI, or SVG content identifier) */
   src: string
+  /** Alternative text from alt attribute (for accessibility) */
   alt?: string
+  /** Title attribute (often shown as tooltip) */
   title?: string
+  /** Image dimensions as (width, height) if available */
   dimensions?: Array<number>
+  /** Image type classification */
   imageType: JsImageType
+  /** Additional HTML attributes */
   attributes: Record<string, string>
 }
 
-export declare const enum JsImageType {
+/**
+ * Image source classification for proper handling and processing.
+ *
+ * Determines whether an image is embedded (data URI), inline SVG, external, or relative.
+ */
+export declare const enum ImageType {
+  /** Data URI embedded image (base64 or other encoding) */
   DataUri = 'data_uri',
+  /** Inline SVG element */
   InlineSvg = 'inline_svg',
+  /** External image URL (http/https) */
   External = 'external',
+  /** Relative image path */
   Relative = 'relative'
 }
 
-export interface JsLinkMetadata {
+/**
+ * Hyperlink metadata with categorization and attributes.
+ *
+ * Represents `<a>` elements with parsed href values, text content, and link type classification.
+ *
+ * # Examples
+ */
+export interface LinkMetadata {
+  /** The href URL value */
   href: string
+  /** Link text content (normalized, concatenated if mixed with elements) */
   text: string
+  /** Optional title attribute (often shown as tooltip) */
   title?: string
+  /** Link type classification */
   linkType: JsLinkType
+  /** Rel attribute values (e.g., "nofollow", "stylesheet", "canonical") */
   rel: Array<string>
+  /** Additional HTML attributes */
   attributes: Record<string, string>
 }
 
-export declare const enum JsLinkStyle {
+/**
+ * Link rendering style in Markdown output.
+ *
+ * Controls whether links and images use inline `[text](url)` syntax or
+ * reference-style `[text][1]` syntax with definitions collected at the end.
+ */
+export declare const enum LinkStyle {
+  /** Inline links: `[text](url)`. Default. */
   Inline = 'Inline',
+  /** Reference-style links: `[text][1]` with `[1]: url` at end of document. */
   Reference = 'Reference'
 }
 
-export declare const enum JsLinkType {
+/**
+ * Link classification based on href value and document context.
+ *
+ * Used to categorize links during extraction for filtering and analysis.
+ */
+export declare const enum LinkType {
+  /** Anchor link within same document (href starts with #) */
   Anchor = 'anchor',
+  /** Internal link within same domain */
   Internal = 'internal',
+  /** External link to different domain */
   External = 'external',
+  /** Email link (mailto:) */
   Email = 'email',
+  /** Phone link (tel:) */
   Phone = 'phone',
+  /** Other protocol or unclassifiable */
   Other = 'other'
 }
 
-export declare const enum JsListIndentType {
+/**
+ * List indentation character type.
+ *
+ * Controls whether list items are indented with spaces or tabs.
+ */
+export declare const enum ListIndentType {
+  /** Use spaces for indentation. Default. Width controlled by `list_indent_width`. */
   Spaces = 'Spaces',
+  /** Use tabs for indentation. */
   Tabs = 'Tabs'
 }
 
-export declare const enum JsNewlineStyle {
+/**
+ * Line break syntax in Markdown output.
+ *
+ * Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
+ */
+export declare const enum NewlineStyle {
+  /** Two trailing spaces at end of line. Default. Standard Markdown syntax. */
   Spaces = 'Spaces',
+  /** Backslash at end of line. Alternative Markdown syntax. */
   Backslash = 'Backslash'
 }
 
-export interface JsNodeContent {
+/**
+ * The semantic content type of a document node.
+ *
+ * Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
+ */
+export interface NodeContent {
   node_type: string
   level?: number
   text?: string
   ordered?: boolean
-  grid?: JsTableGrid
+  grid?: TableGrid
   description?: string
   src?: string
   imageIndex?: number
@@ -259,191 +562,444 @@ export interface JsNodeContent {
   headingText?: string
 }
 
-export interface JsNodeContext {
+/**
+ * Context information passed to all visitor methods.
+ *
+ * Provides comprehensive metadata about the current node being visited,
+ * including its type, attributes, position in the DOM tree, and parent context.
+ */
+export interface NodeContext {
+  /** Coarse-grained node type classification */
   nodeType: JsNodeType
+  /** Raw HTML tag name (e.g., "div", "h1", "custom-element") */
   tagName: string
+  /** All HTML attributes as key-value pairs */
   attributes: Record<string, string>
+  /** Depth in the DOM tree (0 = root) */
   depth: number
+  /** Index among siblings (0-based) */
   indexInParent: number
+  /** Parent element's tag name (None if root) */
   parentTag?: string
+  /** Whether this element is treated as inline vs block */
   isInline: boolean
 }
 
-export declare const enum JsNodeType {
+/**
+ * Node type enumeration covering all HTML element types.
+ *
+ * This enum categorizes all HTML elements that the converter recognizes,
+ * providing a coarse-grained classification for visitor dispatch.
+ */
+export declare const enum NodeType {
+  /** Text node (most frequent - 100+ per document) */
   Text = 'Text',
+  /** Generic element node */
   Element = 'Element',
+  /** Heading elements (h1-h6) */
   Heading = 'Heading',
+  /** Paragraph element */
   Paragraph = 'Paragraph',
+  /** Generic div container */
   Div = 'Div',
+  /** Blockquote element */
   Blockquote = 'Blockquote',
+  /** Preformatted text block */
   Pre = 'Pre',
+  /** Horizontal rule */
   Hr = 'Hr',
+  /** Ordered or unordered list (ul, ol) */
   List = 'List',
+  /** List item (li) */
   ListItem = 'ListItem',
+  /** Definition list (dl) */
   DefinitionList = 'DefinitionList',
+  /** Definition term (dt) */
   DefinitionTerm = 'DefinitionTerm',
+  /** Definition description (dd) */
   DefinitionDescription = 'DefinitionDescription',
+  /** Table element */
   Table = 'Table',
+  /** Table row (tr) */
   TableRow = 'TableRow',
+  /** Table cell (td, th) */
   TableCell = 'TableCell',
+  /** Table header cell (th) */
   TableHeader = 'TableHeader',
+  /** Table body (tbody) */
   TableBody = 'TableBody',
+  /** Table head (thead) */
   TableHead = 'TableHead',
+  /** Table foot (tfoot) */
   TableFoot = 'TableFoot',
+  /** Anchor link (a) */
   Link = 'Link',
+  /** Image (img) */
   Image = 'Image',
+  /** Strong/bold (strong, b) */
   Strong = 'Strong',
+  /** Emphasis/italic (em, i) */
   Em = 'Em',
+  /** Inline code (code) */
   Code = 'Code',
+  /** Strikethrough (s, del, strike) */
   Strikethrough = 'Strikethrough',
+  /** Underline (u, ins) */
   Underline = 'Underline',
+  /** Subscript (sub) */
   Subscript = 'Subscript',
+  /** Superscript (sup) */
   Superscript = 'Superscript',
+  /** Mark/highlight (mark) */
   Mark = 'Mark',
+  /** Small text (small) */
   Small = 'Small',
+  /** Line break (br) */
   Br = 'Br',
+  /** Span element */
   Span = 'Span',
+  /** Article element */
   Article = 'Article',
+  /** Section element */
   Section = 'Section',
+  /** Navigation element */
   Nav = 'Nav',
+  /** Aside element */
   Aside = 'Aside',
+  /** Header element */
   Header = 'Header',
+  /** Footer element */
   Footer = 'Footer',
+  /** Main element */
   Main = 'Main',
+  /** Figure element */
   Figure = 'Figure',
+  /** Figure caption */
   Figcaption = 'Figcaption',
+  /** Time element */
   Time = 'Time',
+  /** Details element */
   Details = 'Details',
+  /** Summary element */
   Summary = 'Summary',
+  /** Form element */
   Form = 'Form',
+  /** Input element */
   Input = 'Input',
+  /** Select element */
   Select = 'Select',
+  /** Option element */
   Option = 'Option',
+  /** Button element */
   Button = 'Button',
+  /** Textarea element */
   Textarea = 'Textarea',
+  /** Label element */
   Label = 'Label',
+  /** Fieldset element */
   Fieldset = 'Fieldset',
+  /** Legend element */
   Legend = 'Legend',
+  /** Audio element */
   Audio = 'Audio',
+  /** Video element */
   Video = 'Video',
+  /** Picture element */
   Picture = 'Picture',
+  /** Source element */
   Source = 'Source',
+  /** Iframe element */
   Iframe = 'Iframe',
+  /** SVG element */
   Svg = 'Svg',
+  /** Canvas element */
   Canvas = 'Canvas',
+  /** Ruby annotation */
   Ruby = 'Ruby',
+  /** Ruby text */
   Rt = 'Rt',
+  /** Ruby parenthesis */
   Rp = 'Rp',
+  /** Abbreviation */
   Abbr = 'Abbr',
+  /** Keyboard input */
   Kbd = 'Kbd',
+  /** Sample output */
   Samp = 'Samp',
+  /** Variable */
   Var = 'Var',
+  /** Citation */
   Cite = 'Cite',
+  /** Quote */
   Q = 'Q',
+  /** Deleted text */
   Del = 'Del',
+  /** Inserted text */
   Ins = 'Ins',
+  /** Data element */
   Data = 'Data',
+  /** Meter element */
   Meter = 'Meter',
+  /** Progress element */
   Progress = 'Progress',
+  /** Output element */
   Output = 'Output',
+  /** Template element */
   Template = 'Template',
+  /** Slot element */
   Slot = 'Slot',
+  /** HTML root element */
   Html = 'Html',
+  /** Head element */
   Head = 'Head',
+  /** Body element */
   Body = 'Body',
+  /** Title element */
   Title = 'Title',
+  /** Meta element */
   Meta = 'Meta',
+  /** Link element (not anchor) */
   LinkTag = 'LinkTag',
+  /** Style element */
   Style = 'Style',
+  /** Script element */
   Script = 'Script',
+  /** Base element */
   Base = 'Base',
+  /** Custom element (web components) or unknown tag */
   Custom = 'Custom'
 }
 
-export declare const enum JsOutputFormat {
+/**
+ * Output format for conversion.
+ *
+ * Specifies the target markup language format for the conversion output.
+ */
+export declare const enum OutputFormat {
+  /** Standard Markdown (CommonMark compatible). Default. */
   Markdown = 'Markdown',
+  /** Djot lightweight markup language. */
   Djot = 'Djot',
+  /** Plain text output (no markup, visible text only). */
   Plain = 'Plain'
 }
 
-export interface JsPreprocessingOptions {
+/** HTML preprocessing options for document cleanup before conversion. */
+export interface PreprocessingOptions {
+  /** Enable HTML preprocessing globally */
   enabled?: boolean
+  /** Preprocessing preset level (Minimal, Standard, Aggressive) */
   preset?: JsPreprocessingPreset
+  /** Remove navigation elements (nav, breadcrumbs, menus, sidebars) */
   removeNavigation?: boolean
+  /** Remove form elements (forms, inputs, buttons, etc.) */
   removeForms?: boolean
 }
 
-export interface JsPreprocessingOptionsUpdate {
-  enabled?: boolean
-  preset?: JsPreprocessingPreset
-  removeNavigation?: boolean
-  removeForms?: boolean
-}
+export declare function preprocessingOptionsDefault(): PreprocessingOptions
 
-export declare const enum JsPreprocessingPreset {
+/**
+ * HTML preprocessing aggressiveness level.
+ *
+ * Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
+ */
+export declare const enum PreprocessingPreset {
+  /** Minimal cleanup. Remove only essential noise (scripts, styles). */
   Minimal = 'Minimal',
+  /** Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. */
   Standard = 'Standard',
+  /** Aggressive cleanup. Remove extensive non-content elements and structure. */
   Aggressive = 'Aggressive'
 }
 
-export interface JsProcessingWarning {
+/**
+ * A non-fatal diagnostic produced during HTML conversion.
+ *
+ * Warnings indicate that conversion completed but some content may have been handled
+ * differently than expected — for example, an image that could not be extracted, a truncated
+ * input, or malformed HTML that was repaired with best-effort parsing.
+ *
+ * Conversion always succeeds (returns `ConversionResult`) even when warnings are
+ * present. Callers should inspect `warnings` and decide how to
+ * handle them based on their tolerance for partial results:
+ *
+ * - **Logging pipelines**: emit each warning at `WARN` level and continue.
+ * - **Strict pipelines**: treat any warning as a hard error by checking
+ *   `result.warnings.is_empty()` before using the output.
+ *
+ * See `WarningKind` for the full taxonomy of warning categories.
+ */
+export interface ProcessingWarning {
+  /** Human-readable warning message. */
   message: string
+  /** The category of warning. */
   kind: JsWarningKind
 }
 
-export interface JsStructuredData {
+/**
+ * Structured data block (JSON-LD, Microdata, or RDFa).
+ *
+ * Represents machine-readable structured data found in the document.
+ * JSON-LD blocks are collected as raw JSON strings for flexibility.
+ *
+ * # Examples
+ */
+export interface StructuredData {
+  /** Type of structured data (JSON-LD, Microdata, RDFa) */
   dataType: JsStructuredDataType
+  /** Raw JSON string (for JSON-LD) or serialized representation */
   rawJson: string
+  /** Schema type if detectable (e.g., "Article", "Event", "Product") */
   schemaType?: string
 }
 
-export declare const enum JsStructuredDataType {
+/**
+ * Structured data format type.
+ *
+ * Identifies the schema/format used for structured data markup.
+ */
+export declare const enum StructuredDataType {
+  /** JSON-LD (JSON for Linking Data) script blocks */
   JsonLd = 'json_ld',
+  /** HTML5 Microdata attributes (itemscope, itemtype, itemprop) */
   Microdata = 'microdata',
+  /** RDF in Attributes (RDFa) markup */
   RDFa = 'rdfa'
 }
 
-export interface JsTableData {
-  grid: JsTableGrid
+/** A top-level extracted table with both structured data and markdown representation. */
+export interface TableData {
+  /** The structured table grid. */
+  grid: TableGrid
+  /** The markdown rendering of this table. */
   markdown: string
 }
 
-export interface JsTableGrid {
+/** A structured table grid with cell-level data including spans. */
+export interface TableGrid {
+  /** Number of rows. */
   rows?: number
+  /** Number of columns. */
   cols?: number
+  /**
+   * All cells in the table as a flat, sparse list.
+   *
+   * The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells
+   * that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear
+   * in the list. Only the top-left "origin" cell of a span is present, with its `row_span`
+   * and `col_span` fields set accordingly.
+   *
+   * To reconstruct the full visual grid, iterate over all cells and mark the rectangular
+   * region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any
+   * `(row, col)` position that is not the origin of any cell is covered by a span from an
+   * earlier cell.
+   *
+   * The length of this vec is `≤ rows * cols`. An empty table (`rows == 0 || cols == 0`)
+   * produces an empty vec.
+   */
   cells?: Array<JsGridCell>
 }
 
-export interface JsTextAnnotation {
+/**
+ * A styling or semantic annotation that applies to a byte range within a node's text.
+ *
+ * Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.),
+ * a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and
+ * similar — that spans a contiguous run of bytes inside `DocumentNode.content`'s text field.
+ *
+ * Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range
+ * follows Rust slice conventions: `start` is inclusive and `end` is exclusive, so the annotated
+ * text is `text[start as usize..end as usize]`.
+ *
+ * Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are
+ * stored in the order they are encountered during DOM traversal.
+ *
+ * See `AnnotationKind` for the full list of supported annotation types.
+ */
+export interface TextAnnotation {
+  /** Start byte offset (inclusive) into the parent node's text. */
   start: number
+  /** End byte offset (exclusive) into the parent node's text. */
   end: number
+  /** The type of annotation. */
   kind: JsAnnotationKind
 }
 
-export declare const enum JsTextDirection {
+/**
+ * Text directionality of document content.
+ *
+ * Corresponds to the HTML `dir` attribute and `bdi` element directionality.
+ */
+export declare const enum TextDirection {
+  /** Left-to-right text flow (default for Latin scripts) */
   LeftToRight = 'ltr',
+  /** Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) */
   RightToLeft = 'rtl',
+  /** Automatic directionality detection */
   Auto = 'auto'
 }
 
-export declare const enum JsVisitResult {
+/**
+ * Result of a visitor callback.
+ *
+ * Allows visitors to control the conversion flow by either proceeding
+ * with default behavior, providing custom output, skipping elements,
+ * preserving HTML, or signaling errors.
+ */
+export declare const enum VisitResult {
+  /** Continue with default conversion behavior */
   Continue = 'Continue',
+  /**
+   * Replace default output with custom markdown
+   *
+   * The visitor takes full responsibility for the markdown output
+   * of this node and its children.
+   */
   Custom = 'Custom',
+  /**
+   * Skip this element entirely (don't output anything)
+   *
+   * The element and all its children are ignored in the output.
+   */
   Skip = 'Skip',
+  /**
+   * Preserve original HTML (don't convert to markdown)
+   *
+   * The element's raw HTML is included verbatim in the output.
+   */
   PreserveHtml = 'PreserveHtml',
+  /**
+   * Stop conversion with an error
+   *
+   * The conversion process halts and returns this error message.
+   */
   Error = 'Error'
 }
 
-export declare const enum JsWarningKind {
+/** Categories of processing warnings. */
+export declare const enum WarningKind {
+  /** An image could not be extracted (e.g. invalid data URI, unsupported format). */
   ImageExtractionFailed = 'image_extraction_failed',
+  /** The input encoding was not recognized; fell back to UTF-8. */
   EncodingFallback = 'encoding_fallback',
+  /** The input was truncated due to size limits. */
   TruncatedInput = 'truncated_input',
+  /** The HTML was malformed but processing continued with best effort. */
   MalformedHtml = 'malformed_html',
+  /** Sanitization was applied to remove potentially unsafe content. */
   SanitizationApplied = 'sanitization_applied',
+  /** DOM traversal was truncated because max_depth was exceeded. */
   DepthLimitExceeded = 'depth_limit_exceeded'
 }
 
-export declare const enum JsWhitespaceMode {
+/**
+ * Whitespace handling strategy during conversion.
+ *
+ * Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
+ */
+export declare const enum WhitespaceMode {
+  /** Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. */
   Normalized = 'Normalized',
+  /** Preserve all whitespace exactly as it appears in the HTML. */
   Strict = 'Strict'
 }