r2ui 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd8c94c82db6c74efb8c77dba2e80155c61336aa2e2f7e0c49ada508f0ea0ddf
-  data.tar.gz: 338646823240fdbecd726268b2ef4f72388a5e7633cbdbd0eb3acd0cc143d96a
+  metadata.gz: c882ac44b504e3e363957635e8cb4333d278c7f7d446a9e9c0a6afebc0dae542
+  data.tar.gz: 2c59540c2b881f51d0934d3f574140375b6745b7dce753b27e7e232ee1488abe
 SHA512:
-  metadata.gz: 91cc25cf40c7a4beedc55caf86f4dc13703c92c493bbadaccf326a60dea821611024f6a5f9ed8fdb8c6924e25596748c9d0948c6c35cab6291e526321b494ca5
-  data.tar.gz: 6c5f8747986ac1b5219ecfe3bc415ccac2ed79d23b107af5ec00616daac862e1e842ef030c0fbc214bba8ff7999351aa513bcda0a88528a77884ca0517bb373b
+  metadata.gz: a33b57ba6c51dd22b69b6e712e7599d6a32ba12f14dd6aed97c19852ba65a9051b1395d5b8064f6b427fd274559932dd7ea6cc38c4beb2091a0f3d8645c3aa04
+  data.tar.gz: ee66ef296a9e0f8b69af324d73efacd9c7f07fbfd4eed11b46e50895fa8a26590d778ba3f323168240bdfd00f466f9795438ee0e2c3a19de90848fa20c781581

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+Add entries under `## Unreleased`. To cut a release, the owner renames that heading to `## X.Y.Z` and adds a fresh `## Unreleased` above it (see docs/releasing.md).
+
+## Unreleased
+
+## 0.2.0
+
+### Upgrading from 0.1.0
+
+- Dashboards now run on r2ui's pure-Ruby Bubble Tea engine: `R2UI::App` is a Bubbletea model (`init`/`update`/`view`) and `R2UI.run` runs it on the compat runner. The old terminal loop and raw key parser are gone; keys, search, sorting and folding behave as before.
+- Plain `require "r2ui"` loads the engine by path and leaves `require "bubbletea"` / `require "lipgloss"` alone; the drop-in is opt-in.
+- Dashboards default to the alt screen at 20 fps with synchronized output and line-diffed redraws, and only draw a frame when something changed (an update, new feed data, an animation, a flash, or once a second when idle).
+
+### Bubble Tea drop-in and compat engine
+
+- **Pure-Ruby drop-in for Bubble Tea.** `require "r2ui/drop_in"` makes `require "bubbletea"` and `require "lipgloss"` load r2ui's own versions of bubbletea 0.1.4 and lipgloss 0.2.2 (Style, borders, join/place, Table, List, Tree, colour profiles): no native extensions, no Go toolchain, no runtime dependencies.
+- **bubbles runs unchanged.** bubbles 0.1.1 (and other pure-Ruby gems built on bubbletea/lipgloss) loads on top of the drop-in as-is.
+- **Conformance harness** (`bin/conformance`, `conformance/`). Cases run in a pty against the real gems to record goldens, then against r2ui to check them; the screen is decoded and compared cell by cell, styles included. `conformance/ratchet/` lists the cases that must keep passing, and CI fails if one regresses.
+- **Known intentional deviations** (listed in `conformance/concessions/`; the goldens still show upstream's behaviour):
+  - Several keys arriving in one read become several events. Upstream makes one event from the first character of a read and drops the rest.
+  - Bracketed paste is delivered whole, even when it spans several reads. Upstream can break a long paste into key events.
+- r2ui-only renderer options, off by default so the engine matches upstream byte for byte: `synchronized:` (each frame wrapped in DEC mode 2026) and `line_diff:` (in the alt screen, write only the lines that changed).
+- Fixes: renderer write errors after a hangup are ignored, as upstream; ticks scheduled from command threads are no longer lost.
+
+### Dashboard DSL: extension point and extensions
+
+- `R2UI.extension(name) { ... }` registers DSL keywords, helpers, message handlers (`on`, `observe`, `after_update`), panel items, hosted Bubbletea-style components, status hints and program options; blocks run on an `R2UI::Context` (`state`, `flash`, `quit`, `command`, ...). See docs/dsl.md.
+- Panels can have no resource (`panel :clock, resource: nil do ... end`) and hold only extension items.
+- Timers and commands: `every`, `after`, `async`, `batch` / `sequence`, `execute` (run a program in the foreground), `println`, `refresh` (fetch a resource now).
+- Keys and messages: `on_key` (with help labels), your own messages with `on` and `emit`, declared initial `state`.
+- Terminal: `inline` vs alt screen (and `enter_alt_screen` / `exit_alt_screen`), `window_title`, `mouse` with `on_click` and the wheel, `paste` / `on_paste`, `report_focus` with `on_focus` / `on_blur`, `on_resize` and `min_size`, `suspendable` / `on_resume` / `suspend`.
+- Drawing: `view` (a panel item drawn by a block), `screen` (the whole view drawn by a block), `theme` (lipgloss styles for titles, borders, focus) and a `style` helper.
+- Hosted bubbles components as panel keywords (needs the bubbles gem): `text_input`, `text_area`, `list`, `data_table`, `viewport`, `spinner`, `progress`, `countdown` (Timer), `stopwatch`, `paginate` (Paginator), `help`, `file_picker`.
+
+### Dashboard views
+
+- `R2UI::Motion` (`app.motion`, `motion` in extension blocks): tweens, pulses and ages evaluated per frame, with eases; frames keep drawing only while something moves. `app.motion.enabled = false` turns it off.
+- `R2UI::Widgets::Glyphs`: braille line and area charts, partial-block bars, 24-bit heat colours and gradients, as plain ANSI strings for panel items.
+- `table(columns: [...])` picks and orders a table's columns (sort cycling follows them); `table(motion: true)` marks moved and new lines in a left gutter and keeps the selection on its line across re-sorts.
+- Column options: `style:` (a callable per value), `priority:` (lowest dropped first when columns don't fit), `sparkline: :braille` with `spark_width:`, `spark_max:` and `spark_style:`.
+- `panel(..., border_style:)` colours a panel's border and title (a style or a callable); `row(height:)` accepts a callable evaluated each frame.
+
+### Performance
+
+- Dashboard frames cost a third or less of what they did (median, YJIT off: dense animating 14.3 → 5.0 ms, visual animating 24.4 → 5.4 ms), with identical screens. See docs/performance.md.
+- Exact fast path for ANSI string width and truncation on valid UTF-8; Canvas cells hold codepoints with memoized widths and SGR prefixes; extension hooks cached; table cells and braille drawn without per-cell allocations.
+- `R2UI::App` turns on the line-diff renderer, so animating frames write about 30% fewer bytes.
+- `rake bench` / `rake bench:profile` measure per-frame cost by stage against a baseline; `bench/cpu.rb` measures a real program's CPU in a pty.
+
+### CLI toolkit (`require "r2ui/cli"`)
+
+- A second product line for command-line tools, inline (no alt screen): redrawn in place on a terminal, plain stable lines in a pipe or CI. See docs/cli.md and `examples/cli/deployer.rb`.
+- Commands DSL: `R2UI.cli`, nested `command`s with `aliases`, `argument`, typed `option` (defaults, `in:` choices, required), `flag`, generated `--help`, usage errors with "did you mean".
+- Runner and exit codes: 0 success, 1 error, 2 usage error, 130 ctrl+c; `abort!`, `halt`, `usage_error!`; a closed stdout ends quietly.
+- `Shell` decides live redraw, interactivity (`TERM=dumb` is neither) and colour (`NO_COLOR`, `FORCE_COLOR`) once; `Theme` styles output; `R2UI::CLI.extension` adds keywords, helpers, hooks and help sections; `run_cli` for tests.
+- Output helpers: `say`, `tasks` / `step`, `spin`, `progress` (rate and ETA), `info` / `success` / `warn` / `error` / `debug`, `box`, `pairs`, `tree`, `table`, `list`, `diff`, `pager`, `parallel` / `job`, `heading` / `done`, and `duration`, `bytes`, `plural`, `link`.
+- Prompts (inline Bubbletea, line-based off a terminal): `confirm`, `ask`, `password`, `choose`, `choose_many`, `filter`, `edit` ($VISUAL / $EDITOR).
+- Command keywords: `version` (`-V, --version`), `option ..., env:`, `config_file` (YAML/JSON, `--config`), `trace_option` (`--trace`), `example` (Examples in help), `reference_command` (Markdown reference), `color_option` (`--color` / `--no-color`), `completion` (bash, zsh, fish scripts), and a `dashboard` helper that opens an r2ui dashboard from a command (one snapshot frame off a terminal).
+
+## 0.1.0
+
+- ActiveAdmin-style DSL for terminal dashboards: `R2UI.resource` (source, refresh, scopes, `group_by` including trees, columns with formats and sparklines, filters, actions) and `R2UI.dashboard` (rows, panels, gauges, stats, sparklines, tables).
+- `exe/r2ui` runs a dashboard file interactively or prints one frame with `--snapshot`.

data/README.md

@@ -74,6 +74,85 @@ exe/r2ui --snapshot examples/agents.rb   # print one frame and exit
 
 `:text`, `:id`, `:integer`, `:number`, `:percent`, `:bytes`, `:bytes_per_sec`, `:ratio`, `:short_path`. The format decides display, alignment, how grouped lines aggregate (`:sum`, `:count` or a single shared value) and how search operands are parsed (`500M`, `5%`).
 
+## Extensions
+
+Everything a Bubble Tea program can do, a dashboard can declare: `on_key`, `state`, `every`/`after`/`async`, `emit`, `execute`, `println`, `inline` vs alt screen, `window_title`, `mouse`, `paste`, `on_resize`, `theme`, `view` and `screen` blocks, and bubbles components as panel keywords (`text_input`, `list`, `data_table`, `viewport`, `spinner`, `progress`, ...). Each is one file in `lib/r2ui/ext/` registered with `R2UI.extension`, the same hook you use to add your own. See [docs/dsl.md](docs/dsl.md).
+
+```ruby
+R2UI.dashboard do
+  state deploys: 0
+  on_key("d", help: "deploy") { state[:deploys] += 1; flash "deploying" }
+  row height: 3 do
+    panel(:status, resource: nil) { view { "#{state[:deploys]} deploys" } }
+  end
+end
+```
+
+## Views: motion, glyphs, columns
+
+For dense monitors: `R2UI::Motion` tweens, pulses and ages values while frames draw (and stops drawing when nothing moves); `R2UI::Widgets::Glyphs` draws braille charts, partial-block bars and heat colours as ANSI strings. Tables take `columns:` to pick and order columns and `motion: true` to mark moved rows; columns take `style:`, `priority:` and `sparkline: :braille`; panels take `border_style:`. Frame costs and how they're measured: [docs/performance.md](docs/performance.md).
+
+## CLI toolkit
+
+`require "r2ui/cli"` builds command-line tools that look like npm, pnpm or bun on a terminal and print plain, stable lines in a pipe or CI: a commands DSL with generated help and exit codes, task lists, spinners, progress bars, log levels, boxes, tables, trees, diffs, prompts (`confirm`, `ask`, `choose`, `filter`, ...), `--version`, env/config-file options, shell completion, and a command that opens a dashboard. See [docs/cli.md](docs/cli.md) and `examples/cli/deployer.rb`.
+
+```ruby
+require "r2ui/cli"
+
+R2UI.cli "deployer" do
+  command :deploy do
+    argument :app
+    run do
+      tasks do
+        step("Building") { build(args[:app]) }
+        step("Uploading") { upload }
+      end
+    end
+  end
+end.start
+```
+
+## Drop-in for Bubble Tea
+
+r2ui also ships pure-Ruby versions of the Charm gems bubbletea 0.1.4 and lipgloss 0.2.2: no native extensions, nothing to compile. Require `r2ui/drop_in` before anything else, and existing programs, including ones built on bubbles 0.1.1, run unchanged:
+
+```ruby
+require "r2ui/drop_in"   # first: `require "bubbletea"` / `"lipgloss"` now load r2ui's versions
+require "bubbletea"
+require "bubbles"        # the real bubbles gem, unmodified
+
+class Prompt
+  include Bubbletea::Model
+
+  def initialize
+    @input = Bubbles::TextInput.new
+    @input.placeholder = "Your name"
+    @input.focus
+  end
+
+  def init = [self, nil]
+
+  def update(message)
+    return [self, Bubbletea.quit] if message.is_a?(Bubbletea::KeyMessage) && message.to_s == "enter"
+
+    @input, command = @input.update(message)
+    [self, command]
+  end
+
+  def view = "What's your name?\n\n#{@input.view}\n\n(enter to finish)"
+end
+
+Bubbletea.run(Prompt.new)
+```
+
+bubbles itself is still installed as a gem (`gem install bubbles`); bubbletea and lipgloss don't need to be.
+
+**How conformance is measured.** The upstream gems are the spec. Each case in `conformance/cases/` is a small program or lipgloss call; `bin/conformance record` runs it on the real gems in a pty and saves the decoded screen (text, styles, alt screen, cursor and mouse/paste modes) as a golden, and `bin/conformance check` runs it on r2ui and diffs. Cases listed in `conformance/ratchet/` must keep passing; CI runs `bin/conformance check --ratchet` on every PR and re-records the goldens from the real gems to catch stale ones. Where r2ui differs on purpose, the case is listed in `conformance/concessions/` with the reason (for example, r2ui keeps every key from a multi-key read and delivers long pastes whole, where upstream drops or splits them). See [conformance/README.md](conformance/README.md).
+
+## Contributing and releases
+
+Open PRs against `develop`; `main` holds released code only. Releases and hotfixes are cut from GitHub Actions; see [docs/releasing.md](docs/releasing.md).
+
 ## Next: active_tui
 
 A Rails engine on top of the same DSL: `ActiveTui.register Order do ... end` reads columns, scopes and associations from the model, `source` defaults to the relation, and actions become model methods. This gem stays Rails-free.

data/lib/r2ui/app.rb

@@ -1,42 +1,171 @@
 # frozen_string_literal: true
 
 module R2UI
-  # The running program: feeds, panel focus, key handling and the draw loop.
+  # The running program, as a Bubbletea model: `init` starts the feeds and runs extension init
+  # hooks, `update` routes each message (extension observers and handlers, components, then the
+  # core keys) and returns their commands, `view` draws the dashboard. `run` runs it on r2ui's
+  # Bubbletea engine (lib/r2ui/compat/bubbletea).
   class App
-    FRAME = 0.25
+    include Bubbletea::Model
+
     FLASH_SECONDS = 3
+    # Runner options; extensions change them with `program_options`. `synchronized` wraps each
+    # frame in DEC 2026 synchronized output, so terminals paint it at once; `line_diff` writes only
+    # the lines that changed since the last frame (dashboards run in the alt screen).
+    PROGRAM_OPTIONS = { alt_screen: true, fps: 20, synchronized: true, line_diff: true }.freeze
+    # Seconds after which a frame is due even if nothing changed (clocks, ages, "3s ago" texts).
+    IDLE_FRAME = 1.0
+    # How often `view` forgets motion keys nothing evaluates any more.
+    SWEEP_SECONDS = 1.0
+    # Where the focused component takes keys among the `on` handlers: those with priority >= 50 run
+    # before it, the rest after.
+    COMPONENT_PRIORITY = 50
+
+    attr_reader :registry, :dashboard, :feeds, :focus, :state, :width, :height, :components
+    # The app's animation state (R2UI::Motion): tweens, pulses and ages evaluated while drawing.
+    attr_reader :motion
 
     def initialize(registry, name = nil)
       @registry = registry
       @dashboard = registry.screen(name)
-      resources = @dashboard.panels.map(&:resource).uniq.map { |r| registry.resource(r) }
+      resources = @dashboard.panels.filter_map(&:resource).uniq.map { |r| registry.resource(r) }
       @feeds = resources.to_h { |r| [r.name, Feed.new(r)] }
       @states = @dashboard.panels.to_h do |p|
-        [p, p.table && PanelState.new(registry.resource(p.resource), p.table)]
+        [p, p.table && p.resource && PanelState.new(registry.resource(p.resource), p.table)]
       end
       @focus = @dashboard.panels.find(&:table) || @dashboard.panels.first
-      @renderer = Renderer.new(registry, @feeds, @states)
+      @motion = Motion.new
+      @renderer = Renderer.new(registry, @feeds, @states, draw_item: method(:draw_item), motion: @motion)
       @mode = :normal
       @zoomed = false
+      @state = {}
+      @stores = Hash.new { |h, k| h[k] = {} }
+      @components = []
+      @width = 80
+      @height = 24
+      @changed = true # an init/update ran since the last view
+      @viewed_at = nil
+      @viewed_versions = {}
+      @viewed_flash = false
+      @swept_at = nil
+      setup = Context.new(self)
+      Extensions.hooks(:setup).each { |h| setup.call(h.block) }
     end
 
+    # Runs on the terminal until quit. Feeds stop on every exit path.
     def run
-      terminal = Terminal.new
-      @resized = false
-      previous_winch = Signal.trap("WINCH") { @resized = true }
-      @feeds.each_value(&:start)
-      terminal.open do
-        loop do
-          width, height = terminal.size
-          terminal.clear if @resized
-          @resized = false
-          terminal.draw(frame(width, height))
-          break if terminal.read_keys(FRAME).any? { |key| handle(key) == :quit }
-        end
-      end
+      Bubbletea::Runner.new(self, **program_options).run
     ensure
-      @feeds.each_value(&:stop)
-      Signal.trap("WINCH", previous_winch || "DEFAULT")
+      stop
+    end
+
+    def stop = @feeds.each_value(&:stop)
+
+    # --- Bubbletea::Model ---
+
+    def init
+      ctx = Context.new(self)
+      @feeds.each_value(&:start) unless @started
+      @started = true
+      start_components(ctx)
+      Extensions.hooks(:init).each { |h| ctx.call(h.block) }
+      after_update(ctx)
+      @changed = true
+      [self, ctx.commands]
+    end
+
+    def update(message)
+      ctx = Context.new(self, message)
+      dispatch(ctx, message)
+      sync_component_focus(ctx) if @components_started
+      after_update(ctx)
+      @changed = true
+      [self, ctx.commands]
+    end
+
+    # Whether the next frame slot should draw: an init/update ran or a feed has new data since the
+    # last `view`, something animates, a flash shows (or vanished since), or IDLE_FRAME passed.
+    # The runner asks this every frame slot, so it allocates nothing.
+    def frame_due?
+      return true if @changed || @viewed_at.nil?
+      return true if @feeds.any? { |name, feed| feed.version != @viewed_versions[name] }
+      return true if @motion.active?
+      return true if @viewed_flash || flash_showing?
+
+      @motion.now - @viewed_at > IDLE_FRAME
+    end
+
+    def view
+      seen_view
+      width, height = frame_size
+      ctx = Context.new(self)
+      ctx.width = width
+      ctx.height = height
+      Extensions.hooks(:view_override).each do |h|
+        text = ctx.call(h.block)
+        return text.to_s if text
+      end
+      frame(width, height).ansi_lines.join("\n")
+    end
+
+    # --- for extensions and tests ---
+
+    # Runner options: the defaults merged with every extension's `program_options`.
+    def program_options
+      ctx = Context.new(self)
+      Extensions.hooks(:program_options).reduce(PROGRAM_OPTIONS) { |opts, h| opts.merge(ctx.call(h.block) || {}) }
+    end
+
+    # Private state for one extension.
+    def store(name) = @stores[name.to_sym]
+
+    def flash(text)
+      @flash = text
+      @flash_at = Time.now
+    end
+
+    def selected_rows
+      return [] unless state_for_focus
+
+      lines[state_for_focus.selected]&.rows || []
+    end
+
+    # Panel => Rect where each panel was drawn in the last frame.
+    def panel_rects = @renderer.rects
+
+    def focus=(panel)
+      raise Error, "no panel #{panel.inspect}" unless @dashboard.panels.include?(panel)
+
+      @focus = panel
+    end
+
+    # The hosted model for the component item named `name` (nil if none).
+    def component(name)
+      build_components
+      @components.find { |c| c.name == name }&.model
+    end
+
+    # Gives key focus to the named component (blurring the others), or takes it away with `nil`:
+    # e.g. esc in a text input hands keys back to the core while its panel stays focused.
+    # Focus commands go on `ctx`. Panel focus changes move it to that panel's first focusable
+    # component again.
+    def focus_component(name, ctx = Context.new(self))
+      target = name && @components.find { |c| c.focusable? && c.name == name }
+      raise Error, "no focusable component #{name.inspect}" if name && !target
+
+      @components.each { |c| set_component_focus(ctx, c, c.equal?(target)) if c.focusable? }
+      ctx.commands
+    end
+
+    # The PanelState (scope, sort, search, selection, offset) of a table panel, or nil.
+    def panel_state(panel) = @states[panel]
+
+    # The lines a table panel showed in the last frame (Query::Line objects).
+    def panel_lines(panel) = @renderer.lines.fetch(panel, [])
+
+    # Status-bar hints as [key, label] pairs: extensions' first, then the core's.
+    def hint_pairs(ctx = Context.new(self))
+      Extensions.hooks(:hints).flat_map { |h| ctx.call(h.block) || [] } + Renderer::HINT_PAIRS
     end
 
     def snapshot(width:, height:, ticks: 1)
@@ -47,29 +176,178 @@ module R2UI
       frame(width, height).plain_lines.join("\n")
     end
 
-    # Exposed for tests: feed keys without a terminal.
-    def press(*keys) = keys.each { |k| handle(k) }
+    # Feeds keys without a terminal, as if typed: core names (:up, "q") or Bubbletea names
+    # ("ctrl+r"). Returns the commands they produced.
+    def press(*keys) = keys.filter_map { |k| update(Keys.message(k)).last }
+
+    # [width, height] to draw at: the terminal size, changed by extensions' `frame_size`.
+    def frame_size
+      ctx = Context.new(self)
+      Extensions.hooks(:frame_size).reduce([@width, @height]) { |size, h| ctx.call(h.block, *size) }
+    end
 
     def frame(width, height)
-      @renderer.render(@dashboard, width:, height:, focus: @focus, zoomed: @zoomed, prompt:)
+      ctx = Context.new(self)
+      build_components(ctx)
+      styles = Extensions.hooks(:styles).reduce({}) { |acc, h| acc.merge(ctx.call(h.block) || {}) }
+      @renderer.render(@dashboard, width:, height:, focus: @focus, zoomed: @zoomed, prompt: prompt(ctx),
+                                   hints: hints(ctx), styles: styles.empty? ? nil : styles)
     end
 
     private
 
-    def state = @states[@focus]
+    def dispatch(ctx, message)
+      if message.is_a?(Bubbletea::WindowSizeMessage)
+        @width = message.width
+        @height = message.height
+      end
+      Extensions.hooks(:observe).each { |h| ctx.call(h.block, message) if h.match?(message) }
+      key = message.is_a?(Bubbletea::KeyMessage) ? Keys.name(message) : nil
+      return ctx.quit if key == :interrupt
+      return core_key(ctx, key) if key && @mode != :normal
+
+      broadcast_to_components(ctx, message) unless key
+      before, after = Extensions.hooks(:on).partition { |h| h.priority >= COMPONENT_PRIORITY }
+      return if handled?(ctx, before, message)
+      return if key && focused_component_key(ctx, message, key)
+      return if handled?(ctx, after, message)
+
+      core_key(ctx, key) if key
+    end
+
+    def after_update(ctx) = Extensions.hooks(:after_update).each { |h| ctx.call(h.block) }
+
+    # Records what this view draws, for frame_due?, and sweeps stale motion keys once a second.
+    def seen_view
+      now = @motion.now
+      @changed = false
+      @viewed_at = now
+      @feeds.each { |name, feed| @viewed_versions[name] = feed.version }
+      @flash = nil if @flash && !flash_showing?
+      @viewed_flash = !@flash.nil?
+      return if @swept_at && now - @swept_at < SWEEP_SECONDS
+
+      @swept_at = now
+      @motion.sweep!
+    end
+
+    def flash_showing? = @flash ? Time.now - @flash_at < FLASH_SECONDS : false
+
+    def handled?(ctx, hooks, message) = hooks.any? { |h| h.match?(message) && ctx.handle(h.block, message) }
+
+    def core_key(ctx, key)
+      ctx.quit if handle(key) == :quit
+    end
+
+    # --- components ---
+
+    # Builds the component models once (first frame or init, whichever comes first).
+    def build_components(ctx = Context.new(self))
+      return if @components_built
+
+      @components_built = true
+      specs = Extensions.hooks(:component)
+      @dashboard.panels.each do |panel|
+        panel.items.each do |item|
+          spec = specs.find { |h| h.match?(item) }&.block
+          next unless spec
+
+          instance = Component::Instance.new(panel:, item:, spec:, focused: false)
+          instance.model = ctx.call(spec.build, item)
+          @components << instance
+        end
+      end
+    end
+
+    # Runs each model's `init` once, in App#init, and gives the focused panel's component focus.
+    def start_components(ctx)
+      build_components(ctx)
+      return if @components_started
+
+      @components_started = true
+      @components.each do |instance|
+        next unless instance.model.respond_to?(:init)
+
+        instance.model, cmd = Component.split(instance.model, instance.model.init)
+        ctx.command(cmd)
+      end
+      sync_component_focus(ctx)
+    end
+
+    def broadcast_to_components(ctx, message)
+      @components.each { |c| update_component(ctx, c, message) }
+    end
+
+    def focused_component_key(ctx, message, key)
+      return false if Component::RESERVED.include?(key)
+
+      instance = @components.find { |c| c.focused && c.panel == @focus }
+      return false unless instance
+
+      update_component(ctx, instance, message)
+      true
+    end
+
+    def set_component_focus(ctx, instance, want)
+      return if instance.focused == want
+
+      instance.focused = want
+      cmd = want ? Component.focus(instance) : Component.blur(instance)
+      ctx.command(cmd) if Context.command?(cmd)
+    end
+
+    def update_component(ctx, instance, message)
+      instance.model, cmd = Component.split(instance.model, instance.model.update(message))
+      ctx.command(cmd)
+    end
+
+    # When panel focus has changed: focus the first focusable component of the focused panel and
+    # blur the rest.
+    def sync_component_focus(ctx)
+      return if @component_focus_panel.equal?(@focus) && @components_synced
+
+      @components_synced = true
+      @component_focus_panel = @focus
+      active = @components.find { |c| c.focusable? && c.panel == @focus }
+      @components.each { |c| set_component_focus(ctx, c, c.equal?(active)) if c.focusable? }
+    end
+
+    def draw_item(panel, item, width, height)
+      ctx = Context.new(self)
+      ctx.panel = panel
+      ctx.width = width
+      ctx.height = height
+      drawer = Extensions.hooks(:panel_item).find { |h| h.match?(item) }
+      return ctx.call(drawer.block, item) if drawer
+
+      @components.find { |c| c.item.equal?(item) && c.panel == panel }&.model&.view
+    end
+
+    # --- core keys and status bar ---
+
+    def state_for_focus = @states[@focus]
 
     def lines = @renderer.lines.fetch(@focus, [])
 
     def resource = @registry.resource(@focus.resource)
 
-    def prompt
+    def prompt(ctx)
       case @mode
-      when :search then "/#{state.search}▏"
+      when :search then "/#{state_for_focus.search}▏"
       when Array then "#{@mode[1].label} #{@mode[2].size} #{@mode[2].size == 1 ? "row" : "rows"}? y/n"
-      else @flash if @flash && Time.now - @flash_at < FLASH_SECONDS
+      else
+        return @flash if flash_showing?
+
+        Extensions.hooks(:status).each do |h|
+          text = ctx.call(h.block)
+          return text if text
+        end
+        nil
       end
     end
 
+    def hints(ctx) = hint_pairs(ctx).map { |key, label| "#{key} #{label}" }.join("  ")
+
     def handle(key)
       return :quit if key == :interrupt
 
@@ -87,11 +365,12 @@ module R2UI
       when :back_tab then cycle_focus(-1)
       when "z" then @zoomed = !@zoomed
       end
-      table_key(key) if state
+      table_key(key) if state_for_focus
       nil
     end
 
     def table_key(key)
+      state = state_for_focus
       case key
       when :up, "k" then state.move(-1, lines.size)
       when :down, "j" then state.move(1, lines.size)
@@ -113,6 +392,7 @@ module R2UI
     end
 
     def search_key(key)
+      state = state_for_focus
       case key
       when :enter then @mode = :normal
       when :escape
@@ -124,7 +404,7 @@ module R2UI
     end
 
     def start_action(action)
-      rows = lines[state.selected]&.rows
+      rows = lines[state_for_focus.selected]&.rows
       return if rows.nil? || rows.empty?
 
       action.confirm ? @mode = [:confirm, action, rows] : run_action(action, rows)
@@ -143,13 +423,10 @@ module R2UI
       flash("#{action.label} failed: #{e.message}")
     end
 
-    def flash(text)
-      @flash = text
-      @flash_at = Time.now
-    end
-
     def cycle_focus(step)
       panels = @dashboard.panels
+      return if panels.empty?
+
       @focus = panels[(panels.index(@focus) + step) % panels.size]
     end
   end