Development Roadmap

Version: v2.0.1 Updated: 2025-12-05 Status: Graphics integration complete, ready for Hex.pm publishing

Document Organization

This TODO is organized by priority:

IMMEDIATE NEXT STEPS - What to do now (Hex.pm publishing workflow)
RECENTLY COMPLETED - Work completed for v2.0.1 (graphics integration)
CRITICAL PRIORITIES - Blocking issues (none currently)
HIGH PRIORITY - Release process details (publishing steps)
FUTURE ENHANCEMENTS - Post-release features with implementation plans (v2.2+)
TECHNICAL DEBT - Minor issues to address when convenient
KNOWN NON-ISSUES - Reference documentation for expected behaviors
FUTURE ROADMAP - Long-term vision (Q2 2025+)

Quick Links

Hex.pm Publishing: See "IMMEDIATE NEXT STEPS" section below
Recent Work: See "RECENTLY COMPLETED" for graphics integration details
Kitty Protocol Plan: docs/project/KITTY_PROTOCOL_PLAN.md
Code Review: docs/project/CODE_REVIEW_GRAPHICS_INTEGRATION.md
Session Summary: docs/project/SESSION_SUMMARY.md

IMMEDIATE NEXT STEPS

🎯 Publish to Hex.pm (v2.0.1)

Priority: Immediate Effort: 1-2 hours Status: Ready - all prerequisites met

Why now?

✅ All tests passing (4344 tests)
✅ Zero compilation warnings
✅ Graphics system integration complete
✅ Package structure verified
✅ Documentation complete
✅ Domain purchased (raxol.io)

Workflow (see detailed steps below in HIGH PRIORITY section):

Run final tests and build docs
Authenticate with Hex.pm
Publish packages in order (core → plugin → liveview → meta)
Create git tags

What happens after publishing?

Users can install via {:raxol, "~> 2.0"}
Gather feedback on graphics features
Prioritize v2.2 features based on user demand
Consider Kitty Graphics Protocol implementation

RECENTLY COMPLETED (v2.0.1)

Plugin Visualization Integration ✅

Completed: 2025-12-05 Effort: 2 days (as estimated)

Summary: Full integration of Sixel graphics rendering in plugin visualization system.

Implementation:

Created create_sixel_cells_from_buffer/2 bridging plugin → terminal Sixel
Integrated with Raxol.Terminal.ANSI.SixelGraphics.process_sequence/2
Implemented pixel buffer → Cell grid conversion with RGB color mapping
Comprehensive test suite: 8 tests, 100% passing
Code quality improvements: DRY helpers, flattened cases, pattern matching
Test code reduced by 45% through helper functions

Quality Metrics:

Zero compilation warnings
Zero test regressions
Code quality score: 8.7/10 → 9.3/10 (+7%)
Fully functional, idiomatic Elixir patterns

Files:

lib/raxol/plugins/visualization/image_renderer.ex
test/raxol/plugins/visualization/image_renderer_test.exs
docs/project/KITTY_PROTOCOL_PLAN.md (400+ lines)
docs/project/CODE_REVIEW_GRAPHICS_INTEGRATION.md
docs/project/SESSION_SUMMARY.md

Documentation: See CHANGELOG.md for detailed changes.

Test Type Warnings Fixed ✅

Completed: 2025-12-05 Effort: 15 minutes (as estimated)

Summary: Removed unreachable pattern matching clauses causing Dialyzer warnings.

Fixes:

Removed unreachable %Emulator{} = emu -> emu patterns (lines 178, 350)
DCS handlers return tuples {:ok, emu} or {:error, reason, emu}, not bare structs
Pattern matching now correctly handles all return types

Quality Metrics:

Zero compilation warnings in Raxol code
All 10 DCS handler tests passing
Clean build with --warnings-as-errors

Files Modified:

test/raxol/terminal/commands/dcs_handlers_test.exs

CRITICAL PRIORITIES

No critical blockers identified

HIGH PRIORITY (v2.0.1 Release Process)

Hex.pm Publishing Checklist

Priority: Required for public release
Status: Ready for publishing
Changes Made:
- [x] Configured root as meta-package with path dependencies to apps/
- [x] Verified all package READMEs use GitHub links correctly
- [x] Tested independent compilation of all packages (raxol_core, raxol_plugin, raxol_liveview)
- [x] Tested root compilation with path dependencies
- [x] Removed duplicate files from root lib/raxol/core/ (box.ex, buffer.ex, renderer.ex, style.ex)
- [x] Verified zero warnings and all tests passing after cleanup

Publishing Workflow:

Prepare for Publishing:

# Ensure all tests pass
env TMPDIR=/tmp SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker

# Ensure no warnings
env TMPDIR=/tmp SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix compile --warnings-as-errors

# Build docs for each package
cd apps/raxol_core && mix docs
cd ../raxol_plugin && mix docs
cd ../raxol_liveview && mix docs
cd ../..

Authenticate with Hex.pm:
```
mix hex.user auth
```

Publish Packages in Order:

# Publish raxol_core first (no dependencies)
cd apps/raxol_core
mix hex.publish

# Publish raxol_plugin (depends on raxol_core)
cd ../raxol_plugin
mix hex.publish

