Add page-based TUI DSL

Each screen is now a self-contained `page` block with its own `enter`,
`render`, and `key` handlers. Shared logic lives in a `helpers` block
mixed into the render context. A `chrome` block renders persistent UI
(header, sidebar, footer) before every frame.

New context primitives: `go(page)` for transitions, `reload` to re-run
the current page's `enter` block, `printable` key binding for text input.

`FlowRunner#run_tui` now passes the flow context to TUIRunner so username
and other session data are available without reaching into internals.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bbs.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'bbs'
-  s.version     = '0.1.0'
+  s.version     = '0.2.0'
   s.summary     = 'Universal telnet BBS server library'
   s.author      = 'Zsolt Tasnadi'
   s.files       = Dir['lib/**/*.rb']

lib/bbs/flow_runner.rb

@@ -18,7 +18,7 @@ module BBS
       red:     "\e[1;31m",
     }.freeze
 
-    attr_reader :session_id
+    attr_reader :session_id, :session
 
     def initialize(session, session_id, flow)
       @session    = session
@@ -343,7 +343,7 @@ module BBS
     end
 
     def run_tui(step)
-      TUIRunner.new(@session, @session_id, step[:definition]).run
+      TUIRunner.new(@session, @session_id, step[:definition], context: @ctx).run
       nil
     rescue IOError, Errno::EPIPE, Errno::ECONNRESET
       :halt

lib/bbs/tui.rb

@@ -2,28 +2,45 @@
 
 module BBS
   class TUI
-    attr_reader :init_block, :render_block, :key_bindings
+    attr_reader :init_block, :chrome_block, :pages, :start_page, :helper_module
 
     def self.define(&block)
       tui = new
       tui.instance_eval(&block)
-      tui.freeze
+      tui
     end
 
     def initialize
+      @pages      = {}
+      @start_page = :idle
+    end
+
+    def init(&block)   = @init_block   = block
+    def chrome(&block) = @chrome_block = block
+    def start(name)    = @start_page   = name
+
+    def helpers(&block)
+      @helper_module = Module.new(&block)
+    end
+
+    def page(name, &block)
+      p = Page.new(name)
+      p.instance_eval(&block)
+      @pages[name] = p
+    end
+
+    class Page
+      attr_reader :name, :enter_block, :render_block, :key_bindings
+
+      def initialize(name)
+        @name         = name
         @key_bindings = {}
       end
 
-    def init(&block)
-      @init_block = block
-    end
-
-    def render(&block)
-      @render_block = block
-    end
-
-    def key(k, action = nil, &block)
-      @key_bindings[k] = action || block
+      def enter(&block)     = @enter_block  = block
+      def render(&block)    = @render_block = block
+      def key(k, &block)    = (@key_bindings[k] = block)
+      def printable(&block) = (@key_bindings[:printable] = block)
     end
   end
 end

lib/bbs/tui_runner.rb

@@ -2,27 +2,24 @@
 
 module BBS
   class TUIRunner
-    def initialize(session, session_id, tui)
+    def initialize(session, session_id, tui, context: {})
       @session    = session
       @session_id = session_id
       @tui        = tui
+      @context    = context
     end
 
     def run
-      ctx = Context.new(@session, @session_id)
+      ctx = Context.new(@session, @session_id, @tui)
+      @context.each { |k, v| ctx.instance_variable_set(:"@#{k}", v) }
       ctx.instance_eval(&@tui.init_block) if @tui.init_block
+      ctx.go(@tui.start_page)
 
       loop do
-        ctx.do_render(@tui.render_block) if @tui.render_block
-
+        ctx.do_render
         key = @session.readkey
         break if key.nil?
-
-        handler = @tui.key_bindings[key]
-        next unless handler
-
-        result = handler.is_a?(Symbol) ? handler : ctx.instance_eval(&handler)
-        break if result == :halt
+        break if ctx.dispatch_key(key) == :halt
       end
     rescue IOError, Errno::EPIPE, Errno::ECONNRESET
       nil
@@ -33,32 +30,58 @@ module BBS
     class Context
       STYLES = FlowRunner::STYLES
 
-      def initialize(session, session_id)
+      def initialize(session, session_id, tui)
         @session      = session
         @session_id   = session_id
+        @tui          = tui
+        @current_page = nil
         @buf          = +""
+        extend(@tui.helper_module) if @tui.helper_module
       end
 
-      def do_render(block)
+      def go(page_name)
+        @current_page = page_name
+        page = @tui.pages[page_name]
+        instance_eval(&page.enter_block) if page&.enter_block
+        nil
+      end
+
+      def reload = go(@current_page)
+
+      def do_render
         @buf = +"\e[?25l"
-        instance_eval(&block)
+        clear
+        instance_eval(&@tui.chrome_block) if @tui.chrome_block
+        page = @tui.pages[@current_page]
+        instance_eval(&page.render_block) if page&.render_block
         @buf << "\e[?25h"
         @session.write(@buf)
       end
 
-      # ── drawing primitives ────────────────────────────────────────────────
+      def dispatch_key(key)
+        page    = @tui.pages[@current_page]
+        handler = page&.key_bindings&.[](key)
 
-      def clear
-        @buf << "\e[2J\e[H"
+        if handler.nil? && key.is_a?(String) && key.length == 1
+          if (ph = page&.key_bindings&.[](:printable))
+            return instance_exec(key, &ph)
           end
+        end
+
+        return nil unless handler
+        instance_eval(&handler)
+      end
+
+      # ── drawing primitives ──────────────────────────────────────────────────
+
+      def clear     = @buf << "\e[2J\e[H"
+      def term_cols = @session.term_cols || 80
+      def term_rows = @session.term_rows || 24
 
       def at(col, row)
         @buf << "\e[#{row};#{col}H"
       end
 
-      def term_cols = @session.term_cols || 80
-      def term_rows = @session.term_rows || 24
-
       def text(content, x: nil, y: nil, style: nil)
         at(x, y) if x && y
         color = STYLES[style]