charming 0.2.0 → 0.2.2

data/lib/charming/presentation/ui/style.rb

@@ -18,6 +18,7 @@ module Charming
         @options = {
           attributes: [],
           padding: [0, 0, 0, 0],
+          margin: [0, 0, 0, 0],
           align: :left
         }.merge(options)
       end
@@ -49,11 +50,31 @@ module Charming
         with(padding: expand_box_values(values))
       end
 
+      # Returns a new Style with the margin set — blank space applied outside the border and
+      # untouched by the style's colors. Accepts the same CSS-style shorthand as `padding`.
+      def margin(*values)
+        with(margin: expand_box_values(values))
+      end
+
+      # Per-side setters: padding_top/right/bottom/left and margin_top/right/bottom/left,
+      # each returning a new Style with just that side changed.
+      %i[padding margin].each do |box|
+        %i[top right bottom left].each_with_index do |side, index|
+          define_method(:"#{box}_#{side}") do |value|
+            values = @options.fetch(box).dup
+            values[index] = value
+            with(box => values)
+          end
+        end
+      end
+
       # Returns a new Style with the border set. *style* is a border name (e.g., :normal,
-      # :rounded). *sides* optionally restricts the border to specific sides. *foreground*
-      # sets the border color.
-      def border(style = :normal, sides: nil, foreground: nil)
-        with(border: style, border_sides: sides, border_foreground: foreground)
+      # :rounded, :square, :hidden, :block) or a custom Border instance. *sides* optionally
+      # restricts the border to specific sides. *foreground* colors the border — a single
+      # color, or a per-side hash like `{top: :red, left: :green}`. *background* colors the
+      # border independently of the box background.
+      def border(style = :normal, sides: nil, foreground: nil, background: nil)
+        with(border: style, border_sides: sides, border_foreground: foreground, border_background: background)
       end
 
       # Returns a new Style that fixes the rendered width to *value* (in display columns).
@@ -66,19 +87,50 @@ module Charming
         with(height: value)
       end
 
+      # Returns a new Style that caps the rendered width to *value* display columns.
+      # Unlike `width`, content narrower than the cap is not padded out to it.
+      def max_width(value)
+        with(max_width: value)
+      end
+
+      # Returns a new Style that caps the rendered height to *value* rows. Unlike
+      # `height`, content shorter than the cap is not filled with blank rows.
+      def max_height(value)
+        with(max_height: value)
+      end
+
+      # Returns a new Style that word-wraps overflowing lines at the fixed width
+      # instead of clipping them.
+      def wrap
+        with(fit: :wrap)
+      end
+
+      # Returns a new Style that marks lines clipped at the fixed width with a
+      # trailing *ellipsis* instead of cutting them silently.
+      def truncate(ellipsis: Truncate::ELLIPSIS)
+        with(fit: :truncate, ellipsis: ellipsis)
+      end
+
       # Returns a new Style with horizontal alignment set (`:left`, `:right`, or `:center`).
       def align(value)
         with(align: value)
       end
 
+      # Returns a new Style with vertical alignment within a fixed height set
+      # (`:top`, `:middle`, or `:bottom`).
+      def align_vertical(value)
+        with(align_vertical: value)
+      end
+
       # Applies the configured style to *value* and returns the styled string. Steps:
-      # 1. wrap to `:width`, 2. align horizontally, 3. expand to `:height`, 4. apply padding,
-      # 5. paint border, 6. emit ANSI attribute/foreground/background escapes.
+      # 1. wrap to `:width`, 2. align horizontally and vertically, 3. expand to `:height`,
+      # 4. apply padding, 5. paint border, 6. emit ANSI attribute/foreground/background
+      # escapes, 7. surround with unstyled margin space.
       def render(value)
         lines = apply_dimensions(value.to_s.lines(chomp: true))
         lines = apply_padding(lines)
         lines = apply_border(lines)
-        apply_ansi(lines.join("\n"))
+        apply_margin(apply_ansi(lines.join("\n")))
       end
 
       private
@@ -91,40 +143,87 @@ module Charming
       # Wraps each line to the target width and applies horizontal alignment, then expands
       # to the target height.
       def apply_dimensions(lines)
