feat(tui): add Unicode text service and document layout

10 files changed, 1072 insertions, 22 deletions

diff --git a/include/ricochet/tui/session.hh b/include/ricochet/tui/session.hh
index 9968178..94cae68 100644
--- a/include/ricochet/tui/session.hh
+++ b/include/ricochet/tui/session.hh
@@ -71,7 +71,7 @@ private:
 struct StepResult
 {
   bool running { true };
-  // Content editing/layout handlers are subsequent milestones. Until they exist,
+  // Incremental document updates and editing are subsequent milestones. Until then,
   // unsupported updates are returned intact rather than silently acknowledged.
   std::vector<HostUpdate> unhandled_updates {};
   std::optional<TerminalClosed> terminal_closed {};
diff --git a/src/tui/CMakeLists.txt b/src/tui/CMakeLists.txt
index 908448e..8b49cf1 100644
--- a/src/tui/CMakeLists.txt
+++ b/src/tui/CMakeLists.txt
@@ -1,8 +1,10 @@
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(NCURSESW REQUIRED IMPORTED_TARGET ncursesw)
 find_package(Threads REQUIRED)
+# ICU 76.1 supplies UTF-8 grapheme/line boundaries and Unicode properties.
+pkg_check_modules(ICU REQUIRED IMPORTED_TARGET icu-uc>=76.1 icu-i18n>=76.1)
 
-add_library(ricochet_tui STATIC document.cc mailbox.cc screen.cc session.cc)
+add_library(ricochet_tui STATIC document.cc mailbox.cc screen.cc session.cc text.cc layout.cc)
 target_include_directories(ricochet_tui PUBLIC ${PROJECT_SOURCE_DIR}/include)
 target_compile_features(ricochet_tui PUBLIC cxx_std_23)
-target_link_libraries(ricochet_tui PRIVATE PkgConfig::NCURSESW Threads::Threads)
+target_link_libraries(ricochet_tui PRIVATE PkgConfig::NCURSESW PkgConfig::ICU Threads::Threads)
diff --git a/src/tui/layout.cc b/src/tui/layout.cc
new file mode 100644
index 0000000..5aebe17
--- /dev/null
+++ b/src/tui/layout.cc
@@ -0,0 +1,677 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "layout.hh"
+
+#include <algorithm>
+#include <limits>
+#include <map>
+#include <numeric>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+namespace ricochet::tui::detail {
+namespace {
+
+constexpr int tab_columns = 8;
+constexpr std::int64_t cell_gap = 3;
+constexpr std::int64_t minimum_cell_columns = 4;
+
+TextStyle overlay( TextStyle base, TextStyle extra )
+{
+  return { base.emphasis || extra.emphasis,
+           base.strong || extra.strong,
+           base.code || extra.code,
+           base.subdued || extra.subdued,
+           base.warning || extra.warning };
+}
+
+struct Atom
+{
+  Grapheme glyph {};
+  DocumentRange source {};
+  TextStyle style {};
+  std::optional<HitTarget> target {};
+  bool decoration { false };
+};
+
+struct TextSpan
+{
+  const Text* leaf;
+  ByteRange bytes;
+};
+
+DocumentPoint text_point( std::span<const TextSpan> spans, std::size_t offset, bool end )
+{
+  for ( const auto& span : spans ) {
+    // At an inline seam an end belongs to the preceding leaf, a start to the next.
+    if ( offset < span.bytes.end || ( end && offset == span.bytes.end ) ) {
+      return TextPosition { span.leaf->id, offset - span.bytes.start };
+    }
+  }
+  const auto& last = spans.back();
+  return TextPosition { last.leaf->id, last.leaf->utf8.size() };
+}
+
+LayoutGlyph anchor( DocumentPoint point, LayoutPoint location, std::int64_t width )
+{ return { .position = location, .source = { point, point }, .clip_right = width }; }
+
+void append_box( LayoutData& destination, LayoutData source, std::size_t row, std::int64_t column )
+{
+  destination.rows = std::max( destination.rows, row + source.rows );
+  destination.extent = std::max( destination.extent, column + source.extent );
+  for ( auto& glyph : source.glyphs ) {
+    glyph.position.row += row;
+    glyph.position.column += column;
+    glyph.line_start += column;
+    glyph.clip_left += column;
+    glyph.clip_right += column;
+    destination.glyphs.push_back( std::move( glyph ) );
+  }
+}
+
+class LayoutBuilder
+{
+public:
+  LayoutBuilder( const DocumentData& document, const TextService& text, std::span<const HorizontalScroll> scrolls )
+    : document_( document ), text_( text ), scrolls_( scrolls )
+  {
+    for ( const auto& control : document.controls ) {
+      controls_.emplace( control.id, &control );
+    }
+  }
+
+  LayoutData blocks( std::span<const Block> content, std::int64_t width, TextStyle style = {} ) const
+  {
+    LayoutData result;
+    std::size_t row = 0;
+    for ( const auto& block : content ) {
+      auto box = block_box( block, width, style );
+      const auto height = box.rows;
+      append_box( result, std::move( box ), row, 0 );
+      row += height;
+    }
+    return result;
+  }
+
+private:
+  void text_run( std::vector<Atom>& atoms,
+                 std::span<const TextSpan> spans,
+                 const std::string& utf8,
+                 bool tabs,
+                 TextStyle base ) const
+  {
+    const auto analysis = text_.analyze( utf8, true, tabs );
+    for ( const auto& glyph : analysis.graphemes ) {
+      Atom atom { .glyph = glyph,
+                  .source
+                  = { text_point( spans, glyph.bytes.start, false ), text_point( spans, glyph.bytes.end, true ) },
+                  .style = base };
+      for ( const auto& span : spans ) {
+        // Only source portions intersecting this grapheme can contribute style/link.
+        if ( span.bytes.start >= glyph.bytes.end || span.bytes.end <= glyph.bytes.start ) {
+          continue;
+        }
+        const ByteRange local { std::max( span.bytes.start, glyph.bytes.start ) - span.bytes.start,
+                                std::min( span.bytes.end, glyph.bytes.end ) - span.bytes.start };
+        for ( const auto& styled : span.leaf->styles ) {
+          if ( styled.bytes.start < local.end && local.start < styled.bytes.end ) {
+            atom.style = overlay( atom.style, styled.style );
+          }
+        }
+        for ( const auto& link : document_.links ) {
+          for ( const auto& range : link.ranges ) {
+            if ( range.block == span.leaf->id && range.bytes.start < local.end && local.start < range.bytes.end ) {
+              const HitTarget target = link.id;
+              // One grapheme cannot activate two links, including across leaf seams.
+              if ( atom.target && atom.target != target ) {
+                throw std::invalid_argument( "Overlapping links address the same grapheme" );
+              }
+              atom.target = target;
+              atom.style.emphasis = true;
+            }
+          }
+        }
+      }
+      atoms.push_back( std::move( atom ) );
+    }
+    // Empty text still has a real byte boundary; no fabricated display character.
+    if ( utf8.empty() ) {
+      const auto point = text_point( spans, 0, false );
+      atoms.push_back( { .glyph = { .columns = 0 }, .source = { point, point }, .style = base } );
+    }
+  }
+
+  std::string control_text( const Control& control ) const
+  {
+    return std::visit(
+      [this, &control]( const auto& value ) -> std::string {
+        using Value = std::decay_t<decltype( value )>;
+        if constexpr ( std::is_same_v<Value, TextControl> ) {
+          if ( value.kind == TextControlKind::Password ) {
+            return std::string( text_.analyze( value.value, true, false ).graphemes.size(), '*' );
+          }
+          return value.value;
+        } else if constexpr ( std::is_same_v<Value, Checkbox> || std::is_same_v<Value, RadioButton> ) {
+          return control.label;
+        } else if constexpr ( std::is_same_v<Value, SelectControl> ) {
+          std::string result;
+          for ( const auto& option : value.options ) {
+            if ( std::ranges::find( value.selected, option.id ) != value.selected.end() ) {
+              if ( !result.empty() ) {
+                result += ", ";
+              }
+              result += option.label;
+            }
+          }
+          return result;
+        } else if constexpr ( std::is_same_v<Value, Button> ) {
+          return control.label;
+        } else {
+          return value.description;
+        }
+      },
+      control.content );
+  }
+
+  void control_atoms( std::vector<Atom>& atoms, ControlId id, TextStyle base ) const
+  {
+    // A missing ID is a malformed document reference; map::at reports it directly.
+    const auto& control = *controls_.at( id );
+    const auto* input = std::get_if<TextControl>( &control.content );
+    const bool multiline = input && input->kind == TextControlKind::MultiLine;
+    const auto before = ObjectPosition { id, BoundarySide::Before };
+    const auto after = ObjectPosition { id, BoundarySide::After };
+    const auto style = overlay( base, { .subdued = control.disabled, .warning = control.error.has_value() } );
+    std::wstring_view opening = L"[";
+    std::wstring_view closing = L"]";
+    if ( const auto* checkbox = std::get_if<Checkbox>( &control.content ) ) {
+      opening = checkbox->checked ? L"[x] " : L"[ ] ";
+      closing = L"";
+    } else if ( const auto* radio = std::get_if<RadioButton>( &control.content ) ) {
+      opening = radio->checked ? L"(*) " : L"( ) ";
+      closing = L"";
+    }
+    for ( const auto character : opening ) {
+      atoms.push_back( { .glyph = { .display = std::wstring( 1, character ) },
+                         .source = { before, before },
+                         .style = style,
+                         .target = id } );
+    }
+    const auto display = control_text( control );
+    const auto analysis = text_.analyze( display, multiline, false );
+    for ( const auto& glyph : analysis.graphemes ) {
+      atoms.push_back( { .glyph = glyph,
+                         .source = { ControlTextPosition { id, {}, glyph.bytes.start },
+                                     ControlTextPosition { id, {}, glyph.bytes.end } },
+                         .style = style,
+                         .target = id } );
+    }
+    if ( display.empty() ) {
+      const auto point = ControlTextPosition { id, {}, 0 };
+      atoms.push_back( { .glyph = { .display = L" " }, .source = { point, point }, .style = style, .target = id } );
+    }
+    for ( const auto character : closing ) {
+      atoms.push_back( { .glyph = { .display = std::wstring( 1, character ), .break_after = true },
+                         .source = { after, after },
+                         .style = style,
+                         .target = id } );
+    }
+    // Checkbox/radio controls have no closing bracket but still have an after boundary.
+    atoms.push_back( { .glyph = { .columns = 0, .break_after = true },
+                       .source = { after, after },
+                       .style = style,
+                       .target = id } );
+  }
+
+  std::vector<Atom> inline_atoms( std::span<const Inline> content, TextStyle style ) const
+  {
+    std::vector<Atom> result;
+    std::vector<TextSpan> spans;
+    std::string utf8;
+    const auto flush = [&] {
+      if ( !spans.empty() ) {
+        text_run( result, spans, utf8, false, style );
+        spans.clear();
+        utf8.clear();
+      }
+    };
+    for ( const auto& item : content ) {
+      if ( const auto* text = std::get_if<Text>( &item ) ) {
+        const auto start = utf8.size();
+        utf8 += text->utf8;
+        spans.push_back( { text, { start, utf8.size() } } );
+      } else {
+        flush();
+        control_atoms( result, std::get<ControlPlaceholder>( item ).control, style );
+      }
+    }
+    flush();
+    return result;
+  }
+
+  LayoutData flow( std::span<const Atom> atoms, std::int64_t width, bool wrap ) const
+  {
+    LayoutData result;
+    std::size_t start = 0;
+    std::size_t row = 0;
+    while ( start < atoms.size() ) {
+      std::size_t end = start;
+      std::size_t opportunity = start;
+      std::int64_t column = 0;
+      while ( end < atoms.size() && atoms[end].glyph.kind != TextUnitKind::LineBreak ) {
+        const auto& glyph = atoms[end].glyph;
+        const int cells = glyph.kind == TextUnitKind::Tab ? tab_columns - column % tab_columns : glyph.columns;
+        if ( wrap && column + cells > width && end > start ) {
+          break;
+        }
+        column += cells;
+        ++end;
+        if ( glyph.break_after ) {
+          opportunity = end;
+        }
+      }
+      // Prefer a Unicode line boundary; an overlong word breaks at a grapheme.
+      if ( end < atoms.size() && atoms[end].glyph.kind != TextUnitKind::LineBreak && opportunity > start ) {
+        end = opportunity;
+      }
+      column = 0;
+      for ( auto index = start; index < end; ++index ) {
+        const auto& atom = atoms[index];
+        const bool tab = atom.glyph.kind == TextUnitKind::Tab;
+        const int cells = tab ? tab_columns - column % tab_columns : atom.glyph.columns;
+        result.glyphs.push_back( { .position = { row, column },
+                                   .columns = cells,
+                                   .text = atom.glyph.display,
+                                   .style = atom.style,
+                                   .source = atom.source,
+                                   .target = atom.target,
+                                   .clip_right = wrap ? width : std::numeric_limits<std::int64_t>::max(),
+                                   .decoration = atom.decoration,
+                                   .fill = tab } );
+        column += cells;
+      }
+      result.extent = std::max( result.extent, column );
+      if ( end < atoms.size() && atoms[end].glyph.kind == TextUnitKind::LineBreak ) {
+        const auto& atom = atoms[end++];
+        result.glyphs.push_back( { .position = { row, column },
+                                   .source = atom.source,
+                                   .target = atom.target,
+                                   .clip_right = width,
+                                   .line_break = true } );
+        // The endpoint of a hard LF belongs to the next line, including a
+        // trailing empty line; it must also be reachable by hit testing.
+        auto boundary = anchor( atom.source.end, { row + 1, 0 }, width );
+        boundary.target = atom.target;
+        result.glyphs.push_back( std::move( boundary ) );
+        result.rows = row + 2;
+      } else {
+        result.rows = row + 1;
+      }
+      start = end;
+      ++row;
+    }
+    return result;
+  }
+
+  void horizontal( LayoutData& box, BlockId block, std::int64_t width ) const
+  {
+    const auto scroll = std::ranges::find( scrolls_, block, &HorizontalScroll::block );
+    const auto requested = scroll == scrolls_.end() ? 0 : scroll->columns;
+    const auto maximum = std::max<std::int64_t>( 0, box.extent - width );
+    const auto shift = static_cast<std::int64_t>( std::min<std::uint64_t>( requested, maximum ) );
+    for ( auto& glyph : box.glyphs ) {
+      glyph.position.column -= shift;
+      glyph.line_start -= shift;
+      glyph.clip_left = std::max<std::int64_t>( 0, glyph.clip_left - shift );
+      glyph.clip_right = std::min( width, glyph.clip_right - shift );
+    }
+  }
+
+  LayoutData list_box( const List& list, std::int64_t width, TextStyle style ) const
+  {
+    LayoutData result;
+    std::size_t row = 0;
+    auto number = list.first_number;
+    for ( const auto& item : list.items ) {
+      const auto marker
+        = item.marker.value_or( list.kind == ListKind::Ordered ? std::to_string( number ) + "." : "-" );
+      const auto analysis = text_.analyze( marker, false, false );
+      const auto marker_width
+        = std::accumulate( analysis.graphemes.begin(),
+                           analysis.graphemes.end(),
+                           std::int64_t { 0 },
+                           []( auto total, const auto& glyph ) { return total + glyph.columns; } );
+      // Deep nesting must leave at least one body cell; clipped markers stay decoration.
+      const auto indent = std::min( marker_width + 1, width - 1 );
+      auto body = blocks( item.content, width - indent, style );
+      const auto height = body.rows;
+      append_box( result, std::move( body ), row, indent );
+      std::int64_t column = 0;
+      for ( const auto& glyph : analysis.graphemes ) {
+        result.glyphs.push_back( { .position = { row, column },
+                                   .columns = glyph.columns,
+                                   .text = glyph.display,
+                                   .style = style,
+                                   .clip_right = indent,
+                                   .decoration = true } );
+        column += glyph.columns;
+      }
+      row += height;
+      // Ordered counters can start at the model's largest int64 value.
+      if ( number < std::numeric_limits<std::int64_t>::max() ) {
+        ++number;
+      }
+    }
+    return result;
+  }
+
+  LayoutData table_box( const Table& table, BlockId id, std::int64_t width, TextStyle style ) const
+  {
+    if ( table.columns == 0 ) {
+      return {};
+    }
+    std::vector<std::int64_t> widths( table.columns, 1 );
+    std::vector<std::int64_t> desired( table.columns, 1 );
+    for ( std::size_t row = 0; row < table.rows.size(); ++row ) {
+      for ( const auto& cell : table.rows[row].cells ) {
+        // Spans index the supplied grid. Reject zero/out-of-grid spans before indexing.
+        if ( cell.column >= table.columns || cell.column_span == 0 || cell.row_span == 0
+             || cell.column_span > table.columns - cell.column || cell.row_span > table.rows.size() - row ) {
+          throw std::invalid_argument( "Table cell span lies outside its resolved grid" );
+        }
+        const auto measure = blocks( cell.content, width, style );
+        const auto span = static_cast<std::int64_t>( cell.column_span );
+        const auto preferred = std::max<std::int64_t>( 1, ( measure.extent + span - 1 ) / span );
+        for ( auto column = cell.column; column < cell.column + cell.column_span; ++column ) {
+          desired[column] = std::max( desired[column], preferred );
+          widths[column] = std::max( widths[column], std::min( preferred, minimum_cell_columns ) );
+        }
+      }
+    }
+    const auto gaps = cell_gap * static_cast<std::int64_t>( table.columns - 1 );
+    auto remaining = width - gaps - std::accumulate( widths.begin(), widths.end(), std::int64_t { 0 } );
+    // Grow content-bearing columns toward their preferred width, within the viewport.
+    while ( remaining > 0 ) {
+      bool grew = false;
+      for ( std::size_t column = 0; column < widths.size() && remaining > 0; ++column ) {
+        if ( widths[column] < desired[column] ) {
+          ++widths[column];
+          --remaining;
+          grew = true;
+        }
+      }
+      if ( !grew ) {
+        break;
+      }
+    }
+    struct CellBox
+    {
+      const TableCell* cell;
+      std::size_t row;
+      LayoutData box;
+    };
+    std::vector<CellBox> cells;
+    std::vector<std::size_t> heights( table.rows.size(), 1 );
+    for ( std::size_t row = 0; row < table.rows.size(); ++row ) {
+      for ( const auto& cell : table.rows[row].cells ) {
+        const auto first = widths.begin() + static_cast<std::ptrdiff_t>( cell.column );
+        const auto last = first + static_cast<std::ptrdiff_t>( cell.column_span );
+        const auto cell_width = std::accumulate( first, last, std::int64_t { 0 } )
+                                + cell_gap * static_cast<std::int64_t>( cell.column_span - 1 );
+        auto box = blocks( cell.content, cell_width, overlay( style, { .strong = cell.header } ) );
+        const auto begin = heights.begin() + static_cast<std::ptrdiff_t>( row );
+        const auto end = begin + static_cast<std::ptrdiff_t>( cell.row_span );
+        const auto height = std::accumulate( begin, end, std::size_t { 0 } );
+        if ( box.rows > height ) {
+          heights[row + cell.row_span - 1] += box.rows - height;
+        }
+        cells.push_back( { &cell, row, std::move( box ) } );
+      }
+    }
+    std::vector<std::size_t> row_offsets( heights.size() + 1, 0 );
+    std::partial_sum( heights.begin(), heights.end(), row_offsets.begin() + 1 );
+    std::vector<std::int64_t> column_offsets( widths.size(), 0 );
+    for ( std::size_t column = 1; column < widths.size(); ++column ) {
+      column_offsets[column] = column_offsets[column - 1] + widths[column - 1] + cell_gap;
+    }
+    LayoutData result;
+    result.extent = std::accumulate( widths.begin(), widths.end(), gaps );
+    result.rows = std::max<std::size_t>( 1, row_offsets.back() );
+    for ( auto& cell : cells ) {
+      const auto column = column_offsets[cell.cell->column];
+      append_box( result, std::move( cell.box ), row_offsets[cell.row], column );
+      if ( cell.cell->column != 0 ) {
+        for ( auto row = row_offsets[cell.row]; row < row_offsets[cell.row + cell.cell->row_span]; ++row ) {
+          result.glyphs.push_back( { .position = { row, column - 2 },
+                                     .columns = 1,
+                                     .text = L"|",
+                                     .style = { .subdued = true },
+                                     .clip_right = result.extent,
+                                     .decoration = true } );
+        }
+      }
+    }
+    // A nested preformatted block scrolls inside its cell; its natural extent
+    // must not enlarge the enclosing table's horizontal scroll range.
+    result.extent = std::accumulate( widths.begin(), widths.end(), gaps );
+    horizontal( result, id, width );
+    return result;
+  }
+
+  LayoutData block_box( const Block& block, std::int64_t width, TextStyle style ) const
+  {
+    auto result = std::visit(
+      [this, &block, width, style]( const auto& value ) -> LayoutData {
+        using Value = std::decay_t<decltype( value )>;
+        if constexpr ( std::is_same_v<Value, Paragraph> ) {
+          return flow( inline_atoms( value.content, style ), width, true );
+        } else if constexpr ( std::is_same_v<Value, Heading> ) {
+          return flow( inline_atoms( value.content, overlay( style, { .strong = true } ) ), width, true );
+        } else if constexpr ( std::is_same_v<Value, Preformatted> || std::is_same_v<Value, Alternative> ) {
+          const Text& leaf = [&]() -> const Text& {
+            if constexpr ( std::is_same_v<Value, Preformatted> ) {
+              return value.content;
+            } else {
+              return value.description;
+            }
+          }();
+          const TextSpan span { &leaf, { 0, leaf.utf8.size() } };
+          std::vector<Atom> atoms;
+          constexpr bool preformatted = std::is_same_v<Value, Preformatted>;
+          text_run(
+            atoms, std::span( &span, 1 ), leaf.utf8, preformatted, overlay( style, { .code = preformatted } ) );
+          auto box = flow( atoms, width, !preformatted );
+          if constexpr ( preformatted ) {
+            horizontal( box, block.id, width );
+          }
+          return box;
+        } else if constexpr ( std::is_same_v<Value, List> ) {
+          return list_box( value, width, style );
+        } else if constexpr ( std::is_same_v<Value, Table> ) {
+          return table_box( value, block.id, width, style );
+        } else if constexpr ( std::is_same_v<Value, ControlPlaceholder> ) {
+          std::vector<Atom> atoms;
+          control_atoms( atoms, value.control, style );
+          return flow( atoms, width, true );
+        } else {
+          LayoutData box;
+          box.extent = width;
+          for ( std::int64_t column = 0; column < width; ++column ) {
+            box.glyphs.push_back( { .position = { 0, column },
+                                    .columns = 1,
+                                    .text = L"-",
+                                    .style = { .subdued = true },
+                                    .clip_right = width,
+                                    .decoration = true } );
+          }
+          return box;
+        }
+      },
+      block.content );
+    const bool has_text
+      = std::ranges::any_of( result.glyphs, []( const auto& glyph ) { return !glyph.decoration; } );
+    auto before = anchor( ObjectPosition { block.id, BoundarySide::Before }, {}, width );
+    auto after = anchor( ObjectPosition { block.id, BoundarySide::After },
+                         { result.rows - 1, std::min( result.extent, width ) },
+                         width );
+    before.boundary_only = has_text;
+    after.boundary_only = has_text;
+    result.glyphs.push_back( std::move( before ) );
+    result.glyphs.push_back( std::move( after ) );
+    return result;
+  }
+
+  const DocumentData& document_;
+  const TextService& text_;
+  std::span<const HorizontalScroll> scrolls_;
+  std::map<ControlId, const Control*> controls_ {};
+};
+
+LayoutPoint end_point( const LayoutGlyph& glyph )
+{
+  // Object decorations and empty fields do not create a second text boundary.
+  if ( glyph.source.start == glyph.source.end ) {
+    return glyph.position;
+  }
+  if ( glyph.line_break ) {
+    return { glyph.position.row + 1, glyph.line_start };
+  }
+  return { glyph.position.row, glyph.position.column + glyph.columns };
+}
+
+} // namespace
+
+DocumentLayout::DocumentLayout( const Document& document,
+                                const TextService& text,
+                                int columns,
+                                std::span<const HorizontalScroll> scrolls )
+  : columns_( std::max( 1, columns ) )
+  , data_( LayoutBuilder( document.data(), text, scrolls ).blocks( document.data().blocks, columns_ ) )
+{
+  // An empty document still has a location for its cursor/viewport anchor.
+  if ( data_.glyphs.empty() ) {
+    data_.glyphs.push_back( anchor( DocumentStart {}, {}, columns_ ) );
+  }
+}
+
+int DocumentLayout::columns() const
+{ return columns_; }
+std::size_t DocumentLayout::rows() const
+{ return data_.rows; }
+
+std::optional<LayoutPoint> DocumentLayout::locate( const DisplayPosition& position ) const
+{
+  if ( std::holds_alternative<DocumentStart>( position.point ) ) {
+    return LayoutPoint {};
+  }
+  std::optional<LayoutPoint> fallback;
+  for ( const auto& glyph : data_.glyphs ) {
+    if ( glyph.decoration ) {
+      continue;
+    }
+    if ( position.point == glyph.source.start ) {
+      if ( position.affinity == WrapAffinity::NextLine ) {
+        return glyph.position;
+      }
+      fallback = glyph.position;
+    }
+    if ( position.point == glyph.source.end ) {
+      if ( position.affinity == WrapAffinity::PreviousLine ) {
+        return end_point( glyph );
+      }
+      fallback = end_point( glyph );
+    }
+  }
+  return fallback;
+}
+
+std::optional<LayoutHit> DocumentLayout::hit( LayoutPoint point ) const
+{
+  const LayoutGlyph* nearest = nullptr;
+  auto distance
+    = std::tuple { std::numeric_limits<std::size_t>::max(), std::numeric_limits<std::int64_t>::max(), true };
+  for ( const auto& glyph : data_.glyphs ) {
+    // Decorations and partially clipped wide glyphs have no independent text hit.
+    if ( glyph.decoration || glyph.boundary_only ) {
+      continue;
+    }
+    const auto left = std::max( glyph.position.column, glyph.clip_left );
+    const auto edge = std::min( glyph.position.column + glyph.columns, glyph.clip_right );
+    // Tab blanks may be clipped individually; a wide glyph remains indivisible.
+    if ( ( glyph.fill && left >= edge )
+         || ( !glyph.fill
+              && ( glyph.position.column < glyph.clip_left
+                   || glyph.position.column + glyph.columns > glyph.clip_right ) ) ) {
+      continue;
+    }
+    const auto row_distance
+      = glyph.position.row > point.row ? glyph.position.row - point.row : point.row - glyph.position.row;
+    const auto right = std::max( left, edge - 1 );
+    const auto column_distance = std::max( { left - point.column, point.column - right, std::int64_t { 0 } } );
+    const auto candidate = std::tuple { row_distance, column_distance, glyph.columns == 0 };
+    if ( candidate < distance ) {
+      nearest = &glyph;
+      distance = candidate;
+    }
+  }
+  if ( !nearest ) {
+    return std::nullopt;
+  }
+  const bool after = !nearest->line_break && point.column >= nearest->position.column + nearest->columns;
+  return LayoutHit { .position = { after ? nearest->source.end : nearest->source.start,
+                                   after ? WrapAffinity::PreviousLine : WrapAffinity::NextLine },
+                     .unit = nearest->source,
+                     .target = nearest->target };
+}
+
+void DocumentLayout::append_frame( Frame& frame,
+                                   std::size_t first_row,
+                                   CellPoint origin,
+                                   ScreenSize viewport ) const
+{
+  for ( const auto& glyph : data_.glyphs ) {
+    if ( glyph.text.empty() || glyph.position.row < first_row
+         || glyph.position.row - first_row >= static_cast<std::size_t>( std::max( 0, viewport.rows ) ) ) {
+      continue;
+    }
+    const auto left = std::max<std::int64_t>( 0, glyph.clip_left );
+    const auto right = std::min<std::int64_t>( viewport.columns, glyph.clip_right );
+    const auto row = origin.row + static_cast<int>( glyph.position.row - first_row );
+    if ( glyph.fill ) {
+      // Expanded tabs are many blank cells but keep a single source range/hit unit.
+      for ( auto column = std::max( left, glyph.position.column );
+            column < std::min( right, glyph.position.column + glyph.columns );
+            ++column ) {
+        frame.glyphs.push_back(
+          { .position = { row, origin.column + static_cast<int>( column ) }, .text = L" ", .style = glyph.style } );
+      }
+    } else if ( glyph.position.column >= left && glyph.position.column + glyph.columns <= right ) {
+      frame.glyphs.push_back( { .position = { row, origin.column + static_cast<int>( glyph.position.column ) },
+                                .width = glyph.columns,
+                                .text = glyph.text,
+                                .style = glyph.style } );
+    }
+  }
+}
+
+} // namespace ricochet::tui::detail
diff --git a/src/tui/layout.hh b/src/tui/layout.hh
new file mode 100644
index 0000000..5feb0cd
--- /dev/null
+++ b/src/tui/layout.hh
@@ -0,0 +1,98 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "paint.hh"
+#include "ricochet/tui/view.hh"
+#include "text.hh"
+
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <variant>
+#include <vector>
+
+namespace ricochet::tui::detail {
+
+using HitTarget = std::variant<LinkId, ControlId>;
+
+struct LayoutPoint
+{
+  std::size_t row { 0 };
+  std::int64_t column { 0 };
+};
+
+struct LayoutHit
+{
+  DisplayPosition position {};
+  DocumentRange unit {};
+  std::optional<HitTarget> target {};
+};
+
+struct LayoutGlyph
+{
+  LayoutPoint position {};
+  int columns { 0 };
+  std::wstring text {};
+  TextStyle style {};
+  DocumentRange source {};
+  std::optional<HitTarget> target {};
+  // Clip bounds are in document-layout columns and also constrain hit testing.
+  std::int64_t clip_left { 0 };
+  std::int64_t clip_right { 0 };
+  // Structural boundaries locate anchors but do not displace nearby text hits.
+  bool boundary_only { false };
+  std::int64_t line_start { 0 };
+  bool decoration { false };
+  bool line_break { false };
+  bool fill { false };
+};
+
+struct LayoutData
+{
+  // Reading order, including table cells in row/cell order; not screen order.
+  std::vector<LayoutGlyph> glyphs {};
+  std::size_t rows { 1 };
+  std::int64_t extent { 0 };
+};
+
+// A derived snapshot for one Document + initial control values + width/scrolls.
+// Editing will supply a separate draft snapshot; this stage uses revision zero.
+// No ncurses headers, terminal objects or business-module dependencies.
+class DocumentLayout
+{
+public:
+  DocumentLayout( const Document& document,
+                  const TextService& text,
+                  int columns,
+                  std::span<const HorizontalScroll> scrolls );
+
+  int columns() const;
+  std::size_t rows() const;
+  std::optional<LayoutPoint> locate( const DisplayPosition& position ) const;
+  std::optional<LayoutHit> hit( LayoutPoint point ) const;
+  void append_frame( Frame& frame, std::size_t first_row, CellPoint origin, ScreenSize viewport ) const;
+
+private:
+  int columns_;
+  LayoutData data_;
+};
+
+} // namespace ricochet::tui::detail
diff --git a/src/tui/paint.hh b/src/tui/paint.hh
new file mode 100644
index 0000000..549718d
--- /dev/null
+++ b/src/tui/paint.hh
@@ -0,0 +1,46 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "ricochet/tui/document.hh"
+#include "ricochet/tui/input.hh"
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace ricochet::tui::detail {
+
+// Layout supplies one printable spacing character and its combining marks per
+// glyph, with a measured width. Raw document text never goes directly to curses.
+struct PaintGlyph
+{
+  CellPoint position {};
+  int width { 1 };
+  std::wstring text {};
+  TextStyle style {};
+};
+
+struct Frame
+{
+  std::vector<PaintGlyph> glyphs {};
+  std::optional<CellPoint> cursor {};
+};
+
+} // namespace ricochet::tui::detail
diff --git a/src/tui/screen.cc b/src/tui/screen.cc
index 43582cd..34a8542 100644
--- a/src/tui/screen.cc
+++ b/src/tui/screen.cc
@@ -574,6 +574,9 @@ Screen::Screen( std::FILE& input, std::FILE& output, TerminalOptions options )
 
 Screen::~Screen() = default;
 
