Introduction to DOTORIXEL
Relevant source files
The following files were used as context for generating this wiki page:
DOTORIXEL is a cross-platform 2D pixel art editor designed with a "learning-first" philosophy. It allows users to open a browser or native application and start drawing immediately. The project utilizes a shared core logic written in Rust to ensure high performance and consistency across different platforms, including Web (TypeScript/Svelte), macOS, and iPadOS (Swift/SwiftUI).
Sources: README.md:1-5, CLAUDE.md:3-5
The application is structured around a multi-shell architecture where a single Rust core provides the heavy lifting for pixel manipulation, coordinate transforms, and history management. This core is then exposed to platform-specific UI shells via WebAssembly (WASM) for the web and UniFFI for Apple platforms.
Sources: issues/013-apple-native-catchup.md:21-27, tasks/records/001-pre-workflow-migration.md:46-51
Project Architecture
DOTORIXEL follows a "Multi-Shell, Single-Core" architecture. The core logic is decoupled from the UI framework to ensure testability and portability.
Core-Shell Relationship
The shared Rust core (located in crates/core/) handles domain-specific logic, while the Web and Apple shells handle user interaction and rendering.
The diagram shows how the Rust Core acts as the single source of truth for logic, consumed by different platform bindings.
Sources: CLAUDE.md:7-21, issues/013-apple-native-catchup.md:21-27, tasks/records/001-pre-workflow-migration.md:46-51
Tech Stack Summary
| Component | Web Technology | Apple Technology |
|---|---|---|
| UI Framework | TypeScript + Svelte (SvelteKit) | SwiftUI |
| Rendering | Canvas2D (WebGL2 planned) | Metal |
| Bindings | wasm-pack (WASM) | UniFFI |
| State Management | Svelte Runes / Classes | SwiftUI @Observable |
| Persistence | IndexedDB (idb) | SwiftData (Planned) |
Sources: CLAUDE.md:7-21, README.md:47-56, issues/007-session-persistence.md:29-35
Core Systems
Pixel Manipulation and Tools
The editor supports a variety of drawing tools, including Pencil, Eraser, Line, Rectangle, Ellipse, Flood Fill, and Eyedropper. The algorithms for these tools (such as Bresenham's line drawing) are implemented in Rust to ensure identical behavior across platforms.
Sources: README.md:14-16, issues/013-apple-native-catchup.md:33-40
History Manager (Undo/Redo)
Undo and redo functionality is snapshot-based and managed within the Rust core. This ensures that state-changing operations are tracked consistently regardless of the UI shell.
Sources: tasks/records/001-pre-workflow-migration.md:22-24, tasks/records/001-pre-workflow-migration.md:58-60
Viewport and Transforms
Coordinate transforms (converting screen/mouse coordinates to pixel grid coordinates) are handled by the core. This system supports zooming and panning, with logic shared across the Web and Apple shells.
Sources: tasks/records/001-pre-workflow-migration.md:61-62, issues/013-apple-native-catchup.md:45-48
Design System
DOTORIXEL uses a unified design system referred to as the "Pebble" theme or the --ds-* token system. It prioritizes warm earth tones, rounded floating panels, and retro pixel aesthetics.
Token Architecture
The design system is based on CSS custom properties for the web and static SwiftUI.Color properties for Apple platforms, ensuring visual parity.
- Prefix: Tokens are unified under the
--ds-namespace (e.g.,--ds-accent,--ds-bg-base). - Theme Support: Supports light and dark modes via
data-theme="dark"attributes or platform-native color schemes. - Typography: Primarily uses pixel fonts like Galmuri and GeistPixel.
Sources: CLAUDE.md:126-135, tasks/records/045-design-system-application.md:14-18, src/app.html:10-16
Layout Paradigms
The application transitions between different layouts based on screen size:
- Compact: Tab navigation (mobile).
- Medium: Floating panels (tablets).
- Wide/X-Wide: Docked panels including TopBar, LeftToolbar, RightPanel, and StatusBar.
Sources: issues/014-apple-native-docked-layout.md:12-22, tasks/records/040-screen-inventory-breakpoint-matrix.md:19-22
Data Persistence
Persistence is handled using a "silent restore" strategy. On the web, the editor uses IndexedDB to store the workspace state and document data.
The flow shows the dirty-tracking and auto-save mechanism used to prevent data loss.
Sources: issues/007-session-persistence.md:37-45
Storage Schema
The persistence layer uses two primary object stores:
documents: Stores individual canvas data (pixels, dimensions, metadata).workspace: Stores session metadata (tab order, active tool, color selections, viewport state).
Sources: issues/007-session-persistence.md:29-35
Development Workflow
The project uses a structured task management system located in the tasks/ directory, utilizing files like todo.md, progress.md, and done.md.
Core Commands
| Action | Command |
|---|---|
| Install dependencies | bun install |
| Development (WASM + Web) | bun run dev |
| Run tests | bun run test |
| UI Component preview | bun run storybook |
| Build WASM only | bun run wasm:build |
Sources: README.md:65-80, CLAUDE.md:26-30
Conclusion
DOTORIXEL is an architecturally robust pixel art editor that leverages Rust for its core logic to maintain high performance across Web and Apple ecosystems. By combining a shared logic core with platform-native rendering (Metal/Canvas2D) and a unified design system, it provides a consistent and responsive experience for artists on any device.
Sources: README.md:1-5, CLAUDE.md:154-159