magpie-html 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,3072 @@
+/**
+ * Content extraction types.
+ *
+ * @remarks
+ * Types for article content extraction using Mozilla Readability.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for content extraction.
+ */
+interface ContentExtractionOptions {
+    /**
+     * Base URL for resolving relative links and images.
+     * Highly recommended for proper link resolution.
+     */
+    baseUrl?: string;
+    /**
+     * Minimum character count for article content.
+     * Articles shorter than this are considered too short.
+     * @default 500
+     */
+    charThreshold?: number;
+    /**
+     * Maximum number of elements to parse.
+     * Set to 0 for no limit.
+     * @default 0
+     */
+    maxElemsToParse?: number;
+    /**
+     * Whether to preserve CSS classes in extracted HTML.
+     * @default false
+     */
+    keepClasses?: boolean;
+    /**
+     * CSS classes to preserve when keepClasses is false.
+     */
+    classesToPreserve?: string[];
+    /**
+     * Whether to skip JSON-LD parsing for metadata.
+     * @default false
+     */
+    disableJSONLD?: boolean;
+    /**
+     * Check if content is probably readerable before extraction.
+     * If true and content is not readerable, returns early with failure.
+     * @default false
+     */
+    checkReadability?: boolean;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Successfully extracted content.
+ */
+interface ExtractedContent {
+    /** Extraction succeeded */
+    success: true;
+    /** Article title */
+    title: string;
+    /** Cleaned HTML content */
+    content: string;
+    /** Plain text content (HTML stripped) */
+    textContent: string;
+    /** Article excerpt/summary */
+    excerpt: string;
+    /** Author byline */
+    byline?: string;
+    /** Site name */
+    siteName?: string;
+    /** Content language code (e.g., 'en', 'de') */
+    lang?: string;
+    /** Text direction */
+    dir?: 'ltr' | 'rtl';
+    /** Published time (ISO 8601 string if available) */
+    publishedTime?: string;
+    /** Character count of text content */
+    length: number;
+    /** Word count */
+    wordCount: number;
+    /** Estimated reading time in minutes */
+    readingTime: number;
+    /** Whether content passed readability check */
+    readerable: boolean;
+    /** Extraction time in milliseconds */
+    extractionTime: number;
+}
+/**
+ * Error types for extraction failures.
+ */
+type ExtractionErrorType = 'NOT_READERABLE' | 'PARSE_ERROR' | 'EXTRACTION_FAILED' | 'INVALID_HTML' | 'UNKNOWN';
+/**
+ * Failed content extraction.
+ */
+interface ExtractionFailure {
+    /** Extraction failed */
+    success: false;
+    /** Error message */
+    error: string;
+    /** Categorized error type */
+    errorType: ExtractionErrorType;
+    /** Whether content passed readability check (if checked) */
+    readerable: boolean;
+    /** Extraction time in milliseconds */
+    extractionTime: number;
+    /** Original error details (if available) */
+    details?: unknown;
+}
+/**
+ * Result of content extraction.
+ *
+ * @remarks
+ * Always returns a result, never throws exceptions.
+ */
+type ContentResult = ExtractedContent | ExtractionFailure;
+/**
+ * Quality assessment metrics.
+ */
+interface ContentQuality {
+    /** Word count */
+    wordCount: number;
+    /** Character count */
+    charCount: number;
+    /** Estimated reading time in minutes */
+    readingTime: number;
+    /** Average words per sentence */
+    avgWordsPerSentence: number;
+    /** Paragraph count */
+    paragraphCount: number;
+    /** Image count in content */
+    imageCount: number;
+    /** Link count in content */
+    linkCount: number;
+    /** Link density (ratio of link text to total text) */
+    linkDensity: number;
+    /** Overall quality score (0-100) */
+    qualityScore: number;
+}
+
+/**
+ * Main content extraction module.
+ *
+ * @remarks
+ * Extracts article content from HTML using Mozilla Readability.
+ * Never throws exceptions - always returns a ContentResult.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract article content from HTML.
+ *
+ * @remarks
+ * Uses Mozilla Readability to extract clean article content from a pre-parsed Document.
+ * This function never throws exceptions - always returns a ContentResult.
+ *
+ * Error handling:
+ * - Returns success: false for any extraction failure
+ * - Categorizes errors by type for better handling
+ * - Includes extraction time even for failures
+ *
+ * @param doc - Pre-parsed Document to extract content from
+ * @param options - Extraction options
+ * @returns Extraction result (success or failure)
+ *
+ * @example
+ * ```typescript
+ * import { parseHTML } from '../utils/html-parser.js';
+ * import { extractSEO } from '../metadata/index.js';
+ *
+ * const doc = parseHTML(html);
+ * const metadata = extractSEO(doc);
+ * const content = extractContent(doc, {
+ *   baseUrl: 'https://example.com/article',
+ *   charThreshold: 300,
+ *   checkReadability: true,
+ * });
+ *
+ * if (content.success) {
+ *   console.log(content.title);
+ *   console.log(content.wordCount);
+ *   console.log(`${content.readingTime} min read`);
+ * } else {
+ *   console.error(content.error);
+ * }
+ * ```
+ */
+declare function extractContent(doc: Document, options?: ContentExtractionOptions): ContentResult;
+
+/**
+ * HTML to text conversion types.
+ *
+ * @remarks
+ * Types for converting HTML to plain text with the `htmlToText` function.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for HTML to plain text conversion.
+ */
+interface HtmlToTextOptions {
+    /**
+     * How to treat the input HTML.
+     *
+     * @remarks
+     * - `"fragment"`: Treat as HTML fragment (default)
+     * - `"document"`: Treat as full document (ignores `<head>` content)
+     *
+     * @defaultValue `"fragment"`
+     */
+    mode?: 'fragment' | 'document';
+    /**
+     * How to render anchor (`<a>`) tags.
+     *
+     * @remarks
+     * - `"text"`: Show only the link text (default)
+     * - `"inline"`: Show text followed by URL in parentheses, e.g., "Click here (https://example.com)"
+     * - `"remove"`: Remove links entirely
+     *
+     * @defaultValue `"text"`
+     */
+    links?: 'text' | 'inline' | 'remove';
+    /**
+     * How to render image (`<img>`) tags.
+     *
+     * @remarks
+     * - `"alt"`: Show the alt text (default)
+     * - `"remove"`: Remove images entirely
+     *
+     * @defaultValue `"alt"`
+     */
+    images?: 'alt' | 'remove';
+    /**
+     * Collapse consecutive whitespace outside preserved tags.
+     *
+     * @remarks
+     * When `true`, multiple spaces, tabs, and line breaks are collapsed into single spaces.
+     * Whitespace inside preserved tags (e.g., `<pre>`, `<code>`) is always kept intact.
+     *
+     * @defaultValue `true`
+     */
+    collapseWhitespace?: boolean;
+    /**
+     * Maximum consecutive newlines allowed after compaction.
+     *
+     * @remarks
+     * Limits runs of newlines to this value. Set to `1` for single spacing,
+     * `2` for double spacing (default), or higher values as needed.
+     *
+     * @defaultValue `2`
+     */
+    maxNewlines?: number;
+    /**
+     * Optional hard-wrap column width.
+     *
+     * @remarks
+     * When set to a positive number, lines will be wrapped at this column width.
+     * Does not wrap inside preserved tags like `<pre>` or `<code>`.
+     * Set to `null` to disable wrapping (default).
+     *
+     * @defaultValue `null`
+     */
+    wrap?: number | null;
+    /**
+     * Separator between table cells.
+     *
+     * @remarks
+     * - `"tab"`: Use tab character (default)
+     * - `"space"`: Use space character
+     *
+     * @defaultValue `"tab"`
+     */
+    tableCellSeparator?: 'tab' | 'space';
+    /**
+     * HTML tags to exclude entirely along with their contents.
+     *
+     * @remarks
+     * By default excludes: `script`, `style`, `noscript`, `template`, `svg`, `canvas`
+     *
+     * @defaultValue `["script", "style", "noscript", "template", "svg", "canvas"]`
+     */
+    excludeTags?: string[];
+    /**
+     * Decode HTML entities.
+     *
+     * @remarks
+     * When `true`, decodes entities like `&amp;`, `&lt;`, `&#8212;`, etc.
+     *
+     * @defaultValue `true`
+     */
+    decodeEntities?: boolean;
+    /**
+     * Tags whose internal whitespace is preserved.
+     *
+     * @remarks
+     * These tags will not have their whitespace collapsed, allowing proper
+     * formatting of code blocks and preformatted text.
+     *
+     * @defaultValue `["pre", "code", "textarea"]`
+     */
+    preserveTags?: string[];
+    /**
+     * Trim leading and trailing whitespace from the result.
+     *
+     * @defaultValue `true`
+     */
+    trim?: boolean;
+}
+
+/**
+ * HTML to text conversion.
+ *
+ * @remarks
+ * Convert HTML to plain text using a zero-dependency streaming tokenizer.
+ * Pure, deterministic transformation suitable for logs, previews, classification,
+ * and search indexing. Preserves essential structure by inserting newlines at
+ * block boundaries, handles entities, and provides configurable options.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Convert an HTML string to plain text.
+ *
+ * @remarks
+ * This function uses a streaming tokenizer to parse HTML and extract text content.
+ * It handles block elements, whitespace preservation, HTML entities, tables, and more.
+ *
+ * Features:
+ * - Preserves document structure with appropriate line breaks
+ * - Handles HTML entities (numeric and common named entities)
+ * - Configurable link and image handling
+ * - Table rendering with configurable cell separators
+ * - Whitespace preservation for code/pre blocks
+ * - Optional hard-wrapping at column width
+ *
+ * @param html - HTML string (fragment or full document)
+ * @param options - Conversion options
+ * @returns Plain text string
+ *
+ * @throws {TypeError} If html is not a string
+ *
+ * @example
+ * ```typescript
+ * const html = '<div><h1>Hello</h1><p>World!</p></div>';
+ * const text = htmlToText(html);
+ * console.log(text); // "Hello\n\nWorld!"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const html = '<a href="https://example.com">Visit</a>';
+ * const text = htmlToText(html, { links: 'inline' });
+ * console.log(text); // "Visit (https://example.com)"
+ * ```
+ */
+declare function htmlToText(html: string, options?: HtmlToTextOptions): string;
+
+/**
+ * Content quality assessment.
+ *
+ * @remarks
+ * Analyzes extracted content to provide quality metrics.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Calculate word count from text.
+ *
+ * @param text - Text to count words in
+ * @returns Number of words
+ */
+declare function countWords(text: string): number;
+/**
+ * Calculate reading time in minutes.
+ *
+ * @remarks
+ * Uses average reading speed of 200 words per minute.
+ *
+ * @param wordCount - Number of words
+ * @returns Estimated reading time in minutes
+ */
+declare function calculateReadingTime(wordCount: number): number;
+/**
+ * Assess content quality.
+ *
+ * @remarks
+ * Analyzes extracted content and returns comprehensive quality metrics.
+ *
+ * @param content - Extracted content
+ * @returns Quality assessment
+ *
+ * @example
+ * ```typescript
+ * const content = extractContent(html);
+ * if (content.success) {
+ *   const quality = assessContentQuality(content);
+ *   console.log(`Quality score: ${quality.qualityScore}/100`);
+ *   console.log(`Reading time: ${quality.readingTime} minutes`);
+ * }
+ * ```
+ */
+declare function assessContentQuality(content: ExtractedContent): ContentQuality;
+
+/**
+ * Mozilla Readability wrapper with linkedom.
+ *
+ * @remarks
+ * Provides a clean interface to Mozilla Readability using linkedom as the DOM implementation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Check if HTML content is probably readerable.
+ *
+ * @remarks
+ * Quick check to determine if content extraction is likely to succeed.
+ * This is a heuristic check and may produce false positives/negatives.
+ *
+ * @param doc - Pre-parsed Document to check
+ * @param options - Readability check options
+ * @returns True if content appears to be an article
+ *
+ * @example
+ * ```typescript
+ * import { parseHTML } from '../utils/html-parser.js';
+ *
+ * const doc = parseHTML(html);
+ * if (isProbablyReaderable(doc)) {
+ *   const result = extractContent(doc);
+ * }
+ * ```
+ */
+declare function isProbablyReaderable(doc: Document, options?: {
+    minContentLength?: number;
+    minScore?: number;
+}): boolean;
+
+/**
+ * Feed format detection utilities.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Feed format type.
+ *
+ * @remarks
+ * Represents the detected or expected format of a feed.
+ * - `'rss'` - RSS 2.0, 0.9x, or RSS 1.0 (RDF)
+ * - `'atom'` - Atom 1.0
+ * - `'json-feed'` - JSON Feed 1.0 or 1.1
+ * - `'unknown'` - Format could not be determined
+ */
+type FeedFormat = 'rss' | 'atom' | 'json-feed' | 'unknown';
+/**
+ * Detect feed format from content string.
+ *
+ * @remarks
+ * Analyzes the content to determine if it's RSS, Atom, or JSON Feed.
+ * Detection is based on root elements, namespaces, and structure.
+ *
+ * Detection priority:
+ * 1. JSON Feed (checks for JSON with jsonfeed.org version)
+ * 2. RSS (checks for `<rss>` or `<rdf:RDF>` root elements)
+ * 3. Atom (checks for `<feed>` root element with Atom namespace)
+ *
+ * @param content - Feed content as string
+ * @returns Detected format or 'unknown' if format cannot be determined
+ *
+ * @example
+ * ```typescript
+ * const format = detectFormat(feedContent);
+ * if (format === 'rss') {
+ *   console.log('This is an RSS feed');
+ * }
+ * ```
+ */
+declare function detectFormat(content: string): FeedFormat;
+/**
+ * Check if content is a valid feed (any format).
+ *
+ * @param content - Feed content as string
+ * @returns `true` if content is RSS, Atom, or JSON Feed
+ *
+ * @example
+ * ```typescript
+ * if (isFeed(content)) {
+ *   const result = parseFeed(content);
+ * }
+ * ```
+ */
+declare function isFeed(content: string): boolean;
+/**
+ * Check if content is RSS format.
+ *
+ * @param content - Feed content as string
+ * @returns `true` if content is RSS (any version)
+ */
+declare function isRSS(content: string): boolean;
+/**
+ * Check if content is Atom format.
+ *
+ * @param content - Feed content as string
+ * @returns `true` if content is Atom 1.0
+ */
+declare function isAtom(content: string): boolean;
+/**
+ * Check if content is JSON Feed format.
+ *
+ * @param content - Feed content as string
+ * @returns `true` if content is JSON Feed (1.0 or 1.1)
+ */
+declare function isJSONFeed(content: string): boolean;
+
+/**
+ * Unified feed types - normalized interface across all feed formats.
+ *
+ * @remarks
+ * These types provide a consistent interface for working with feeds regardless
+ * of the original format (RSS, Atom, or JSON Feed). All format-specific data
+ * is normalized to this structure by the parser.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Feed author information.
+ *
+ * @remarks
+ * Represents author/contributor information normalized across all feed formats.
+ * Not all formats provide all fields.
+ */
+interface FeedAuthor {
+    /** Author's name */
+    name?: string;
+    /** Author's email address */
+    email?: string;
+    /** Author's website URL */
+    url?: string;
+}
+/**
+ * Feed enclosure (attached file).
+ *
+ * @remarks
+ * Represents attached files like audio, video, or documents. Commonly used
+ * for podcasts and media feeds.
+ */
+interface FeedEnclosure {
+    /** URL of the attached file */
+    url: string;
+    /** MIME type of the file (e.g., 'audio/mpeg', 'video/mp4') */
+    type?: string;
+    /** File size in bytes */
+    length?: number;
+}
+/**
+ * Feed item (entry/article/post).
+ *
+ * @remarks
+ * Represents a single item in a feed. Items are normalized across all formats
+ * to provide a consistent interface. Not all fields are available in all formats.
+ */
+interface FeedItem {
+    /** Unique identifier for the item (GUID, ID, or URL) */
+    id: string;
+    /** Item title */
+    title?: string;
+    /** Canonical URL for the item */
+    url?: string;
+    /** External URL for linked posts (when different from canonical URL) */
+    externalUrl?: string;
+    /** Full HTML content of the item */
+    contentHtml?: string;
+    /** Plain text content of the item */
+    contentText?: string;
+    /** Short summary or description */
+    summary?: string;
+    /** Publication date in ISO 8601 format */
+    published?: string;
+    /** Last modified date in ISO 8601 format */
+    modified?: string;
+    /** Item authors (may be empty if using feed-level authors) */
+    authors?: FeedAuthor[];
+    /** Tags, categories, or keywords */
+    tags?: string[];
+    /** Featured image URL */
+    image?: string;
+    /** Attached files (audio, video, documents) */
+    enclosures?: FeedEnclosure[];
+}
+/**
+ * Normalized feed data.
+ *
+ * @remarks
+ * The main feed object containing metadata and items. This is the recommended
+ * interface for working with feeds as it provides a consistent structure
+ * regardless of the original format.
+ */
+interface Feed {
+    /** Original feed format */
+    format: 'rss' | 'atom' | 'json-feed';
+    /** Feed title (required) */
+    title: string;
+    /** Feed description or subtitle */
+    description?: string;
+    /** Feed's home page URL */
+    url?: string;
+    /** Feed's own URL (self-reference) */
+    feedUrl?: string;
+    /** Feed language code (e.g., 'en', 'de') */
+    language?: string;
+    /** Feed icon or logo URL */
+    image?: string;
+    /** Feed-level authors */
+    authors?: FeedAuthor[];
+    /** Last update date in ISO 8601 format */
+    updated?: string;
+    /** Feed items (entries/articles/posts) */
+    items: FeedItem[];
+}
+/**
+ * Parse result containing both normalized and original data.
+ *
+ * @remarks
+ * Returned by {@link parseFeed}. Contains both the normalized feed data
+ * (recommended for most use cases) and the original format-specific data
+ * (for advanced use cases requiring format-specific fields).
+ */
+interface ParseResult {
+    /** Normalized feed data (recommended) */
+    feed: Feed;
+    /** Original format-specific data (advanced use) */
+    original: unknown;
+}
+
+/**
+ * Unified feed parser with automatic format detection.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parse any feed format with automatic format detection.
+ *
+ * @remarks
+ * This is the main entry point for feed parsing. It automatically detects whether
+ * the content is RSS, Atom, or JSON Feed, parses it, and returns a normalized
+ * output structure along with the original format-specific data.
+ *
+ * All relative URLs in the feed are converted to absolute URLs if a base URL is provided.
+ * This is essential for feed readers that need to fetch images, enclosures, or follow links.
+ *
+ * @param content - Feed content as string (XML or JSON)
+ * @param baseUrl - Optional base URL for resolving relative URLs (string or URL object)
+ * @returns Object containing normalized feed data and original format-specific data
+ * @throws Error if format cannot be detected or parsing fails
+ *
+ * @example
+ * ```typescript
+ * const feedContent = await fetch('https://example.com/feed.xml').then(r => r.text());
+ * const result = parseFeed(feedContent, 'https://example.com/feed.xml');
+ *
+ * console.log(result.feed.title);
+ * console.log(result.feed.items[0].title);
+ * console.log(result.feed.items[0].url); // Absolute URL
+ * ```
+ */
+declare function parseFeed(content: string, baseUrl?: string | URL): ParseResult;
+
+/**
+ * Types for high-level gathering functionality.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Gathered website data.
+ *
+ * @remarks
+ * This interface represents the complete gathered data from a website,
+ * including the authoritative URL and all extracted metadata.
+ * It will be extended incrementally with more properties.
+ */
+interface Website {
+    /**
+     * Authoritative URL for the page.
+     *
+     * @remarks
+     * Uses canonical URL if present, otherwise the final URL after redirects.
+     */
+    url: URL;
+    /** Discovered feed URLs (RSS, Atom, JSON Feed) as URL objects */
+    feeds: URL[];
+    /**
+     * Page title (cleaned, from best available source).
+     *
+     * @remarks
+     * Collects titles from multiple sources, cleans them, and picks the longest.
+     * Sources: OpenGraph, Twitter Card, HTML title tag, First H1
+     */
+    title?: string;
+    /**
+     * Page description (from best available source).
+     *
+     * @remarks
+     * Collects descriptions from metadata and picks the longest.
+     * Sources: OpenGraph, Twitter Card, HTML meta description
+     */
+    description?: string;
+    /**
+     * Page keyvisual/image URL (from best available source).
+     *
+     * @remarks
+     * Priority: OpenGraph > Twitter Card > Largest Apple Touch Icon > Favicon
+     * Returns the URL object of the best visual representation of the site.
+     */
+    image?: URL;
+    /**
+     * Best available icon/favicon for the site.
+     *
+     * @remarks
+     * Priority: Largest Apple Touch Icon > Safari mask icon > Favicon > Shortcut icon > MS tile > Fluid icon
+     * Returns the highest quality icon available, preferring modern, high-resolution formats.
+     */
+    icon?: URL;
+    /**
+     * Primary language code (ISO 639-1).
+     *
+     * @remarks
+     * Extracted from HTML lang attribute, content-language meta tag, or OpenGraph locale.
+     * Normalized to lowercase ISO 639-1 format (e.g., 'en', 'de', 'fr', 'ja').
+     */
+    language?: string;
+    /**
+     * Region code (ISO 3166-1 alpha-2).
+     *
+     * @remarks
+     * Only present if the language includes a region specifier.
+     * Normalized to uppercase ISO 3166-1 alpha-2 format (e.g., 'US', 'GB', 'DE').
+     */
+    region?: string;
+    /**
+     * Raw HTML content of the page (UTF-8).
+     *
+     * @remarks
+     * The complete HTML source after fetching and decoding to UTF-8.
+     * Useful for custom processing or caching.
+     */
+    html: string;
+    /**
+     * Plain text content extracted from the HTML.
+     *
+     * @remarks
+     * Automatically converted from HTML using the `htmlToText` function.
+     * Removes all tags, decodes entities, and preserves document structure
+     * with appropriate line breaks.
+     */
+    text: string;
+    /**
+     * Internal links found on the page (same domain, excluding current URL).
+     *
+     * @remarks
+     * All links are URL objects. The current page URL is excluded to avoid
+     * self-references. Useful for site crawling and navigation analysis.
+     */
+    internalLinks: URL[];
+    /**
+     * External links found on the page (different domains).
+     *
+     * @remarks
+     * All links are URL objects. Useful for analyzing outbound links,
+     * citations, and external resources.
+     */
+    externalLinks: URL[];
+}
+/**
+ * Gathered article data.
+ *
+ * @remarks
+ * This interface represents the complete gathered data from an article page,
+ * including the authoritative URL, raw HTML, and extracted content.
+ * It will be extended incrementally with more properties.
+ */
+interface Article {
+    /**
+     * Authoritative URL for the article.
+     *
+     * @remarks
+     * Uses canonical URL if present, otherwise the final URL after redirects.
+     */
+    url: URL;
+    /**
+     * Raw HTML content of the article page (UTF-8).
+     *
+     * @remarks
+     * The complete HTML source after fetching and decoding to UTF-8.
+     * Useful for custom processing or caching.
+     */
+    html: string;
+    /**
+     * Plain text content extracted from the HTML.
+     *
+     * @remarks
+     * Automatically converted from HTML using the `htmlToText` function.
+     * Removes all tags, decodes entities, and preserves document structure
+     * with appropriate line breaks.
+     */
+    text: string;
+    /**
+     * Cleaned article content (plain text).
+     *
+     * @remarks
+     * Extracted using Mozilla Readability (cleaned HTML), then converted to
+     * plain text using `htmlToText` for proper formatting.
+     * This is the main article body without navigation, ads, or other clutter.
+     * Falls back to undefined if Readability extraction fails.
+     */
+    content?: string;
+    /**
+     * Article title.
+     *
+     * @remarks
+     * Extracted from Mozilla Readability if available.
+     * Falls back to metadata (Schema.org, OpenGraph, Twitter Card, HTML title)
+     * if Readability extraction fails or title is empty.
+     */
+    title?: string;
+    /**
+     * Article description/excerpt.
+     *
+     * @remarks
+     * Extracted from Mozilla Readability's excerpt if available.
+     * Falls back to metadata (OpenGraph, Twitter Card, HTML meta description)
+     * if Readability excerpt is empty or extraction fails.
+     */
+    description?: string;
+    /**
+     * Article keyvisual/image URL (from best available source).
+     *
+     * @remarks
+     * Priority: Schema.org NewsArticle/Article (largest) > OpenGraph > Twitter Card > Largest Apple Touch Icon > Favicon
+     * Returns the URL object of the best visual representation of the article.
+     */
+    image?: URL;
+    /**
+     * Primary language code (ISO 639-1).
+     *
+     * @remarks
+     * Extracted from HTML lang attribute, Content-Language meta, or OpenGraph locale.
+     * Returns lowercase 2-letter ISO 639-1 code (e.g., 'en', 'de', 'fr').
+     */
+    language?: string;
+    /**
+     * Region/country code (ISO 3166-1 alpha-2).
+     *
+     * @remarks
+     * Extracted from language tags like 'en-US' or 'de-DE'.
+     * Returns uppercase 2-letter ISO 3166-1 alpha-2 code (e.g., 'US', 'GB', 'DE').
+     */
+    region?: string;
+    /**
+     * Internal links found in the article (same domain/subdomain).
+     *
+     * @remarks
+     * Links pointing to pages within the same domain.
+     * Automatically excludes the current article URL.
+     * All URLs are absolute and normalized.
+     */
+    internalLinks: URL[];
+    /**
+     * External links found in the article (different domains).
+     *
+     * @remarks
+     * Links pointing to external domains (useful for citations, references).
+     * All URLs are absolute and normalized.
+     */
+    externalLinks: URL[];
+    /**
+     * Word count of the article.
+     *
+     * @remarks
+     * Calculated from `content` if available (Readability-cleaned content),
+     * otherwise calculated from `text` (full page text).
+     * Based on whitespace-separated word boundaries.
+     */
+    wordCount: number;
+    /**
+     * Estimated reading time in minutes.
+     *
+     * @remarks
+     * Calculated from word count using average reading speed of 200 words per minute.
+     * Minimum value is 1 minute.
+     */
+    readingTime: number;
+}
+
+/**
+ * High-level article gathering functionality.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Gather article data from a URL in one convenient call.
+ *
+ * @remarks
+ * This is a high-level convenience method that fetches an article page and extracts
+ * relevant data. It handles encoding detection, redirects, and provides
+ * a unified interface for all article data.
+ *
+ * This method will be extended incrementally to include metadata extraction,
+ * content extraction, and more.
+ *
+ * @param url - Article URL as string or URL object
+ * @returns Gathered article data including URL, content, metadata, language, and links
+ * @throws Error if URL is invalid or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Fetch an article and get its data
+ * const article = await gatherArticle('https://example.com/article');
+ * console.log(article.url);            // Final URL after redirects
+ * console.log(article.html);           // Raw HTML content (UTF-8)
+ * console.log(article.text);           // Plain text (full page HTML converted)
+ * console.log(article.content);        // Cleaned article content (Readability + htmlToText)
+ * console.log(article.title);          // Article title (from Readability or metadata)
+ * console.log(article.description);    // Article excerpt or description
+ * console.log(article.image);          // Article keyvisual/image (from best source)
+ * console.log(article.language);       // Language code (ISO 639-1, e.g., 'en')
+ * console.log(article.region);         // Region code (ISO 3166-1 alpha-2, e.g., 'US')
+ * console.log(article.internalLinks);  // Array of internal link URLs
+ * console.log(article.externalLinks);  // Array of external link URLs
+ * console.log(article.wordCount);      // Word count (from content or text)
+ * console.log(article.readingTime);    // Estimated reading time in minutes
+ * ```
+ */
+declare function gatherArticle(url: string | URL): Promise<Article>;
+
+/**
+ * High-level feed gathering functionality.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Gather and parse a feed from a URL in one convenient call.
+ *
+ * @remarks
+ * This is a high-level convenience method that combines fetching and parsing.
+ * It handles encoding detection, redirects, and feed format detection automatically.
+ *
+ * @param url - Feed URL as string or URL object
+ * @returns Normalized feed data
+ * @throws Error if URL is invalid, fetch fails, or feed cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * // Fetch and parse a feed
+ * const feed = await gatherFeed('https://example.com/feed.xml');
+ *
+ * console.log(feed.title);
+ * console.log(feed.items[0].title);
+ * console.log(feed.items[0].url);
+ * ```
+ */
+declare function gatherFeed(url: string | URL): Promise<Feed>;
+
+/**
+ * High-level website gathering functionality.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Gather website data from a URL in one convenient call.
+ *
+ * @remarks
+ * This is a high-level convenience method that fetches a website and extracts
+ * all relevant data. It handles encoding detection, redirects, and provides
+ * a unified interface for all website data.
+ *
+ * This method will be extended incrementally to include metadata extraction,
+ * content extraction, and more.
+ *
+ * @param url - Website URL as string or URL object
+ * @returns Gathered website data including final URL, title, description, image, icon, language, html, text, feeds, and links
+ * @throws Error if URL is invalid or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Fetch a website and get its data
+ * const site = await gatherWebsite('https://example.com');
+ * console.log(site.url);            // Final URL after redirects
+ * console.log(site.title);          // Page title (cleaned, from best source)
+ * console.log(site.description);    // Page description (from best source)
+ * console.log(site.image);          // Page image/keyvisual (from best source)
+ * console.log(site.icon);           // Best available icon/favicon
+ * console.log(site.language);       // Primary language code (ISO 639-1)
+ * console.log(site.region);         // Region code (ISO 3166-1 alpha-2)
+ * console.log(site.html);           // Raw HTML content (UTF-8)
+ * console.log(site.text);           // Plain text content (extracted from HTML)
+ * console.log(site.feeds);          // Array of feed URL objects
+ * console.log(site.internalLinks);  // Array of internal link URL objects
+ * console.log(site.externalLinks);  // Array of external link URL objects
+ * ```
+ */
+declare function gatherWebsite(url: string | URL): Promise<Website>;
+
+/**
+ * HTML parsing utilities using linkedom.
+ *
+ * @remarks
+ * This module provides a simple wrapper around linkedom for consistent
+ * HTML parsing across all metadata extraction modules. Parsing should happen
+ * once at the top level and the parsed document passed to all extractors.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parse HTML string into a DOM document.
+ *
+ * @remarks
+ * Parses HTML using linkedom, providing a standards-compliant DOM implementation.
+ * This should be called once per document, with the result passed to all metadata
+ * extractors for performance.
+ *
+ * Never throws - returns a document even for malformed HTML.
+ *
+ * @param html - HTML string to parse
+ * @param baseUrl - Optional base URL for resolving relative URLs
+ * @returns Parsed DOM document
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML('<html><head><title>Test</title></head></html>');
+ * const title = doc.querySelector('title')?.textContent;
+ * ```
+ */
+declare function parseHTML(html: string, baseUrl?: string): Document;
+type HTMLDocument = Document;
+
+/**
+ * Analytics and tracking types.
+ *
+ * @remarks
+ * Types for analytics service detection (IDs only, no tracking).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Analytics metadata.
+ *
+ * @remarks
+ * Contains detected analytics service IDs. Privacy-conscious - only extracts IDs,
+ * doesn't perform any tracking.
+ */
+interface AnalyticsMetadata {
+    /** Google Analytics tracking IDs (UA-, G-, GT- prefixes) */
+    googleAnalytics?: string[];
+    /** Google Tag Manager container IDs */
+    googleTagManager?: string[];
+    /** Facebook Pixel IDs */
+    facebookPixel?: string[];
+    /** Matomo/Piwik site IDs */
+    matomo?: string[];
+    /** Plausible Analytics domains */
+    plausible?: string[];
+    /** Adobe Analytics (Omniture) IDs */
+    adobe?: string[];
+    /** Cloudflare Web Analytics tokens */
+    cloudflare?: string[];
+    /** Fathom Analytics site IDs */
+    fathom?: string[];
+}
+
+/**
+ * Analytics and tracking extraction.
+ *
+ * @remarks
+ * Detects analytics service IDs from HTML documents.
+ * Privacy-conscious - only extracts IDs, doesn't perform any tracking.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract analytics metadata from parsed HTML document.
+ *
+ * @remarks
+ * Detects analytics service IDs by examining script tags and their content.
+ * Only extracts identifiers, does not track or collect user data.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Analytics metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const analytics = extractAnalytics(doc);
+ * console.log(analytics.googleAnalytics);
+ * console.log(analytics.googleTagManager);
+ * ```
+ */
+declare function extractAnalytics(doc: HTMLDocument): AnalyticsMetadata;
+
+/**
+ * Assets extraction types.
+ *
+ * @remarks
+ * Types for categorized asset URLs extracted from HTML documents.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+/**
+ * Categorized assets extracted from HTML.
+ *
+ * @remarks
+ * Contains all external assets referenced in the document, organized by type.
+ * All URLs are normalized to absolute format if a base URL is available.
+ */
+interface AssetsMetadata {
+    /** Image URLs from img, picture, srcset, and meta tags */
+    images?: string[];
+    /** Stylesheet URLs from link tags */
+    stylesheets?: string[];
+    /** Script URLs from script tags */
+    scripts?: string[];
+    /** Font URLs extracted from CSS */
+    fonts?: string[];
+    /** Media URLs from video, audio, source, and track elements */
+    media?: string[];
+    /** Web app manifest URLs */
+    manifests?: string[];
+    /** Preload/prefetch resource hints */
+    preloads?: PreloadResource[];
+    /** DNS prefetch and preconnect hints */
+    connectionHints?: ConnectionHint[];
+}
+/**
+ * Preload or prefetch resource hint.
+ */
+interface PreloadResource {
+    /** Resource URL */
+    url: string;
+    /** Resource type (script, style, font, image, etc.) */
+    as?: string;
+    /** MIME type */
+    type?: string;
+    /** Crossorigin attribute */
+    crossorigin?: string;
+    /** Whether this is a prefetch (true) or preload (false) */
+    prefetch?: boolean;
+}
+/**
+ * DNS prefetch or preconnect hint.
+ */
+interface ConnectionHint {
+    /** Domain URL */
+    url: string;
+    /** Whether this is a preconnect (true) or dns-prefetch (false) */
+    preconnect?: boolean;
+    /** Crossorigin attribute */
+    crossorigin?: string;
+}
+
+/**
+ * Assets extraction.
+ *
+ * @remarks
+ * Extracts categorized asset URLs from HTML documents.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract assets metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts all external assets referenced in the document, organized by type.
+ * All URLs are normalized to absolute format based on the document's base URL.
+ *
+ * The extractor finds assets from:
+ * - Images: `<img>`, `<picture>`, `srcset`, OpenGraph meta tags
+ * - Stylesheets: `<link rel="stylesheet">`
+ * - Scripts: `<script src>`
+ * - Fonts: CSS `@font-face` and `url()` with font extensions
+ * - Media: `<video>`, `<audio>`, `<source>`, `<track>`
+ * - Manifests: `<link rel="manifest">`
+ * - Preloads: `<link rel="preload">` and `<link rel="prefetch">`
+ * - Connection hints: `<link rel="dns-prefetch">` and `<link rel="preconnect">`
+ *
+ * @param doc - Parsed HTML document
+ * @param baseUrl - Optional base URL for resolving relative URLs
+ * @returns Assets metadata object with categorized URLs
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const assets = extractAssets(doc, 'https://example.com');
+ * console.log(assets.images);
+ * console.log(assets.stylesheets);
+ * console.log(assets.scripts);
+ * ```
+ */
+declare function extractAssets(doc: HTMLDocument, baseUrl?: string | URL | null): AssetsMetadata;
+
+/**
+ * Canonical and alternate URL metadata types.
+ *
+ * @remarks
+ * URL relationships, internationalization, and special versions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Alternate URL relationship.
+ */
+interface AlternateLink {
+    /** URL of the alternate version */
+    href: string;
+    /** Language/locale code (hreflang) */
+    hreflang?: string;
+    /** MIME type */
+    type?: string;
+    /** Title/description */
+    title?: string;
+}
+/**
+ * App link metadata for deep linking.
+ */
+interface AppLinks {
+    /** iOS app URL */
+    ios?: string;
+    /** Android app URL */
+    android?: string;
+    /** Web fallback URL */
+    web?: string;
+}
+/**
+ * Canonical and alternate URL metadata.
+ *
+ * @remarks
+ * Contains canonical URLs, language alternates, special versions (AMP),
+ * and app linking metadata.
+ */
+interface CanonicalMetadata {
+    /** Canonical URL for this page */
+    canonical?: string;
+    /** Language/region alternates */
+    alternates?: AlternateLink[];
+    /** AMP (Accelerated Mobile Pages) version URL */
+    amphtml?: string;
+    /** Web app manifest URL */
+    manifest?: string;
+    /** App deep linking URLs */
+    appLinks?: AppLinks;
+}
+
+/**
+ * Canonical and alternate URL extraction.
+ *
+ * @remarks
+ * Extracts canonical URLs, alternates, and special versions from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract canonical and alternate URL metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts canonical URLs, language alternates, AMP versions, manifests,
+ * and app linking metadata.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Canonical metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const canonical = extractCanonical(doc);
+ * console.log(canonical.canonical);
+ * console.log(canonical.alternates);
+ * ```
+ */
+declare function extractCanonical(doc: HTMLDocument): CanonicalMetadata;
+
+/**
+ * Copyright and licensing types.
+ *
+ * @remarks
+ * Types for copyright and content licensing information.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Copyright and licensing metadata.
+ *
+ * @remarks
+ * Contains copyright and license information from various sources.
+ */
+interface CopyrightMetadata {
+    /** Copyright notice */
+    copyright?: string;
+    /** License URL or identifier */
+    license?: string;
+    /** Copyright holder/owner */
+    holder?: string;
+    /** Copyright year */
+    year?: string;
+}
+
+/**
+ * Copyright and licensing extraction.
+ *
+ * @remarks
+ * Extracts copyright and license metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract copyright metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts copyright and licensing information from meta tags, link tags,
+ * and Schema.org structured data.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Copyright metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const copyright = extractCopyright(doc);
+ * console.log(copyright.copyright);
+ * console.log(copyright.license);
+ * ```
+ */
+declare function extractCopyright(doc: HTMLDocument): CopyrightMetadata;
+
+/**
+ * Dublin Core metadata types.
+ *
+ * @remarks
+ * Library and academic metadata standard.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Dublin Core metadata extracted from meta tags.
+ *
+ * @remarks
+ * Contains metadata using the Dublin Core standard, commonly used in
+ * academic and library contexts. Supports both DC. and dcterms. prefixes.
+ */
+interface DublinCoreMetadata {
+    /** Resource title */
+    title?: string;
+    /** Entity responsible for making the resource (authors, creators) */
+    creator?: string[];
+    /** Topic or subject of the resource */
+    subject?: string[];
+    /** Description of the resource */
+    description?: string;
+    /** Entity responsible for making the resource available */
+    publisher?: string;
+    /** Entity responsible for contributions to the resource */
+    contributor?: string[];
+    /** Date of resource creation/publication */
+    date?: string;
+    /** Nature or genre of the resource */
+    type?: string;
+    /** File format, physical medium, or dimensions */
+    format?: string;
+    /** Unambiguous reference to the resource */
+    identifier?: string;
+    /** Related resource from which the described resource is derived */
+    source?: string;
+    /** Language of the resource */
+    language?: string;
+    /** Related resource */
+    relation?: string;
+    /** Spatial or temporal topic, location, or period */
+    coverage?: string;
+    /** Information about rights held in and over the resource */
+    rights?: string;
+}
+
+/**
+ * Dublin Core metadata extraction.
+ *
+ * @remarks
+ * Extracts Dublin Core metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract Dublin Core metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts Dublin Core metadata using both DC. and dcterms. prefixes.
+ * Fields that can have multiple values (creator, subject, contributor)
+ * are extracted as arrays.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Dublin Core metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const dc = extractDublinCore(doc);
+ * console.log(dc.title);
+ * console.log(dc.creator);
+ * ```
+ */
+declare function extractDublinCore(doc: HTMLDocument): DublinCoreMetadata;
+
+/**
+ * Feed discovery types.
+ *
+ * @remarks
+ * Types for discovering RSS, Atom, and JSON feeds.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Discovered feed information.
+ */
+interface DiscoveredFeed {
+    /** Feed URL */
+    url: string;
+    /** Feed type */
+    type: 'rss' | 'atom' | 'json' | 'unknown';
+    /** Feed title (if provided in link tag) */
+    title?: string;
+}
+/**
+ * Feed discovery metadata.
+ *
+ * @remarks
+ * Contains all discovered feeds and suggested feed URLs based on common patterns.
+ */
+interface FeedDiscoveryMetadata {
+    /** Feeds explicitly declared in <link> tags */
+    feeds: DiscoveredFeed[];
+    /** Suggested feed URLs based on common patterns (not verified) */
+    suggestions?: string[];
+}
+
+/**
+ * Feed discovery extraction.
+ *
+ * @remarks
+ * Discovers RSS, Atom, and JSON feeds in HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract feed discovery metadata from parsed HTML document.
+ *
+ * @remarks
+ * Finds all feeds declared in <link rel="alternate"> tags and generates
+ * suggestions for common feed URL patterns.
+ *
+ * @param doc - Parsed HTML document
+ * @param documentUrl - Optional document URL for generating absolute feed suggestions
+ * @returns Feed discovery metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const feeds = extractFeedDiscovery(doc, 'https://example.com');
+ * console.log(feeds.feeds); // Discovered feeds
+ * console.log(feeds.suggestions); // Suggested feed URLs
+ * ```
+ */
+declare function extractFeedDiscovery(doc: HTMLDocument, documentUrl?: string | URL): FeedDiscoveryMetadata;
+
+/**
+ * Geographic location types.
+ *
+ * @remarks
+ * Types for geographic location metadata.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Geographic coordinates.
+ *
+ * @remarks
+ * Latitude and longitude coordinates.
+ */
+interface GeoPosition {
+    /** Latitude in decimal degrees */
+    latitude: number;
+    /** Longitude in decimal degrees */
+    longitude: number;
+}
+/**
+ * Geographic metadata.
+ *
+ * @remarks
+ * Contains geographic location information from meta tags.
+ */
+interface GeoMetadata {
+    /** Geographic position (latitude/longitude) */
+    position?: GeoPosition;
+    /** Place name */
+    placename?: string;
+    /** Region code (e.g., US-CA for California, USA) */
+    region?: string;
+    /** Country name or code */
+    country?: string;
+}
+
+/**
+ * Geographic location extraction.
+ *
+ * @remarks
+ * Extracts geographic location metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract geographic metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts geographic location information including coordinates,
+ * place names, and region codes from meta tags.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Geographic metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const geo = extractGeo(doc);
+ * console.log(geo.position?.latitude);
+ * console.log(geo.placename);
+ * ```
+ */
+declare function extractGeo(doc: HTMLDocument): GeoMetadata;
+
+/**
+ * Icons and visual assets types.
+ *
+ * @remarks
+ * Types for favicons, app icons, and visual branding.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Apple touch icon metadata.
+ */
+interface AppleTouchIcon {
+    /** Icon URL */
+    url: string;
+    /** Icon size (e.g., "180x180") */
+    sizes?: string;
+    /** Whether it's precomposed (no effects applied) */
+    precomposed?: boolean;
+}
+/**
+ * Safari mask icon metadata.
+ */
+interface MaskIcon {
+    /** SVG icon URL */
+    url: string;
+    /** Icon color */
+    color?: string;
+}
+/**
+ * Microsoft tile metadata.
+ */
+interface MSTile {
+    /** Tile image URL */
+    image?: string;
+    /** Tile background color */
+    color?: string;
+    /** Microsoft browserconfig XML URL */
+    config?: string;
+}
+/**
+ * Icons and visual assets metadata.
+ *
+ * @remarks
+ * Contains all icon-related metadata including favicons, app icons,
+ * and platform-specific icons.
+ */
+interface IconsMetadata {
+    /** Standard favicon */
+    favicon?: string;
+    /** Shortcut icon (legacy) */
+    shortcutIcon?: string;
+    /** Apple touch icons for iOS */
+    appleTouchIcons?: AppleTouchIcon[];
+    /** Safari pinned tab icon */
+    maskIcon?: MaskIcon;
+    /** Microsoft tile configuration */
+    msTile?: MSTile;
+    /** Fluid icon (legacy) */
+    fluidIcon?: string;
+}
+
+/**
+ * Icons and visual assets extraction.
+ *
+ * @remarks
+ * Extracts icon metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract icons metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts all icon-related metadata including favicons, Apple touch icons,
+ * Safari mask icons, and Microsoft tile configuration.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Icons metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const icons = extractIcons(doc);
+ * console.log(icons.favicon);
+ * console.log(icons.appleTouchIcons);
+ * ```
+ */
+declare function extractIcons(doc: HTMLDocument): IconsMetadata;
+
+/**
+ * Language and localization types.
+ *
+ * @remarks
+ * Types for language and locale metadata.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Language and localization metadata.
+ *
+ * @remarks
+ * Contains language and locale information from various sources including
+ * HTML lang attribute, meta tags, and OpenGraph locale.
+ */
+interface LanguageMetadata {
+    /** HTML lang attribute from <html> tag */
+    htmlLang?: string;
+    /** Content-Language meta tag */
+    contentLanguage?: string;
+    /** OpenGraph locale */
+    ogLocale?: string;
+    /** OpenGraph alternate locales */
+    alternateLocales?: string[];
+    /** Primary language (best guess, normalized to ISO 639-1) */
+    primary?: string;
+    /** Region code (if available, ISO 3166-1 alpha-2) */
+    region?: string;
+}
+
+/**
+ * Language and localization extraction.
+ *
+ * @remarks
+ * Extracts language and locale metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract language and localization metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts language information from HTML lang attribute, meta tags,
+ * and OpenGraph locale. Normalizes to provide a primary language and region.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Language metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const lang = extractLanguage(doc);
+ * console.log(lang.primary); // 'en'
+ * console.log(lang.region); // 'US'
+ * ```
+ */
+declare function extractLanguage(doc: HTMLDocument): LanguageMetadata;
+
+/**
+ * Links extraction types.
+ *
+ * @remarks
+ * Types for navigational link extraction and analysis.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extracted link with metadata.
+ *
+ * @remarks
+ * Represents a single hyperlink with all relevant attributes.
+ * URLs are normalized to absolute format if a base URL is available.
+ */
+interface ExtractedLink {
+    /** Absolute URL of the link */
+    url: string;
+    /** Anchor text (visible text content) */
+    text?: string;
+    /** Title attribute */
+    title?: string;
+    /** Rel attribute value */
+    rel?: string;
+    /** Target attribute (_blank, _self, etc.) */
+    target?: string;
+    /** Whether this is an internal link (same origin) */
+    internal?: boolean;
+    /** Whether this is an external link (different origin) */
+    external?: boolean;
+    /** Whether link has nofollow rel */
+    nofollow?: boolean;
+    /** Whether link has ugc (User Generated Content) rel */
+    ugc?: boolean;
+    /** Whether link has sponsored rel */
+    sponsored?: boolean;
+    /** Whether link has noopener rel */
+    noopener?: boolean;
+    /** Whether link has noreferrer rel */
+    noreferrer?: boolean;
+}
+/**
+ * Links extraction options.
+ */
+interface LinksExtractionOptions {
+    /**
+     * Filter links by scope.
+     *
+     * @remarks
+     * - `'all'` - Return all links (default)
+     * - `'internal'` - Only links to same origin
+     * - `'external'` - Only links to different origins
+     */
+    scope?: 'all' | 'internal' | 'external';
+    /**
+     * Filter out links with specific rel attributes.
+     *
+     * @remarks
+     * Useful for crawlers to skip nofollow, sponsored, or UGC links.
+     *
+     * @example
+     * ```typescript
+     * // Skip nofollow and sponsored links
+     * { excludeRel: ['nofollow', 'sponsored'] }
+     * ```
+     */
+    excludeRel?: Array<'nofollow' | 'noopener' | 'noreferrer' | 'ugc' | 'sponsored'>;
+    /**
+     * Include only links with specific rel attributes.
+     *
+     * @remarks
+     * If specified, only links matching these rel values are included.
+     */
+    includeRel?: Array<'nofollow' | 'noopener' | 'noreferrer' | 'ugc' | 'sponsored'>;
+    /**
+     * Whether to include hash-only links (#anchor).
+     *
+     * @default false
+     */
+    includeHashLinks?: boolean;
+    /**
+     * Whether to deduplicate URLs.
+     *
+     * @remarks
+     * If true, only unique URLs are returned (keeps first occurrence).
+     *
+     * @default true
+     */
+    deduplicate?: boolean;
+    /**
+     * Maximum number of links to extract.
+     *
+     * @remarks
+     * Useful for limiting extraction on large pages.
+     */
+    limit?: number;
+}
+/**
+ * Links metadata extracted from HTML.
+ *
+ * @remarks
+ * Contains categorized and analyzed links from the document.
+ */
+interface LinksMetadata {
+    /** All extracted links */
+    all?: ExtractedLink[];
+    /** Internal links (same origin) */
+    internal?: ExtractedLink[];
+    /** External links (different origin) */
+    external?: ExtractedLink[];
+    /** Links with nofollow rel */
+    nofollow?: ExtractedLink[];
+    /** Total count of links found */
+    totalCount?: number;
+    /** Count of internal links */
+    internalCount?: number;
+    /** Count of external links */
+    externalCount?: number;
+    /** Count of nofollow links */
+    nofollowCount?: number;
+}
+
+/**
+ * Links extraction.
+ *
+ * @remarks
+ * Extract navigational links from HTML documents with advanced filtering
+ * and categorization for crawler and SEO use cases.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract links from parsed HTML document.
+ *
+ * @remarks
+ * Extracts all `<a href>` links with comprehensive metadata and filtering options.
+ * Perfect for crawlers, SEO analysis, and link discovery.
+ *
+ * Features:
+ * - Internal/external link categorization
+ * - Rel attribute filtering (nofollow, ugc, sponsored, etc.)
+ * - Automatic URL normalization
+ * - Hash link filtering
+ * - Scheme filtering (only http/https)
+ * - Deduplication
+ * - Link text extraction
+ *
+ * @param doc - Parsed HTML document
+ * @param baseUrl - Base URL for resolving relative links and determining internal/external
+ * @param options - Extraction options for filtering and categorization
+ * @returns Links metadata with categorized links
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const links = extractLinks(doc, 'https://example.com');
+ *
+ * // Get all internal links (same origin)
+ * console.log(links.internal);
+ *
+ * // Get external links excluding nofollow
+ * const linksNoFollow = extractLinks(doc, 'https://example.com', {
+ *   scope: 'external',
+ *   excludeRel: ['nofollow']
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Crawler use case - get follow-able links
+ * const links = extractLinks(doc, baseUrl, {
+ *   excludeRel: ['nofollow', 'ugc', 'sponsored'],
+ *   includeHashLinks: false
+ * });
+ * ```
+ */
+declare function extractLinks(doc: HTMLDocument, baseUrl?: string | URL | null, options?: LinksExtractionOptions): LinksMetadata;
+
+/**
+ * Monetization and payment types.
+ *
+ * @remarks
+ * Types for web monetization and payment metadata.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Monetization metadata.
+ *
+ * @remarks
+ * Contains web monetization and payment verification metadata.
+ */
+interface MonetizationMetadata {
+    /** Web Monetization API payment pointer */
+    webMonetization?: string;
+    /** PayPal site verification token */
+    paypalVerification?: string;
+    /** Brave Creator verification token */
+    braveCreator?: string;
+    /** Coil payment pointer (legacy) */
+    coil?: string;
+    /** Bitcoin address */
+    bitcoin?: string;
+    /** Ethereum address */
+    ethereum?: string;
+}
+
+/**
+ * Monetization and payment extraction.
+ *
+ * @remarks
+ * Extracts web monetization and payment metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract monetization metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts web monetization, payment verification, and cryptocurrency
+ * addresses from meta tags and link tags.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Monetization metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const monetization = extractMonetization(doc);
+ * console.log(monetization.webMonetization);
+ * console.log(monetization.bitcoin);
+ * ```
+ */
+declare function extractMonetization(doc: HTMLDocument): MonetizationMetadata;
+
+/**
+ * News and press types.
+ *
+ * @remarks
+ * Types for news-specific metadata.
+ *
+ * @packageDocumentation
+ */
+/**
+ * News metadata.
+ *
+ * @remarks
+ * Contains news-specific metadata for articles and press releases.
+ */
+interface NewsMetadata {
+    /** News keywords (distinct from regular keywords) */
+    keywords?: string[];
+    /** Google News standout tag (indicates exceptional journalism) */
+    standout?: string;
+    /** Syndication source (original publisher) */
+    syndicationSource?: string;
+    /** Original source URL */
+    originalSource?: string;
+}
+
+/**
+ * News and press extraction.
+ *
+ * @remarks
+ * Extracts news-specific metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract news metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts news-specific metadata including keywords, standout tags,
+ * and syndication information.
+ *
+ * @param doc - Parsed HTML document
+ * @returns News metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const news = extractNews(doc);
+ * console.log(news.keywords);
+ * console.log(news.standout);
+ * ```
+ */
+declare function extractNews(doc: HTMLDocument): NewsMetadata;
+
+/**
+ * OpenGraph metadata types.
+ *
+ * @remarks
+ * Facebook's Open Graph protocol for rich social sharing.
+ *
+ * @packageDocumentation
+ */
+/**
+ * OpenGraph article metadata.
+ */
+interface OpenGraphArticle {
+    /** Publication date */
+    publishedTime?: string;
+    /** Last modification date */
+    modifiedTime?: string;
+    /** Expiration date */
+    expirationTime?: string;
+    /** Article authors */
+    authors?: string[];
+    /** Article section/category */
+    section?: string;
+    /** Article tags */
+    tags?: string[];
+}
+/**
+ * OpenGraph video metadata.
+ */
+interface OpenGraphVideo {
+    /** Video URL */
+    url?: string;
+    /** HTTPS video URL */
+    secureUrl?: string;
+    /** MIME type */
+    type?: string;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+    /** Video duration in seconds */
+    duration?: number;
+    /** Release date */
+    releaseDate?: string;
+    /** Video tags */
+    tags?: string[];
+}
+/**
+ * OpenGraph audio metadata.
+ */
+interface OpenGraphAudio {
+    /** Audio URL */
+    url?: string;
+    /** HTTPS audio URL */
+    secureUrl?: string;
+    /** MIME type */
+    type?: string;
+}
+/**
+ * OpenGraph image metadata.
+ */
+interface OpenGraphImage {
+    /** Image URL */
+    url: string;
+    /** HTTPS image URL */
+    secureUrl?: string;
+    /** MIME type */
+    type?: string;
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+    /** Alt text */
+    alt?: string;
+}
+/**
+ * OpenGraph book metadata.
+ */
+interface OpenGraphBook {
+    /** Book authors */
+    authors?: string[];
+    /** ISBN number */
+    isbn?: string;
+    /** Release date */
+    releaseDate?: string;
+    /** Book tags */
+    tags?: string[];
+}
+/**
+ * OpenGraph profile metadata.
+ */
+interface OpenGraphProfile {
+    /** First name */
+    firstName?: string;
+    /** Last name */
+    lastName?: string;
+    /** Username */
+    username?: string;
+    /** Gender */
+    gender?: string;
+}
+/**
+ * OpenGraph metadata extracted from meta tags.
+ *
+ * @remarks
+ * Contains metadata from the Open Graph protocol used for rich social sharing.
+ * All fields are optional - only present if found in the document.
+ */
+interface OpenGraphMetadata {
+    /** Content title */
+    title?: string;
+    /** Content type (article, website, video, etc.) */
+    type?: string;
+    /** Preview image URL (primary image) */
+    image?: string;
+    /** Canonical URL */
+    url?: string;
+    /** Content description */
+    description?: string;
+    /** Site name */
+    siteName?: string;
+    /** Content locale (e.g., en_US) */
+    locale?: string;
+    /** Alternate locales */
+    localeAlternate?: string[];
+    /** Article-specific metadata (if type is article) */
+    article?: OpenGraphArticle;
+    /** Video metadata (if type is video or video present) */
+    video?: OpenGraphVideo;
+    /** Audio metadata (if audio present) */
+    audio?: OpenGraphAudio;
+    /** All images with full metadata (if multiple images) */
+    images?: OpenGraphImage[];
+    /** Book metadata (if type is book) */
+    book?: OpenGraphBook;
+    /** Profile metadata (if type is profile) */
+    profile?: OpenGraphProfile;
+}
+
+/**
+ * OpenGraph metadata extraction.
+ *
+ * @remarks
+ * Extracts Open Graph protocol metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract OpenGraph metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts Open Graph protocol metadata including basic metadata,
+ * article data, video/audio, images, books, and profiles.
+ *
+ * @param doc - Parsed HTML document
+ * @returns OpenGraph metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const og = extractOpenGraph(doc);
+ * console.log(og.title);
+ * console.log(og.image);
+ * console.log(og.article?.publishedTime);
+ * ```
+ */
+declare function extractOpenGraph(doc: HTMLDocument): OpenGraphMetadata;
+
+/**
+ * Pagination metadata types.
+ *
+ * @remarks
+ * Types for multi-page content navigation.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Pagination metadata.
+ *
+ * @remarks
+ * Contains navigation links for multi-page content series.
+ */
+interface PaginationMetadata {
+    /** Previous page URL */
+    prev?: string;
+    /** Next page URL */
+    next?: string;
+    /** First page URL */
+    first?: string;
+    /** Last page URL */
+    last?: string;
+    /** Parent/up level URL */
+    up?: string;
+    /** Index/table of contents URL */
+    index?: string;
+}
+
+/**
+ * Pagination metadata extraction.
+ *
+ * @remarks
+ * Extracts pagination navigation links from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract pagination metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts pagination navigation links including prev, next, first, last,
+ * up (parent), and index links.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Pagination metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const pagination = extractPagination(doc);
+ * console.log(pagination.prev); // Previous page URL
+ * console.log(pagination.next); // Next page URL
+ * ```
+ */
+declare function extractPagination(doc: HTMLDocument): PaginationMetadata;
+
+/**
+ * Robots and crawling directives types.
+ *
+ * @remarks
+ * Types for robot crawling and indexing directives.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parsed robot directives.
+ */
+interface RobotDirectives {
+    /** Allow indexing */
+    index?: boolean;
+    /** Allow following links */
+    follow?: boolean;
+    /** Prevent archiving/caching */
+    noarchive?: boolean;
+    /** Prevent showing snippets */
+    nosnippet?: boolean;
+    /** Prevent indexing images */
+    noimageindex?: boolean;
+    /** Maximum snippet length (characters) */
+    maxSnippet?: number;
+    /** Maximum image preview size */
+    maxImagePreview?: string;
+    /** Maximum video preview length (seconds) */
+    maxVideoPreview?: number;
+    /** Prevent translation */
+    notranslate?: boolean;
+    /** Date after which content is unavailable */
+    unavailableAfter?: string;
+}
+/**
+ * Robots and crawling metadata.
+ *
+ * @remarks
+ * Contains robot directives for search engines and crawlers.
+ */
+interface RobotsMetadata {
+    /** General robots directives */
+    robots?: RobotDirectives;
+    /** Google-specific directives */
+    googlebot?: RobotDirectives;
+    /** Bing-specific directives */
+    bingbot?: RobotDirectives;
+    /** Google News-specific directives */
+    googlebotNews?: RobotDirectives;
+}
+
+/**
+ * Robots and crawling directives extraction.
+ *
+ * @remarks
+ * Extracts robot crawling and indexing directives from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract robots metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts robot directives from meta tags for general robots,
+ * Googlebot, Bingbot, and Google News bot.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Robots metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const robots = extractRobots(doc);
+ * console.log(robots.robots?.index); // true/false
+ * console.log(robots.robots?.follow); // true/false
+ * ```
+ */
+declare function extractRobots(doc: HTMLDocument): RobotsMetadata;
+
+/**
+ * Schema.org / JSON-LD metadata types.
+ *
+ * @remarks
+ * Structured data for search engines and rich snippets using JSON-LD format.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single JSON-LD block found in the document.
+ */
+interface JsonLdBlock {
+    /** Original JSON string */
+    raw: string;
+    /** Parsed JSON object */
+    parsed: unknown;
+    /** @type field(s) from the JSON-LD */
+    type?: string | string[];
+    /** JSON-LD context field */
+    context?: string | unknown;
+}
+/**
+ * Schema.org metadata extracted from JSON-LD scripts.
+ *
+ * @remarks
+ * Contains all JSON-LD structured data blocks found in the document.
+ * Provides convenience accessors for common types.
+ */
+interface SchemaOrgMetadata {
+    /** All JSON-LD blocks found in the document */
+    jsonLd: JsonLdBlock[];
+    /** Convenience: Article/NewsArticle/BlogPosting types */
+    articles?: unknown[];
+    /** Convenience: WebPage/WebSite types */
+    webPages?: unknown[];
+    /** Convenience: BreadcrumbList type */
+    breadcrumbs?: unknown[];
+    /** Convenience: Organization type */
+    organization?: unknown;
+    /** Convenience: Person type */
+    person?: unknown;
+    /** Convenience: Product types */
+    products?: unknown[];
+    /** Convenience: Event types */
+    events?: unknown[];
+    /** Convenience: Recipe types */
+    recipes?: unknown[];
+    /** Convenience: VideoObject types */
+    videos?: unknown[];
+    /** Convenience: ImageObject types */
+    images?: unknown[];
+}
+
+/**
+ * Schema.org / JSON-LD extraction.
+ *
+ * @remarks
+ * Extracts structured data from JSON-LD script tags.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract Schema.org metadata from parsed HTML document.
+ *
+ * @remarks
+ * Finds all <script type="application/ld+json"> tags, parses the JSON-LD,
+ * and organizes by type for easy access.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Schema.org metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const schema = extractSchemaOrg(doc);
+ * console.log(schema.jsonLd.length);
+ * console.log(schema.articles);
+ * ```
+ */
+declare function extractSchemaOrg(doc: HTMLDocument): SchemaOrgMetadata;
+
+/**
+ * Security and privacy types.
+ *
+ * @remarks
+ * Types for security and privacy-related metadata.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Security metadata.
+ *
+ * @remarks
+ * Contains security and privacy-related headers and meta tags.
+ */
+interface SecurityMetadata {
+    /** Referrer policy (controls Referer header) */
+    referrerPolicy?: string;
+    /** Content Security Policy directives */
+    contentSecurityPolicy?: string;
+    /** X-UA-Compatible directive (IE compatibility mode) */
+    xUaCompatible?: string;
+    /** Format detection (phone numbers, dates, etc.) */
+    formatDetection?: string;
+}
+
+/**
+ * Security and privacy extraction.
+ *
+ * @remarks
+ * Extracts security and privacy-related metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract security metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts security and privacy-related meta tags including referrer policy,
+ * content security policy, and browser compatibility directives.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Security metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const security = extractSecurity(doc);
+ * console.log(security.referrerPolicy);
+ * console.log(security.contentSecurityPolicy);
+ * ```
+ */
+declare function extractSecurity(doc: HTMLDocument): SecurityMetadata;
+
+/**
+ * SEO metadata types.
+ *
+ * @remarks
+ * Standard HTML meta tags used by search engines and browsers.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Basic SEO metadata extracted from standard HTML meta tags.
+ *
+ * @remarks
+ * Contains metadata from common SEO-related meta tags including
+ * title, description, keywords, and browser-specific tags.
+ */
+interface SEOMetadata {
+    /** Page title from <title> tag */
+    title?: string;
+    /** Meta description for search results */
+    description?: string;
+    /** Keywords (legacy but still used) */
+    keywords?: string[];
+    /** Page author */
+    author?: string;
+    /** Site generator (e.g., WordPress, Hugo) */
+    generator?: string;
+    /** Viewport settings */
+    viewport?: string;
+    /** Browser theme color */
+    themeColor?: string;
+    /** Color scheme preference (light, dark, auto) */
+    colorScheme?: string;
+    /** Web application name */
+    applicationName?: string;
+    /** iOS web app title */
+    appleMobileWebAppTitle?: string;
+    /** iOS web app capable (standalone mode) */
+    appleMobileWebAppCapable?: boolean;
+    /** iOS status bar style */
+    appleMobileWebAppStatusBarStyle?: string;
+}
+
+/**
+ * SEO metadata extraction.
+ *
+ * @remarks
+ * Extracts standard SEO meta tags from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract SEO metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts standard SEO meta tags including title, description, keywords,
+ * and browser-specific configuration. All fields are optional.
+ *
+ * @param doc - Parsed HTML document
+ * @returns SEO metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const seo = extractSEO(doc);
+ * console.log(seo.title); // Page title
+ * console.log(seo.description); // Meta description
+ * ```
+ */
+declare function extractSEO(doc: HTMLDocument): SEOMetadata;
+
+/**
+ * Sitemap discovery types.
+ *
+ * @remarks
+ * Types for discovering XML sitemaps and sitemap indexes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Sitemap discovery metadata.
+ *
+ * @remarks
+ * Contains discovered sitemaps from <link> tags and suggested common sitemap URLs.
+ */
+interface SitemapDiscoveryMetadata {
+    /** Sitemaps explicitly declared in <link rel="sitemap"> tags */
+    sitemaps: string[];
+    /** Suggested sitemap URLs based on common patterns (not verified) */
+    suggestions?: string[];
+}
+
+/**
+ * Sitemap discovery extraction.
+ *
+ * @remarks
+ * Discovers XML sitemaps in HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract sitemap discovery metadata from parsed HTML document.
+ *
+ * @remarks
+ * Finds all sitemaps declared in <link rel="sitemap"> tags and generates
+ * suggestions for common sitemap URL patterns.
+ *
+ * @param doc - Parsed HTML document
+ * @param documentUrl - Optional document URL for generating absolute sitemap suggestions
+ * @returns Sitemap discovery metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const sitemaps = extractSitemapDiscovery(doc, 'https://example.com');
+ * console.log(sitemaps.sitemaps); // Discovered sitemaps
+ * console.log(sitemaps.suggestions); // Suggested sitemap URLs
+ * ```
+ */
+declare function extractSitemapDiscovery(doc: HTMLDocument, documentUrl?: string | URL): SitemapDiscoveryMetadata;
+
+/**
+ * Social profiles types.
+ *
+ * @remarks
+ * Types for social media profile links.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Social profile metadata.
+ *
+ * @remarks
+ * Contains social media profile URLs and handles from various platforms.
+ */
+interface SocialProfilesMetadata {
+    /** Twitter/X username (without @) */
+    twitter?: string;
+    /** Facebook profile/page URL */
+    facebook?: string;
+    /** Instagram username or URL */
+    instagram?: string;
+    /** LinkedIn profile/company URL */
+    linkedin?: string;
+    /** YouTube channel URL */
+    youtube?: string;
+    /** GitHub username or organization URL */
+    github?: string;
+    /** TikTok username or URL */
+    tiktok?: string;
+    /** Pinterest username or URL */
+    pinterest?: string;
+    /** Mastodon profile URL */
+    mastodon?: string;
+    /** Reddit username or URL */
+    reddit?: string;
+    /** Other social profiles (platform: url/username) */
+    other?: Record<string, string>;
+}
+
+/**
+ * Social profiles extraction.
+ *
+ * @remarks
+ * Extracts social media profile links from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract social profiles metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts social media profile URLs and handles from meta tags and structured data.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Social profiles metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const profiles = extractSocialProfiles(doc);
+ * console.log(profiles.twitter);
+ * console.log(profiles.facebook);
+ * ```
+ */
+declare function extractSocialProfiles(doc: HTMLDocument): SocialProfilesMetadata;
+
+/**
+ * Twitter Card metadata types.
+ *
+ * @remarks
+ * Twitter-specific metadata for rich cards.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Twitter app card metadata for a specific platform.
+ */
+interface TwitterAppPlatform {
+    /** App name */
+    name?: string;
+    /** App ID */
+    id?: string;
+    /** App URL/deep link */
+    url?: string;
+}
+/**
+ * Twitter app card metadata.
+ */
+interface TwitterApp {
+    /** iPhone app details */
+    iphone?: TwitterAppPlatform;
+    /** iPad app details */
+    ipad?: TwitterAppPlatform;
+    /** Google Play app details */
+    googleplay?: TwitterAppPlatform;
+}
+/**
+ * Twitter player card metadata.
+ */
+interface TwitterPlayer {
+    /** Player URL */
+    url?: string;
+    /** Player width in pixels */
+    width?: number;
+    /** Player height in pixels */
+    height?: number;
+    /** Stream URL */
+    stream?: string;
+}
+/**
+ * Twitter Card metadata extracted from meta tags.
+ *
+ * @remarks
+ * Contains metadata for Twitter Cards used for rich social sharing on Twitter.
+ * All fields are optional - only present if found in the document.
+ */
+interface TwitterCardMetadata {
+    /** Card type (summary, summary_large_image, app, player) */
+    card?: 'summary' | 'summary_large_image' | 'app' | 'player' | string;
+    /** Twitter username of website (with or without @ symbol) */
+    site?: string;
+    /** Twitter username of content creator (with or without @ symbol) */
+    creator?: string;
+    /** Content title (max 70 chars) */
+    title?: string;
+    /** Content description (max 200 chars) */
+    description?: string;
+    /** Image URL */
+    image?: string;
+    /** Image alt text */
+    imageAlt?: string;
+    /** App card details (if card type is 'app') */
+    app?: TwitterApp;
+    /** Player card details (if card type is 'player') */
+    player?: TwitterPlayer;
+}
+
+/**
+ * Twitter Card metadata extraction.
+ *
+ * @remarks
+ * Extracts Twitter Card metadata from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract Twitter Card metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts Twitter Card metadata including card type, site/creator info,
+ * title/description, images, app cards, and player cards.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Twitter Card metadata object
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const twitter = extractTwitterCard(doc);
+ * console.log(twitter.card);
+ * console.log(twitter.title);
+ * ```
+ */
+declare function extractTwitterCard(doc: HTMLDocument): TwitterCardMetadata;
+
+/**
+ * Verification tags types.
+ *
+ * @remarks
+ * Types for domain and ownership verification tags.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Verification metadata.
+ *
+ * @remarks
+ * Contains verification tags from various platforms for domain and ownership verification.
+ */
+interface VerificationMetadata {
+    /** Google Site Verification token */
+    googleSiteVerification?: string;
+    /** Bing/Microsoft verification token */
+    msvalidate?: string;
+    /** Yandex verification token */
+    yandexVerification?: string;
+    /** Facebook domain verification token */
+    facebookDomainVerification?: string;
+    /** Pinterest domain verification token */
+    pinterestVerification?: string;
+    /** Alexa verification token */
+    alexaVerification?: string;
+    /** Norton Safe Web verification token */
+    nortonSafeWeb?: string;
+    /** Other verification tags (platform: token) */
+    other?: Record<string, string>;
+}
+
+/**
+ * Verification tags extraction.
+ *
+ * @remarks
+ * Extracts domain and ownership verification tags from HTML documents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract verification metadata from parsed HTML document.
+ *
+ * @remarks
+ * Extracts verification tags used by various platforms for domain and ownership verification.
+ *
+ * @param doc - Parsed HTML document
+ * @returns Verification metadata
+ *
+ * @example
+ * ```typescript
+ * const doc = parseHTML(htmlString);
+ * const verification = extractVerification(doc);
+ * console.log(verification.googleSiteVerification);
+ * console.log(verification.facebookDomainVerification);
+ * ```
+ */
+declare function extractVerification(doc: HTMLDocument): VerificationMetadata;
+
+/**
+ * Enhanced fetch types for web scraping.
+ *
+ * @remarks
+ * Types for pluck() - fetch-compatible enhanced HTTP client.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extended RequestInit with pluck-specific options.
+ *
+ * @remarks
+ * Extends standard fetch RequestInit with additional options for
+ * robust web scraping. All standard fetch options are supported.
+ */
+interface PluckInit extends RequestInit {
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of redirects to follow.
+     *
+     * @default 10
+     */
+    maxRedirects?: number;
+    /**
+     * Maximum response size in bytes.
+     *
+     * @default 10485760 (10MB)
+     */
+    maxSize?: number;
+    /**
+     * User-Agent header shortcut.
+     *
+     * @remarks
+     * Convenience property that sets the User-Agent header.
+     * Overrides any User-Agent in the headers object.
+     */
+    userAgent?: string;
+    /**
+     * Throw error on HTTP error status (4xx, 5xx).
+     *
+     * @default true
+     */
+    throwOnHttpError?: boolean;
+    /**
+     * Validate Content-Type header.
+     *
+     * @remarks
+     * If true, throws error if Content-Type is not in allowedContentTypes.
+     *
+     * @default false
+     */
+    strictContentType?: boolean;
+    /**
+     * Allowed Content-Type values for strictContentType.
+     *
+     * @default ['text/html', 'text/xml', 'application/xml', 'application/xhtml+xml', 'application/rss+xml', 'application/atom+xml', 'application/json']
+     */
+    allowedContentTypes?: string[];
+    /**
+     * Follow redirects automatically.
+     *
+     * @remarks
+     * If false, returns the 3xx response directly without following.
+     *
+     * @default true
+     */
+    followRedirects?: boolean;
+    /**
+     * Validate detected encoding.
+     *
+     * @remarks
+     * If true, throws error if detected encoding is invalid or unsupported.
+     *
+     * @default true
+     */
+    validateEncoding?: boolean;
+}
+/**
+ * Enhanced Response with pluck-specific properties.
+ *
+ * @remarks
+ * Extends standard Response with additional metadata about the request.
+ * All standard Response properties and methods are available.
+ */
+interface PluckResponse extends Response {
+    /**
+     * Final URL after following redirects.
+     */
+    finalUrl: string;
+    /**
+     * Original request URL.
+     */
+    originalUrl: string;
+    /**
+     * Array of redirect URLs (excluding original and final).
+     */
+    redirectChain: string[];
+    /**
+     * Detected character encoding.
+     *
+     * @example 'utf-8', 'windows-1252', 'iso-8859-1'
+     */
+    detectedEncoding: string;
+    /**
+     * Request timing information.
+     */
+    timing: {
+        /** Request start timestamp (milliseconds since epoch) */
+        start: number;
+        /** Request end timestamp (milliseconds since epoch) */
+        end: number;
+        /** Total duration in milliseconds */
+        duration: number;
+        /** Time spent in redirects (milliseconds) */
+        redirectDuration?: number;
+    };
+    /**
+     * Get response body as UTF-8 text.
+     *
+     * @remarks
+     * Unlike standard text(), this guarantees UTF-8 output regardless
+     * of the source encoding. Uses detected encoding to decode properly.
+     *
+     * @returns UTF-8 decoded text
+     */
+    textUtf8(): Promise<string>;
+}
+/**
+ * Base error class for pluck errors.
+ */
+declare class PluckError extends Error {
+    constructor(message: string);
+}
+/**
+ * Network error (connection failed, DNS, etc.).
+ */
+declare class PluckNetworkError extends PluckError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Request timeout error.
+ */
+declare class PluckTimeoutError extends PluckError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/**
+ * HTTP error (4xx, 5xx status codes).
+ */
+declare class PluckHttpError extends PluckError {
+    readonly statusCode: number;
+    readonly statusText: string;
+    readonly response: Response;
+    constructor(message: string, statusCode: number, statusText: string, response: Response);
+}
+/**
+ * Response size exceeded maximum.
+ */
+declare class PluckSizeError extends PluckError {
+    readonly maxSize: number;
+    readonly actualSize?: number | undefined;
+    constructor(message: string, maxSize: number, actualSize?: number | undefined);
+}
+/**
+ * Encoding detection or conversion error.
+ */
+declare class PluckEncodingError extends PluckError {
+    readonly encoding?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, encoding?: string | undefined, cause?: Error | undefined);
+}
+/**
+ * Too many redirects or redirect loop detected.
+ */
+declare class PluckRedirectError extends PluckError {
+    readonly redirectChain: string[];
+    readonly maxRedirects?: number | undefined;
+    constructor(message: string, redirectChain: string[], maxRedirects?: number | undefined);
+}
+/**
+ * Invalid or disallowed Content-Type.
+ */
+declare class PluckContentTypeError extends PluckError {
+    readonly contentType: string;
+    readonly allowedTypes?: string[] | undefined;
+    constructor(message: string, contentType: string, allowedTypes?: string[] | undefined);
+}
+
+/**
+ * Enhanced fetch for web scraping.
+ *
+ * @remarks
+ * fetch-compatible HTTP client with robust handling of real-world web content.
+ *
+ * @author Anonyfox <max@anonyfox.com>
+ * @license MIT
+ * @see {@link https://github.com/Anonyfox/ravenjs}
+ * @see {@link https://ravenjs.dev}
+ * @see {@link https://anonyfox.com}
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Enhanced fetch for web scraping.
+ *
+ * @remarks
+ * Drop-in replacement for fetch() with enhanced error handling, encoding detection,
+ * redirect tracking, and size limits. Perfect for scraping HTML, feeds, and APIs.
+ *
+ * Features:
+ * - Manual redirect tracking with full chain
+ * - Automatic encoding detection and UTF-8 conversion
+ * - Configurable timeouts and size limits
+ * - Smart default headers for web scraping
+ * - Content-Type validation
+ * - Comprehensive error types
+ *
+ * @param input - URL string or Request object
+ * @param init - Request options (extends standard RequestInit)
+ * @returns Enhanced Response with additional metadata
+ * @throws {PluckTimeoutError} Request timeout
+ * @throws {PluckNetworkError} Network or DNS error
+ * @throws {PluckHttpError} HTTP error status (4xx, 5xx)
+ * @throws {PluckRedirectError} Too many redirects or loop
+ * @throws {PluckSizeError} Response too large
+ * @throws {PluckEncodingError} Invalid encoding
+ * @throws {PluckContentTypeError} Invalid content type
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (works like fetch)
+ * const response = await pluck('https://example.com');
+ * const html = await response.text();
+ *
+ * // With enhancements
+ * console.log(response.redirectChain);
+ * console.log(response.detectedEncoding);
+ * console.log(response.timing);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const response = await pluck('https://example.com', {
+ *   timeout: 60000,
+ *   maxRedirects: 5,
+ *   userAgent: 'MyBot/1.0',
+ *   throwOnHttpError: true
+ * });
+ * ```
+ */
+declare function pluck(input: string | URL | Request, init?: PluckInit): Promise<PluckResponse>;
+
+export { type AlternateLink, type AnalyticsMetadata, type AppLinks, type AppleTouchIcon, type Article, type AssetsMetadata, type CanonicalMetadata, type ConnectionHint, type ContentExtractionOptions, type ContentQuality, type ContentResult, type CopyrightMetadata, type DiscoveredFeed, type DublinCoreMetadata, type ExtractedContent, type ExtractedLink, type ExtractionErrorType, type ExtractionFailure, type Feed, type FeedAuthor, type FeedDiscoveryMetadata, type FeedEnclosure, type FeedFormat, type FeedItem, type GeoMetadata, type GeoPosition, type HTMLDocument, type HtmlToTextOptions, type IconsMetadata, type JsonLdBlock, type LanguageMetadata, type LinksExtractionOptions, type LinksMetadata, type MSTile, type MaskIcon, type MonetizationMetadata, type NewsMetadata, type OpenGraphArticle, type OpenGraphAudio, type OpenGraphBook, type OpenGraphImage, type OpenGraphMetadata, type OpenGraphProfile, type OpenGraphVideo, type PaginationMetadata, type ParseResult, PluckContentTypeError, PluckEncodingError, PluckError, PluckHttpError, type PluckInit, PluckNetworkError, PluckRedirectError, type PluckResponse, PluckSizeError, PluckTimeoutError, type PreloadResource, type RobotDirectives, type RobotsMetadata, type SEOMetadata, type SchemaOrgMetadata, type SecurityMetadata, type SitemapDiscoveryMetadata, type SocialProfilesMetadata, type TwitterApp, type TwitterAppPlatform, type TwitterCardMetadata, type TwitterPlayer, type VerificationMetadata, type Website, assessContentQuality, calculateReadingTime, countWords, detectFormat, extractAnalytics, extractAssets, extractCanonical, extractContent, extractCopyright, extractDublinCore, extractFeedDiscovery, extractGeo, extractIcons, extractLanguage, extractLinks, extractMonetization, extractNews, extractOpenGraph, extractPagination, extractRobots, extractSEO, extractSchemaOrg, extractSecurity, extractSitemapDiscovery, extractSocialProfiles, extractTwitterCard, extractVerification, gatherArticle, gatherFeed, gatherWebsite, htmlToText, isAtom, isFeed, isJSONFeed, isProbablyReaderable, isRSS, parseFeed, parseHTML, pluck };