# Publish raxol_liveview (depends on raxol_core)
cd ../raxol_liveview
mix hex.publish

# Publish raxol meta-package last (depends on all three)
cd ../..
mix hex.publish

Create Git Tags:
```
git tag v2.0.1
git push origin v2.0.1
```

Package Structure:

raxol_core - Core buffer primitives (zero dependencies, <100KB)
raxol_plugin - Plugin framework (depends on raxol_core)
raxol_liveview - Phoenix LiveView integration (depends on raxol_core)
raxol - Meta-package (includes all three packages)

Installation Options for Users:

# Minimal - just buffer primitives
{:raxol_core, "~> 2.0"}

# With LiveView support
{:raxol_core, "~> 2.0"}
{:raxol_liveview, "~> 2.0"}

# Everything (meta-package)
{:raxol, "~> 2.0"}

FUTURE ENHANCEMENTS (v2.2+)

Post-Release Improvements (Optional)

Documentation & Examples

Priority: Medium
Effort: 2-3 days
Tasks:
- Create demo application showcasing Sixel rendering capabilities
- Add cookbook examples for plugin visualization usage
- Performance benchmarks for image rendering
- Video tutorials for graphics features
- Point raxol.io domain to documentation site

Property-Based Tests

Priority: Low
Effort: 1-2 days
Tasks:
- Add property-based tests for graphics modules
- Test grid dimension invariants
- Test color conversion edge cases
- Test Sixel parser with random valid sequences

Graphics System Enhancements

1. Kitty Graphics Protocol

Priority: Medium (based on user demand)
Effort: 14 days (1-2 weeks)
Status: Planned - detailed implementation plan ready
Plan Document: docs/project/KITTY_PROTOCOL_PLAN.md
Rationale: Modern protocol superior to Sixel in several ways:
- Native animation support (unlike Sixel)
- Better compression (zlib, PNG)
- More efficient for large images
- Pixel-perfect placement with z-indexing
- Base64 transmission for compatibility
Implementation Phases:
1. Parser (3 days) - Control data parsing, base64 decoding, chunking
2. Graphics State (3 days) - Image store, placement management, z-index
3. DCS Integration (1 day) - Route Kitty sequences to graphics handler
4. Compression (1 day) - zlib/PNG decompression support
5. Animation (2 days) - Frame sequencing, playback scheduling
6. Plugin Integration (2 days) - Update create_kitty_cells function
7. Testing (2 days) - Comprehensive test suite
Architecture: Mirrors proven Sixel pattern (KittyParser, KittyGraphics, KittyAnimation)
Decision Point: Gather user feedback post-v2.0.1 release before implementing

2. Sixel Animation Support

Priority: Low
Effort: 3-5 days
Status: Not in DEC Sixel spec (extension would be custom)
Note: Original Sixel protocol supports static images only (by design)
Implementation Plan:
1. Add frame sequencing to SixelGraphics state
2. Implement frame timing and delay parameters
3. Add frame buffer management with double buffering
4. Create animation playback scheduler
5. Handle frame transitions and cleanup
Alternative: Use Kitty protocol which has native animation support
Considerations: Custom extension may not be compatible with other Sixel implementations

Distributed Systems

Distributed Session Management

Location: lib/raxol/core/session/distributed_session_registry.ex:899, 912
Functions: Session rebalancing and migration stubs
Status: Infrastructure for future distributed deployment
Rationale: Future feature, not needed for current release

Distributed Test Infrastructure

~10 distributed session registry tests skipped
Requires multi-node Erlang setup
See test/raxol/core/session/distributed_session_registry_test.exs
Defer until distributed features are prioritized

Code Quality

Credo Warnings

Various code quality suggestions
Non-blocking, address incrementally
Can be tackled during maintenance windows

TECHNICAL DEBT

Dependency Warnings (Jason)

Priority: Very Low
Source: Jason dependency (deprecated charlist syntax)
Impact: None on Raxol code
Status: Will be fixed in future Jason releases
Note: These warnings are from dependencies, not Raxol code

Minor Test Variable Warnings

Priority: Very Low
Impact: None (tests pass, cosmetic only)
Examples: Unused variables in test setups
Fix: Can be addressed incrementally during maintenance

KNOWN NON-ISSUES (For Reference Only)

RuntimeTest - Skipped by Design

Location: test/raxol/runtime_test.exs
Status: 6 tests tagged @tag skip: "Requires messaging infrastructure not yet implemented"
Lines: 220, 274, 308, 364, 408, 442
Rationale: Intentional, not a bug

Termbox2LoadingTest - NIF Loading

Status: Expected failure when SKIP_TERMBOX2_TESTS=true
Rationale: By design, no action required

FUTURE ROADMAP

Platform Expansion (Q2 2025)

WASM production support
PWA capabilities
Mobile terminal support
Cloud session management

Long-term Vision

AI-powered command completion
IDE integrations
Natural language interfaces
Collaborative terminal sessions

Development Commands

# Testing
TMPDIR=/tmp SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker

# Quality
mix raxol.check
mix format
TMPDIR=/tmp SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix compile --warnings-as-errors

← Previous Page Raxol.Core Examples

Next Page → CHANGELOG