npm - @kreuzberg/html-to-markdown-node - Versions diffs - 3.4.0-rc.9 → 3.5.0-rc.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/index.d.ts CHANGED Viewed

@@ -1,242 +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 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>
-}
-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>
-}
-export interface JsConversionResult {
+  /**
+   * 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 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
@@ -251,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',
-  RDFa = 'rd_fa'
+  /** 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 {
-  LeftToRight = 'LeftToRight',
-  RightToLeft = 'RightToLeft',
-  Auto = 'Auto'
-}
-export declare const enum JsVisitResult {
+/**
+ * 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'
+}
+/**
+ * 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'
 }