html2canvas-pro 1.6.6 → 2.0.0

package/dist/types/index.d.ts

@@ -1,15 +1,60 @@
 import { CloneOptions, WindowOptions } from './dom/document-cloner';
 import { RenderOptions } from './render/canvas/canvas-renderer';
 import { ContextOptions } from './core/context';
+import { Html2CanvasConfig, ConfigOptions } from './config';
+import { createDefaultValidator, Validator, ValidationResult } from './core/validator';
+import { PerformanceMonitor } from './core/performance-monitor';
 export type Options = CloneOptions & WindowOptions & RenderOptions & ContextOptions & {
     backgroundColor: string | null;
     foreignObjectRendering: boolean;
     removeContainer?: boolean;
+    cspNonce?: string;
+    validator?: Validator;
+    skipValidation?: boolean;
+    enablePerformanceMonitoring?: boolean;
+    /**
+     * Enable/disable image smoothing (anti-aliasing) globally.
+     * - `false`: Pixel-perfect rendering for pixel art, sprites, and retro graphics
+     * - `true`: Smooth rendering for photos and high-quality images
+     * - CSS `image-rendering` property on individual elements takes precedence
+     * @default true (browser default)
+     * @example
+     * // Pixel art game screenshot
+     * html2canvas(element, { imageSmoothing: false, scale: 2 });
+     *
+     * // High-quality photo
+     * html2canvas(element, { imageSmoothing: true, imageSmoothingQuality: 'high' });
+     */
+    imageSmoothing?: boolean;
+    /**
+     * Image smoothing quality level when imageSmoothing is enabled.
+     * - `'low'`: Faster, lower quality (good for preview)
+     * - `'medium'`: Balanced (default in most browsers)
+     * - `'high'`: Slower, best quality (good for final export)
+     *
+     * Browser support: Chrome 54+, Firefox 94+, Safari 17+
+     * Falls back gracefully in older browsers.
+     * @default browser default (usually 'low' or 'medium')
+     */
+    imageSmoothingQuality?: 'low' | 'medium' | 'high';
 };
-declare const setCspNonce: (nonce: string) => void;
+/**
+ * Main html2canvas function with improved configuration management
+ *
+ * @param element - Element to render
+ * @param options - Rendering options
+ * @param config - Optional configuration (for advanced use cases)
+ * @returns Promise resolving to rendered canvas
+ */
 declare const html2canvas: {
-    (element: HTMLElement, options?: Partial<Options>): Promise<HTMLCanvasElement>;
+    (element: HTMLElement, options?: Partial<Options>, config?: Html2CanvasConfig): Promise<HTMLCanvasElement>;
     setCspNonce: (nonce: string) => void;
 };
+/**
+ * Set CSP nonce for inline styles
+ * @deprecated Use options.cspNonce instead
+ */
+declare const setCspNonce: (nonce: string) => void;
 export default html2canvas;
-export { html2canvas, setCspNonce };
+export { html2canvas, setCspNonce, Html2CanvasConfig, ConfigOptions, Validator, ValidationResult, createDefaultValidator, PerformanceMonitor };
+export { IMAGE_RENDERING } from './css/property-descriptors/image-rendering';

