Core Engine (Rust)

The Core Engine is the self-contained, high-performance heart of Dotorixel, implemented in Rust to ensure platform-agnostic logic and computational efficiency. It handles the critical domain logic of the pixel art editor, including pixel buffer management, coordinate transformations, drawing tool algorithms, and undo/redo history.

By decoupling this core logic from the UI shells (Web/Svelte and Apple/SwiftUI), the engine serves as a "single source of truth" for pixel manipulation across all supported platforms. It is compiled to WebAssembly (WASM) for web use via wasm-pack and linked as a static library for Apple platforms using UniFFI bindings.

Sources: CLAUDE.md, README.md, wasm/src/lib.rs

Architecture and Integration

The engine is structured as a standalone library within crates/core/, which is consumed by different platform-specific bindings. This architecture ensures that core logic remains pure and free from framework dependencies like the DOM or SwiftUI.

The diagram above illustrates how the shared Rust core provides centralized logic to different platform shells.
Sources: CLAUDE.md, wasm/src/lib.rs, tasks/records/001-pre-workflow-migration.md

Canvas and Pixel Management

The primary data structure is the PixelCanvas, which manages a flat RGBA pixel buffer. It supports operations for pixel manipulation, bulk buffer restoration, and resizing with anchor points.

Pixel Storage

Pixels are stored as a flat Vec<u8> where each pixel occupies 4 bytes (RGBA). The engine enforces specific constraints on canvas dimensions to ensure stability and performance.

Sources: crates/core/src/canvas.rs:7-12, tasks/records/057-canvas-resize-ux.md

Resize Logic and Anchors

The engine supports resizing the canvas while maintaining existing content through a ResizeAnchor system. This allows users to expand or shrink the canvas relative to nine different positions (e.g., TopLeft, Center, BottomRight).

The resize process uses integer arithmetic to compute offsets, often resulting in truncation on odd deltas, which is standard behavior for pixel editors.
Sources: crates/core/src/canvas.rs:88-150, tasks/records/057-canvas-resize-ux.md

Tool System and Algorithms

The core defines a ToolType enum and associated algorithms for manipulating the pixel buffer.

Supported Tools

The engine implements various drawing behaviors, including:

• Pencil: Direct pixel manipulation.
• Eraser: Sets pixels to transparent.
• Line: Implements the Bresenham line drawing algorithm via interpolate_pixels.
• Shapes: Logic for rectangles and ellipses.
• Flood Fill: Seed-based fill algorithm.

Sources: crates/core/src/tool.rs, tasks/records/020-line-tool.md

Interpolation

The engine provides a wasm_interpolate_pixels utility (and internal core equivalent) that generates a sequence of coordinates between two points. This is used for continuous brush strokes and the line tool. It returns a flat integer array [x0, y0, x1, y1, ...] for efficient transfer across the WASM boundary.

Sources: wasm/src/lib.rs:175-185, tasks/records/004-wasm-bindings.md

State and History Management

The HistoryManager handles undo and redo operations using a snapshot-based approach.

Snapshot Logic

When a state-changing operation occurs, the entire pixel buffer state is captured. The history system allows for stepping through these snapshots.

• push_snapshot: Adds the current pixel state to the undo stack and clears the redo stack.
• undo / redo: Returns the previous or next snapshot to be applied to the canvas.
• restore_pixels: A bulk operation that allows the shell to overwrite the entire canvas buffer with a snapshot retrieved from history.

Sources: crates/core/src/canvas.rs:165-175, tasks/records/005-ts-wasm-migration.md, tasks/records/003-history-undo-redo.md

Coordinate Systems and Viewport

The engine manages the transformation between Screen Coordinates (used by UI events) and Canvas Coordinates (used for pixel buffer indices).

The viewport logic handles pan clamping to prevent the canvas from disappearing and provides "fit to viewport" calculations to center the canvas at appropriate zoom levels.
Sources: wasm/src/lib.rs:120-160, tasks/records/004-wasm-bindings.md, tasks/records/001-pre-workflow-migration.md

Performance and Constraints

To ensure responsiveness, the engine imposes a performance-based threshold for certain operations:

• Snapshot-Restore Pattern: Used for tool previews (like the Line tool). This is deemed safe for canvases up to 512x512 pixels due to low memcpy costs.
• Guard Tests: Rust unit tests enforce MAX_DIMENSION limits. If the threshold is raised beyond 512, the engine requires a switch to an "overlay preview" approach to prevent frame drops.

Sources: tasks/records/020-line-tool.md

Conclusion

The Rust Core Engine provides the reliable, high-performance foundation required for a cross-platform pixel art editor. By encapsulating complex logic like Bresenham interpolation, coordinate math, and snapshot-based history, it allows the platform-specific shells to focus purely on UI and rendering performance (Canvas2D/Metal), ensuring a consistent user experience regardless of the device.