charming 0.2.1 → 0.2.3

data/lib/charming/presentation/ui.rb

@@ -13,22 +13,38 @@ module Charming
       Style.new
     end
 
+    # Builds a color that resolves to *light* or *dark* at render time based on
+    # the terminal background. Usable anywhere a color is accepted.
+    def adaptive(light:, dark:)
+      AdaptiveColor.new(light: light, dark: dark)
+    end
+
     # Horizontally concatenates *blocks* into a single multi-line string, padding each block's
     # rows to match the widest row. A *gap* argument (in spaces) can separate adjacent columns.
-    def join_horizontal(*blocks, gap: 0)
+    # *align* positions shorter blocks along the cross axis: `:top` (default), `:center`,
+    # `:bottom`, or a fraction between 0.0 and 1.0.
+    def join_horizontal(*blocks, gap: 0, align: :top)
       normalized = normalize_blocks(blocks)
+      height = block_height(normalized)
+      aligned = normalized.map { |lines| offset_rows(lines, height, align) }
       widths = block_widths(normalized)
       separator = " " * gap
 
-      Array.new(block_height(normalized)) do |index|
-        horizontal_line(normalized, widths, index).join(separator)
+      Array.new(height) do |index|
+        horizontal_line(aligned, widths, index).join(separator)
       end.join("\n")
     end
 
-    # Stacks *blocks* vertically separated by one or more blank lines. A *gap* of N inserts N
-    # extra newline characters between blocks (1 gap = 1 blank line, 2 gaps = 2 blank lines, etc.).
-    def join_vertical(*blocks, gap: 0)
-      blocks.join("\n" * (gap + 1))
+    # Stacks *blocks* vertically separated by one or more blank lines, padding narrower
+    # blocks' lines to the widest block. A *gap* of N inserts N extra newline characters
+    # between blocks. *align* positions narrower lines along the cross axis: `:left`
+    # (default), `:center`, `:right`, or a fraction between 0.0 and 1.0.
+    def join_vertical(*blocks, gap: 0, align: :left)
+      normalized = normalize_blocks(blocks)
+      width = block_widths(normalized).max || 0
+
+      normalized.map { |lines| lines.map { |line| align_to(line, width, align) }.join("\n") }
+        .join("\n" * (gap + 1))
     end
 
     # Places *block* onto a blank canvas of *width* × *height* at an offset determined by *top* (row)
@@ -63,13 +79,13 @@ module Charming
 
     # Measures the displayed (visual) width of each normalised block, returning an array of integer widths.
     def block_widths(blocks)
-      blocks.map { |lines| lines.map { |line| Width.measure(line) }.max || 0 }
+      blocks.map { |lines| Width.widest(lines) }
     end
 
     # Returns the maximum visual character width across all *lines*, accounting for multi-column characters
     # (e.g., full-width CJK glyphs) and invisible ANSI escape sequences.
     def block_width(lines)
-      lines.map { |line| Width.measure(line) }.max || 0
+      Width.widest(lines)
     end
 
     # Returns the height in rows of each normalised block, taking the maximum across all blocks.
@@ -81,9 +97,34 @@ module Charming
     # every segment to its corresponding *width* in spaces. Returns the assembled array of padded segments.
     def horizontal_line(blocks, widths, index)
       blocks.each_with_index.map do |lines, block_index|
-        line = lines[index] || ""
-        line + (" " * (widths[block_index] - Width.measure(line)))
+        Width.pad_to(lines[index] || "", widths[block_index])
       end
     end
+
+    # Prepends blank rows to *lines* so the block sits at the cross-axis position
+    # given by *align* within *height* total rows.
+    def offset_rows(lines, height, align)
+      Array.new(cross_offset(align, height - lines.length), "") + lines
+    end
+
+    # Pads *line* to *width*, splitting the slack per the cross-axis *align* position.
+    def align_to(line, width, align)
+      slack = width - Width.measure(line)
+      return line if slack <= 0
+
+      leading = cross_offset(align, slack)
+      (" " * leading) + line + (" " * (slack - leading))
+    end
+
+    # Resolves an alignment (`:top`/`:left` → 0.0, `:center` → 0.5, `:bottom`/`:right` → 1.0,
+    # or a fraction) into a whole-cell offset within *slack* spare cells.
+    CROSS_POSITIONS = {top: 0.0, left: 0.0, center: 0.5, middle: 0.5, bottom: 1.0, right: 1.0}.freeze
+
+    def cross_offset(align, slack)
+      return 0 if slack <= 0
+
+      position = CROSS_POSITIONS.fetch(align, align)
+      (slack * position.to_f).round.clamp(0, slack)
+    end
   end
 end

