thaum 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf87796b15b377e1fb9630d63a89c488c3ef127afe5f86b00748ffe40ea6bc2
-  data.tar.gz: 4a3b2b5883f17d2a3050dc9ca0e07802c722757b4f27516ea92b73eafea53b44
+  metadata.gz: 2a57f1cd2382c79243a8c7cb1de2294e73c63cc8c1ac5d3aa53550a1804b8e18
+  data.tar.gz: 15c723d96a1820f1685ebbfec62f1a8be56f497b77136a8641ebfc12dba9b8d3
 SHA512:
-  metadata.gz: cd4dac7b5e97854e8347f382101690d15216450e64de3626ac561629a763811ce6557ece95968f41cf6dfc3bd3c44357df68592dfaf16f83d3fa9b88596824c2
-  data.tar.gz: d7855d4542eb89480e215f8dd42acd9c15e444db41a9fe83acc7f1cb9f6b0d4baa02803352454767f4ce3fa8f6894063a6f29f5395db031e750d069497dbe34e
+  metadata.gz: a745ca6c770a9ed3fe5bacf49bbf5e0e857e3c7f343717e6383dfbf79fe88b82db5071f8fbbc58ef5c3f303d0b69a4dcb97e018bfadb50474a2fa12e0a225d41
+  data.tar.gz: 3d0645793d58cb962df5dcbb00f561fcb7dcb41a63b6045d026821f81a36a88ae31e3f13bede63a2572a4e22201f9707c85a129d0f0a9ca7d20b4ecec95dd2ea

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-06-17
+
+### Fixed
+
+- `InputReader#stop` no longer blocks ~1s on quit; the reader thread is interrupted instead of left to time out.
+- Escape sequences split across read boundaries are now coalesced instead of being mis-parsed as a stray Escape plus garbage keys. `InputReader#read_chunk` now extends the read whenever a chunk ends mid-sequence (CSI/SS3/SGR-mouse or a bare ESC), bounded by a timeout and an extend cap.
+- Centered/right-aligned wrapped text drawn at an x-offset is now positioned against the offset content area instead of the full canvas width.
+
+### Added
+
+- Honor the `NO_COLOR` environment variable — when set and non-empty, color output is disabled.
+
+### Changed
+
+- Moved `Thaum::Concerns::Layout` back to `Thaum::Layout`. Includes in `App`, `Octagram`, and downstream code should reference the top-level module.
+- `Thaum::Action` raises a clear `Thaum::Error` when a background method is called outside a running app, instead of a `NoMethodError` on nil.

data/lib/thaum/action.rb

@@ -1,6 +1,18 @@
 # frozen_string_literal: true
 
 module Thaum
+  # Mixin that turns a plain class into a background "action".
+  #
+  # Including this module promotes every *public* instance method into a
+  # class method (see {ClassMethods#method_added}). Calling that class method
+  # schedules the work on the run loop's background thread pool:
+  #
+  #   - A fresh instance is built with an argless `new`, so Actions must not
+  #     require constructor arguments.
+  #   - The method runs fire-and-forget; its return value is discarded.
+  #   - Use {#emit} to push results back to the run loop as events.
+  #   - Calling a promoted method outside a running Thaum app (no pool) raises
+  #     {Thaum::Error}.
   module Action
     class << self
       attr_accessor :queue, :pool
@@ -22,7 +34,13 @@ module Thaum
         return if singleton_class.method_defined?(name, false)
 
         define_singleton_method(name) do |*args, **kwargs|
-          Thaum::Action.pool.post { new.public_send(name, *args, **kwargs) }
+          pool = Thaum::Action.pool
+          unless pool
+            raise Thaum::Error,
+                  "Thaum::Action method called outside a running Thaum app (no thread pool available)"
+          end
+
+          pool.post { new.public_send(name, *args, **kwargs) }
         end
       end
     end

data/lib/thaum/app.rb

@@ -2,7 +2,7 @@
 
 module Thaum
   module App
-    include Concerns::Layout
+    include Layout
     include Concerns::Focus
     include Concerns::ContextUpdate
     include Concerns::Modal

data/lib/thaum/color.rb

@@ -28,6 +28,8 @@ module Thaum
     }.freeze
 
     def self.detect(env)
+      return :none if no_color?(env)
+
       colorterm = env["COLORTERM"]
       term      = env["TERM"]
       return :truecolor if %w[truecolor 24bit].include?(colorterm)
@@ -37,6 +39,11 @@ module Thaum
       :ansi
     end
 
+    def self.no_color?(env)
+      value = env["NO_COLOR"]
+      !value.nil? && !value.empty?
+    end
+
     def self.to_escape(color, capability:, base:)
       return "" if capability == :none
       return "" if color.nil?