+std::size_t Screen::glyph_capacity()
+{ return CCHARW_MAX - 1; }
+
 ScreenSize Screen::size() const
 { return impl_->size(); }
 
diff --git a/src/tui/screen.hh b/src/tui/screen.hh
index f0df278..9677eb0 100644
--- a/src/tui/screen.hh
+++ b/src/tui/screen.hh
@@ -18,7 +18,7 @@
 
 #pragma once
 
-#include "ricochet/tui/document.hh"
+#include "paint.hh"
 #include "ricochet/tui/session.hh"
 
 #include <chrono>
@@ -26,27 +26,10 @@
 #include <cstdio>
 #include <memory>
 #include <optional>
-#include <string>
 #include <vector>
 
 namespace ricochet::tui::detail {
 
-// Layout supplies one printable spacing character and its combining marks per
-// glyph, with a measured width. Raw document text never goes directly to curses.
-struct PaintGlyph
-{
-  CellPoint position {};
-  int width { 1 };
-  std::wstring text {};
-  TextStyle style {};
-};
-
-struct Frame
-{
-  std::vector<PaintGlyph> glyphs {};
-  std::optional<CellPoint> cursor {};
-};
-
 struct InputBatch
 {
   std::vector<InputEvent> events {};
@@ -62,6 +45,7 @@ public:
   Screen& operator=( const Screen& ) = delete;
 
   ScreenSize size() const;
+  static std::size_t glyph_capacity();
   TerminalCapabilities capabilities() const;
   InputBatch read_events( std::size_t limit );
   // Wait only polls descriptors; wgetch remains the sole terminal reader.
diff --git a/src/tui/session.cc b/src/tui/session.cc
index 38d501e..a596c87 100644
--- a/src/tui/session.cc
+++ b/src/tui/session.cc
@@ -18,6 +18,7 @@
 
 #include "ricochet/tui/session.hh"
 
+#include "layout.hh"
 #include "mailbox.hh"
 #include "screen.hh"
 
@@ -36,12 +37,13 @@ struct TabState
   TabInfo info {};
   std::optional<RequestId> navigation {};
   std::optional<Document> document {};
+  std::optional<detail::DocumentLayout> layout {};
   std::optional<ViewSnapshot> view {};
   std::optional<ActionFailed> failure {};
 };
 
 // Only fixed ASCII chrome uses this helper. Document text goes through the
-// forthcoming Unicode layout service, not a second ad-hoc text renderer.
+// Unicode text service and document layout.
 void append_chrome( detail::Frame& frame, CellPoint start, std::wstring_view text, TextStyle style = {} )
 {
   int column = start.column;
@@ -147,6 +149,7 @@ public:
     tab.info.display_url = update.document.data().metadata.display_url;
     tab.info.loading_task.reset();
     tab.document = std::move( update.document );
+    tab.layout.reset();
     tab.failure.reset();
     dirty_ = true;
   }
@@ -252,6 +255,26 @@ public:
     return batch.consumed || !batch.events.empty();
   }
 