+        lines = wrap_lines(lines)
         content_width = target_content_width(lines)
         dimensioned = lines.map { |line| align_line(fit_line(line, content_width), content_width) }
-        apply_height(dimensioned, content_width)
+        apply_max_height(apply_height(dimensioned, content_width))
+      end
+
+      # Word-wraps lines at the fixed width when the style is in wrap mode.
+      def wrap_lines(lines)
+        wrap_width = @options[:width]
+        return lines unless wrap_width && @options[:fit] == :wrap
+
+        wrapper = TextWrapper.new(width: wrap_width)
+        lines.flat_map { |line| wrapper.wrap(line).lines(chomp: true) }
       end
 
       # Returns the target content width: the explicit :width if set, otherwise the natural
-      # max display width of the lines.
+      # max display width of the lines, capped to :max_width when configured.
       def target_content_width(lines)
-        explicit_width = @options[:width]
-        natural_width = lines.map { |line| Width.measure(line) }.max || 0
-        explicit_width || natural_width
+        width = @options[:width] || Width.widest(lines)
+        max = @options[:max_width]
+        max ? [width, max].min : width
       end
 
-      # Clips *line* to *width* display columns, preserving ANSI styling where possible.
+      # Fits *line* into *width* display columns: clipped by default, or marked with an
+      # ellipsis in truncate mode. Preserves ANSI styling active at the cut.
       def fit_line(line, width)
         return line if Width.measure(line) <= width
+        return Truncate.tail(line, width, ellipsis: @options.fetch(:ellipsis, Truncate::ELLIPSIS)) if @options[:fit] == :truncate
 
         UI.visible_slice(line, 0, width)
       end
 
-      # Truncates or pads the lines array to *height* rows, filling with blank rows.
+      # Truncates or pads the lines array to *height* rows, distributing blank fill
+      # rows according to :align_vertical (:top, :middle, or :bottom).
       def apply_height(lines, width)
         height = @options[:height]
         return lines unless height
 
         visible = lines.first(height)
-        visible + Array.new([height - visible.length, 0].max) { " " * width }
+        distribute_rows(visible, height - visible.length, width)
+      end
+
+      # Places *missing* blank rows around *visible* per the vertical alignment.
+      def distribute_rows(visible, missing, width)
+        blank = ->(count) { Array.new([count, 0].max) { " " * width } }
+        case @options.fetch(:align_vertical, :top)
+        when :bottom
+          blank.call(missing) + visible
+        when :middle
+          top = missing / 2
+          blank.call(top) + visible + blank.call(missing - top)
+        else
+          visible + blank.call(missing)
+        end
+      end
+
+      # Surrounds the styled block with unstyled margin space: blank rows above and
+      # below, plain-space columns left and right. Applied after ANSI styling so the
+      # margin never carries the style's colors.
+      def apply_margin(styled)
+        top, right, bottom, left = @options.fetch(:margin)
+        return styled if [top, right, bottom, left].all?(&:zero?)
+
+        lines = styled.lines(chomp: true)
+        width = Width.widest(lines)
+        body = lines.map { |line| (" " * left) + Width.pad_to(line, width) + (" " * right) }
+        blank = " " * (left + width + right)
+        (Array.new(top, blank) + body + Array.new(bottom, blank)).join("\n")
+      end
+
+      # Caps the lines array to :max_height rows without filling missing rows.
+      def apply_max_height(lines)
+        max = @options[:max_height]
+        max ? lines.first(max) : lines
       end
 
       # Applies padding by prepending/appending blank rows (vertical) and indenting each
       # line (horizontal).
       def apply_padding(lines)
         top, right, bottom, left = @options.fetch(:padding)
-        inner_width = lines.map { |line| Width.measure(line) }.max || 0
+        inner_width = Width.widest(lines)
         empty = " " * (left + inner_width + right)
         padded = lines.map do |line|
           pad_line(line, inner_width, left, right)
@@ -143,7 +242,7 @@ module Charming
 
       # Pads a single line to *inner_width*, with *left* and *right* padding spaces.
       def pad_line(line, inner_width, left, right)
-        (" " * left) + line + (" " * (inner_width - Width.measure(line) + right))
+        (" " * left) + Width.pad_to(line, inner_width) + (" " * right)
       end
 
       # Builds a BorderPainter configured for the current border options.