@@ -92,6 +99,6 @@ module Thaum
       end.first
     end
 
-    private_class_method :named_escape, :hex_escape, :hex_to_256, :hex_to_ansi # rubocop:disable Naming/VariableNumber
+    private_class_method :no_color?, :named_escape, :hex_escape, :hex_to_256, :hex_to_ansi # rubocop:disable Naming/VariableNumber
   end
 end

data/lib/thaum/input_reader.rb

@@ -4,6 +4,14 @@ module Thaum
   # Reads raw bytes from an input stream in a background thread and pushes KeyEvents onto a queue.
   class InputReader
     ESCAPE_TIMEOUT = 0.05 # seconds to wait after a bare \e before treating it as Escape
+    MAX_ESCAPE_EXTENDS = 4 # cap extend reads so malformed input can't hang the reader
+
+    ESC = "\e"
+    CSI_INTRO   = 0x5b  # '[' — Control Sequence Introducer
+    SS3_INTRO   = 0x4f  # 'O' — Single Shift 3
+    SGR_MOUSE_MARKER = 0x3c # '<' — SGR mouse introducer
+    CSI_FINAL_RANGE  = 0x40..0x7e # any byte in this range terminates a CSI
+    SGR_MOUSE_FINAL  = [0x4d, 0x6d].freeze # 'M' / 'm' terminate an SGR mouse sequence
 
     def initialize(input:, queue:, parser: EscapeParser.new)
       @input  = input
@@ -17,7 +25,13 @@ module Thaum
     end
 
     def stop
-      @thread&.join(1)
+      return unless @thread
+
+      # Give the thread a moment to finish on its own (e.g. input already closed).
+      # If it's still blocked in readpartial, interrupt it so stop doesn't wait out
+      # the full join timeout (~1s) on every quit.
+      @thread.kill unless @thread.join(0.1)
+      @thread.join(1)
       @thread = nil
     end
 
@@ -38,9 +52,64 @@ module Thaum
 
     def read_chunk
       bytes = @input.readpartial(1024)
-      # If bytes end with a bare ESC, wait briefly — it may be the start of a sequence.
-      bytes += @input.readpartial(1024) if bytes.end_with?("\e") && @input.wait_readable(ESCAPE_TIMEOUT)
+      # The chunk may end in the middle of an escape sequence (a bare ESC, or
+      # an in-progress CSI/SS3/mouse sequence whose final byte hasn't arrived).
+      # Extend the read while that's the case and more bytes are available,
+      # bounded by MAX_ESCAPE_EXTENDS so malformed input can't hang the reader.
+      # A genuinely-bare ESC keypress resolves to :escape once wait_readable
+      # times out (no more bytes) and we return what we have.
+      extends = 0
+      while pending_escape?(bytes) && extends < MAX_ESCAPE_EXTENDS && @input.wait_readable(ESCAPE_TIMEOUT)
+        bytes += @input.readpartial(1024)
+        extends += 1
+      end
       bytes
     end
+
+    # True when `bytes` ends with an incomplete escape sequence — a trailing
+    # ESC that the parser cannot yet dispatch as a complete sequence. Covers
+    # the three forms the parser recognizes: CSI (\e[ … final byte 0x40–0x7e,
+    # with SGR mouse \e[< … terminated by M/m), SS3 (\eO needs one more byte),
+    # and a lone trailing ESC. A complete bracketed-paste START (\e[200~) is
+    # NOT pending — paste accumulation is handled statefully by the parser.
+    def pending_escape?(bytes)
+      esc = bytes.byterindex(ESC)
+      return false if esc.nil?
+
+      # A complete bracketed-paste START (\e[200~) is treated as a normal,
+      # dispatchable CSI here (its '~' is a CSI final byte), so it is NOT
+      # pending — the parser takes over paste accumulation statefully. A
+      # *partial* marker (e.g. \e[2 / \e[200) is an incomplete CSI and stays
+      # pending so we keep reading until the '~' arrives.
+      tail = bytes.byteslice(esc, bytes.bytesize - esc)
+      incomplete_escape_tail?(tail)
+    end
+
+    # `tail` starts at an ESC byte. Returns true if it is NOT yet a complete,
+    # dispatchable escape sequence.
+    def incomplete_escape_tail?(tail)
+      return true if tail.bytesize == 1 # lone trailing ESC
+
+      case tail.getbyte(1)
+      when CSI_INTRO then incomplete_csi_tail?(tail)
+      when SS3_INTRO then tail.bytesize < 3 # \eO needs exactly one more byte
+      else false # \e + ground byte (Alt+key) is complete in two bytes
+      end
+    end
+
+    # `tail` begins with \e[. SGR mouse (\e[<) terminates on M/m; a plain CSI
+    # terminates on any byte in 0x40–0x7e. Incomplete until that final byte.
+    def incomplete_csi_tail?(tail)
+      return true if tail.bytesize == 2 # just "\e[" so far
+
+      sgr = tail.getbyte(2) == SGR_MOUSE_MARKER
+      body_start = sgr ? 3 : 2
+      body = tail.byteslice(body_start, tail.bytesize - body_start)
+      body.each_byte.none? { |b| csi_final?(b, sgr: sgr) }
+    end
+
+    def csi_final?(byte, sgr:)
+      sgr ? SGR_MOUSE_FINAL.include?(byte) : CSI_FINAL_RANGE.cover?(byte)
+    end
   end
 end

