TODO.md

GPUI-WGPU Implementation TODO

This document outlines the incremental implementation plan for building GPUI on top of WGPU and winit. We're starting from a basic WGPU + winit foundation and gradually adding GPUI concepts.

Phase 1: Foundation (WGPU + winit)

Core Infrastructure

• Basic WGPU Context - Instance, adapter, device, queue setup
• Basic winit Window - Event loop, window creation, basic event handling
• Surface Management - Create and configure WGPU surface for rendering
• Basic Render Loop - Clear screen, present frames
• Coordinate Systems - Define pixel types (logical vs device pixels)

Basic Rendering

• Clear Color - Render solid color background
• Basic Shapes - Rectangles, circles using simple shaders
• Color Management - RGB/RGBA color types and conversion
• Viewport Management - Handle window resizing

Phase 2: Core Geometry and Math

Geometry Types (from geometry.rs)

• Point - 2D points with generic units
• Size - Width/height with generic units
• Bounds - Rectangle defined by origin + size
• Margins/Padding - Layout spacing types
• Transform2D - 2D transformations (translate, scale, rotate)
• Unit Types - Pixels, DevicePixels, ScaledPixels, etc.

Math Utilities

• Vector Math - Basic 2D vector operations
• Rectangle Operations - Intersection, union, contains, etc.
• Coordinate Conversions - Between different pixel types

Phase 3: Basic Element System

Core Element Types (from element.rs)

• Element Trait - Core rendering interface
• IntoElement Trait - Conversion to elements
• LayoutId - Unique identifiers for layout nodes
• ElementId - Unique identifiers for elements
• Hitbox - Click/interaction target areas

Basic Elements (from elements/)

• Div - Basic rectangular container (div.rs)
• Text - Basic text rendering (text.rs)
• Image - Basic image display (img.rs)
• Canvas - Custom drawing surface (canvas.rs)

Phase 4: Layout System

Taffy Integration (from taffy.rs)

• Layout Engine - Integrate Taffy flexbox/grid layout
• Layout Tree - Build and maintain layout hierarchy
• Layout Constraints - Min/max sizes, aspect ratios
• Layout Caching - Avoid unnecessary recalculations

Style System (from style.rs)

• Style Types - Width, height, margins, padding, etc.
• Flexbox Properties - Direction, justify, align, wrap, etc.
• Position Types - Relative, absolute positioning
• Style Resolution - Apply styles to layout engine

Phase 5: Text System

Core Text (from text_system/)

• Font Loading - Load system fonts and custom fonts
• Font Fallbacks - Handle missing glyphs (font_fallbacks.rs)
• Text Shaping - Layout text with proper spacing
• Line Layout - Multi-line text layout (line_layout.rs)
• Line Wrapping - Break text across lines (line_wrapper.rs)
• Text Rendering - Raster glyphs to texture atlas

Text Features

• Font Features - Ligatures, kerning, etc. (font_features.rs)
• Text Selection - Highlight ranges of text
• Text Editing - Cursor, insertion, deletion
• Rich Text - Multiple fonts/styles in one block

Phase 6: Input and Interaction

Input System (from input.rs, interactive.rs)

• Mouse Events - Click, move, enter/exit, wheel
• Keyboard Events - Key press/release, text input
• Touch Events - For touch-capable devices
• Focus Management - Tab order, focus states
• Hit Testing - Determine which element receives events

Event Dispatch (from key_dispatch.rs)

• Event Routing - Send events to appropriate handlers
• Event Bubbling - Propagate events up the tree
• Event Prevention - Stop propagation when handled
• Keyboard Shortcuts - Global and context-sensitive

Phase 7: Window Management

Basic Window (from window.rs)

• Window State - Size, position, focus, etc.
• Window Events - Resize, close, minimize, etc.
• Window Options - Title, decorations, transparency
• Multi-Window - Support multiple windows

Platform Integration

• Native Window - Bridge to OS window system
• Window Controls - Min/max/close buttons
• Window Menu - Native menu integration (if needed)
• Clipboard - Copy/paste support

Phase 8: Advanced Rendering

Scene Management (from scene.rs)

• Scene Graph - Hierarchical rendering structure
• Render Batching - Group similar draw calls
• Clipping - Scissor rectangles for overflow
• Layering - Z-order and transparency

Advanced Graphics

• Gradients - Linear and radial gradients
• Shadows - Drop shadows and box shadows
• Borders - Border styles, rounded corners
• Animations - Interpolated property changes
• GPU Shaders - Custom fragment/vertex shaders

Phase 9: Asset Management

Asset System (from assets.rs, asset_cache.rs)

• Asset Loading - Images, fonts, other resources
• Asset Caching - Avoid redundant loading
• Asset Watching - Reload changed assets in dev
• Asset Bundling - Package assets for distribution

Image Handling

• Image Formats - PNG, JPEG, SVG support
• Image Caching - GPU texture management
• Image Scaling - High-DPI support
• Image Effects - Filters, color adjustments

Phase 10: Advanced Elements

Container Elements

• List - Scrollable lists (list.rs)
• UniformList - Virtualized lists (uniform_list.rs)
• Anchored - Positioned overlays (anchored.rs)
• Deferred - Lazy-rendered content (deferred.rs)

Rich Elements

• SVG - Scalable vector graphics (svg.rs)
• Animation - Animated transitions (animation.rs)
• Surface - 3D-like surfaces (surface.rs)

Phase 11: Application Framework

Application Structure (from app.rs, app/)

• Application - Main app lifecycle management
• App Context - Global application state
• Entity System - Component-entity management
• View System - MVC-like view management

State Management

• Global State - Application-wide state (global.rs)
• Actions - Command pattern for user actions (action.rs)
• Subscriptions - Reactive data updates (subscription.rs)
• Context Propagation - Pass data down the tree

Phase 12: Developer Tools

Debugging and Testing

• Inspector - Runtime UI debugging (inspector.rs)
• Test Framework - Automated UI testing (test.rs)
• Performance Profiling - Frame time, memory usage
• Hot Reload - Live code updates during development

Development Experience

• Error Handling - Clear error messages
• Documentation - Examples and API docs
• Type Safety - Leverage Rust's type system
• IDE Integration - Good tooling support

Implementation Strategy

Start Simple

1. Begin with the basic WGPU hello triangle/rectangle
2. Add one concept at a time
3. Test thoroughly at each step
4. Keep examples working as we go

Incremental Approach

• Each phase builds on the previous
• Maintain backward compatibility within phases
• Create examples for each major milestone
• Document decisions and trade-offs

Integration Points

• Design for eventual integration with full GPUI
• Keep APIs similar to original GPUI where possible
• Plan for features like hot-reload and debugging
• Consider WASM compatibility from the start

Current Status

• Project setup in fts-extensions
• Phase 1: Foundation
• All other phases pending

Notes

• This is a substantial project that will take considerable time
• Focus on getting a minimal viable implementation first
• Consider which GPUI features are truly essential vs nice-to-have
• The goal is to prove WGPU viability, not feature parity