@progress/kendo-image-editor-common

Framework-neutral TypeScript engine for Kendo UI Image Editor components.

This repository contains the initial core engine. It owns serializable editor state, commands, undo/redo, rendering, export, annotations, redaction, viewport projection, and keyboard-action resolution. Framework adapters own the toolbar, panels, file pickers, floating toolbars, layout, and user interaction.

Current capabilities

• Crop, resize, rotate, straighten, flip, and zoom
• Color adjustments and filter presets
• Blur and pixelate redaction regions
• Shapes, lines, arrows, free text, frames, image roundness, and shadows
• Preview/commit gestures with undo and redo
• Serializable state with defensive deserialization
• PNG, JPEG, and runtime-supported WebP export
• Bounded preview/export rendering that respects canvas dimension and area limits
• Source/stage/viewport coordinate projection
• Keyboard shortcut resolution independent of framework UI

Architecture

The engine keeps edits as plain ImageEditorState data and applies typed commands through ImageEditor and its history invoker. It renders pixels only when previewing or exporting; it does not retain an editable bitmap document.

The main entry point is ImageEditor from src/image-editor/image-editor.ts. The package root exports the public API from src/main.ts.

Installation

npm install @progress/kendo-image-editor-common

The package requires Node.js 18 or later for development.

Development commands

npm ci
npm run lint
npm run build-package
npm run test:ci
npm pack --dry-run

npm run test:ci also prints shadow-preview timings for 1200×800 and 4000×3000 sources at a fixed 900px preview edge, including the no-shadow baseline, command time, first shadow render, and warmed shadow renders.

Run the playground locally

The playground exercises the public API with a deterministic sample image. It includes grouped controls for every registered command, common edits, image upload, history, state save/load, preview, and export.

1. Open a terminal in the repository root.
2. Install the locked dependencies:

npm ci

3. Start the development server:

npm start

4. Open http://localhost:3000 if Vite does not open a browser automatically.
5. Select Open sample to reset to the built-in image, or Open file to load a local image.
6. Choose a feature from the Tool dropdown and use its contextual configurator while keeping the image canvas visible.

Stop the server with Ctrl+C when finished.

Run browser tests

The functional browser tests use a separate, deterministic page. Start it in one terminal, then run the tests in another:

npm run start:e2e
npm run e2e

The E2E page runs at http://localhost:3001. It does not require network images or a file dialog. A local Chrome/WebDriver installation is required by @progress/kendo-e2e.

The Image Editor E2E suite measures preview time before shadow is enabled, on the first render after applying it, and on warmed subsequent renders. It logs [shadow-preview-performance]; browser timings are diagnostic and do not have a CI failure threshold.

The package publishes CommonJS, ES module, ES2015/browser, and TypeScript declaration entry points. @napi-rs/canvas is a development-only dependency used by raster and rendering tests; it is not shipped to consumers.