data/lib/thaum/layout.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Layout
+    attr_reader :rect, :leaf_sigils, :subtree_leaves, :child_layouts, :subtree_children
+
+    # Override on any Layout node (including App) to specify a Tab traversal
+    # order for that subtree. Return an array of leaf Sigils. nil (default)
+    # means "use left-to-right leaf order."
+    def focus_order = nil
+
+    # Called by the run loop (or repartition) to assign geometry and walk the partition tree.
+    # Returns the flat list of leaf Sigils in render order.
+    def run_partition(rect:, collector: nil)
+      @rect = rect
+      collector ||= []
+      start = collector.size
+      @leaf_sigils     = collector
+      @child_layouts   = []
+      @subtree_children = []
+      # An Octagram may inset the rect its children partition into so its
+      # render hook (border, padding) survives. Plain Layout passes through.
+      @rect = inset_for_partition(rect)
+      partition
+      @rect = rect
+      @subtree_leaves = collector[start..] || []
+      collector
+    end
+
+    # Override on Octagram (or any Layout) to inset the rect that this
+    # node's children partition into. Defaults to identity.
+    def inset_for_partition(rect)
+      return rect unless respond_to?(:partition_inset)
+
+      inset = partition_inset || {}
+      Rect.new(
+        x:      rect.x + (inset[:left]   || 0),
+        y:      rect.y + (inset[:top]    || 0),
+        width:  [rect.width  - (inset[:left] || 0) - (inset[:right]  || 0), 0].max,
+        height: [rect.height - (inset[:top]  || 0) - (inset[:bottom] || 0), 0].max
+      )
+    end
+
+    # Re-run partition for this node's subtree using its current rect.
+    def repartition
+      return unless @rect
+
+      old_leaves    = @leaf_sigils || []
+      old_octagrams = collect_octagrams
+
+      new_leaves = []
+      run_partition(rect: @rect, collector: new_leaves)
+
+      new_octagrams = collect_octagrams
+
+      # Fire on_unmount for removed Sigils and Octagrams.
+      (old_leaves - new_leaves).each(&:on_unmount)
+      (old_octagrams - new_octagrams).each(&:on_unmount)
+
+      # Rewire handler parents across the (possibly restructured) subtree so
+      # newly-added Octagrams and Sigils see the right chain BEFORE on_mount.
+      # Only rewires when we can identify this node's role in the dispatch
+      # chain — App (root) or Octagram (its own handler scope).
+      app = thaum_app_ref || (is_a?(Octagram) ? @thaum_app : nil)
+      wire_handler_parents(handler_parent: self, app: app) if app
+
+      # Fire on_mount for newly-added Sigils and Octagrams.
+      (new_octagrams - old_octagrams).each do |o|
+        o.thaum_app = app if app
+        o.on_mount
+      end
+      (new_leaves - old_leaves).each do |s|
+        s.thaum_app = app if app
+        s.on_mount
+      end
+
+      @leaf_sigils = new_leaves
+
+      # Re-validate focus_order in this subtree after structural change.
+      validate_focus_order_tree
+    end
+
+    # Walk this subtree and collect every Octagram node (excluding self).
+    def collect_octagrams
+      result = []
+      (@subtree_children || []).each do |child|
+        if child.is_a?(Octagram)
+          result << child
+          result.concat(child.collect_octagrams)
+        elsif child.respond_to?(:collect_octagrams)
+          result.concat(child.collect_octagrams)
+        end
+      end
+      result
+    end
+
+    # Walk this Layout node and every descendant Layout, raising
+    # FocusOrderError if any defines a focus_order that does not exactly
+    # cover the focusable leaves in its subtree.
+    def validate_focus_order_tree
+      validate_focus_order_node
+      (@child_layouts || []).each(&:validate_focus_order_tree)
+    end
+
+    # Build the Tab traversal order for this subtree, recursively expanding
+    # any nested Layout that itself has focus_order. When no focus_order is
+    # defined at any level, this falls through to left-to-right leaf order.
+    def effective_focus_order
+      order = focus_order
+      return order if order
+
+      result = []
+      layout_subtree_in_order.each do |node|
+        if node.is_a?(Sigil)
+          result << node if node.focusable?
+        else
+          result.concat(node.effective_focus_order)
+        end
+      end
+      result
+    end
+
+    # The direct children of this Layout in declaration order — both Sigils
+    # and nested Layouts. Built during partition (see place_child).
+    def layout_subtree_in_order = @subtree_children || []
+
+    # Scope units for Tab cycling within THIS focus scope. A "scope" is the
+    # App or an Octagram. A unit is either a focusable Sigil (reached through
+    # plain Layouts only) or a nested Octagram (which appears as one unit and
+    # is itself a scope). Plain Layouts are transparent — their units are
+    # flattened into the parent scope.
+    def focus_scope_units
+      result = []
+      (@subtree_children || []).each do |child|
+        case child
+        when Sigil
+          result << child if child.focusable?
+        when Octagram
+          result << child if child.focusable_descendant?
+        else
+          result.concat(child.focus_scope_units) if child.respond_to?(:focus_scope_units)
+        end
+      end
+      result
+    end
+
+    # Recursively descend into this Octagram (or plain Layout) to find its
+    # first focusable leaf — used when Tab enters an Octagram unit.
+    def first_focusable_leaf
+      (@subtree_children || []).each do |child|
+        case child
+        when Sigil
+          return child if child.focusable?
+        else
+          leaf = child.first_focusable_leaf if child.respond_to?(:first_focusable_leaf)
+          return leaf if leaf
+        end
+      end
+      nil
+    end
+
+    # Mirror of first_focusable_leaf for Shift-Tab entry.
+    def last_focusable_leaf
+      (@subtree_children || []).reverse_each do |child|
+        case child
+        when Sigil
+          return child if child.focusable?
+        else
+          leaf = child.last_focusable_leaf if child.respond_to?(:last_focusable_leaf)
+          return leaf if leaf
+        end
+      end
+      nil
+    end
+
+    def focusable_descendant?
+      !first_focusable_leaf.nil?
+    end
+
+    # Walk the subtree top-down, wiring each leaf Sigil and each Octagram.
+    # Leaves and Octagrams get _handler_parent set to the innermost
+    # enclosing Octagram (or the App when there is none). Plain Layout
+    # nodes are transparent — their children inherit the outer parent.
+    def wire_handler_parents(handler_parent:, app:)
+      (@subtree_children || []).each do |child|
+        case child
+        when Sigil
+          child.handler_parent = handler_parent
+          child.thaum_app      = app
+        when Octagram
+          child.handler_parent = handler_parent
+          child.thaum_app      = app
+          child.wire_handler_parents(handler_parent: child, app: app)
+        else
+          child.wire_handler_parents(handler_parent:, app:) if child.respond_to?(:wire_handler_parents)
+        end
+      end
+    end
+
+    # Override to specify the layout. Must call horizontal/vertical.
+    def partition; end
+
+    private
+
+    def horizontal(&) = divide_axis(:cols, &)
+    def vertical(&)   = divide_axis(:rows, &)
+
+    def region(**opts, &child_block)
+      @divide_frame << { opts: opts, block: child_block }
+    end
+
+    def divide_axis(axis, &block)
+      parent_rect = @rect
+      saved_frame = @divide_frame
+      @divide_frame = []
+
+      block.call
+
+      specs = @divide_frame
+      @divide_frame = saved_frame
+
+      validate_axis_kwargs(axis: axis, specs: specs)
+
+      calc_rects(parent_rect: parent_rect, axis: axis, specs: specs).each_with_index do |child_rect, i|
+        @rect = child_rect
+        place_child(child: specs[i][:block].call, rect: child_rect)
+      end
+
+      @rect = parent_rect
+    end
+
+    def validate_axis_kwargs(axis:, specs:)
+      expected, forbidden = axis == :cols ? %i[width height] : %i[height width]
+      specs.each do |spec|
+        next unless spec[:opts].key?(forbidden)
+
+        direction = axis == :cols ? "horizontal" : "vertical"
+        raise LayoutError,
+              "region(#{forbidden}:) is invalid inside #{direction} — use #{expected}: instead"
+      end
+    end
+
+    def place_child(child:, rect:)
+      @subtree_children ||= []
+      if child.is_a?(Sigil)
+        child.rect = rect
+        @leaf_sigils << child
+        @subtree_children << child
+      elsif child.respond_to?(:run_partition)
+        @child_layouts << child
+        @subtree_children << child
+        child.run_partition(rect: rect, collector: @leaf_sigils)
+      end
+    end
+
+    def validate_focus_order_node
+      order = focus_order
+      return if order.nil?
+
+      unless order.is_a?(Array)
+        raise FocusOrderError,
+              "#{self.class}#focus_order must return an Array, got #{order.class}"
+      end
+
+      focusable = (@subtree_leaves || []).select(&:focusable?)
+      missing    = focusable - order
+      extras     = order - focusable
+      duplicates = order.tally.select { |_, c| c > 1 }.keys
+
+      return if missing.empty? && extras.empty? && duplicates.empty?
+
+      msg = "#{self.class}#focus_order is invalid:"
+      msg += " missing #{missing.map(&:class).join(', ')};" unless missing.empty?
+      msg += " unknown entries #{extras.map(&:class).join(', ')};" unless extras.empty?
+      msg += " duplicates #{duplicates.map(&:class).join(', ')};" unless duplicates.empty?
+      raise FocusOrderError, msg
+    end
+
+    def calc_rects(parent_rect:, axis:, specs:)
+      if axis == :cols
+        total       = parent_rect.width
+        fixed_total = specs.sum { |s| integer_size(val: s[:opts][:width], total: total) || 0 }
+        fill_count  = specs.count { |s| s[:opts][:width] == :fill }
+        fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
+        leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
+
+        x = parent_rect.x
+        specs.each_with_index.map do |spec, i|
+          fill_index = specs[0..i].count { |s| s[:opts][:width] == :fill } - 1
+          last_fill  = fill_index >= 0 && fill_index == fill_count - 1
+
+          w = resolved_size(val: spec[:opts][:width], total: total, fill_size: fill_size,
+                            extra: last_fill ? leftover : 0)
+          w = apply_min_max(size: w, min: spec[:opts][:min], max: spec[:opts][:max])
+          r = Rect.new(x: x, y: parent_rect.y, width: w, height: parent_rect.height)
+          x += w
+          r
+        end
+      else
+        total       = parent_rect.height
+        fixed_total = specs.sum { |s| integer_size(val: s[:opts][:height], total: total) || 0 }
+        fill_count  = specs.count { |s| s[:opts][:height] == :fill }
+        fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
+        leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
+
+        y = parent_rect.y
+        specs.each_with_index.map do |spec, i|
+          fill_index = specs[0..i].count { |s| s[:opts][:height] == :fill } - 1
+          last_fill  = fill_index >= 0 && fill_index == fill_count - 1
+
+          h = resolved_size(val: spec[:opts][:height], total: total, fill_size: fill_size,
+                            extra: last_fill ? leftover : 0)
+          h = apply_min_max(size: h, min: spec[:opts][:min], max: spec[:opts][:max])
+          r = Rect.new(x: parent_rect.x, y: y, width: parent_rect.width, height: h)
+          y += h
+          r
+        end
+      end
+    end
+
+    def integer_size(val:, total:)
+      return val             if val.is_a?(Integer)
+      return nil             if val == :fill
+      return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
+
+      nil
+    end
+
+    def resolved_size(val:, total:, fill_size:, extra:)
+      return val + 0                             if val.is_a?(Integer)
+      return fill_size + extra                   if val == :fill
+      return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
+
+      fill_size + extra # default to fill if unspecified
+    end
+
+    def apply_min_max(size:, min:, max:)
+      size = [size, min].max if min
+      size = [size, max].min if max
+      [size, 0].max
+    end
+
+    # Used by repartition to wire new sigils to the app.
+    # overridden in App
+    def thaum_app_ref = nil
+  end
+end

