html2canvas-pro 2.5.1 → 2.5.2

package/dist/types/render/canvas/filter-surface.d.ts

@@ -1,17 +1,43 @@
 export declare class FilterSurfaceError extends Error {
 }
 export declare const releaseSurface: (canvas: HTMLCanvasElement) => void;
-export interface SimpleFilter {
+/**
+ * A parsed CSS filter chain. Functions keep their declaration order — CSS
+ * applies them left to right, and the native canvas backend reproduces that
+ * order exactly. Chains containing functions the backends cannot express
+ * (url() references, unknown functions) fail parsing and stay on the legacy
+ * renderer, where ctx.filter receives the full string natively.
+ */
+export type FilterFunction = {
+    kind: 'blur';
+    value: number;
+} | {
+    kind: 'drop-shadow';
+    x: number;
+    y: number;
     blur: number;
-    shadow?: {
-        x: number;
-        y: number;
-        blur: number;
-        color: string;
-    };
+    color: string;
+} | {
+    kind: 'unitless';
+    name: UnitlessFilterName;
+    value: number;
+};
+export type UnitlessFilterName = 'brightness' | 'contrast' | 'grayscale' | 'hue-rotate' | 'invert' | 'opacity' | 'saturate' | 'sepia';
+export interface ParsedFilter {
+    functions: FilterFunction[];
 }
-export declare function parseSimpleFilter(value: string | null): SimpleFilter | null;
-export declare function filterOutset(filter: SimpleFilter): number;
+export declare function parseFilterChain(value: string | null): ParsedFilter | null;
+/**
+ * Render the chain as a canvas ctx.filter string, scaling all device-space
+ * lengths (blur radii, shadow offsets) by the capture scale. Unitless
+ * functions and hue angles are scale-invariant.
+ */
+export declare const nativeFilterString: (filter: ParsedFilter, scale: number) => string;
+/**
+ * Outset (in CSS pixels) a surface must grow so blur/shadow spillover is not
+ * cropped. Unitless functions never spread beyond the bounds. Consecutive
+ * blurs compound, so their radii sum.
+ */
+export declare function filterOutset(filter: ParsedFilter): number;
 export declare function supportsNativeFilters(owner?: Document): boolean;
-export declare function renderFilterSurface(source: HTMLCanvasElement, filter: SimpleFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;
-export declare function renderSvgFilterSurface(source: HTMLCanvasElement, { blur, shadow }: SimpleFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;
+export declare function renderFilterSurface(source: HTMLCanvasElement, filter: ParsedFilter, opacity: number, scale: number, signal?: AbortSignal): Promise<HTMLCanvasElement>;

package/dist/types/render/canvas/gradient-rasterizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared gradient rasterisation primitives.
+ *
+ * Canvas 2D has no repeating gradients and no native elliptical radial
+ * gradients, so every gradient painter (background, mask, border-image) needs
+ * the same two building blocks:
+ *
+ * 1. periodic stop stacking — the one-cycle stop list re-added k·period + s
+ *    for k = 0..cycles-1, clamped to the [0, 1] gradient range;
+ * 2. ellipse rasterisation — a circle of radius rx scaled vertically by
+ *    ry / rx, painted on a 2rx × 2ry offscreen canvas.
+ *
+ * Centralising them keeps the subtle invariants in one place:
+ * - stop positions are normalised against rx (the canvas gradient radius),
+ *   NOT the diameter — normalising against the diameter halves every
+ *   absolute-px stop;
+ * - the fill must cover the pre-scale circle (fillRect of the rx*2 square),
+ *   not the post-scale ellipse box — a user-space (2rx × 2ry) rect shrinks
+ *   vertically under the y-scale and clips the ellipse whenever ry < rx;
+ * - outside the ending shape a radial gradient continues with its last
+ *   colour, which callers must paint across the full area first.
+ */
+import { UnprocessedGradientColorStop, GradientColorStop } from '../../css/types/image';
+export interface StringColorStop {
+    stop: number;
+    color: string;
+}
+/**
+ * Stack the one-cycle stop list periodically across [0, 1]. Returns null for
+ * a degenerate period (all stops clamped to one point) — CSS renders the
+ * last colour across the whole area in that case, and callers should paint
+ * the last colour instead of stacking.
+ */
+export declare const stackRepeatingStops: (processed: GradientColorStop[]) => StringColorStop[] | null;
+/** Map parsed stops to string-colour stops clamped into the canvas [0, 1] range. */
+export declare const toCanvasStops: (processed: GradientColorStop[]) => StringColorStop[];
+export interface RasterizedRadialGradient {
+    /** 2rx × 2ry device-pixel canvas holding the gradient ellipse. */
+    canvas: HTMLCanvasElement;
+    /** Colour beyond the ending shape (the last stop's colour). */
+    lastColor: string;
+    rx: number;
+    ry: number;
+}
+/**
+ * Rasterise a radial gradient's ending-shape ellipse to an offscreen canvas.
+ *
+ * The ellipse is a circle of radius rx scaled vertically by ry / rx around
+ * the canvas centre, so the offscreen canvas is the ellipse's full 2rx × 2ry
+ * bounding box and callers draw it at (centre - rx, centre - ry). Handles the
+ * repeating variant by stacking stops across the [0, 1] gradient range.
+ */
+export declare const rasterizeRadialGradient: (ownerDocument: Document, rx: number, ry: number, stops: UnprocessedGradientColorStop[], repeating?: boolean) => RasterizedRadialGradient | null;

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

@@ -10,8 +10,11 @@
  * always fills the whole area — a mask surface is about alpha coverage, not
  * about what is visible underneath.
  *
- * Limitations (v1): repeating gradients render their base cycle; mask-mode is
- * alpha-only; layers composite with source-over (≈ the default `add`).
+ * Gradient layers share the rasterisation primitives of the background
+ * renderer (gradient-rasterizer.ts): repeating gradients stack their stop
+ * cycles, and the area beyond a radial gradient's ending shape keeps the
+ * last stop's colour. Limitations (v1): mask-mode is alpha-only; layers
+ * composite with source-over (≈ the spec-default `add`).
  */
 import { ICSSImage } from '../../css/types/image';
 import { LengthPercentage } from '../../css/types/length-percentage';

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

@@ -52,5 +52,4 @@ export declare class TextClipRenderer {
      * null when the element has no text shadows.
      */
     private renderShadowSilhouettes;
-    private getTextStrokeLineJoin;
 }

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

@@ -25,6 +25,7 @@ export interface TextRendererDependencies {
     };
 }
 export declare const hasCJKCharacters: (text: string) => boolean;
+export declare const getTextStrokeLineJoin: () => CanvasLineJoin;
 /**
  * Text Renderer
  *

package/package.json

@@ -19,7 +19,7 @@
       "default": "./dist/html2canvas-pro.esm.js"
     }
   },
-  "version": "2.5.1",
+  "version": "2.5.2",
   "author": {
     "name": "yorickshan",
     "email": "yorickshan@gmail.com",
@@ -41,27 +41,18 @@
   "devDependencies": {
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@types/chai": "^5.2.3",
     "@types/express": "^5.0.6",
-    "@types/karma": "^6.3.9",
-    "@types/mocha": "^10.0.10",
     "@types/node": "^26.6.3",
-    "@types/platform": "^1.3.6",
     "@types/pngjs": "^6.0.5",
     "@types/serve-index": "^1.9.4",
     "@typescript-eslint/eslint-plugin": "^8.70.1",
     "@typescript-eslint/parser": "^8.70.1",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^5.0.2",
-    "appium-ios-simulator": "^8.2.8",
-    "base64-arraybuffer": "1.0.2",
     "body-parser": "^2.3.0",
-    "chai": "6.2.2",
-    "change-case": "^5.4.4",
     "conventional-changelog": "^8.1.3",
     "conventional-changelog-conventionalcommits": "^10.4.0",
     "cors": "^2.8.6",
-    "cz-conventional-changelog": "^3.3.0",
     "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
@@ -70,23 +61,11 @@
     "glob": "^13.0.6",
     "husky": "^9.1.7",
     "jsdom": "^30.1.1",
-    "karma": "^6.4.4",
-    "karma-chrome-launcher": "^3.2.0",
-    "karma-edge-launcher": "^0.4.2",
-    "karma-firefox-launcher": "^2.1.3",
-    "karma-ie-launcher": "^1.0.0",
-    "karma-junit-reporter": "^2.0.1",
-    "karma-mocha": "^2.0.1",
-    "karma-safarinative-launcher": "^1.1.0",
     "lint-staged": "^17.6.0",
-    "mocha": "^12.0.2",
-    "node-simctl": "^8.2.9",
     "pixelmatch": "^7.2.0",
-    "platform": "^1.3.6",
     "playwright": "1.63.0",
     "pngjs": "^7.0.0",
     "prettier": "^3.9.9",
-    "puppeteer": "^25.12.0",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.11",
     "serve-index": "^1.9.2",
@@ -99,10 +78,7 @@
     "vitest": "^5.0.2",
     "yargs": "^18.2.0"
   },
-  "dependencies": {
-    "css-line-break": "^2.1.0",
-    "text-segmentation": "^1.0.3"
-  },
+  "dependencies": {},
   "lint-staged": {
     "{src,tests}/**/*.ts": [
       "prettier --write",
@@ -111,20 +87,19 @@
   },
   "scripts": {
     "prebuild": "rimraf dist/ && rimraf build/ && mkdir -p dist && mkdir -p build",
-    "build": "tsc -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && rolldown -c tests/rolldown.testrunner.config.ts && node scripts/bundle-filter-surface.mjs",
+    "build": "tsc -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && node scripts/bundle-filter-surface.mjs",
     "build:testrunner": "rolldown -c tests/rolldown.testrunner.config.ts",
     "build:reftest-result-list": "tsx scripts/create-reftest-result-list.ts",
     "build:create-reftest-list": "tsx scripts/create-reftest-list.ts tests/reftests/ignore.txt build/reftests.js",
     "release": "sh scripts/version-upgrade.sh",
     "format": "prettier --write \"{src,tests,scripts}/**/*.ts\"",
     "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\" \"scripts/**/*.mjs\" --max-warnings 0",
-    "test": "pnpm lint && pnpm unittest && pnpm karma",
+    "test": "pnpm lint && pnpm unittest && pnpm reftests:pw",
     "unittest": "vitest run",
     "unittest:coverage": "vitest run --coverage",
     "bench:css-parse": "tsx scripts/benchmarks/css-parse.bench.ts",
+    "bench:render": "node scripts/benchmarks/render.bench.mjs",
     "reftests-diff": "mkdir -p tmp/snapshots && vitest run --config vitest.reftest.config.ts",
-    "prekarma": "node scripts/ensure-karma-prereqs.mjs",
-    "karma": "tsx tests/karma",
     "watch": "rolldown -w",
     "watch:unittest": "vitest",
     "start": "tsx tests/server --port=8080 --cors=8081",
@@ -133,6 +108,9 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:api": "typedoc",
-    "docs:api:watch": "typedoc --watch"
+    "docs:api:watch": "typedoc --watch",
+    "reftests:pw": "tsx tests/reftests-playwright.ts",
+    "reftests": "pnpm reftests:pw",
+    "prebrowser": "node scripts/ensure-browser-prereqs.mjs"
   }
 }