data/lib/charming/presentation/view.rb

@@ -57,14 +57,16 @@ module Charming
       apply_style(content, style)
     end
 
-    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
-    def row(*items, gap: 0)
-      UI.join_horizontal(*items, gap: gap)
+    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports `gap:`
+    # spacing and cross-axis `align:` (`:top`/`:center`/`:bottom` or a 0.0–1.0 fraction).
+    def row(*items, gap: 0, align: :top)
+      UI.join_horizontal(*items, gap: gap, align: align)
     end
 
-    # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
-    def column(*items, gap: 0)
-      UI.join_vertical(*items, gap: gap)
+    # Stacks items vertically using the UI rendering engine. Supports `gap:` spacing and
+    # cross-axis `align:` (`:left`/`:center`/`:right` or a 0.0–1.0 fraction).
+    def column(*items, gap: 0, align: :left)
+      UI.join_vertical(*items, gap: gap, align: align)
     end
 
     # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.

data/lib/charming/response.rb

@@ -4,20 +4,25 @@ module Charming
   # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another route, or quit.
   # Rails-style factories (`render`, `navigate`, `quit`) serve as the public API and map to :kind values
   # that the Runtime interprets at the end of each event loop iteration.
-  Response = Data.define(:kind, :body, :path) do
-    # Factory constructing a Render response for displaying *body* text on the current screen.
-    def self.render(body)
-      new(kind: :render, body: body, path: nil)
+  #
+  # *escapes* carries any out-of-band terminal sequences (image transmissions, clipboard writes,
+  # notifications, window-title changes) gathered during the dispatch. The Runtime flushes them straight
+  # to the backend, bypassing the line-based frame pipeline. It is empty for ordinary responses.
+  Response = Data.define(:kind, :body, :path, :escapes) do
+    # Factory constructing a Render response for displaying *body* text on the current screen. *escapes*
+    # is the list of out-of-band sequences gathered during the dispatch (defaults to none).
+    def self.render(body, escapes: [])
+      new(kind: :render, body: body, path: nil, escapes: escapes)
     end
 
     # Factory constructing a NavigateResponse routing to the named *path* (string).
     def self.navigate(path)
-      new(kind: :navigate, body: "", path: path)
+      new(kind: :navigate, body: "", path: path, escapes: [])
     end
 
     # Factory constructing a QuitResponse signalling termination of the top-level event loop.
     def self.quit
-      new(kind: :quit, body: "", path: nil)
+      new(kind: :quit, body: "", path: nil, escapes: [])
     end
 
     # Returns `true` when this response is navigating to another screen or route.

data/lib/charming/runtime.rb

@@ -6,7 +6,7 @@ module Charming
   # reads keyboard, mouse, timer, and task events, dispatching them to
   # controllers, rendering responses, and tearing down cleanly on exit.
   class Runtime
-    DEFAULT_READ_TIMEOUT = 0.05
+    DEFAULT_READ_TIMEOUT = Internal::EventLoop::DEFAULT_READ_TIMEOUT
 
     def initialize(application, backend: nil, renderer: nil, clock: nil, task_executor: nil)
       @application = application
@@ -16,9 +16,10 @@ module Charming
       @task_queue = Thread::Queue.new
       @task_executor = build_task_executor(task_executor)
       @application.task_executor = @task_executor
-      @route = @application.routes.resolve("/")
+      @route = resolve_route("/")
       @screen = backend_screen
-      @timers = build_timers
+      @coalesce_input = @application.respond_to?(:coalesce_input?) && @application.coalesce_input?
+      @event_loop = build_event_loop
     end
 
     # Runs the event loop: enters alt-screen, dispatches incoming events
@@ -27,59 +28,87 @@ module Charming
     # actions render an ErrorScreen instead of crashing the terminal.
     def run
       setup_terminal
-      install_interrupt_handler
+      install_signal_handlers
+      install_exit_hook
       with_raw_input do
         render(initial_response)
