Phosphor

For the Rails developer who misses the terminal

A Crystal terminal UI framework that maps Rails conventions onto the Elm Architecture (MVU). If you've written a Rails app, you can read this framework's code on day one.

---

Why Crystal?

Crystal reads almost exactly like Ruby but compiles to native binaries — no JIT, no GC pauses at the wrong moment, no runtime to ship. A Rails developer can read Crystal code on day one. The differences that matter for a TUI framework are type safety (no NoMethodError at runtime) and fibers (lightweight green threads, like Go's goroutines, built in).

# This is valid Crystal. It looks like Ruby.
class TodoItem
  getter text : String
  getter done : Bool

  def initialize(@text, @done = false)
  end

  def render
    done ? "[✓] #{text}" : "[ ] #{text}"
  end
end

---

The core mental model: Rails MVC → MVU

Rails developers think in Model–View–Controller. This framework maps most naturally to Model–View–Update — Elm's architecture, the same pattern Bubbletea uses — but with Rails naming conventions so nothing feels alien.

For the full architectural rationale, see DESIGN.md.

---

Project structure

Familiar to any Rails developer:

my_tui_app/
├── src/
│   ├── app.cr                      # Entry point — like config/application.rb
│   ├── state/
│   │   └── app_state.cr            # Like your AR models, but an immutable struct
│   ├── screens/
│   │   ├── dashboard_screen.cr     # Like a controller — owns a View
│   │   └── detail_screen.cr
│   ├── widgets/
│   │   ├── mock/
│   │   │   ├── list_mock.cr        # Reusable primitive — could be its own shard
│   │   │   ├── input_mock.cr
│   │   │   └── spinner_mock.cr
│   │   ├── todo_list_widget.cr     # App-specific wrapper around ListMock
│   │   ├── search_input_widget.cr
│   │   └── status_bar_widget.cr
│   ├── ports/
│   │   ├── stdin_port.cr           # Continuous event source — keyboard
│   │   └── live_feed_port.cr       # Continuous event source — e.g. live data feed
│   ├── handlers/
│   │   └── key_handler.cr          # Like controller actions
│   └── router.cr                   # Like config/routes.rb
├── spec/
└── shard.yml                       # Like Gemfile

The key addition is widgets/mock/ — a home for reusable primitives that could be extracted into their own published shard, like a gem for UI components. The ports/ directory holds anything that emits events continuously, as opposed to one-shot async work.

---

What you get for free vs. Rails

---

Platform support

phosphor supports Unix-like systems only: macOS, Linux, BSD, and WSL2 on Windows.

Native Windows console support is not on the roadmap. Windows users should run phosphor through WSL2, where it works the same as on any other Linux. See TASKS.md's Explicitly out of scope section for the full rationale.

---

Documentation

• DESIGN.md — Architecture: every layer explained with code samples and Rails analogies
• TASKS.md — Implementation roadmap, in build order
• CHANGELOG.md — Release notes
• CONTRIBUTING.md — How to contribute, report bugs, suggest features
• STABILITY.md — API stability tiers
• RELEASING.md — Versioning and release process

License

TBD