package/dist/types/render/canvas/__tests__/background-renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/render/canvas/__tests__/border-renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/render/canvas/__tests__/effects-renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/render/canvas/__tests__/text-renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/render/canvas/background-renderer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Background Renderer
+ *
+ * Handles rendering of element backgrounds including:
+ * - Background colors
+ * - Background images (URL)
+ * - Linear gradients
+ * - Radial gradients
+ * - Background patterns and repeats
+ */
+import { Context } from '../../core/context';
+import { ElementContainer } from '../../dom/element-container';
+/**
+ * Dependencies required for BackgroundRenderer
+ */
+export interface BackgroundRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    context: Context;
+    canvas: HTMLCanvasElement;
+    options: {
+        width: number;
+        height: number;
+        scale: number;
+    };
+}
+/**
+ * Background Renderer
+ *
+ * Specialized renderer for element backgrounds.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export declare class BackgroundRenderer {
+    private readonly ctx;
+    private readonly context;
+    private readonly canvas;
+    constructor(deps: BackgroundRendererDependencies);
+    /**
+     * Render background images for a container
+     * Supports URL images, linear gradients, and radial gradients
+     *
+     * @param container - Element container with background styles
+     */
+    renderBackgroundImage(container: ElementContainer): Promise<void>;
+    /**
+     * Render a URL-based background image
+     */
+    private renderBackgroundURLImage;
+    /**
+     * Render a linear gradient background
+     */
+    private renderLinearGradient;
+    /**
+     * Render a radial gradient background
+     */
+    private renderRadialGradient;
+    /**
+     * Render a repeating pattern with offset
+     *
+     * @param path - Path to fill
+     * @param pattern - Canvas pattern or gradient
+     * @param offsetX - X offset for pattern
+     * @param offsetY - Y offset for pattern
+     */
+    private renderRepeat;
+    /**
+     * Resize an image to target dimensions
+     *
+     * @param image - Source image
+     * @param width - Target width
+     * @param height - Target height
+     * @param imageRendering - CSS image-rendering property value
+     * @returns Resized canvas or original image
+     */
+    private resizeImage;
+    /**
+     * Create a canvas path from path array
+     *
+     * @param paths - Array of path points
+     */
+    private path;
+    /**
+     * Format path points into canvas path
+     *
+     * @param paths - Array of path points
+     */
+    private formatPath;
+}

package/dist/types/render/canvas/border-renderer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Border Renderer
+ *
+ * Handles rendering of element borders including:
+ * - Solid borders
+ * - Double borders
+ * - Dashed borders
+ * - Dotted borders
+ */
+import { Color } from '../../css/types/color';
+import { BoundCurves } from '../bound-curves';
+import { BORDER_STYLE } from '../../css/property-descriptors/border-style';
+import { Path } from '../path';
+/**
+ * Dependencies required for BorderRenderer
+ */
+export interface BorderRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+}
+/**
+ * Path creation callbacks
+ * The main CanvasRenderer retains path() and formatPath() methods,
+ * so we inject them as callbacks to avoid duplication
+ */
+export interface PathCallbacks {
+    path(paths: Path[]): void;
+    formatPath(paths: Path[]): void;
+}
+/**
+ * Border Renderer
+ *
+ * Specialized renderer for element borders.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export declare class BorderRenderer {
+    private readonly ctx;
+    private pathCallbacks;
+    constructor(deps: BorderRendererDependencies, pathCallbacks: PathCallbacks);
+    /**
+     * Render a solid border
+     *
+     * @param color - Border color
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     */
+    renderSolidBorder(color: Color, side: number, curvePoints: BoundCurves): Promise<void>;
+    /**
+     * Render a double border
+     * Falls back to solid border if width is too small
+     *
+     * @param color - Border color
+     * @param width - Border width
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     */
+    renderDoubleBorder(color: Color, width: number, side: number, curvePoints: BoundCurves): Promise<void>;
+    /**
+     * Render a dashed or dotted border
+     *
+     * @param color - Border color
+     * @param width - Border width
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     * @param style - Border style (DASHED or DOTTED)
+     */
+    renderDashedDottedBorder(color: Color, width: number, side: number, curvePoints: BoundCurves, style: BORDER_STYLE): Promise<void>;
+}

package/dist/types/render/canvas/canvas-renderer.d.ts

@@ -1,19 +1,28 @@
 import { ElementPaint, StackingContext } from '../stacking-context';
 import { Color } from '../../css/types/color';
 import { ElementContainer } from '../../dom/element-container';
-import { BORDER_STYLE } from '../../css/property-descriptors/border-style';
-import { CSSParsedDeclaration } from '../../css';
-import { TextContainer } from '../../dom/text-container';
 import { Path } from '../path';
 import { BoundCurves } from '../bound-curves';
-import { TextBounds } from '../../css/layout/text';
 import { ReplacedElementContainer } from '../../dom/replaced-elements';