-        loop do
-          break if @interrupted
-
-          event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
-          unless event
-            break if backend_exhausted?
-            next
-          end
-          break if process(event) == :quit
-        end
+        @event_loop.run { |event, more_ready| process(event, flush: !more_ready) }
+      ensure
+        restore_signal_handlers
+        @task_executor&.shutdown(timeout: 2.0)
+        @application.save_session if @application.respond_to?(:save_session)
+        restore_terminal
       end
-    ensure
-      restore_interrupt_handler
-      @task_executor&.shutdown(timeout: 2.0)
-      @application.save_session if @application.respond_to?(:save_session)
-      restore_terminal
     end
 
     private
 
     attr_reader :screen
 
-    # The first frame's response — the root route's action, with errors caught.
+    # Builds the event pump, wiring in the current controller's timer bindings and
+    # an interrupt check backed by the SIGINT flag set in install_interrupt_handler.
+    def build_event_loop
+      Internal::EventLoop.new(
+        backend: @backend,
+        clock: @clock,
+        task_queue: @task_queue,
+        timer_bindings: @route.controller_class.timer_bindings.values,
+        coalesce_input: @coalesce_input,
+        interrupted: -> { @interrupted }
+      )
+    end
+
+    # The first frame's response — the root route's action, with errors caught. Out-of-band escape
+    # sequences registered while rendering are collected and attached to the response.
     def initial_response
-      resolve_response(dispatch(@route.action))
+      response = nil
+      escapes = Escape.collecting { response = resolve_response(dispatch(@route.action)) }
+      attach_escapes(response, escapes)
     rescue => e
       error_response(e)
     end
 
     # Handles a single event. Returns :quit to stop the loop, nil otherwise.
     # While an error screen is showing, only key events are honored: q quits,
-    # any other key dismisses and re-renders the current route.
-    def process(event)
+    # any other key dismisses and re-renders the current route. When *flush* is
+    # false (more events are already due), the response is held so a burst of
+    # task/timer events paints once with the final state; held escapes are
+    # carried forward in order so none are lost.
+    def process(event, flush: true)
       return process_error_event(event) if @error
       return :quit if unbound_interrupt?(event)
 
-      response = dispatch_event(event)
-      return unless response
-      return :quit if response.quit?
-
-      response = resolve_response(response)
+      response = nil
+      escapes = Escape.collecting do
+        response = dispatch_event(event)
+        response = resolve_response(response) if response
+      end
+      return flush_pending if response.nil?
       return :quit if response.quit?
 
-      render(response)
-      nil
+      hold_response(response, escapes)
+      flush ? flush_pending : nil
     rescue => e
+      @pending_response = nil
       render(error_response(e))
       nil
     end
 
+    # Replaces the held response with *response*, prepending any escapes held
+    # from earlier events in the burst so they still flush in order.
+    def hold_response(response, escapes)
+      held = @pending_response&.escapes || []
+      @pending_response = response.with(escapes: held + response.escapes + escapes)
+    end
+
+    # Renders the held response, if any. Always returns nil (the loop's "keep going").
+    def flush_pending
+      response = @pending_response
+      @pending_response = nil
+      render(response) if response
+      nil
+    end
+
     # Error-mode event handling: q quits, any other key dismisses the error
     # and re-dispatches the current route's action. Timer/task events are ignored.
     def process_error_event(event)
@@ -91,13 +120,6 @@ module Charming
       nil
     end
 
-    # True when the backend reports it has no more events to deliver (test backends
-    # only — the TTY backend never exhausts). Prevents the loop from spinning forever
-    # in tests that forget a trailing quit event.
-    def backend_exhausted?
-      @backend.respond_to?(:exhausted?) && @backend.exhausted?
-    end
-
     # True for a Ctrl+C key press that the current controller has no binding for —
     # the runtime treats it as quit so apps always have an escape hatch. Controllers
     # can take over by binding "ctrl+c" themselves.
@@ -108,20 +130,66 @@ module Charming
       @route.controller_class.key_bindings[:"ctrl+c"].nil?
     end
 
-    # Traps SIGINT so Ctrl+C (when delivered as a signal rather than a key) exits the
-    # loop cleanly through the ensure block instead of crashing mid-frame.
-    def install_interrupt_handler
+    # Signals that should exit the loop cleanly through the ensure block (restoring
+    # the terminal) instead of killing the process mid-frame.
+    QUIT_SIGNALS = %w[INT TERM HUP].freeze
+
+    # Traps quit signals to set the interrupt flag the event loop checks, and —
+    # when the backend supports it — SIGTSTP/SIGCONT for shell suspend/resume.
+    def install_signal_handlers
       @interrupted = false