@@ -152,13 +251,14 @@ module Charming
           border: Border.fetch(border_name),
           sides: @options[:border_sides],
           foreground: @options[:border_foreground],
-          background: @options[:background]
+          background: @options[:border_background] || @options[:background],
+          background_explicit: !@options[:border_background].nil?
         )
       end
 
       # Returns the natural display width of the longest line in *lines*.
       def content_width(lines)
-        lines.map { |line| Width.measure(line) }.max || 0
+        Width.widest(lines)
       end
 
       # Applies the active ANSI attribute/foreground/background codes to *value*.

data/lib/charming/presentation/ui/text_wrapper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # TextWrapper greedily word-wraps text blocks to a display width.
+    class TextWrapper
+      def initialize(width:)
+        @width = width
+      end
+
+      def wrap(value)
+        return value unless width
+
+        value.to_s.lines(chomp: true).map { |line| wrap_line(line) }.join("\n")
+      end
+
+      private
+
+      attr_reader :width
+
+      def wrap_line(line)
+        return line if Width.measure(line) <= width
+
+        wrap_words(line.split(/\s+/))
+      end
+
+      def wrap_words(words)
+        words.each_with_object([]) { |word, lines| append_word(lines, word) }.join("\n")
+      end
+
+      def append_word(lines, word)
+        current = lines.pop.to_s
+        candidate = current.empty? ? word : "#{current} #{word}"
+        return lines.push(candidate) if current.empty? || Width.measure(candidate) <= width
+
+        lines.push(current.rstrip, word)
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/theme.rb

@@ -109,6 +109,13 @@ module Charming
       end
       alias_method :[], :style
 
+      # Returns a new Theme with *overrides* (token name → style spec hash) merged over
+      # this theme's tokens. Override colors are literal (hex strings, named symbols, or
+      # 256 indexes) — the parent's palette names are already resolved.
+      def merge(overrides, background: @background)
+        self.class.new(@tokens.merge(symbolize_keys(overrides.to_h)), background: background)
+      end
+
       def method_missing(name, ...)
         return style(name) if @tokens.key?(name)
 

data/lib/charming/presentation/ui/themes/catppuccin-latte.json