-import { IElementEffect } from '../effects';
-import { Bounds } from '../../css/layout/bounds';
 import { Renderer } from '../renderer';
 import { Context } from '../../core/context';
 export type RenderConfigurations = RenderOptions & {
     backgroundColor: Color | null;
+    /**
+     * Enable/disable image smoothing (anti-aliasing).
+     * When disabled, images are rendered with pixel-perfect sharpness (no interpolation).
+     * CSS `image-rendering` property on individual elements takes precedence.
+     * @default browser default (usually true)
+     */
+    imageSmoothing?: boolean;
+    /**
+     * Image smoothing quality level when imageSmoothing is enabled.
+     * Higher quality may be slower for large images.
+     * Only supported in modern browsers (Chrome 54+, Firefox 94+, Safari 17+).
+     * Falls back gracefully in older browsers.
+     * @default browser default
+     */
+    imageSmoothingQuality?: 'low' | 'medium' | 'high';
 };
 export interface RenderOptions {
     scale: number;
@@ -26,37 +35,24 @@ export interface RenderOptions {
 export declare class CanvasRenderer extends Renderer {
     canvas: HTMLCanvasElement;
     ctx: CanvasRenderingContext2D;
-    private readonly _activeEffects;
     private readonly fontMetrics;
+    private readonly backgroundRenderer;
+    private readonly borderRenderer;
+    private readonly effectsRenderer;
+    private readonly textRenderer;
     constructor(context: Context, options: RenderConfigurations);
-    applyEffects(effects: IElementEffect[]): void;
-    applyEffect(effect: IElementEffect): void;
-    popEffect(): void;
     renderStack(stack: StackingContext): Promise<void>;
     renderNode(paint: ElementPaint): Promise<void>;
-    renderTextWithLetterSpacing(text: TextBounds, letterSpacing: number, baseline: number): void;
     /**
      * Helper method to render text with paint order support
      * Reduces code duplication in line-clamp and normal rendering
      */
-    private renderTextBoundWithPaintOrder;
-    private renderTextDecoration;
-    private drawDecorationLine;
-    private truncateTextWithEllipsis;
-    private createFontStyle;
-    renderTextNode(text: TextContainer, styles: CSSParsedDeclaration, containerBounds?: Bounds): Promise<void>;
     renderReplacedElement(container: ReplacedElementContainer, curves: BoundCurves, image: HTMLImageElement | HTMLCanvasElement): void;
     renderNodeContent(paint: ElementPaint): Promise<void>;
     renderStackContent(stack: StackingContext): Promise<void>;
     mask(paths: Path[]): void;
     path(paths: Path[]): void;
     formatPath(paths: Path[]): void;
-    renderRepeat(path: Path[], pattern: CanvasPattern | CanvasGradient, offsetX: number, offsetY: number): void;
-    resizeImage(image: HTMLImageElement, width: number, height: number): HTMLCanvasElement | HTMLImageElement;
-    renderBackgroundImage(container: ElementContainer): Promise<void>;
-    renderSolidBorder(color: Color, side: number, curvePoints: BoundCurves): Promise<void>;
-    renderDoubleBorder(color: Color, width: number, side: number, curvePoints: BoundCurves): Promise<void>;
     renderNodeBackgroundAndBorders(paint: ElementPaint): Promise<void>;
-    renderDashedDottedBorder(color: Color, width: number, side: number, curvePoints: BoundCurves, style: BORDER_STYLE): Promise<void>;
     render(element: ElementContainer): Promise<HTMLCanvasElement>;
 }

package/dist/types/render/canvas/effects-renderer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Effects Renderer
+ *
+ * Handles rendering effects including:
+ * - Opacity effects
+ * - Transform effects (matrix transformations)
+ * - Clip effects (clipping paths)
+ */
+import { IElementEffect } from '../effects';
+import { Path } from '../path';
+/**
+ * Dependencies required for EffectsRenderer
+ */
+export interface EffectsRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+}
+/**
+ * Path callback for clip effects
+ */
+export interface EffectsPathCallback {
+    path(paths: Path[]): void;
+}
+/**
+ * Effects Renderer
+ *
+ * Manages rendering effects stack including opacity, transforms, and clipping.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export declare class EffectsRenderer {
+    private readonly ctx;
+    private readonly pathCallback;
+    private readonly activeEffects;
+    constructor(deps: EffectsRendererDependencies, pathCallback: EffectsPathCallback);
+    /**
+     * Apply multiple effects
+     * Clears existing effects and applies new ones
+     *
+     * @param effects - Array of effects to apply
+     */
+    applyEffects(effects: IElementEffect[]): void;
+    /**
+     * Apply a single effect
+     *
+     * @param effect - Effect to apply
+     */
+    applyEffect(effect: IElementEffect): void;
+    /**
+     * Remove the most recent effect
+     * Restores the canvas state before the effect was applied
+     */
+    popEffect(): void;
+    /**
+     * Get the current number of active effects
+     *
+     * @returns Number of active effects
+     */
+    getActiveEffectCount(): number;
+    /**
+     * Check if there are any active effects
+     *
+     * @returns True if there are active effects
+     */
+    hasActiveEffects(): boolean;
+}