+  void draw_document( TabState& tab, detail::Frame& frame, ScreenSize dimensions )
+  {
+    // The cached layout belongs to the committed snapshot and terminal width.
+    // CommitDocument drops it; resizing rebuilds it from logical view anchors.
+    if ( !tab.layout || tab.layout->columns() != dimensions.columns ) {
+      tab.layout.emplace( *tab.document, text_, dimensions.columns, tab.view->horizontal_scroll );
+    }
+    const auto& layout = *tab.layout;
+    const auto anchor = layout.locate( tab.view->viewport_anchor ).value_or( detail::LayoutPoint {} );
+    const auto body_rows = dimensions.rows - 2;
+    const auto first_row = std::min( anchor.row, layout.rows() - 1 );
+    layout.append_frame( frame, first_row, { 1, 0 }, { body_rows, dimensions.columns } );
+    const auto cursor = layout.locate( tab.view->cursor );
+    if ( cursor && cursor->row >= first_row && cursor->row - first_row < static_cast<std::size_t>( body_rows )
+         && cursor->column >= 0 && cursor->column < dimensions.columns ) {
+      frame.cursor
+        = CellPoint { 1 + static_cast<int>( cursor->row - first_row ), static_cast<int>( cursor->column ) };
+    }
+  }
+
   void draw()
   {
     detail::Frame frame;
@@ -271,6 +294,9 @@ public:
       if ( active_ ) {
         const auto found = tabs_.find( *active_ );
         if ( found != tabs_.end() ) {
+          if ( found->second.document ) {
+            draw_document( found->second, frame, dimensions );
+          }
           if ( found->second.info.loading_task ) {
             status = L"Loading | q quit";
           }
@@ -327,6 +353,7 @@ public:
   std::shared_ptr<detail::Mailbox> mailbox_;
   std::unique_ptr<detail::Screen> screen_;
   TerminalCapabilities capabilities_;
+  detail::TextService text_ { detail::Screen::glyph_capacity() };
   std::map<TabId, TabState> tabs_ {};
   std::vector<TabId> tab_order_ {};
   std::optional<TabId> active_ {};
diff --git a/src/tui/text.cc b/src/tui/text.cc
new file mode 100644
index 0000000..14f0e09
--- /dev/null
+++ b/src/tui/text.cc
@@ -0,0 +1,138 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "text.hh"
+
+#include <climits>
+#include <cwchar>
+#include <memory>
+#include <stdexcept>
+#include <unicode/ubrk.h>
+#include <unicode/uchar.h>
+#include <unicode/utext.h>
+#include <utility>
+
+namespace ricochet::tui::detail {
+namespace {
+
+using UnicodeText = std::unique_ptr<UText, decltype( &utext_close )>;
+using Breaks = std::unique_ptr<UBreakIterator, decltype( &ubrk_close )>;
+
+Breaks breaks_for( UBreakIteratorType type, UText& text )
+{
+  UErrorCode status = U_ZERO_ERROR;
+  Breaks breaks( ubrk_open( type, "root", nullptr, 0, &status ), &ubrk_close );
+  if ( U_FAILURE( status ) ) {
+    throw std::runtime_error( u_errorName( status ) );
+  }
+  ubrk_setUText( breaks.get(), &text, &status );
+  if ( U_FAILURE( status ) ) {
+    throw std::runtime_error( u_errorName( status ) );
+  }
+  return breaks;
+}
+
+WordKind word_kind( UChar32 codepoint )
+{
+  if ( u_isUWhiteSpace( codepoint ) ) {
+    return WordKind::Space;
+  }
+  if ( u_hasBinaryProperty( codepoint, UCHAR_IDEOGRAPHIC ) ) {
+    return WordKind::Ideograph;
+  }
+  if ( codepoint == '_' || u_isalnum( codepoint ) ) {
+    return WordKind::Word;
+  }
+  return WordKind::Punctuation;
+}
+
+} // namespace
+
+TextService::TextService( std::size_t glyph_capacity ) : glyph_capacity_( glyph_capacity ) {}
+
+TextAnalysis TextService::analyze( std::string_view utf8, bool line_breaks, bool tabs ) const
+{
+  // ICU BreakIterator exposes int32_t native offsets even with a UTF-8 UText.
+  if ( utf8.size() > INT32_MAX ) {
+    throw std::length_error( "Text exceeds ICU break-iterator offset capacity" );
+  }
+  UErrorCode status = U_ZERO_ERROR;
+  UnicodeText text(
+    utext_openUTF8( nullptr, utf8.empty() ? "" : utf8.data(), static_cast<int64_t>( utf8.size() ), &status ),
+    &utext_close );
+  if ( U_FAILURE( status ) ) {
+    throw std::runtime_error( u_errorName( status ) );
+  }
+  auto characters = breaks_for( UBRK_CHARACTER, *text );
+  auto lines = breaks_for( UBRK_LINE, *text );
+  TextAnalysis result;
+  int32_t begin = ubrk_first( characters.get() );
+  int32_t line_end = ubrk_next( lines.get() );
+  WordKind previous = WordKind::Space;
+  for ( int32_t end = ubrk_next( characters.get() ); end != UBRK_DONE;
+        begin = end, end = ubrk_next( characters.get() ) ) {
+    while ( line_end != UBRK_DONE && line_end < end ) {
+      line_end = ubrk_next( lines.get() );
+    }
+    Grapheme glyph { .bytes = { static_cast<std::size_t>( begin ), static_cast<std::size_t>( end ) },
+                     .break_after = line_end == end };
+    utext_setNativeIndex( text.get(), begin );
+    const auto first = utext_next32( text.get() );
+    glyph.word = word_kind( first );
+    const auto source = utf8.substr( glyph.bytes.start, glyph.bytes.end - glyph.bytes.start );
+    if ( line_breaks && ( source == "\n" || source == "\r\n" ) ) {
+      glyph.kind = TextUnitKind::LineBreak;
+      glyph.columns = 0;
+    } else if ( tabs && source == "\t" ) {
+      glyph.kind = TextUnitKind::Tab;
+      glyph.display = L" ";
+    } else {
+      const int width = ::wcwidth( static_cast<wchar_t>( first ) );
+      glyph.display.push_back( static_cast<wchar_t>( first ) );
+      bool representable = width > 0 && !u_hasBinaryProperty( first, UCHAR_DEFAULT_IGNORABLE_CODE_POINT )
+                           && !u_hasBinaryProperty( first, UCHAR_EMOJI_PRESENTATION );
+      while ( utext_getNativeIndex( text.get() ) < end ) {
+        const auto codepoint = utext_next32( text.get() );
+        glyph.display.push_back( static_cast<wchar_t>( codepoint ) );
+        // ncurses accepts one spacing character followed by nonspacing marks.
+        // Joiners, selectors and extra spacing characters use one visible fallback.
+        representable = representable && ::wcwidth( static_cast<wchar_t>( codepoint ) ) == 0
+                        && u_charType( codepoint ) == U_NON_SPACING_MARK
+                        && !u_hasBinaryProperty( codepoint, UCHAR_DEFAULT_IGNORABLE_CODE_POINT );
+      }
+      if ( !representable || glyph.display.size() > glyph_capacity_ ) {
+        glyph.display = L"?";
+        glyph.columns = 1;
+      } else {
+        glyph.columns = width;
+      }
+    }
+    if ( glyph.word != WordKind::Space ) {
+      if ( glyph.word == previous && glyph.word != WordKind::Ideograph ) {
+        result.words.back().end = glyph.bytes.end;
+      } else {
+        result.words.push_back( glyph.bytes );
+      }
+    }
+    previous = glyph.word;
+    result.graphemes.push_back( std::move( glyph ) );
+  }
+  return result;
+}
+
+} // namespace ricochet::tui::detail
diff --git a/src/tui/text.hh b/src/tui/text.hh
new file mode 100644
index 0000000..c2d4af9
--- /dev/null
+++ b/src/tui/text.hh
@@ -0,0 +1,75 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "ricochet/tui/position.hh"
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace ricochet::tui::detail {
+
+enum class TextUnitKind : std::uint8_t
+{
+  Glyph,
+  LineBreak,
+  Tab
+};
+enum class WordKind : std::uint8_t
+{
+  Space,
+  Word,
+  Ideograph,
+  Punctuation
+};
+
+struct Grapheme
+{
+  ByteRange bytes {};
+  std::wstring display {};
+  int columns { 1 };
+  TextUnitKind kind { TextUnitKind::Glyph };
+  WordKind word { WordKind::Punctuation };
+  bool break_after { false };
+};
+
+struct TextAnalysis
+{
+  std::vector<Grapheme> graphemes {};
+  // Vim-style reading units: letters/numbers/underscore, punctuation runs,
+  // individual ideographs. Whitespace is excluded; offsets remain UTF-8 bytes.
+  std::vector<ByteRange> words {};
+};
+
+// Called on the UI thread in the same UTF-8 locale as Screen. ICU owns Unicode
+// segmentation/properties; POSIX wcwidth owns terminal widths. No curses types.
+class TextService
+{
+public:
+  explicit TextService( std::size_t glyph_capacity );
+  TextAnalysis analyze( std::string_view utf8, bool line_breaks, bool tabs ) const;
+
+private:
+  std::size_t glyph_capacity_;
+};
+
+} // namespace ricochet::tui::detail