@ohos-ports/html2canvas-pro 0.0.0-stage → 2.3.2-beta.0

package/dist/types/dom/slot-cloner.d.ts

@@ -0,0 +1,66 @@
+import { Context } from '../core/context';
+/** Options subset needed by SlotCloner */
+export interface SlotClonerOptions {
+    ignoreElements?: (element: Element) => boolean;
+    copyStyles: boolean;
+}
+/** Exported for reuse in document-cloner.ts */
+export declare const IGNORE_ATTRIBUTE = "data-html2canvas-ignore";
+/**
+ * Handles shadow DOM child cloning, slot assignment, and light DOM traversal.
+ * Extracted from DocumentCloner to reduce file size and improve separation of concerns.
+ */
+export declare class SlotCloner {
+    private readonly cloneNodeFn;
+    private readonly options;
+    private readonly context;
+    constructor(cloneNodeFn: (node: Node, copyStyles: boolean) => Node, options: SlotClonerOptions, context: Context);
+    appendChildNode(clone: HTMLElement | SVGElement, child: Node, copyStyles: boolean): void;
+    /**
+     * Clone child nodes from source element to clone element.
+     * Handles shadow DOM, slots, and light DOM appropriately.
+     */
+    cloneChildNodes(node: Element, clone: HTMLElement | SVGElement, copyStyles: boolean): void;
+    /**
+     * Check if a child node should be cloned based on filtering rules.
+     * Filters out: scripts, ignored elements, and optionally styles.
+     */
+    private shouldCloneChild;
+    /**
+     * Check if a style element should be cloned based on copyStyles option.
+     */
+    private shouldCloneStyleElement;
+    /**
+     * Safely append a cloned child to a target, applying all filtering rules.
+     */
+    private safeAppendClonedChild;
+    /**
+     * Clone assigned nodes from a slot element to the target.
+     */
+    private cloneAssignedNodes;
+    /**
+     * Clone fallback content from a slot element when no nodes are assigned.
+     */
+    private cloneSlotFallbackContent;
+    /**
+     * Handle cloning of a slot element, including assigned nodes or fallback content.
+     */
+    private cloneSlotElement;
+    /**
+     * Clone shadow DOM children to the target shadow root.
+     */
+    private cloneShadowDOMChildren;
+    /**
+     * Clone light DOM children to the target element.
+     */
+    private cloneLightDOMChildren;
+    /**
+     * Clone slot element as light DOM when shadow root creation failed.
+     */
+    private cloneSlotElementAsLightDOM;
+    /**
+     * Clone shadow DOM content as light DOM when shadow root creation failed.
+     * This is a fallback mechanism to ensure content is not lost.
+     */
+    private cloneShadowDOMAsLightDOM;
+}

package/dist/types/dom/text-container.d.ts

