magpie-html 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -3069,4 +3069,187 @@ declare class PluckContentTypeError extends PluckError {
  */
 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 };
+/**
+ * Base error type for `swoop()`.
+ */
+declare class SwoopError extends Error {
+    name: string;
+}
+/**
+ * Thrown when the current runtime cannot execute `swoop()`.
+ */
+declare class SwoopEnvironmentError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when `swoop()` exceeds its configured timeout.
+ */
+declare class SwoopTimeoutError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when script execution fails in a non-recoverable way.
+ */
+declare class SwoopExecutionError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when `swoop()` is asked to execute potentially unsafe scripts
+ * in a context where the caller should explicitly acknowledge the risk.
+ */
+declare class SwoopSecurityError extends SwoopError {
+    name: string;
+}
+
+/**
+ * How `swoop()` decides when a client-rendered page is "done enough" to snapshot.
+ *
+ * @remarks
+ * This is DOM-only rendering (no layout/paint). "Done" is best-effort.
+ */
+type SwoopWaitStrategy = 'timeout' | 'networkidle';
+type SwoopEngine = 'vm';
+interface SwoopInit {
+    /**
+     * Execution engine used for running third-party scripts.
+     *
+     * @remarks
+     * - `vm` (default): practical, supports `fetch` by reusing host globals
+     *
+     * @defaultValue 'vm'
+     */
+    engine?: SwoopEngine;
+    /**
+     * Pluck options used for the initial HTML request and external script fetching.
+     */
+    pluck?: PluckInit;
+    /**
+     * Execute inline and external scripts found in the HTML.
+     *
+     * @defaultValue true
+     */
+    executeScripts?: boolean;
+    /**
+     * Maximum time to wait for the page to "settle" before taking a snapshot.
+     *
+     * @defaultValue 3000
+     */
+    timeout?: number;
+    /**
+     * Which waiting strategy to use.
+     *
+     * - `timeout`: sleep for `timeout` and snapshot
+     * - `networkidle`: wait until no tracked fetches are pending for `idleTime`
+     *
+     * @defaultValue 'networkidle'
+     */
+    waitStrategy?: SwoopWaitStrategy;
+    /**
+     * Required quiet period (ms) for `networkidle`.
+     *
+     * @defaultValue 250
+     */
+    idleTime?: number;
+    /**
+     * Poll interval (ms) for `networkidle`.
+     *
+     * @defaultValue 25
+     */
+    pollInterval?: number;
+    /**
+     * How many scripts to load/execute at most.
+     *
+     * @defaultValue 64
+     */
+    maxScripts?: number;
+    /**
+     * If true, forward console output from the isolated realm to the host console.
+     *
+     * @defaultValue false
+     */
+    forwardConsole?: boolean;
+    /**
+     * If true, installs permissive Proxy-based stubs for common missing browser APIs.
+     *
+     * @remarks
+     * This may hide some failures (by turning hard crashes into no-ops), but improves
+     * compatibility for a best-effort snapshotter.
+     *
+     * @defaultValue true
+     */
+    permissiveShims?: boolean;
+    /**
+     * Record all sandbox `fetch()` calls into the captured console output.
+     *
+     * @defaultValue false
+     */
+    debugFetch?: boolean;
+    /**
+     * Enable additional sandbox probes to help iterative shim development.
+     *
+     * @remarks
+     * Collects lightweight runtime stats (DOM ops/mutations, app-root growth, etc.)
+     * and emits them via captured console.
+     *
+     * @defaultValue false
+     */
+    debugProbes?: boolean;
+}
+interface SwoopConsoleEntry {
+    level: 'debug' | 'info' | 'warn' | 'error' | 'log';
+    message: string;
+    args?: string[];
+    time: number;
+}
+interface SwoopScriptError {
+    stage: 'bootstrap' | 'script' | 'wait';
+    scriptUrl?: string;
+    message: string;
+    stack?: string;
+}
+interface SwoopResult {
+    /**
+     * Final URL after redirects.
+     */
+    url: string;
+    /**
+     * Snapshot HTML (best-effort).
+     */
+    html: string;
+    /**
+     * Console output captured from the isolated execution environment.
+     */
+    console: SwoopConsoleEntry[];
+    /**
+     * Script/bootstrap errors captured during execution.
+     */
+    errors: SwoopScriptError[];
+    /**
+     * Timing metadata (ms).
+     */
+    timing: {
+        start: number;
+        end: number;
+        duration: number;
+    };
+}
+
+/**
+ * Execute client-side JavaScript against a DOM-only environment and snapshot the resulting HTML.
+ *
+ * @remarks
+ * **Experimental feature**.
+ *
+ * @remarks
+ * - Default engine (`vm`) works on regular Node.js.
+ *
+ * This is *not* a real browser engine:
+ * - No layout/paint/CSS correctness
+ * - No true navigation lifecycle
+ * - Best-effort shims for browser APIs
+ *
+ * ⚠️ **Security**: This executes third-party JavaScript. Only use on trusted sources or in an OS sandbox.
+ */
+declare function swoop(url: string | URL, init?: SwoopInit): Promise<SwoopResult>;
+
+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, SwoopEnvironmentError, SwoopError, SwoopExecutionError, type SwoopInit, type SwoopResult, SwoopSecurityError, SwoopTimeoutError, type SwoopWaitStrategy, 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, swoop };

package/dist/index.d.ts

