How elouangrimm/kelk works
1. What this repo is
- This is a browser-based digital painting app, “Kelk,” forked from Klecks.
- It is a client-side TypeScript application with no visible backend in the repo; persistence and export are handled in-browser using Web APIs.
2. Top-level app shell
- src/app/script/main-standalone.ts is the standalone entrypoint used for the downloadable app build.
- src/index.html, src/style/*, src/app/theme/*, and src/app/fonts/* define the page shell, styling, themeing, and font assets.
- src/app/script/app/* contains bootstrapping and app-level wiring, including import handling and app selection flows.
3. Core painting domain
- The main domain lives under src/app/script/klecks/*.
- This layer owns the project model, layers, brushes, tools, filters, selection, history, storage, and most UI.
- kl.ts, kl-types.ts, and kl-config.ts appear to define the application’s central state and configuration boundaries.
4. Canvas and rendering pipeline
- src/app/script/klecks/canvas/* is the raster drawing/compositing layer.
- It handles painting onto canvases, eyedropper sampling, blending, and composing layer updates into the final project view.
- src/app/script/klecks/ui/project-viewport/* is the preview/render surface shown to the user, including project preview rendering and FX preview integration.
5. Brush and stroke subsystem
- Brushes are separated into a brush engine and brush-specific UI.
- src/app/script/klecks/brushes/* contains the drawing behaviors: pen, blend, sketchy, pixel, chemy, smudge, and eraser.
- src/app/script/klecks/brushes-ui/* contains the settings panels and controls for those brushes.
- Stroke cleanup and smoothing live in src/app/script/klecks/events/*, which sits between raw input and rendered brush paths.
6. Input and gesture architecture
- Raw user input is normalized in src/app/script/bb/input/*.
- There are separate listeners for pointer, key, gesture, and wheel input, plus utilities for pressure normalization and event-chain handling.
- The event-chain utilities suggest a middleware-like pipeline for multi-touch gestures such as pinch zoom, double tap, and pointer coalescing before tools receive input.
7. Tooling and interaction model
- The interactive tool layer is in src/app/script/klecks/ui/easel/* and src/app/script/klecks/ui/tool-tabs/*.
- The easel is the main interaction surface for brush strokes, hand/pan, zoom, rotate, select, paint bucket, gradient, shape, text, and eyedropper tools.
- Tool tabs expose higher-level editing workflows such as file operations, fill, filters, layers, selection, settings, shapes, and text.
8. Selection, transforms, and edit operations
- Selection logic and transform handling are split across src/app/script/klecks/select-tool/*, src/app/script/bb/multi-polygon/*, and src/app/script/bb/transform/*.
- This layer supports polygon/shape selection, bounding-box calculations, free transform, crop/expand, resize, perspective, and related geometry operations.
- It is a distinct boundary between user interaction and pixel-level canvas mutation.
9. Filters and image operations
- There are two filter-related areas:
- src/app/script/fx-canvas/* for WebGL-based effect infrastructure and shaders.
- src/app/script/klecks/filters/* for app-level filter workflows such as blur, curves, distort, noise, rotate, flip, tilt-shift, unsharp mask, and perspective.
- Additional image tools such as flood fill, text rendering, grids, vanish point, and shapes are under src/app/script/klecks/image-operations/*.
- This indicates a split between GPU-accelerated effects and application-level editing commands.
10. History and undo/redo
- src/app/script/klecks/history/* manages project history, temp history, and execution of history entries.
- The history system tracks layer changes, opacity/visibility changes, and canvas tile diffs, which implies fine-grained undo/redo rather than full-scene snapshots only.
- There are helpers for composing history state, estimating memory cost, and converting project state to composable layer data.
11. Storage, import/export, and external boundaries
- Persistence is handled in src/app/script/klecks/storage/*.
- The app uses browser storage primitives such as IndexedDB and likely localStorage for project persistence and state recall.
- It can load/save project formats, export canvas data, and save files to the user’s computer.
- The presence of imgur-upload.ts indicates an optional external service boundary for sharing or uploading images.
12. UI system and modal workflows
- Reusable UI widgets live in src/app/script/klecks/ui/components/*.
- Modal dialogs cover file import, new image creation, clipboard actions, licenses, image import, text tool editing, and iframe-based dialogs.
- Mobile-specific layout and toolspace behavior live under src/app/script/klecks/ui/mobile/*, showing the app is designed for multiple form factors with separate interaction ergonomics.
13. Localization and content assets
- User-facing language content is stored under src/languages/*, with generated JSON5 sources and language metadata.
- src/app/script/language/* likely wires translated strings into runtime language selection.
- Fonts and licenses are bundled locally, so text rendering and legal attribution are part of the app package rather than external dependencies.
14. Build and deployment shape
- This is a Node/npm-based frontend project, built with npm run build into dist/.
- docker-compose.yml and Dockerfile support containerized local serving on port 5050.
- The architecture is therefore a single-page/browser app with static asset delivery, GPU-accelerated effects, and browser-native persistence, rather than a client-server application.
Main entry points: kl.ts Kelk state · kl-app.ts App wiring · easel.ts Easel · file-ui.ts Tool tabs
Components 25
App shell
Standalone entrypoint, page chrome, theme, fonts, and app boot wiring.
- Standalone app · Downloadable app bootstrap and standalone startup.
src/app/script/main-standalone.ts - App wiring · Application selection, import handling, and shell coordination.
src/app/script/app/kl-app.ts - Theme & styles · Global theme, page styles, and visual variables.
src/app/style/style.scss - Fonts · Bundled font data and licenses for text rendering.
src/app/fonts/fonts.ts
Painting core
Project state, tools, brushes, canvas rendering, history, storage, and editing operations.
- Kelk state · Central project and application state boundary.
src/app/script/klecks/kl.ts - Core types · Shared type definitions for the painting domain.
src/app/script/klecks/kl-types.ts - Config · Application configuration and feature/runtime settings.
src/app/script/klecks/kl-config.ts - Brush engine · Brush behaviors including pen, blend, sketchy, pixel, chemy, smudge, and eraser.
src/app/script/klecks/brushes/brushes.ts - Brush UI · Brush settings panels and brush-specific controls.
src/app/script/klecks/brushes-ui/brushes-ui.ts - Canvas core · Painting, compositing, sampling, and layer update operations.
src/app/script/klecks/canvas/kl-canvas.ts - History · Undo/redo execution and fine-grained project change tracking.
src/app/script/klecks/history/kl-history.ts - Storage · Project persistence, PSD conversion, local save/load, and browser storage.
src/app/script/klecks/storage/project-store.ts
Interaction
Input normalization, gesture handling, selection geometry, and transforms.
- Input chain · Pointer, key, gesture, wheel, and pressure normalization pipeline.
src/app/script/bb/input/event-chain/event-chain.ts - Geometry · Multi-polygon selection and transform geometry helpers.
src/app/script/bb/multi-polygon/multi-polygon-from-rect.ts - Selection tools · Selection and transform interaction tools.
src/app/script/klecks/select-tool/select-tool.ts
Effects
GPU effect pipeline and app-level filters/image operations.
- FX canvas · WebGL effect infrastructure, shaders, textures, and shared FX plumbing.
src/app/script/fx-canvas/fx-canvas.ts - Filters · App-level image filters and transformation workflows.
src/app/script/klecks/filters/filters.ts - Image ops · Flood fill, text rendering, grid, vanish point, gradient, and shape operations.
src/app/script/klecks/image-operations/flood-fill.ts
UI
Reusable widgets, easel surface, project viewport, tool tabs, mobile, and modals.
- Easel · Primary drawing surface and tool interaction layer.
src/app/script/klecks/ui/easel/easel.ts - Project view · Project preview rendering, FX preview, and viewport presentation.
src/app/script/klecks/ui/project-viewport/project-viewport.ts - Tool tabs · File, fill, filters, layers, selection, settings, shapes, text, and related workflows.
src/app/script/klecks/ui/tool-tabs/file-ui.ts - UI components · Reusable controls, overlays, sliders, dialogs, and layout primitives.
src/app/script/klecks/ui/components/checkbox.ts - Mobile UI · Mobile-specific layout and toolspace behavior.
src/app/script/klecks/ui/mobile/mobile-ui.ts - Modals · File import, clipboard, licenses, text tool, upload, and other modal workflows.
src/app/script/klecks/ui/modals/show-import-image-dialog.ts
Assets
Language and font assets bundled with the client app.
- Languages · Localized string sources and runtime language selection.
src/app/script/language/language.ts
Connections 29
- Standalone app → App wiring: boots · Standalone entrypoint starts the app shell.
- App wiring → Kelk state: initializes · Boot wiring creates and coordinates the main app state.
- App wiring → Theme & styles: loads · Application shell applies theme and global styles.
- App wiring → Languages: localizes · Runtime selects translated UI strings.
- App wiring → Modals: opens · Shell routes import and setup workflows into dialogs.
- Kelk state → Core types: uses · Core state is defined by shared domain types.
- Kelk state → Config: reads · State and runtime behavior depend on central config.
- Kelk state → Brush engine: coordinates · App state drives brush behavior and active tool state.
- Kelk state → Canvas core: mutates · Brush strokes and edits apply through the canvas pipeline.
- Kelk state → History: records · Project changes are pushed into undo/redo history.
- Kelk state → Storage: persists · Projects are saved, loaded, and exported through storage.
- Brush UI → Brush engine: configures · Brush settings panels control brush engine parameters.
- Input chain → Easel: feeds · Normalized input is consumed by the drawing surface.
- Input chain → Selection tools: drives · Gestures and pointer events feed selection and transform tools.
- Input chain → Brush engine: streams · Pointer and pressure data become brush stroke input.
- Geometry → Selection tools: supports · Selection and transform tools use polygon and transform helpers.
- Selection tools → Canvas core: applies · Selections and transforms alter project pixels and layers.
- Easel → Canvas core: renders via · The easel paints strokes and tool interactions into the canvas layer.
- Easel → Image ops: invokes · Tools like bucket, gradient, shape, and text trigger image operations.
- Project view → FX canvas: previews · Viewport includes FX preview rendering for effects.
- Filters → FX canvas: executes on · App filters use the effect canvas and shader infrastructure.
- Filters → Canvas core: updates · Filter workflows apply changes to project canvas data.
- Tool tabs → Filters: exposes · Filter workflows are surfaced in the workspace tabs.
- Tool tabs → History: commits · Editing workflows push undoable actions into history.
- Tool tabs → Storage: saves · File workflows connect to persistence and export.
- UI components → Easel: compose · Shared UI widgets are used to build the easel surface.
- UI components → Tool tabs: compose · Shared widgets support the tool tab workspace.
- Mobile UI → Easel: adapts · Mobile layout changes the easel and toolspace ergonomics.
- Modals → Storage: imports/exports · Dialogs mediate file and clipboard boundaries.