package/dist/types/render/font-metrics.d.ts

@@ -1,11 +0,0 @@
-export interface FontMetric {
-    baseline: number;
-    middle: number;
-}
-export declare class FontMetrics {
-    private readonly _data;
-    private readonly _document;
-    constructor(document: Document);
-    private parseMetrics;
-    getMetrics(fontFamily: string, fontSize: string): FontMetric;
-}

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

@@ -1,28 +0,0 @@
-/**
- * Base interface for all specialized renderers.
- * Each renderer is responsible for rendering a specific aspect of an element.
- *
- * @internal This interface is a structural contract; prefer using concrete
- *           renderer classes (BackgroundRenderer, BorderRenderer, etc.)
- *           directly rather than relying on the generic IRenderer shape.
- */
-export interface IRenderer {
-    render(...args: unknown[]): void | Promise<void>;
-}
-/**
- * Common dependencies required by renderers.
- * RenderConfigurations from canvas-renderer.ts provides a concrete type.
- */
-export interface RendererDependencies {
-    ctx: CanvasRenderingContext2D;
-    scale: number;
-    options: Record<string, unknown>;
-}
-/**
- * Performance tracking for renderers.
- */
-export interface RenderMetrics {
-    renderCount: number;
-    totalTime: number;
-    averageTime: number;
-}