@@ -0,0 +1,35 @@
+{
+  "name": "Catppuccin Latte",
+  "id": "catppuccin-latte",
+  "background": "background",
+  "palette": {
+    "text": "#4C4F69",
+    "subtext": "#6C6F85",
+    "overlay": "#9CA0B0",
+    "background": "#EFF1F5",
+    "surface": "#CCD0DA",
+    "mauve": "#8839EF",
+    "peach": "#FE640B",
+    "sky": "#04A5E5",
+    "lavender": "#7287FD",
+    "green": "#40A02B",
+    "yellow": "#DF8E1D",
+    "red": "#D20F39"
+  },
+  "styles": {
+    "text": {"foreground": "text", "background": "background"},
+    "muted": {"foreground": "subtext", "background": "background"},
+    "title": {"foreground": "mauve", "background": "background", "bold": true},
+    "selected": {"foreground": "text", "background": "surface", "bold": true},
+    "header": {"foreground": "text", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "overlay"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "overlay"}, "padding": [1, 1]},
+    "main": {"foreground": "text", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "overlay", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "overlay"}, "padding": [0, 1]},
+    "modal": {"foreground": "text", "background": "background", "border": {"style": "rounded", "foreground": "lavender"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "border": {"foreground": "overlay", "background": "background"},
+    "info": {"foreground": "sky", "background": "background"},
+    "warn": {"foreground": "peach", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/catppuccin-mocha.json

@@ -0,0 +1,35 @@
+{
+  "name": "Catppuccin Mocha",
+  "id": "catppuccin-mocha",
+  "background": "background",
+  "palette": {
+    "text": "#CDD6F4",
+    "subtext": "#A6ADC8",
+    "overlay": "#6C7086",
+    "background": "#1E1E2E",
+    "surface": "#313244",
+    "mauve": "#CBA6F7",
+    "peach": "#FAB387",
+    "sky": "#89DCEB",
+    "lavender": "#B4BEFE",
+    "green": "#A6E3A1",
+    "yellow": "#F9E2AF",
+    "red": "#F38BA8"
+  },
+  "styles": {
+    "text": {"foreground": "text", "background": "background"},
+    "muted": {"foreground": "subtext", "background": "background"},
+    "title": {"foreground": "mauve", "background": "background", "bold": true},
+    "selected": {"foreground": "text", "background": "surface", "bold": true},
+    "header": {"foreground": "text", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "overlay"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "overlay"}, "padding": [1, 1]},
+    "main": {"foreground": "text", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "overlay", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "overlay"}, "padding": [0, 1]},
+    "modal": {"foreground": "text", "background": "background", "border": {"style": "rounded", "foreground": "lavender"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "border": {"foreground": "overlay", "background": "background"},
+    "info": {"foreground": "sky", "background": "background"},
+    "warn": {"foreground": "peach", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/gruvbox-dark.json

@@ -0,0 +1,33 @@
+{
+  "name": "Gruvbox Dark",
+  "id": "gruvbox-dark",
+  "background": "background",
+  "palette": {
+    "fg": "#EBDBB2",
+    "gray": "#928374",
+    "background": "#282828",
+    "surface": "#3C3836",
+    "yellow": "#FABD2F",
+    "orange": "#FE8019",
+    "aqua": "#8EC07C",
+    "blue": "#83A598",
+    "green": "#B8BB26",
+    "red": "#FB4934"
+  },
+  "styles": {
+    "text": {"foreground": "fg", "background": "background"},
+    "muted": {"foreground": "gray", "background": "background"},
+    "title": {"foreground": "yellow", "background": "background", "bold": true},
+    "selected": {"foreground": "fg", "background": "surface", "bold": true},
+    "header": {"foreground": "fg", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "gray"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "orange", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "gray"}, "padding": [1, 1]},
+    "main": {"foreground": "fg", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "gray", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "gray"}, "padding": [0, 1]},
+    "modal": {"foreground": "fg", "background": "background", "border": {"style": "rounded", "foreground": "yellow"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "orange", "background": "background", "bold": true},
+    "border": {"foreground": "gray", "background": "background"},
+    "info": {"foreground": "blue", "background": "background"},
+    "warn": {"foreground": "orange", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/nord.json

@@ -0,0 +1,32 @@
+{
+  "name": "Nord",
+  "id": "nord",
+  "background": "background",
+  "palette": {
+    "snow": "#D8DEE9",
+    "comment": "#616E88",
+    "background": "#2E3440",
+    "surface": "#3B4252",
+    "frost_blue": "#88C0D0",
+    "frost_deep": "#81A1C1",
+    "aurora_yellow": "#EBCB8B",
+    "aurora_green": "#A3BE8C",
+    "aurora_red": "#BF616A"
+  },
+  "styles": {
+    "text": {"foreground": "snow", "background": "background"},
+    "muted": {"foreground": "comment", "background": "background"},
+    "title": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "selected": {"foreground": "snow", "background": "surface", "bold": true},
+    "header": {"foreground": "snow", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "comment"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "comment"}, "padding": [1, 1]},
+    "main": {"foreground": "snow", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "comment", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "comment"}, "padding": [0, 1]},
+    "modal": {"foreground": "snow", "background": "background", "border": {"style": "rounded", "foreground": "frost_blue"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "border": {"foreground": "comment", "background": "background"},
+    "info": {"foreground": "frost_deep", "background": "background"},
+    "warn": {"foreground": "aurora_yellow", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/tokyonight.json

@@ -0,0 +1,34 @@
+{
+  "name": "Tokyo Night",
+  "id": "tokyonight",
+  "background": "background",
+  "palette": {
+    "fg": "#C0CAF5",
+    "comment": "#565F89",
+    "background": "#1A1B26",
+    "surface": "#292E42",
+    "blue": "#7AA2F7",
+    "cyan": "#7DCFFF",
+    "yellow": "#E0AF68",
+    "magenta": "#BB9AF7",
+    "green": "#9ECE6A",
+    "red": "#F7768E",
+    "orange": "#FF9E64"
+  },
+  "styles": {
+    "text": {"foreground": "fg", "background": "background"},
+    "muted": {"foreground": "comment", "background": "background"},
+    "title": {"foreground": "blue", "background": "background", "bold": true},
+    "selected": {"foreground": "fg", "background": "surface", "bold": true},
+    "header": {"foreground": "fg", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "comment"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "magenta", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "comment"}, "padding": [1, 1]},
+    "main": {"foreground": "fg", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "comment", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "comment"}, "padding": [0, 1]},
+    "modal": {"foreground": "fg", "background": "background", "border": {"style": "rounded", "foreground": "magenta"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "magenta", "background": "background", "bold": true},
+    "border": {"foreground": "comment", "background": "background"},
+    "info": {"foreground": "cyan", "background": "background"},
+    "warn": {"foreground": "yellow", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/truncate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Truncate cuts ANSI-styled text down to a display width, marking the cut
+    # with a trailing ellipsis. Styling active at the cut is preserved and
+    # terminated, and multi-column glyphs are never split (matching ANSISlicer).
+    module Truncate
+      ELLIPSIS = "…"
+
+      module_function
+
+      # Truncates each line of *text* to *width* display columns, appending
+      # *ellipsis* to lines that overflow. Lines that fit are returned unchanged.
+      def tail(text, width, ellipsis: ELLIPSIS)
+        text.to_s.lines(chomp: true).map { |line| tail_line(line, width, ellipsis) }.join("\n")
+      end
+
+      def tail_line(line, width, ellipsis)
+        return line if Width.measure(line) <= width
+
+        ellipsis_width = Width.measure(ellipsis)
+        return ANSISlicer.slice(line, 0, width) if ellipsis_width >= width
+
+        ANSISlicer.slice(line, 0, width - ellipsis_width) + ellipsis
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/width.rb

@@ -8,17 +8,53 @@ module Charming
     # ANSI escape sequences. It delegates to `Unicode::DisplayWidth` while automatically stripping
     # formatting codes so layout primitives can calculate exact character positions.
     module Width
-      ANSI_PATTERN = /\e\[[0-9;]*m/
+      # Matches OSC sequences (e.g. OSC 8 hyperlinks, terminated by BEL or ST),
+      # CSI sequences (SGR colors/attributes, cursor movement), and single-character
+      # Fe escapes. The OSC branch must come first and the Fe class must exclude
+      # "[" and "]", or "\e]" would match as a bare Fe escape and leave the OSC
+      # payload counted as visible text.
+      ANSI_PATTERN = /\e(?:\][^\a]*?(?:\a|\e\\)|\[[0-9;?]*[@-~]|[@-Z\\^_])/
+
+      # A grapheme cluster containing either codepoint renders as a single emoji
+      # (double-width) cell in a terminal: U+200D ZWJ joins a multi-glyph emoji
+      # sequence, and U+FE0F (VS16) requests emoji presentation. The
+      # unicode-display_width tables disagree with terminals here — e.g. "⚔️"
+      # measures 1 and "🧙‍♂️" measures 3 — so we pin such clusters to 2.
+      EMOJI_PRESENTATION = /[\u200D\uFE0F]/
+
+      # Onig's \X matches one extended grapheme cluster, keeping multi-codepoint
+      # emoji together so each is measured (and later sliced) as one unit.
+      GRAPHEME = /\X/
 
       module_function
 
       def measure(value)
-        Unicode::DisplayWidth.of(strip_ansi(value.to_s))
+        stripped = strip_ansi(value.to_s)
+        return Unicode::DisplayWidth.of(stripped) unless stripped.match?(EMOJI_PRESENTATION)
+
+        stripped.scan(GRAPHEME).sum { |cluster| cluster_width(cluster) }
+      end
+
+      def cluster_width(cluster)
+        return 2 if cluster.match?(EMOJI_PRESENTATION)
+
+        Unicode::DisplayWidth.of(cluster)
       end
 
       def strip_ansi(value)
         value.to_s.gsub(ANSI_PATTERN, "")
       end
+
+      # Pads *line* with trailing spaces to *width* display columns. Lines already at
+      # or beyond the target are returned unchanged.
+      def pad_to(line, width)
+        line + (" " * [width - measure(line), 0].max)
+      end
+
+      # The maximum display width across *lines*; 0 when there are none.
+      def widest(lines)
+        lines.map { |line| measure(line) }.max || 0
+      end
     end
   end
 end

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