-      @previous_int_handler = Signal.trap("INT") { @interrupted = true }
-    rescue ArgumentError
-      @previous_int_handler = nil
+      @previous_handlers = {}
+      QUIT_SIGNALS.each { |signal| trap_signal(signal) { @interrupted = true } }
+      install_suspend_handlers if @backend.respond_to?(:suspend)
+    end
+
+    # Ctrl+Z: return the terminal to its normal state, stop the process, and on
+    # SIGCONT re-enter the TUI and force a repaint via the backend's resize path.
+    def install_suspend_handlers
+      trap_signal("TSTP") { suspend }
+      trap_signal("CONT") { resume }
     end
 
-    # Restores the previous SIGINT handler installed before the runtime started.
-    def restore_interrupt_handler
-      Signal.trap("INT", @previous_int_handler || "DEFAULT")
+    # Traps *signal*, remembering the previous handler for teardown. Platforms
+    # without the signal (or restricted environments) are silently skipped.
+    def trap_signal(signal, &block)
+      @previous_handlers[signal] = Signal.trap(signal, &block)
     rescue ArgumentError
-      nil
+      @previous_handlers.delete(signal)
+    end
+
+    # Restores every signal handler that was replaced when the runtime started.
+    def restore_signal_handlers
+      (@previous_handlers || {}).each do |signal, previous|
+        Signal.trap(signal, previous || "DEFAULT")
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Restores the terminal for the shell and stops the process (the untrappable
+    # SIGSTOP), so Ctrl+Z behaves like it does in any well-behaved TUI.
+    def suspend
+      @backend.suspend
+      Process.kill("STOP", Process.pid)
+    end
+
+    # Re-enters the TUI after a foreground `fg`: raw mode and alt screen come back,
+    # the renderer cache is dropped, and the backend's resize path triggers a repaint.
+    def resume
+      @backend.resume
+      @renderer.invalidate if @renderer.respond_to?(:invalidate)
+      @backend.notify_resize if @backend.respond_to?(:notify_resize)
+    end
+
+    # Registers a process-exit fallback so an unexpected death (an exception that
+    # skips run's ensure, or an exit from within a handler) still restores the
+    # terminal. restore_terminal is idempotent, so the normal path stays cheap.
+    def install_exit_hook
+      return if @exit_hook_installed
+
+      @exit_hook_installed = true
+      at_exit { restore_terminal }
     end
 
     # Records *error*, logs its backtrace, and builds a centered ErrorScreen response.
@@ -208,66 +276,54 @@ module Charming
     end
 
     # Follows navigation responses: resolves the new route from the router,
-    # resets timers for the new route, and dispatches that route's action.
+    # reschedules the event loop's timers for the new controller, and
+    # dispatches that route's action.
     def resolve_response(response)
       return response unless response.navigate?
 
-      @route = @application.routes.resolve(response.path)
-      @timers = build_timers
+      @route = resolve_route(response.path)
+      @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
       dispatch(@route.action)
     end
 
+    # Resolves *path* from the app's router. An unrouted "/" falls back to the app's
+    # first route, or to the built-in welcome screen when no routes are defined yet
+    # (like Rails' welcome page); other unrouted paths still raise.
+    def resolve_route(path)
+      @application.routes.resolve(path)
+    rescue KeyError
+      raise unless path == "/"
+
+      @application.routes.all.first || Welcome.route
+    end
+
     # Derives Screen dimensions (width, height) from the terminal backend.
     def backend_screen
       width, height = @backend.size
       Screen.new(width: width, height: height)
     end
 
-    # Renders the body portion of a response through the renderer.
+    # Renders a response: first flushes any out-of-band escape sequences (image transmissions,
+    # clipboard writes, notifications, title changes) straight to the backend — ahead of the frame so
+    # image data is registered before its placeholder cells reference it — then renders the body.
     def render(response)
+      flush_escapes(response)
       @renderer.render(response.body)
     end
 
-    # Builds the initial set of timer states from controller bindings and the current clock time.
-    def build_timers
-      now = clock_now
-      @route.controller_class.timer_bindings.values.map do |binding|
-        {binding: binding, next_at: now + binding.interval}
-      end
-    end
-
-    # Returns a TimerEvent for the first due timer and advances its next fire time.
-    # Returns nil if no timers are ready or registered.
-    def next_timer_event
-      timer = due_timer
-      return unless timer
+    # Writes a response's out-of-band escape sequences to the backend, ahead of the frame. No-op for
+    # backends that don't support them or responses that carry none.
+    def flush_escapes(response)
+      return unless @backend.respond_to?(:write_escape)
 
-      now = clock_now
-      timer[:next_at] = now + timer.fetch(:binding).interval
-      Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
+      response.escapes&.each { |sequence| @backend.write_escape(sequence) }
     end
 
-    # Pops a task event from the thread-safe queue if one is available.
-    # Non-blocking — returns nil immediately when the queue is empty.
-    def next_task_event
-      @task_queue.pop(true)
-    rescue ThreadError
-      nil
-    end
-
-    # Returns timer values due at or before `now`, sorted by next fire time.
-    def due_timer
-      now = clock_now
-      @timers.select { |timer| timer.fetch(:next_at) <= now }.min_by { |timer| timer.fetch(:next_at) }
-    end
-
-    # Computes how long to block waiting for input based on when the next timer is due,
-    # clamped between 0 and DEFAULT_READ_TIMEOUT (0.05s). Returns DEFAULT when no timers exist.
-    def read_timeout
-      next_at = @timers.map { |timer| timer.fetch(:next_at) }.min
-      return DEFAULT_READ_TIMEOUT unless next_at
+    # Returns *response* with *escapes* appended, or unchanged when none were collected.
+    def attach_escapes(response, escapes)
+      return response if escapes.nil? || escapes.empty?
 
-      (next_at - clock_now).clamp(0, DEFAULT_READ_TIMEOUT)
+      response.with(escapes: response.escapes + escapes)
     end
 
     # Constructs a task executor: supports explicit instances, callable factories, or the default Threaded executor.
@@ -285,16 +341,33 @@ module Charming
     end
 
     # Enters an alternative screen buffer, hides the cursor, and installs
-    # a terminal resize signal handler if supported by the backend.
+    # a terminal resize signal handler if supported by the backend. Also asks
+    # the terminal for its background color so adaptive colors resolve correctly.
     def setup_terminal
+      detect_background
       @backend.enter_alt_screen
       @backend.hide_cursor
-      @backend.enable_mouse_tracking if @backend.respond_to?(:enable_mouse_tracking)
+      @backend.enable_mouse_tracking(motion: mouse_motion) if @backend.respond_to?(:enable_mouse_tracking)
       @backend.enable_bracketed_paste if @backend.respond_to?(:enable_bracketed_paste)
       @backend.enable_focus_reporting if @backend.respond_to?(:enable_focus_reporting)
       @backend.install_resize_handler if @backend.respond_to?(:install_resize_handler)
     end
 
+    # The app's configured mouse motion mode (:drag unless the app opts into :all hover).
+    def mouse_motion
+      @application.respond_to?(:mouse_motion) ? @application.mouse_motion : :drag
+    end
+
+    # Feeds the terminal's OSC 11 background reply (when the backend can obtain
+    # one) into UI::Background so adaptive colors resolve against reality rather
+    # than the dark-background default.
+    def detect_background
+      return unless @backend.respond_to?(:query_background_color)
+
+      background = @backend.query_background_color
+      UI::Background.assume = background if background
+    end
+
     # Keeps input raw/no-echo across rendering and dispatch, not just during reads.
     def with_raw_input(&block)
       return yield unless @backend.respond_to?(:with_raw_input)
@@ -303,8 +376,12 @@ module Charming
     end
 
     # Restores terminal state: reinstalls any previous resize handler, shows
-    # the cursor, and leaves the alternative screen buffer.
+    # the cursor, and leaves the alternative screen buffer. Idempotent — runs
+    # once whether reached from run's ensure or the at_exit fallback.
     def restore_terminal
+      return if @restored
+
+      @restored = true
       @backend.restore_resize_handler if @backend.respond_to?(:restore_resize_handler)
       @backend.disable_focus_reporting if @backend.respond_to?(:disable_focus_reporting)
       @backend.disable_bracketed_paste if @backend.respond_to?(:disable_bracketed_paste)

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/charming/welcome/controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Charming
+  module Welcome
+    # Controller for the built-in welcome screen. Renders without an app layout and
+    # binds only `q` to quit.
+    class Controller < Charming::Controller
+      key "q", :quit, scope: :global
+
+      def show
+        render_view ShowView, app_name: app_display_name
+      end
+
+      private
+
+      # The app's namespace for the welcome heading, or "Charming" for anonymous apps.
+      def app_display_name
+        name = application.class.namespace
+        name.to_s.empty? ? "Charming" : name
+      end
+    end
+  end
+end

data/lib/charming/welcome/show_view.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Charming
+  module Welcome
+    # The welcome screen body: a pastel Miami-deco skyline over the app name, tagline,
+    # Charming version, and project link, centered on the terminal.
+    class ShowView < Charming::View
+      SKYLINE_COLORS = {
+        "F" => "#f0437c", # flamingo
+        "B" => "#f9cfd8", # blush
+        "M" => "#bfe8dc", # mint
+        "C" => "#f3e6c9", # cream
+        "P" => "#fdfaf3", # plaster
+        "G" => "#1d4b44"  # palm green
+      }.freeze
+
+      # Rows of [art, color mask] pairs; each mask letter colors the glyph above it.
+      SKYLINE = [
+        ["                         ▲                         ",
+          "                         F                         "],
+        ["                         █                         ",
+          "                         F                         "],
+        ["             ▄▄▄        ▄█▄        ▄▄▄             ",
+          "             BBB        PFP        MMM             "],
+        ["             ███       ▐███▌       ███             ",
+          "             BBB       PPPPP       MMM             "],
+        ["            █▀▀▀█      ▐███▌      █▀▀▀█            ",
+          "            BBBBB      PPPPP      MMMMM            "],
+        ["  ▄█▄       █████     ▐█████▌     █████       ▄█▄  ",
+          "  GGG       BBBBB     PPPPPPP     MMMMM       GGG  "],
+        ["   █   ▄▄▄ ██▀▀▀██    ▐█████▌    ██▀▀▀██ ▄▄▄   █   ",
+          "   G   CCC BBBBBBB    PPPPPPP    MMMMMMM CCC   G   "],
+        ["   █   ███ ███████   ▐███████▌   ███████ ███   █   ",
+          "   G   CCC BBBBBBB   PPPPPPPPP   MMMMMMM CCC   G   "],
+        ["   █   ███ ███████   ▐███████▌   ███████ ███   █   ",
+          "   G   CCC BBBBBBB   PPPPPPPPP   MMMMMMM CCC   G   "],
+        ["▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁",
+          "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"]
+      ].freeze
+      SKYLINE_WIDTH = SKYLINE.map { |art, _mask| art.length }.max
+      SKYLINE_HEIGHT = SKYLINE.length
+
+      def render
+        screen_layout(background: theme.background) do
+          pane(style: centered) do
+            welcome_content
+          end
+        end
+      end
+
+      private
+
+      def centered
+        style.align(:center).align_vertical(:middle)
+      end
+
+      def welcome_content
+        column(*blocks, gap: 1, align: :center)
+      end
+
+      def blocks
+        [skyline, heading, tagline, footer, hint].compact
+      end
+
+      def skyline
+        return unless skyline_fits?
+
+        column(*SKYLINE.map { |art, mask| paint_row(art, mask) })
+      end
+
+      # Leave room below the art for the heading, tagline, footer, and hint lines.
+      def skyline_fits?
+        layout_screen.width >= SKYLINE_WIDTH && layout_screen.height >= SKYLINE_HEIGHT + 8
+      end
+
+      def paint_row(art, mask)
+        color_runs(art, mask).map { |run, key| paint(run, key) }.join
+      end
+
+      # Groups adjacent glyphs sharing a mask letter into [run, letter] pairs.
+      def color_runs(art, mask)
+        art.chars.zip(mask.chars)
+          .chunk { |_glyph, key| key || " " }
+          .map { |key, pairs| [pairs.map(&:first).join, key] }
+      end
+
+      def paint(run, key)
+        color = SKYLINE_COLORS[key]
+        color ? style.foreground(color).render(run) : run
+      end
+
+      def heading
+        text app_name, style: theme.title
+      end
+
+      def tagline
+        text "A Rails-inspired Ruby TUI framework", style: theme.text
+      end
+
+      def footer
+        column(
+          text("Charming v#{Charming::VERSION}", style: theme.muted),
+          text("https://github.com/pandorocks/charming", style: theme.muted),
+          align: :center
+        )
+      end
+
+      def hint
+        text "Define a root route in config/routes.rb to replace this screen.", style: theme.muted
+      end
+    end
+  end
+end