package/dist/types/render/canvas/text-renderer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Text Renderer
+ *
+ * Handles rendering of text content including:
+ * - Text with letter spacing
+ * - Text decorations (underline, overline, line-through)
+ * - Text shadows
+ * - Webkit line clamp
+ * - Text overflow ellipsis
+ * - Paint order (fill/stroke)
+ * - Font styles
+ */
+import { Context } from '../../core/context';
+import { TextContainer } from '../../dom/text-container';
+import { CSSParsedDeclaration } from '../../css';
+import { Bounds } from '../../css/layout/bounds';
+import { TextBounds } from '../../css/layout/text';
+/**
+ * Dependencies required for TextRenderer
+ */
+export interface TextRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    context: Context;
+    options: {
+        scale: number;
+    };
+}
+/**
+ * Text Renderer
+ *
+ * Specialized renderer for text content.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export declare class TextRenderer {
+    private readonly ctx;
+    private readonly options;
+    constructor(deps: TextRendererDependencies);
+    /**
+     * Render text with letter spacing
+     * Public method used by list rendering
+     */
+    renderTextWithLetterSpacing(text: TextBounds, letterSpacing: number, baseline: number): void;
+    /**
+     * Helper method to render text with paint order support
+     * Reduces code duplication in line-clamp and normal rendering
+     */
+    private renderTextBoundWithPaintOrder;
+    private renderTextDecoration;
+    private drawDecorationLine;
+    private truncateTextWithEllipsis;
+    /**
+     * Create font style array
+     * Public method used by list rendering
+     */
+    createFontStyle(styles: CSSParsedDeclaration): string[];
+    renderTextNode(text: TextContainer, styles: CSSParsedDeclaration, containerBounds?: Bounds): Promise<void>;
+}

package/dist/types/render/renderer-interface.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Base interface for all specialized renderers
+ * Each renderer is responsible for rendering a specific aspect of an element
+ */
+export interface IRenderer {
+    /**
+     * Render the specified aspect of the element
+     */
+    render(...args: any[]): void | Promise<void>;
+}
+/**
+ * Common dependencies required by renderers
+ */
+export interface RendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    scale: number;
+    options: any;
+}
+/**
+ * Performance tracking for renderers
+ */
+export interface RenderMetrics {
+    renderCount: number;
+    totalTime: number;
+    averageTime: number;
+}

package/package.json

@@ -14,7 +14,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "1.6.6",
+  "version": "2.0.0",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -58,6 +58,7 @@
     "appium-ios-simulator": "^8.0.9",
     "base64-arraybuffer": "1.0.2",
     "body-parser": "^2.2.1",
+    "change-case": "^5.4.4",
     "chai": "6.2.2",
     "conventional-changelog-cli": "^5.0.0",
     "cors": "^2.8.5",