Introduction to Klecks
Relevant source files
The following files were used as context for generating this wiki page:
Klecks (German for "splash of color") is an open-source online painting application and graphics engine. It is designed to function both as a comprehensive standalone creative tool (available at kleki.com) and as a lightweight embedded widget for integration into drawing communities and third-party websites. The application is built using TypeScript and utilizes a hybrid rendering approach that combines standard HTML5 Canvas 2D with CanvasKit (Skia WASM) for high-performance, GPU-accelerated operations.
Sources: README.md:5-9, CLAUDE.md:5-7, prompt.md:5-7
The project emphasizes a professional-grade experience with features typically found in desktop software, including a multi-layered canvas system, pressure-sensitive brush engines, and WebGL-powered filters. Within the Rocreate ecosystem, Klecks serves as the core graphics kernel, evolved to support Procreate-style interface patterns and high-performance creative workflows.
Sources: README.md:12-23, prompt.md:4-10
Core System Architecture
Klecks follows a modular architecture where a central controller coordinates between the UI, rendering engine, and state management. The system is designed for high-performance graphics, minimizing CPU-to-GPU data transfers and utilizing Skia for heavy lifting.
Key Components
| Component | Description | File Reference |
|---|---|---|
| KlApp | The central controller and entry point. Connects the UI components, canvas logic, and history system. | src/app/script/app/kl-app.ts |
| KlCanvas | Manages the image data, including layer stacks, compositing logic, and pixel-level operations. | src/app/script/klecks/canvas/kl-canvas.ts |
| Easel | Handles the viewport, including zooming, panning, and routing input to specific tool interactions. | src/app/script/klecks/ui/easel/ |
| KlHistory | A tile-based undo/redo system that stores changes as efficient deltas. | src/app/script/klecks/history/ |
| CanvasKit | Low-level Skia/WASM wrappers providing GPU-accelerated rendering and compositing. | src/app/script/canvaskit/ |
Sources: CLAUDE.md:15-22, prompt.md:52-56
System Data Flow
The application employs a unidirectional data flow for canvas state to ensure robust undo/redo capabilities. Input processing is managed through a chain of event handlers that sanitize and smooth pointer data before it reaches the rendering layer.
This diagram illustrates the flow from raw user input through the sanitization chain into the core application logic and final hardware-accelerated rendering.
Sources: CLAUDE.md:30-35, prompt.md:41-43, src/app/script/app/kl-app.ts:400-415
Feature Set and Tools
Klecks provides a suite of professional creative tools designed for both desktop and touch interfaces.
Drawing and Editing Tools
- Brush Engine: Supports multiple brush types including pen, blend, sketchy, pixel, and smudge. It includes pressure sensitivity support for styluses and stabilizers to smooth lines.
- Image Operations: Tools for selection (lasso/polygon), paint bucket (flood fill), text rendering, and shape generation.
- Filters: WebGL-powered filters including blur, tilt-shift, curves, distort, and chromatic aberration.
- Transformations: Full support for cropping, resizing, and perspective transforms.
Sources: README.md:12-21, src/help.html:200-240, src/app/script/app/kl-app.ts:500-550
Shortcut System
The application features an extensive shortcut system for efficient workflows.
| Action | Shortcut |
|---|---|
| Eyedropper | Right Click or Alt + Mouse |
| Undo / Redo | Ctrl+Z / Ctrl+Y |
| Zoom | Scroll or Z + Horizontal Drag |
| Rotate View | R + Drag |
| Color Picker HUD | Ctrl + Alt |
| Brush Size | [ and ] |
Sources: src/help.html:105-180
Standalone vs. Embedded Modes
Klecks is uniquely designed to run in two distinct environments:
Standalone Mode
The standalone version (found at src/app/script/main-standalone.ts) is a full-featured application. It includes persistent storage using IndexedDB, a gallery system for managing multiple artworks, and comprehensive file export options (PNG, PSD via ag-psd).
Sources: CLAUDE.md:6-8, src/app/script/main-standalone.ts:1-60, src/app/script/app/kl-app.ts:850-870
Embedded Mode
The embedded version acts as a widget (built via bun run build:embed). It provides an API for parent websites to open projects, read PSD buffers, and handle submissions through an onSubmit callback.
This sequence shows the interaction between a hosting site and the Klecks embedded instance.
Sources: examples/embed/example.html:36-54, src/app/script/app/kl-app.ts:100-110
UI Customization: Rocreate & Procreate Styles
The Rocreate project extends the base Klecks application with a specialized "Procreate-style" interface. This mode, managed by ProcreateLayout, replaces the traditional desktop toolbars with a minimalist, touch-friendly UI featuring:
- Vertical sliders for brush size and opacity.
- A "disappearing UI" philosophy to maximize canvas space.
- Radial "Quick Menu" for frequent actions.
- Gesture-first interactions (e.g., 2-finger tap to undo).
Sources: src/app/script/app/kl-app.ts:1335-1450, src/app/style/procreate.scss:1-50, funkcje-app.txt:1-10
Conclusion
Klecks serves as a high-performance graphics foundation for the Rocreate project. By combining a flexible TypeScript architecture with CanvasKit rendering and a modular UI system, it provides a professional-grade creative environment that scales from simple web embeds to complex, standalone painting suites. Its commitment to open-source accessibility and performant graphics makes it a critical component for browser-based digital artistry.
Sources: README.md:27-30, prompt.md:1-10