data/lib/thaum/octagram.rb

@@ -9,7 +9,7 @@ module Thaum
   #
   # See DECISIONS.md (2026-06-02) for the naming rationale.
   module Octagram
-    include Concerns::Layout
+    include Layout
 
     attr_accessor :thaum_app, :handler_parent
 

data/lib/thaum/rendering/canvas.rb

@@ -135,7 +135,7 @@ module Thaum
           row_y = y + dy
           break if row_y >= @rect.height
 
-          bx = align_offset(line: line, available_width: @rect.width, align: align, x: x)
+          bx = align_offset(line: line, available_width: @rect.width - x, align: align, x: x)
           line.each_char do |char|
             w = char.display_width
             break if bx + w > right_edge
@@ -186,9 +186,11 @@ module Thaum
       end
 
       def align_offset(line:, available_width:, align:, x:)
+        # Origin of the content area is @rect.x + x; alignment is relative to
+        # available_width (the offset content area), so center/right add x too.
         case align
-        when :center then @rect.x + [(available_width - line.display_width) / 2, 0].max
-        when :right  then @rect.x + [available_width - line.display_width, 0].max
+        when :center then @rect.x + x + [(available_width - line.display_width) / 2, 0].max
+        when :right  then @rect.x + x + [available_width - line.display_width, 0].max
         else              @rect.x + x # :left
         end
       end