@@ -0,0 +1,8 @@
+import { CSSParsedDeclaration } from '../css/index';
+import { TextBounds } from '../css/layout/text';
+import { Context } from '../core/context';
+export declare class TextContainer {
+    text: string;
+    textBounds: TextBounds[];
+    constructor(context: Context, node: Text, styles: CSSParsedDeclaration);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,36 @@
+import { Html2CanvasConfig, type ConfigOptions } from './config';
+import { createDefaultValidator, Validator, type ValidationResult } from './core/validator';
+import { PerformanceMonitor } from './core/performance-monitor';
+import type { Options } from './options';
+export type { Options };
+/**
+ * Renders an HTML element to a `<canvas>` element.
+ *
+ * The function clones the target element and its subtree into a hidden iframe,
+ * resolves all computed styles, and paints the result onto a canvas —
+ * producing a visual snapshot of the DOM as it appears in the browser.
+ *
+ * @example
+ * ```ts
+ * import html2canvas from 'html2canvas-pro';
+ *
+ * const canvas = await html2canvas(document.body, {
+ *   backgroundColor: '#ffffff',
+ *   scale: 2,
+ *   useCORS: true
+ * });
+ * document.body.appendChild(canvas);
+ * ```
+ *
+ * @param element - The root HTMLElement to render.
+ * @param options - Rendering options.
+ * @param config  - Advanced configuration. In most cases this is auto-created;
+ *                  only pass it if you need to share a cache across multiple calls.
+ * @returns A promise that resolves to the rendered HTMLCanvasElement.
+ *
+ * @throws {Error} If the element is not attached to a document.
+ * @throws {DOMException} If an {@link Options.signal|AbortSignal} was provided and the operation was aborted.
+ */
+declare const html2canvas: (element: HTMLElement, options?: Partial<Options>, config?: Html2CanvasConfig) => Promise<HTMLCanvasElement>;
+export default html2canvas;
+export { html2canvas, Html2CanvasConfig, ConfigOptions, Validator, ValidationResult, createDefaultValidator, PerformanceMonitor };

package/dist/types/options.d.ts

@@ -0,0 +1,62 @@
+import { CloneOptions, WindowOptions } from './dom/document-cloner';
+import { RenderOptions } from './render/canvas/canvas-renderer';
+import { ContextOptions } from './core/context';
+import { Validator } from './core/validator';
+/**
+ * Options passed to {@link html2canvas}.
+ *
+ * Combines clone, window, render, and context configuration into a single
+ * options object. All properties are optional.
+ */
+export type Options = CloneOptions & WindowOptions & RenderOptions & ContextOptions & {
+    /** Background color for the resulting canvas. Use `null` for transparent. */
+    backgroundColor: string | null;
+    /** Use foreignObject rendering (SVG-based) instead of the default Canvas 2D pipeline. */
+    foreignObjectRendering: boolean;
+    /** Whether to remove the cloned iframe after rendering. @default true */
+    removeContainer?: boolean;
+    /** CSP nonce for inline style elements. */
+    cspNonce?: string;
+    /** Custom input validator. */
+    validator?: Validator;
+    /** Skip pre-render validation of element and options. */
+    skipValidation?: boolean;
+    /** Enable performance monitoring and log a timing summary. */
+    enablePerformanceMonitoring?: boolean;
+    /**
+     * An AbortSignal that can be used to cancel an in-progress render.
+     * When the signal is aborted, the returned promise rejects with an
+     * `AbortError` DOMException.
+     */
+    signal?: AbortSignal;
+    /**
+     * 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)
+     */
+    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';
+    /**
+     * Called when a resource fails to load (image, font, iframe, etc.).
+     * The render continues — this is a notification hook, not an abort.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called at key milestones during the render pipeline.
+     * `phase` is one of: 'clone', 'parse', 'layout', 'render'.
+     * `progress` is 0..100 percentage estimate.
+     */
+    onProgress?: (phase: string, progress: number) => void;
+};

package/dist/types/render/background.d.ts

@@ -0,0 +1,16 @@
+import { Bounds } from '../css/layout/bounds';
+import { BACKGROUND_ORIGIN } from '../css/property-descriptors/background-origin';
+import { ElementContainer } from '../dom/element-container';
+import { BackgroundSizeInfo } from '../css/property-descriptors/background-size';
+import { Vector } from './vector';
+import { BACKGROUND_REPEAT } from '../css/property-descriptors/background-repeat';
+import { CSSValue } from '../css/syntax/parser';
+import { Path } from './path';
+import { BACKGROUND_CLIP } from '../css/property-descriptors/background-clip';
+export declare const calculateBackgroundPositioningArea: (backgroundOrigin: BACKGROUND_ORIGIN, element: ElementContainer) => Bounds;
+export declare const calculateBackgroundPaintingArea: (backgroundClip: BACKGROUND_CLIP, element: ElementContainer) => Bounds;
+export declare const calculateBackgroundRendering: (container: ElementContainer, index: number, intrinsicSize: [number | null, number | null, number | null]) => [Path[], number, number, number, number];
+export declare const isAuto: (token: CSSValue) => boolean;
+export declare const calculateBackgroundSize: (size: BackgroundSizeInfo[], [intrinsicWidth, intrinsicHeight, intrinsicProportion]: [number | null, number | null, number | null], bounds: Bounds) => [number, number];
+export declare const getBackgroundValueForIndex: <T>(values: T[], index: number) => T;
+export declare const calculateBackgroundRepeatPath: (repeat: BACKGROUND_REPEAT, [x, y]: [number, number], [width, height]: [number, number], backgroundPositioningArea: Bounds, backgroundPaintingArea: Bounds) => [Vector, Vector, Vector, Vector];

package/dist/types/render/bezier-curve.d.ts

@@ -0,0 +1,14 @@
+import { Vector } from './vector';
+import { IPath, PathType, Path } from './path';
+export declare class BezierCurve implements IPath {
+    type: PathType;
+    start: Vector;
+    startControl: Vector;
+    endControl: Vector;
+    end: Vector;
+    constructor(start: Vector, startControl: Vector, endControl: Vector, end: Vector);
+    subdivide(t: number, firstHalf: boolean): BezierCurve;
+    add(deltaX: number, deltaY: number): BezierCurve;
+    reverse(): BezierCurve;
+}
+export declare const isBezierCurve: (path: Path) => path is BezierCurve;

package/dist/types/render/border.d.ts

@@ -0,0 +1,6 @@
+import { Path } from './path';
+import { BoundCurves } from './bound-curves';
+export declare const parsePathForBorder: (curves: BoundCurves, borderSide: number) => Path[];
+export declare const parsePathForBorderDoubleOuter: (curves: BoundCurves, borderSide: number) => Path[];
+export declare const parsePathForBorderDoubleInner: (curves: BoundCurves, borderSide: number) => Path[];
+export declare const parsePathForBorderStroke: (curves: BoundCurves, borderSide: number) => Path[];

package/dist/types/render/bound-curves.d.ts

@@ -0,0 +1,32 @@
+import { ElementContainer } from '../dom/element-container';
+import { Path } from './path';
+export declare class BoundCurves {
+    readonly topLeftBorderDoubleOuterBox: Path;
+    readonly topRightBorderDoubleOuterBox: Path;
+    readonly bottomRightBorderDoubleOuterBox: Path;
+    readonly bottomLeftBorderDoubleOuterBox: Path;
+    readonly topLeftBorderDoubleInnerBox: Path;
+    readonly topRightBorderDoubleInnerBox: Path;
+    readonly bottomRightBorderDoubleInnerBox: Path;
+    readonly bottomLeftBorderDoubleInnerBox: Path;
+    readonly topLeftBorderStroke: Path;
+    readonly topRightBorderStroke: Path;
+    readonly bottomRightBorderStroke: Path;
+    readonly bottomLeftBorderStroke: Path;
+    readonly topLeftBorderBox: Path;
+    readonly topRightBorderBox: Path;
+    readonly bottomRightBorderBox: Path;
+    readonly bottomLeftBorderBox: Path;
+    readonly topLeftPaddingBox: Path;
+    readonly topRightPaddingBox: Path;
+    readonly bottomRightPaddingBox: Path;
+    readonly bottomLeftPaddingBox: Path;
+    readonly topLeftContentBox: Path;
+    readonly topRightContentBox: Path;
+    readonly bottomRightContentBox: Path;
+    readonly bottomLeftContentBox: Path;
+    constructor(element: ElementContainer);
+}
+export declare const calculateBorderBoxPath: (curves: BoundCurves) => Path[];
+export declare const calculateContentBoxPath: (curves: BoundCurves) => Path[];
+export declare const calculatePaddingBoxPath: (curves: BoundCurves) => Path[];

package/dist/types/render/box-sizing.d.ts

@@ -0,0 +1,4 @@
+import { Bounds } from '../css/layout/bounds';
+import { ElementContainer } from '../dom/element-container';
+export declare const paddingBox: (element: ElementContainer) => Bounds;
+export declare const contentBox: (element: ElementContainer) => Bounds;

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

@@ -0,0 +1,94 @@
+/**
+ * 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;
+    /**
+     * Instance-level LRU cache for background-image patterns.
+     * CanvasPatterns are tied to the rendering context and must not be
+     * shared across different render passes. This cache lives for the
+     * duration of one html2canvas() call.
+     */
+    private readonly patternCache;
+    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 repeating linear gradient background.
+     * Renders one cycle of the gradient to a pattern canvas, then fills
+     * the background area using createPattern('repeat').
+     */
+    private renderRepeatingLinearGradient;
+    /**
+     * 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;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Border Image Renderer
+ *
+ * Renders CSS border-image using 9-slice scaling.
+ * The source image is divided into 9 regions (4 corners, 4 edges, 1 center)
+ * based on border-image-slice values, then each region is drawn to the
+ * corresponding area of the element's border box.
+ */
+import { BorderImageSlice } from '../../css/property-descriptors/border-image-slice';
+import { BorderImageRepeat } from '../../css/property-descriptors/border-image-repeat';
+import { Bounds } from '../../css/layout/bounds';
+export declare class BorderImageRenderer {
+    private readonly ctx;
+    constructor(ctx: CanvasRenderingContext2D);
+    renderBorderImage(bounds: Bounds, image: HTMLImageElement, slice: BorderImageSlice, repeat: BorderImageRepeat, borderTopWidth: number, borderRightWidth: number, borderBottomWidth: number, borderLeftWidth: number): void;
+    private drawRegion;
+    private drawRepeatedEdge;
+}

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-path.d.ts

@@ -0,0 +1,3 @@
+import { Path } from '../path';
+export declare const formatCanvasPath: (ctx: CanvasRenderingContext2D, paths: Path[]) => void;
+export declare const createCanvasPath: (ctx: CanvasRenderingContext2D, paths: Path[]) => void;

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

@@ -0,0 +1,60 @@
+import { ElementPaint, StackingContext } from '../stacking-context';
+import { Color } from '../../css/types/color';
+import { ElementContainer } from '../../dom/element-container';
+import { Path } from '../path';
+import { BoundCurves } from '../bound-curves';
+import { ReplacedElementContainer } from '../../dom/replaced-elements';
+import { Context } from '../../core/context';
+export type RenderConfigurations = RenderOptions & {
+    backgroundColor: Color | null;
+    signal?: AbortSignal;
+    /**
+     * 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;
+    canvas?: HTMLCanvasElement;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare class CanvasRenderer {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    private readonly context;
+    private readonly options;
+    private readonly backgroundRenderer;
+    private readonly borderRenderer;
+    private readonly borderImageRenderer;
+    private readonly effectsRenderer;
+    private readonly textRenderer;
+    constructor(context: Context, options: RenderConfigurations);
+    renderStack(stack: StackingContext): Promise<void>;
+    renderNode(paint: ElementPaint): Promise<void>;
+    /**
+     * Helper method to render text with paint order support
+     * Reduces code duplication in line-clamp and normal rendering
+     */
+    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;
+    renderNodeBackgroundAndBorders(paint: ElementPaint): Promise<void>;
+    render(element: ElementContainer): Promise<HTMLCanvasElement>;
+}

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

@@ -0,0 +1,43 @@
+import { ElementPaint } from '../stacking-context';
+import { ReplacedElementContainer } from '../../dom/replaced-elements';
+import { ElementContainer } from '../../dom/element-container';
+import { BoundCurves } from '../bound-curves';
+import { Vector } from '../vector';
+import { Context } from '../../core/context';
+import { TextRenderer } from './text-renderer';
+import { Color } from '../../css/types/color';
+import { CSSParsedDeclaration } from '../../css/index';
+/**
+ * Factory type for creating an iframe canvas renderer — avoids circular import
+ * from canvas-renderer.ts which in turn imports content-renderer.ts.
+ */
+type IframeRendererFactory = (context: Context, options: {
+    scale: number;
+    backgroundColor: Color | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}) => {
+    render: (element: ElementContainer) => Promise<HTMLCanvasElement>;
+};
+/**
+ * Render replaced elements: Image, Canvas, SVG, IFrame.
+ */
+export declare function renderReplacedElements(ctx: CanvasRenderingContext2D, context: Context, options: {
+    scale: number;
+    backgroundColor: Color | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, iframeRendererFactory: IframeRendererFactory, container: ElementContainer, curves: BoundCurves, styles: CSSParsedDeclaration, renderReplacedElementFn: (container: ReplacedElementContainer, curves: BoundCurves, image: HTMLImageElement | HTMLCanvasElement) => void): Promise<void>;
+/**
+ * Render form element content: checkbox, radio, text input.
+ */
+export declare function renderFormElements(ctx: CanvasRenderingContext2D, textRenderer: TextRenderer, pathFn: (paths: Vector[]) => void, container: ElementContainer, styles: CSSParsedDeclaration): void;
+/**
+ * Render list-item marker (image or text).
+ */
+export declare function renderListMarker(ctx: CanvasRenderingContext2D, context: Context, textRenderer: TextRenderer, paint: ElementPaint, container: ElementContainer, styles: CSSParsedDeclaration): Promise<void>;
+export {};

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

@@ -0,0 +1,90 @@
+/**
+ * Effects Renderer
+ *
+ * Handles rendering effects including:
+ * - Opacity effects
+ * - Transform effects (matrix transformations)
+ * - Clip effects (overflow / border-radius clipping via Path[])
+ * - Clip-path effects (CSS clip-path shapes: inset, circle, ellipse, polygon, path)
+ * - Blend effects (mix-blend-mode)
+ * - Filter effects (CSS filter functions)
+ */
+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.
+ *
+ * ## Save/restore optimisation
+ *
+ * Canvas `save()` / `restore()` snapshot and restore the entire canvas state
+ * (transform matrix, clip region, compositing mode, filter, shadow, …) which
+ * is relatively expensive. The old implementation called `save()` / `restore()`
+ * for every single effect unconditionally.
+ *
+ * This implementation does a **batch pre-scan** before applying effects:
+ *
+ * | Effect type        | Modifies             | Reversible?   | Needs save? |
+ * |--------------------|----------------------|---------------|-------------|
+ * | TransformEffect     | transform matrix     | ❌ irreversible | **YES**     |
+ * | ClipEffect         | clip region          | ❌ cumulative   | **YES**     |
+ * | ClipPathEffect     | clip region          | ❌ cumulative   | **YES**     |
+ * | OpacityEffect      | globalAlpha          | ✅ scalar       | NO          |
+ * | BlendEffect        | globalCompositeOp    | ✅ scalar       | NO          |
+ * | FilterEffect       | filter + shadow      | ✅ string+vec   | NO          |
+ *
+ * When the batch contains *only* lightweight effects (opacity / blend / filter)
+ * we skip `save()` entirely and manually reset properties on pop.
+ *
+ * When the batch contains at least one heavyweight effect (transform / clip /
+ * clip-path) we call `save()` **once** before the first heavyweight effect and
+ * `restore()` **once** when that effect is popped.
+ */
+export declare class EffectsRenderer {
+    private readonly ctx;
+    private readonly pathCallback;
+    private readonly activeEffects;
+    /** Whether a canvas state save was performed for the current batch. */
+    private didSave;
+    /** Index (0-based, from start of activeEffects array) of the last
+     *  heavyweight effect in the batch — the one whose pop triggers
+     *  restore(). Set to -1 when no save was performed. */
+    private saveAtDepth;
+    constructor(deps: EffectsRendererDependencies, pathCallback: EffectsPathCallback);
+    /**
+     * Apply multiple effects.
+     * Clears existing effects and applies new ones.
+     */
+    applyEffects(effects: IElementEffect[]): void;
+    /**
+     * Apply a single effect (called internally by applyEffects).
+     */
+    private applyEffect;
+    /**
+     * Remove the most recent effect.
+     * Restores canvas state if needed.
+     */
+    private popEffect;
+    /**
+     * Get the current number of active effects.
+     */
+    getActiveEffectCount(): number;
+    /**
+     * Check if there are any active effects.
+     */
+    hasActiveEffects(): boolean;
+}

package/dist/types/render/canvas/font-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Font measurement utility
+ *
+ * Provides Canvas API-based baseline measurement that works correctly with
+ * webfonts (which may not be loaded in the original document) and system fonts.
+ *
+ * Fallback chain:
+ *   1. fontBoundingBoxAscent — font-level metric (Chrome 99+, FF 116+, Safari 17.4+)
+ *   2. actualBoundingBoxAscent — glyph-level metric (widely supported)
+ *   3. fallback value — coarse CSS fallback
+ */
+/**
+ * Measure the baseline ascent for the currently set font.
+ *
+ * @param ctx - Canvas 2D rendering context with ctx.font already set
+ * @param fallback - Fallback value when no metrics are available (e.g. fontSize.number)
+ * @returns The distance from the text baseline to the top of the bounding box
+ */
+export declare const measureBaseline: (ctx: CanvasRenderingContext2D, fallback: number) => number;

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

@@ -0,0 +1,10 @@
+import { RenderConfigurations } from './canvas-renderer';
+import { Context } from '../../core/context';
+export declare class ForeignObjectRenderer {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    options: RenderConfigurations;
+    private readonly context;
+    constructor(context: Context, options: RenderConfigurations);
+    render(element: HTMLElement): Promise<HTMLCanvasElement>;
+}