@@ -3069,4 +3069,187 @@ declare class PluckContentTypeError extends PluckError {
  */
 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 };
+/**
+ * Base error type for `swoop()`.
+ */
+declare class SwoopError extends Error {
+    name: string;
+}
+/**
+ * Thrown when the current runtime cannot execute `swoop()`.
+ */
+declare class SwoopEnvironmentError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when `swoop()` exceeds its configured timeout.
+ */
+declare class SwoopTimeoutError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when script execution fails in a non-recoverable way.
+ */
+declare class SwoopExecutionError extends SwoopError {
+    name: string;
+}
+/**
+ * Thrown when `swoop()` is asked to execute potentially unsafe scripts
+ * in a context where the caller should explicitly acknowledge the risk.
+ */
+declare class SwoopSecurityError extends SwoopError {
+    name: string;
+}
+
+/**
+ * How `swoop()` decides when a client-rendered page is "done enough" to snapshot.
+ *
+ * @remarks
+ * This is DOM-only rendering (no layout/paint). "Done" is best-effort.
+ */
+type SwoopWaitStrategy = 'timeout' | 'networkidle';
+type SwoopEngine = 'vm';
+interface SwoopInit {
+    /**
+     * Execution engine used for running third-party scripts.
+     *
+     * @remarks
+     * - `vm` (default): practical, supports `fetch` by reusing host globals
+     *
+     * @defaultValue 'vm'
+     */
+    engine?: SwoopEngine;
+    /**
+     * Pluck options used for the initial HTML request and external script fetching.
+     */
+    pluck?: PluckInit;
+    /**
+     * Execute inline and external scripts found in the HTML.
+     *
+     * @defaultValue true
+     */
+    executeScripts?: boolean;
+    /**
+     * Maximum time to wait for the page to "settle" before taking a snapshot.
+     *
+     * @defaultValue 3000
+     */
+    timeout?: number;
+    /**
+     * Which waiting strategy to use.
+     *
+     * - `timeout`: sleep for `timeout` and snapshot
+     * - `networkidle`: wait until no tracked fetches are pending for `idleTime`
+     *
+     * @defaultValue 'networkidle'
+     */
+    waitStrategy?: SwoopWaitStrategy;
+    /**
+     * Required quiet period (ms) for `networkidle`.
+     *
+     * @defaultValue 250
+     */
+    idleTime?: number;
+    /**
+     * Poll interval (ms) for `networkidle`.
+     *
+     * @defaultValue 25
+     */
+    pollInterval?: number;
+    /**
+     * How many scripts to load/execute at most.
+     *
+     * @defaultValue 64
+     */
+    maxScripts?: number;
+    /**
+     * If true, forward console output from the isolated realm to the host console.
+     *
+     * @defaultValue false
+     */
+    forwardConsole?: boolean;
+    /**
+     * If true, installs permissive Proxy-based stubs for common missing browser APIs.
+     *
+     * @remarks
+     * This may hide some failures (by turning hard crashes into no-ops), but improves
+     * compatibility for a best-effort snapshotter.
+     *
+     * @defaultValue true
+     */
+    permissiveShims?: boolean;
+    /**
+     * Record all sandbox `fetch()` calls into the captured console output.
+     *
+     * @defaultValue false
+     */
+    debugFetch?: boolean;
+    /**
+     * Enable additional sandbox probes to help iterative shim development.
+     *
+     * @remarks
+     * Collects lightweight runtime stats (DOM ops/mutations, app-root growth, etc.)
+     * and emits them via captured console.
+     *
+     * @defaultValue false
+     */
+    debugProbes?: boolean;
+}
+interface SwoopConsoleEntry {
+    level: 'debug' | 'info' | 'warn' | 'error' | 'log';
+    message: string;
+    args?: string[];
+    time: number;
+}
+interface SwoopScriptError {
+    stage: 'bootstrap' | 'script' | 'wait';
+    scriptUrl?: string;
+    message: string;
+    stack?: string;
+}
+interface SwoopResult {
+    /**
+     * Final URL after redirects.
+     */
+    url: string;
+    /**
+     * Snapshot HTML (best-effort).
+     */
+    html: string;
+    /**
+     * Console output captured from the isolated execution environment.
+     */
+    console: SwoopConsoleEntry[];
+    /**
+     * Script/bootstrap errors captured during execution.
+     */
+    errors: SwoopScriptError[];
+    /**
+     * Timing metadata (ms).
+     */
+    timing: {
+        start: number;
+        end: number;
+        duration: number;
+    };
+}
+
+/**
+ * Execute client-side JavaScript against a DOM-only environment and snapshot the resulting HTML.
+ *
+ * @remarks
+ * **Experimental feature**.
+ *
+ * @remarks
+ * - Default engine (`vm`) works on regular Node.js.
+ *
+ * This is *not* a real browser engine:
+ * - No layout/paint/CSS correctness
+ * - No true navigation lifecycle
+ * - Best-effort shims for browser APIs
+ *
+ * ⚠️ **Security**: This executes third-party JavaScript. Only use on trusted sources or in an OS sandbox.
+ */
+declare function swoop(url: string | URL, init?: SwoopInit): Promise<SwoopResult>;
+
+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, SwoopEnvironmentError, SwoopError, SwoopExecutionError, type SwoopInit, type SwoopResult, SwoopSecurityError, SwoopTimeoutError, type SwoopWaitStrategy, 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, swoop };