data/lib/thaum/version.rb

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

data/lib/thaum.rb

@@ -22,7 +22,7 @@ require_relative "thaum/input_reader"
 require_relative "thaum/rendering/renderer"
 require_relative "thaum/themes"
 require_relative "thaum/sigil"
-require_relative "thaum/concerns/layout"
+require_relative "thaum/layout"
 require_relative "thaum/octagram"
 require_relative "thaum/concerns/focus"
 require_relative "thaum/concerns/context_update"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thaum
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Tad Thorley
@@ -61,6 +61,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -89,7 +90,6 @@ files:
 - lib/thaum/color.rb
 - lib/thaum/concerns/context_update.rb
 - lib/thaum/concerns/focus.rb
-- lib/thaum/concerns/layout.rb
 - lib/thaum/concerns/modal.rb
 - lib/thaum/concerns/tab_navigation.rb
 - lib/thaum/dispatch.rb
@@ -100,6 +100,7 @@ files:
 - lib/thaum/input_reader.rb
 - lib/thaum/key_event.rb
 - lib/thaum/keys.rb
+- lib/thaum/layout.rb
 - lib/thaum/minitest.rb
 - lib/thaum/octagram.rb
 - lib/thaum/painter.rb

data/lib/thaum/concerns/layout.rb

@@ -1,349 +0,0 @@
-# frozen_string_literal: true
-
-module Thaum
-  module Concerns
-    module Layout
-      attr_reader :rect, :leaf_sigils, :subtree_leaves, :child_layouts, :subtree_children
-
-      # Override on any Layout node (including App) to specify a Tab traversal
-      # order for that subtree. Return an array of leaf Sigils. nil (default)
-      # means "use left-to-right leaf order."
-      def focus_order = nil
-
-      # Called by the run loop (or repartition) to assign geometry and walk the partition tree.
-      # Returns the flat list of leaf Sigils in render order.
-      def run_partition(rect:, collector: nil)
-        @rect = rect
-        collector ||= []
-        start = collector.size
-        @leaf_sigils     = collector
-        @child_layouts   = []
-        @subtree_children = []
-        # An Octagram may inset the rect its children partition into so its
-        # render hook (border, padding) survives. Plain Layout passes through.
-        @rect = inset_for_partition(rect)
-        partition
-        @rect = rect
-        @subtree_leaves = collector[start..] || []
-        collector
-      end
-
-      # Override on Octagram (or any Layout) to inset the rect that this
-      # node's children partition into. Defaults to identity.
-      def inset_for_partition(rect)
-        return rect unless respond_to?(:partition_inset)
-
-        inset = partition_inset || {}
-        Rect.new(
-          x:      rect.x + (inset[:left]   || 0),
-          y:      rect.y + (inset[:top]    || 0),
-          width:  [rect.width  - (inset[:left] || 0) - (inset[:right]  || 0), 0].max,
-          height: [rect.height - (inset[:top]  || 0) - (inset[:bottom] || 0), 0].max
-        )
-      end
-
-      # Re-run partition for this node's subtree using its current rect.
-      def repartition
-        return unless @rect
-
-        old_leaves    = @leaf_sigils || []
-        old_octagrams = collect_octagrams
-
-        new_leaves = []
-        run_partition(rect: @rect, collector: new_leaves)
-
-        new_octagrams = collect_octagrams
-
-        # Fire on_unmount for removed Sigils and Octagrams.
-        (old_leaves - new_leaves).each(&:on_unmount)
-        (old_octagrams - new_octagrams).each(&:on_unmount)
-
-        # Rewire handler parents across the (possibly restructured) subtree so
-        # newly-added Octagrams and Sigils see the right chain BEFORE on_mount.
-        # Only rewires when we can identify this node's role in the dispatch
-        # chain — App (root) or Octagram (its own handler scope).
-        app = thaum_app_ref || (is_a?(Octagram) ? @thaum_app : nil)
-        wire_handler_parents(handler_parent: self, app: app) if app
-
-        # Fire on_mount for newly-added Sigils and Octagrams.
-        (new_octagrams - old_octagrams).each do |o|
-          o.thaum_app = app if app
-          o.on_mount
-        end
-        (new_leaves - old_leaves).each do |s|
-          s.thaum_app = app if app
-          s.on_mount
-        end
-
-        @leaf_sigils = new_leaves
-
-        # Re-validate focus_order in this subtree after structural change.
-        validate_focus_order_tree
-      end
-
-      # Walk this subtree and collect every Octagram node (excluding self).
-      def collect_octagrams
-        result = []
-        (@subtree_children || []).each do |child|
-          if child.is_a?(Octagram)
-            result << child
-            result.concat(child.collect_octagrams)
-          elsif child.respond_to?(:collect_octagrams)
-            result.concat(child.collect_octagrams)
-          end
-        end
-        result
-      end
-
-      # Walk this Layout node and every descendant Layout, raising
-      # FocusOrderError if any defines a focus_order that does not exactly
-      # cover the focusable leaves in its subtree.
-      def validate_focus_order_tree
-        validate_focus_order_node
-        (@child_layouts || []).each(&:validate_focus_order_tree)
-      end
-
-      # Build the Tab traversal order for this subtree, recursively expanding
-      # any nested Layout that itself has focus_order. When no focus_order is
-      # defined at any level, this falls through to left-to-right leaf order.
-      def effective_focus_order
-        order = focus_order
-        return order if order
-
-        result = []
-        layout_subtree_in_order.each do |node|
-          if node.is_a?(Sigil)
-            result << node if node.focusable?
-          else
-            result.concat(node.effective_focus_order)
-          end
-        end
-        result
-      end
-
-      # The direct children of this Layout in declaration order — both Sigils
-      # and nested Layouts. Built during partition (see place_child).
-      def layout_subtree_in_order = @subtree_children || []
-
-      # Scope units for Tab cycling within THIS focus scope. A "scope" is the
-      # App or an Octagram. A unit is either a focusable Sigil (reached through
-      # plain Layouts only) or a nested Octagram (which appears as one unit and
-      # is itself a scope). Plain Layouts are transparent — their units are
-      # flattened into the parent scope.
-      def focus_scope_units
-        result = []
-        (@subtree_children || []).each do |child|
-          case child
-          when Sigil
-            result << child if child.focusable?
-          when Octagram
-            result << child if child.focusable_descendant?
-          else
-            result.concat(child.focus_scope_units) if child.respond_to?(:focus_scope_units)
-          end
-        end
-        result
-      end
-
-      # Recursively descend into this Octagram (or plain Layout) to find its
-      # first focusable leaf — used when Tab enters an Octagram unit.
-      def first_focusable_leaf
-        (@subtree_children || []).each do |child|
-          case child
-          when Sigil
-            return child if child.focusable?
-          else
-            leaf = child.first_focusable_leaf if child.respond_to?(:first_focusable_leaf)
-            return leaf if leaf
-          end
-        end
-        nil
-      end
-
-      # Mirror of first_focusable_leaf for Shift-Tab entry.
-      def last_focusable_leaf
-        (@subtree_children || []).reverse_each do |child|
-          case child
-          when Sigil
-            return child if child.focusable?
-          else
-            leaf = child.last_focusable_leaf if child.respond_to?(:last_focusable_leaf)
-            return leaf if leaf
-          end
-        end
-        nil
-      end
-
-      def focusable_descendant?
-        !first_focusable_leaf.nil?
-      end
-
-      # Walk the subtree top-down, wiring each leaf Sigil and each Octagram.
-      # Leaves and Octagrams get _handler_parent set to the innermost
-      # enclosing Octagram (or the App when there is none). Plain Layout
-      # nodes are transparent — their children inherit the outer parent.
-      def wire_handler_parents(handler_parent:, app:)
-        (@subtree_children || []).each do |child|
-          case child
-          when Sigil
-            child.handler_parent = handler_parent
-            child.thaum_app      = app
-          when Octagram
-            child.handler_parent = handler_parent
-            child.thaum_app      = app
-            child.wire_handler_parents(handler_parent: child, app: app)
-          else
-            child.wire_handler_parents(handler_parent:, app:) if child.respond_to?(:wire_handler_parents)
-          end
-        end
-      end
-
-      # Override to specify the layout. Must call horizontal/vertical.
-      def partition; end
-
-      private
-
-      def horizontal(&) = divide_axis(:cols, &)
-      def vertical(&)   = divide_axis(:rows, &)
-
-      def region(**opts, &child_block)
-        @divide_frame << { opts: opts, block: child_block }
-      end
-
-      def divide_axis(axis, &block)
-        parent_rect = @rect
-        saved_frame = @divide_frame
-        @divide_frame = []
-
-        block.call
-
-        specs = @divide_frame
-        @divide_frame = saved_frame
-
-        validate_axis_kwargs(axis: axis, specs: specs)
-
-        calc_rects(parent_rect: parent_rect, axis: axis, specs: specs).each_with_index do |child_rect, i|
-          @rect = child_rect
-          place_child(child: specs[i][:block].call, rect: child_rect)
-        end
-
-        @rect = parent_rect
-      end
-
-      def validate_axis_kwargs(axis:, specs:)
-        expected, forbidden = axis == :cols ? %i[width height] : %i[height width]
-        specs.each do |spec|
-          next unless spec[:opts].key?(forbidden)
-
-          direction = axis == :cols ? "horizontal" : "vertical"
-          raise LayoutError,
-                "region(#{forbidden}:) is invalid inside #{direction} — use #{expected}: instead"
-        end
-      end
-
-      def place_child(child:, rect:)
-        @subtree_children ||= []
-        if child.is_a?(Sigil)
-          child.rect = rect
-          @leaf_sigils << child
-          @subtree_children << child
-        elsif child.respond_to?(:run_partition)
-          @child_layouts << child
-          @subtree_children << child
-          child.run_partition(rect: rect, collector: @leaf_sigils)
-        end
-      end
-
-      def validate_focus_order_node
-        order = focus_order
-        return if order.nil?
-
-        unless order.is_a?(Array)
-          raise FocusOrderError,
-                "#{self.class}#focus_order must return an Array, got #{order.class}"
-        end
-
-        focusable = (@subtree_leaves || []).select(&:focusable?)
-        missing    = focusable - order
-        extras     = order - focusable
-        duplicates = order.tally.select { |_, c| c > 1 }.keys
-
-        return if missing.empty? && extras.empty? && duplicates.empty?
-
-        msg = "#{self.class}#focus_order is invalid:"
-        msg += " missing #{missing.map(&:class).join(', ')};" unless missing.empty?
-        msg += " unknown entries #{extras.map(&:class).join(', ')};" unless extras.empty?
-        msg += " duplicates #{duplicates.map(&:class).join(', ')};" unless duplicates.empty?
-        raise FocusOrderError, msg
-      end
-
-      def calc_rects(parent_rect:, axis:, specs:)
-        if axis == :cols
-          total       = parent_rect.width
-          fixed_total = specs.sum { |s| integer_size(val: s[:opts][:width], total: total) || 0 }
-          fill_count  = specs.count { |s| s[:opts][:width] == :fill }
-          fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
-          leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
-
-          x = parent_rect.x
-          specs.each_with_index.map do |spec, i|
-            fill_index = specs[0..i].count { |s| s[:opts][:width] == :fill } - 1
-            last_fill  = fill_index >= 0 && fill_index == fill_count - 1
-
-            w = resolved_size(val: spec[:opts][:width], total: total, fill_size: fill_size,
-                              extra: last_fill ? leftover : 0)
-            w = apply_min_max(size: w, min: spec[:opts][:min], max: spec[:opts][:max])
-            r = Rect.new(x: x, y: parent_rect.y, width: w, height: parent_rect.height)
-            x += w
-            r
-          end
-        else
-          total       = parent_rect.height
-          fixed_total = specs.sum { |s| integer_size(val: s[:opts][:height], total: total) || 0 }
-          fill_count  = specs.count { |s| s[:opts][:height] == :fill }
-          fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
-          leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
-
-          y = parent_rect.y
-          specs.each_with_index.map do |spec, i|
-            fill_index = specs[0..i].count { |s| s[:opts][:height] == :fill } - 1
-            last_fill  = fill_index >= 0 && fill_index == fill_count - 1
-
-            h = resolved_size(val: spec[:opts][:height], total: total, fill_size: fill_size,
-                              extra: last_fill ? leftover : 0)
-            h = apply_min_max(size: h, min: spec[:opts][:min], max: spec[:opts][:max])
-            r = Rect.new(x: parent_rect.x, y: y, width: parent_rect.width, height: h)
-            y += h
-            r
-          end
-        end
-      end
-
-      def integer_size(val:, total:)
-        return val             if val.is_a?(Integer)
-        return nil             if val == :fill
-        return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
-
-        nil
-      end
-
-      def resolved_size(val:, total:, fill_size:, extra:)
-        return val + 0                             if val.is_a?(Integer)
-        return fill_size + extra                   if val == :fill
-        return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
-
-        fill_size + extra # default to fill if unspecified
-      end
-
-      def apply_min_max(size:, min:, max:)
-        size = [size, min].max if min
-        size = [size, max].min if max
-        [size, 0].max
-      end
-
-      # Used by repartition to wire new sigils to the app.
-      # overridden in App
-      def thaum_app_ref = nil
-    end
-  end
-end