zaniah 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f0262e29ecc34754628eac6e0e6b2474697686c0f971d4f1d1ca633783b0759
-  data.tar.gz: 433ff5ae3813cd6dd0569806c773910e46c321978b0e590bfa3768e67b51e97d
+  metadata.gz: f6787d1edc51a6a692859fe62834270cfa2339ade8b00e596e8861632eb59913
+  data.tar.gz: 7407abf9f7a64c80fc307843ffeadd9d130cfb45a12673a85f6cbedf2710a3e4
 SHA512:
-  metadata.gz: e5c369c73ee00cc45d0e6fd81fa5ece2f29b81e920dbcd98f7e0e99dd7f4f8eb003b6c7375b8f1c371273049c4ce64832b17919bb640fdf47ea00ecef6e3803f
-  data.tar.gz: 240f51e2f1b7dde1acda418cbfd8bf2dc7789ee1634729bd055e8b48b93189c954aec844bda2a3fe96ac559b1d676af0eba1c7fa42458f274ea9ee853f5f5b78
+  metadata.gz: 35cdfc811f06f704d21202e60029c2869eb5b01698c4e52cde3ce2b7c0e45eaa0c6c5a60ec46e9e9f4e15fd2e1b7f88a75b71b9ec829423540259238739cf468
+  data.tar.gz: beaae799ef7227cf30d354819b4d896ee1957666c1617d4a43a15fd8d0112180b0dcf74dadf930c6df8376eaa0045663c83400cca2f6bf019142ab9cb2af0592

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.4.0 — 2026-09-15
+
+- Add inline and block text overlays with wrapping-aware layout, hit testing, and row-local relayout.
+
 ## 0.3.0 — 2026-09-14
 
 - Improve large flex layouts, GPU scene submission, and software-rendered gradients for smoother frames.

data/README.md

@@ -37,7 +37,7 @@ the drawing surface beneath the editor.
 - Gradients, transforms, paths, SVG, shadows, clipping, and GPU glyph atlases
 - Retained element state, subscriptions, and non-blocking background tasks
 - Scroll views, inertial input, and uniform or variable-height virtual lists
-- OpenType shaping, font fallback, Japanese wrapping, selection, editing, and IME
+- OpenType shaping, font fallback, Japanese wrapping, text overlays, selection, editing, and IME
 - Themes, state styles, keyed animation, springs, and reduced-motion support
 - Opt-in controls, overlays, tables, trees, charts, forms, and terminal fallbacks
 - Spatial keyboard focus and a diffed cross-platform accessibility tree

data/docs/adr/010-text-overlay-layout.md

@@ -0,0 +1,24 @@
+# ADR 010: Model text overlays as layout gaps
+
+- Status: Accepted
+- Date: 2026-09-15
+- Decision deadline: before text overlay implementation
+
+## Context
+
+Inline hints and block annotations must affect wrapping and pointer mapping without
+becoming editable text. Absolutely painting them over an ordinary paragraph would
+leave wrapping, carets, and selection unaware of their size.
+
+## Decision
+
+Represent inline overlays as measured gaps at UTF-8 grapheme boundaries and block
+overlays as measured rows around logical source lines. Cache the wrapped paragraph
+for each explicit source line so changing one inline overlay only reshapes that row.
+Keep overlay elements as ordinary positioned children for painting and input.
+
+## Consequences
+
+Text offsets remain unchanged, overlay children stay clickable, and coordinate
+conversion accounts for every gap. Layout changes after an overlay row still shift
+later vertical positions, but those rows reuse their shaped and wrapped paragraphs.

data/docs/text.md

@@ -123,3 +123,22 @@ Offsets are UTF-8 byte offsets and edits must land on extended grapheme-cluster
 boundaries. The string-backed buffer is intended for ordinary fields and
 documents up to tens of thousands of characters; a piece table is deliberately
 outside the current scope.
+
+## Inline and block overlays
+
+Attach non-editable UI elements to text without inserting bytes into the source:
+
+```ruby
+hint = Zaniah::Div.new.w(72).h(20).bg("#334155").on_click { show_type_help }
+code_lens = Zaniah::Div.new.h(20).child(Zaniah::Text.new("3 references"))
+
+text = Zaniah::Text.new(source, wrap: :word)
+  .inline_overlay(offset: 42, element: hint, align: :after)
+  .block_overlay(line: 10, element: code_lens, position: :above, height: 20)
+```
+
+Inline overlay width participates in wrapping. `align: :after` keeps the logical
+caret before the overlay; `:before` keeps it after the overlay. Block line numbers
+are zero-based. Overlay elements receive pointer events but are never part of text
+selection. Use `hit_test(point)` and `offset_to_point(offset)` for local display ↔
+UTF-8 byte-offset conversion, and `remove_overlay(element)` to detach an overlay.

data/lib/zaniah/layout/engine.rb

@@ -125,6 +125,16 @@ module Zaniah
       end
 
       def layout(node, x, y, width, height, available_w, available_h, clamp = true)
+        if node.children.empty?
+          if node.style[:display] == :none
+            node.bounds = Bounds.new(x, y, 0, 0)
+          else
+            width = clamp_size(node, :width, width, available_w) if clamp
+            height = clamp_size(node, :height, height, available_h) if clamp
+            node.bounds = Bounds.new(x, y, width, height)
+          end
+          return
+        end
         key = [node.generation, x, y, width, height, available_w, available_h]
         return if node.cache[key]
         if node.style[:display] == :none
@@ -137,11 +147,6 @@ module Zaniah
           height = clamp_size(node, :height, height, available_h)
         end
         node.bounds = Bounds.new(x, y, width, height)
-        if node.children.empty?
-          node.cache.shift if node.cache.length >= 5
-          node.cache[key] = true
-          return
-        end
         content = content_bounds(node)
         flow, absolute = node.children.partition { |child| child.style[:position] != :absolute }
         s = node.style

data/lib/zaniah/text.rb

@@ -2,6 +2,9 @@
 
 module Zaniah
   class Text < Element
+    InlineOverlay = Data.define(:element, :offset, :align)
+    BlockOverlay = Data.define(:element, :line, :position, :height)
+
     attr_reader :text, :font_size, :selection, :buffer
 
     def initialize(text, size: 14, color: "#ddd", font: nil, wrap: :none,
@@ -10,6 +13,7 @@ module Zaniah
       @text, @font_size, @color, @font = text, size, color, font
       @wrap, @line_height, @letter_spacing = wrap, line_height, letter_spacing
       @text_align, @ellipsis, @kinsoku = align, ellipsis, kinsoku
+      @inline_overlays, @block_overlays, @row_layout_cache = [], [], []
     end
 
     def measured(&block) = (@measure = block; self)
@@ -17,6 +21,55 @@ module Zaniah
     def placeholder(text, color: nil) = (@placeholder = text.to_s; @placeholder_color = color; self)
     def secure(value = true) = (@secure = !!value; self)
     def text_color = @color
+
+    def inline_overlay(offset:, element:, align: :after)
+      offset = Integer(offset)
+      raise ArgumentError, "offset is outside the text" unless offset.between?(0, @text.bytesize)
+      raise ArgumentError, "offset splits a grapheme cluster" unless Unicode.grapheme_boundary?(@text, offset)
+      raise ArgumentError, "align must be before or after" unless %i[before after].include?(align)
+      add_overlay(element)
+      @inline_overlays << InlineOverlay.new(element, offset, align)
+      @row_layout_cache[line_at(@text, offset)] = nil
+      self
+    end
+
+    def block_overlay(line:, element:, position: :above, height:)
+      line = Integer(line)
+      height = Float(height)
+      raise ArgumentError, "line is outside the text" unless line.between?(0, @text.count("\n"))
+      raise ArgumentError, "position must be above or below" unless %i[above below].include?(position)
+      raise ArgumentError, "height must be finite and positive" unless height.finite? && height.positive?
+      add_overlay(element)
+      @block_overlays << BlockOverlay.new(element, line, position, height)
+      self
+    end
+
+    def remove_overlay(element)
+      removed = @inline_overlays.select { |overlay| overlay.element.equal?(element) }
+      @inline_overlays.reject! { |overlay| overlay.element.equal?(element) }
+      @block_overlays.reject! { |overlay| overlay.element.equal?(element) }
+      removed.each { |overlay| @row_layout_cache[line_at(@text, overlay.offset)] = nil }
+      if @children.delete(element)
+        element.send(:parent=, nil) if element.respond_to?(:parent=, true)
+      end
+      self
+    end
+
+    def hit_test(point)
+      raise Error, "text must be laid out before coordinate conversion" unless @paragraph || @line
+      offset = @paragraph ? @paragraph.hit_test(point) : @line.index_for_x(point.x)
+      display_to_logical_offset(offset)
+    end
+
+    def offset_to_point(offset)
+      raise Error, "text must be laid out before coordinate conversion" unless @paragraph || @line
+      offset = Integer(offset)
+      raise RangeError, "offset is outside the text" unless offset.between?(0, @text.bytesize)
+      raise ArgumentError, "offset splits a grapheme cluster" unless Unicode.grapheme_boundary?(@text, offset)
+      display_offset = logical_to_display_offset(offset)
+      @paragraph ? @paragraph.offset_to_point(display_offset) : Point.new(@line.x_for_index(display_offset), 0)
+    end
+
     def selection=(value)
       raise ArgumentError, "expected a TextSelection" unless value.is_a?(TextSelection)
       raise ArgumentError, "selection is outside the text" unless value.anchor <= @text.bytesize && value.head <= @text.bytesize
@@ -53,25 +106,51 @@ module Zaniah
     def request_layout(cx)
       @text = @buffer.to_s if @buffer
       value = display_text
-      @paragraph = nil
-      @line = cx.text_system ? cx.text_system.layout_line(value, font: @font, size: @font_size) : approximate_line(value)
+      @paragraph, @line = nil, nil
+      overlays = !@inline_overlays.empty? || !@block_overlays.empty?
+      unless overlays
+        @line = cx.text_system ? cx.text_system.layout_line(value, font: @font, size: @font_size) : approximate_line(value)
+      end
       line_height = @line ? @line.ascent + @line.descent : 0
-      unless @wrap == :none && !@ellipsis
+      unless @wrap == :none && !@ellipsis && !overlays
         available = @style[:width]
         available = available.resolve(cx.window.content_size.width) if available.is_a?(Length)
         available = cx.window.content_size.width unless available.is_a?(Numeric)
-        @paragraph = paragraph(value, available, cx.text_system)
+        @paragraph = overlays ? nil : paragraph(value, available, cx.text_system)
+      end
+      overlay_nodes = overlay_elements.to_h do |element|
+        node = element.request_layout(cx)
+        raise Error, "overlay element must return a layout node" unless node.is_a?(Layout::Node)
+        [element.object_id, node]
       end
-      measurement = @measure || if @wrap == :none && !@ellipsis
+      overlay_styles = overlay_nodes.transform_values(&:style)
+      if overlays
+        @paragraph = overlay_paragraph(value, available, cx.text_system, overlay_nodes, overlay_styles)
+        position_overlay_nodes(overlay_nodes, overlay_styles)
+      end
+      measurement = if @measure
+        lambda do |width, height|
+          if overlays
+            @paragraph = overlay_paragraph(value, effective_width(width), cx.text_system, overlay_nodes, overlay_styles)
+            position_overlay_nodes(overlay_nodes, overlay_styles)
+          end
+          @measure.call(width, height)
+        end
+      elsif @wrap == :none && !@ellipsis && !overlays
         ->(_width, _height) { [@line ? @line.width : value.length * @font_size * 0.6, [@font_size * 1.4, line_height].max, @font_size] }
       else
         lambda do |width, _height|
-          limit = width.finite? ? [width, 0].max : Float::INFINITY
-          @paragraph = paragraph(value, limit, cx.text_system)
+          limit = effective_width(width)
+          @paragraph = if overlays
+            overlay_paragraph(value, limit, cx.text_system, overlay_nodes, overlay_styles)
+          else
+            paragraph(value, limit, cx.text_system)
+          end
+          position_overlay_nodes(overlay_nodes, overlay_styles) if overlays
           [@paragraph.width, @paragraph.height, @paragraph.lines.first&.layout&.ascent || @font_size]
         end
       end
-      @layout_node = Layout::Node.new(style: @style, measure: measurement)
+      @layout_node = Layout::Node.new(style: @style, children: overlay_nodes.values, measure: measurement)
     end
 
     def prepaint(bounds, state, cx)
@@ -118,10 +197,11 @@ module Zaniah
     end
 
     def begin_selection(event)
+      return if overlay_at(local_point(event.position))
       offset = offset_at(event.position)
       @selection = if event.click_count >= 3 && @paragraph
-        range = @paragraph.line_range_at(offset)
-        TextSelection.new(range.begin, range.end)
+        range = @paragraph.line_range_at(logical_to_display_offset(offset))
+        TextSelection.new(display_to_logical_offset(range.begin), display_to_logical_offset(range.end))
       elsif event.click_count == 2
         range = Unicode.word_range_at(@text, [offset, @text.bytesize].min)
         TextSelection.new(range.begin, range.end)
@@ -135,10 +215,12 @@ module Zaniah
     end
 
     def offset_at(position)
-      point = Point.new(position.x - @text_bounds.x, position.y - @text_bounds.y)
-      @paragraph ? @paragraph.hit_test(point) : @line ? @line.index_for_x(point.x) : 0
+      point = local_point(position)
+      hit_test(point)
     end
 
+    def local_point(position) = Point.new(position.x - @text_bounds.x, position.y - @text_bounds.y)
+
     def text_action(action)
       return false unless @selection
       head = @selection.head
@@ -213,14 +295,32 @@ module Zaniah
 
     def paint_selection(bounds, cx)
       range = @selection.range
-      selection_lines.each do |line, start, finish, x, y, height|
+      selection_lines.each_with_index do |(line, start, finish, x, y, height), line_index|
         first, last = [range.begin, start].max, [range.end, finish].min
         next if last <= first
         left = line.x_for_index(first - start)
         right = line.x_for_index(last - start)
+        gaps = if @paragraph.respond_to?(:inline_placements)
+          @paragraph.inline_placements.select { |placement| placement.line == line_index }
+            .map { |placement| [placement.x - x, placement.x - x + placement.width] }
+        else
+          []
+        end
+        segments = gaps.sort.each_with_object([[left, right]]) do |(gap_start, gap_finish), values|
+          segment_start, segment_finish = values.pop
+          if gap_finish <= segment_start || gap_start >= segment_finish
+            values << [segment_start, segment_finish]
+          else
+            values << [segment_start, gap_start] if gap_start > segment_start
+            values << [gap_finish, segment_finish] if gap_finish < segment_finish
+          end
+        end
         cx.scene.layer(Scene::LAYER_SELECTION) do
-          cx.scene.quad(bounds.x + x + left, bounds.y + y, [right - left, 1].max, height,
-            color: cx.theme.colors.selection)
+          segments.each do |segment_start, segment_finish|
+            next unless segment_finish > segment_start
+            cx.scene.quad(bounds.x + x + segment_start, bounds.y + y,
+              segment_finish - segment_start, height, color: cx.theme.colors.selection)
+          end
         end
       end
     end
@@ -279,5 +379,142 @@ module Zaniah
         wrap: @wrap, line_height: @line_height, letter_spacing: @letter_spacing,
         align: @text_align, ellipsis: @ellipsis, kinsoku: @kinsoku, typesetter: typesetter)
     end
+
+    def add_overlay(element)
+      unless element.respond_to?(:request_layout) && element.respond_to?(:prepaint) && element.respond_to?(:paint)
+        raise ArgumentError, "overlay element must be renderable"
+      end
+      raise ArgumentError, "element is already an overlay" if overlay_elements.any? { |candidate| candidate.equal?(element) }
+      child(element)
+    end
+
+    def overlay_elements = (@inline_overlays + @block_overlays).map(&:element)
+
+    def line_at(value, offset) = value.byteslice(0...offset).count("\n")
+
+    def effective_width(width)
+      configured = @style[:width]
+      width = configured.resolve(width) if configured.is_a?(Length)
+      width = configured if configured.is_a?(Numeric)
+      width.finite? ? [width, 0].max : Float::INFINITY
+    end
+
+    def source_rows(value)
+      start = 0
+      value.split("\n", -1).map do |source|
+        [start, source].tap { start += source.bytesize + 1 }
+      end
+    end
+
+    def overlay_paragraph(value, width, typesetter, nodes, styles)
+      engine = Layout::Engine.new
+      rows = source_rows(value)
+      logical_rows = source_rows(@text)
+      logical_boundaries = Unicode.grapheme_boundaries(@text)
+      inline = @inline_overlays.filter_map do |overlay|
+        next if logical_boundaries.bsearch { |offset| offset >= overlay.offset } != overlay.offset
+        display_offset = logical_to_display_offset(overlay.offset, after_insertion: overlay.align == :after)
+        node = nodes.fetch(overlay.element.object_id)
+        node.style = styles.fetch(overlay.element.object_id) unless node.style.equal?(styles.fetch(overlay.element.object_id))
+        measured = engine.measure(node, width: width, height: Float::INFINITY)
+        unless measured.all? { |size| size.is_a?(Numeric) && size.finite? && !size.negative? }
+          raise Error, "inline overlay must have a finite nonnegative size"
+        end
+        [row_at(rows, display_offset), overlay, display_offset, measured]
+      end
+      inline_by_row = inline.group_by(&:first)
+      blocks = @block_overlays.filter_map do |overlay|
+        next unless (logical_row = logical_rows[overlay.line])
+        start, source = logical_row
+        logical_offset = overlay.position == :above ? start : start + source.bytesize
+        offset = logical_to_display_offset(logical_offset, after_insertion: overlay.position == :below)
+        line = row_at(rows, offset)
+        node = nodes.fetch(overlay.element.object_id)
+        node.style = styles.fetch(overlay.element.object_id) unless node.style.equal?(styles.fetch(overlay.element.object_id))
+        block_width = width.finite? ? width : engine.measure(node, width: width, height: overlay.height).first
+        raise Error, "block overlay must have a finite nonnegative width" unless block_width.is_a?(Numeric) && block_width.finite? && !block_width.negative?
+        TextSystem::OverlayParagraph::Block.new(overlay.element.object_id, line,
+          offset, block_width, overlay.height, overlay.position)
+      end
+      layout_key = [value.dup.freeze, width, @font_size, @font&.object_id, @wrap, @line_height,
+        @letter_spacing, @text_align, @ellipsis, @kinsoku, typesetter&.object_id,
+        inline.map { |row, overlay, offset, size| [row, overlay.element.object_id, offset, overlay.align, *size] },
+        blocks.map { |block| [block.key, block.line, block.width, block.height, block.position] }]
+      return @overlay_layout_cache.last if @overlay_layout_cache&.first == layout_key
+
+      composed = rows.each_with_index.map do |(start, source), row|
+        row_overlays = (inline_by_row[row] || []).map do |_target, overlay, offset, (overlay_width, overlay_height)|
+          TextSystem::Paragraph::InlineOverlay.new(overlay.element.object_id,
+            offset - start, overlay_width, overlay_height, overlay.align)
+        end
+        key = [source, width, @font_size, @font&.object_id, @wrap, @line_height,
+          @letter_spacing, @text_align, @ellipsis, @kinsoku, typesetter&.object_id,
+          row_overlays.map { |overlay| [overlay.key, overlay.offset, overlay.width, overlay.height, overlay.align] }]
+        cached = @row_layout_cache[row]
+        unless cached && cached.first == key
+          cached = [key, TextSystem::Paragraph.new(source, width: width, size: @font_size,
+            font: @font, wrap: @wrap, line_height: @line_height, letter_spacing: @letter_spacing,
+            align: @text_align, ellipsis: @ellipsis, kinsoku: @kinsoku, typesetter: typesetter,
+            inline_overlays: row_overlays)]
+          @row_layout_cache[row] = cached
+        end
+        TextSystem::OverlayParagraph::Row.new(cached.last, start)
+      end
+      @row_layout_cache.slice!(rows.length..-1) if @row_layout_cache.length > rows.length
+      result = TextSystem::OverlayParagraph.new(value, rows: composed, blocks: blocks, width: width)
+      @overlay_layout_cache = [layout_key, result]
+      result
+    end
+
+    def row_at(rows, offset)
+      following = rows.bsearch_index { |start, _source| start > offset }
+      following ? following - 1 : rows.length - 1
+    end
+
+    def position_overlay_nodes(nodes, styles)
+      placements = (@paragraph.inline_placements + @paragraph.block_placements).to_h { |placement| [placement.key, placement] }
+      nodes.each do |key, node|
+        unless (placement = placements[key])
+          node.style = styles.fetch(key).merge(position: :absolute, display: :none)
+          next
+        end
+        node = nodes.fetch(placement.key)
+        node.style = styles.fetch(key).merge(position: :absolute, left: placement.x, top: placement.y,
+          width: placement.width, height: placement.height)
+      end
+    end
+
+    def logical_to_display_offset(offset, after_insertion: false)
+      return 0 if @placeholder && @text.empty? && !@buffer&.composition
+      composition = @buffer&.composition
+      return offset unless composition
+      insertion = @selection.head
+      offset > insertion || (after_insertion && offset == insertion) ? offset + composition.text.bytesize : offset
+    end
+
+    def display_to_logical_offset(offset)
+      return 0 if @placeholder && @text.empty? && !@buffer&.composition
+      if (composition = @buffer&.composition)
+        insertion = @selection.head
+        offset = if offset <= insertion
+          offset
+        elsif offset <= insertion + composition.text.bytesize
+          insertion
+        else
+          offset - composition.text.bytesize
+        end
+      end
+      offset = offset.clamp(0, @text.bytesize)
+      return offset if Unicode.grapheme_boundary?(@text, offset)
+      before, after = Unicode.previous_boundary(@text, offset), Unicode.next_boundary(@text, offset)
+      offset - before <= after - offset ? before : after
+    end
+
+    def overlay_at(point)
+      return unless @paragraph.respond_to?(:block_placements)
+      (@paragraph.inline_placements + @paragraph.block_placements).find do |placement|
+        Bounds.new(placement.x, placement.y, placement.width, placement.height).contains?(point)
+      end
+    end
   end
 end

data/lib/zaniah/text_system/line_breaker.rb

@@ -10,6 +10,10 @@ module Zaniah
       end
 
       def ranges(width, &measure)
+        ranges_with_offsets(width) { |value, _first, _finish| measure.call(value) }
+      end
+
+      def ranges_with_offsets(width, &measure)
         width = Float(width)
         raise ArgumentError, "width must be nonnegative" if width.nan? || width.negative?
         result, offset = [], 0
@@ -34,7 +38,7 @@ module Zaniah
           fit, last_word, index = first, nil, first
           while index < clusters.length
             candidate = segment.byteslice(bytes[first]...bytes[index + 1])
-            break if index > first && measure.call(candidate) > width
+            break if index > first && measure.call(candidate, base + bytes[first], base + bytes[index + 1]) > width
             fit = index + 1
             last_word = fit if break_after?(clusters[index])
             index += 1

data/lib/zaniah/text_system/paragraph.rb

@@ -4,10 +4,13 @@ module Zaniah
   module TextSystem
     class Paragraph
       Line = Data.define(:layout, :start, :finish, :x, :y, :height)
-      attr_reader :text, :lines, :width, :height
+      InlineOverlay = Data.define(:key, :offset, :width, :height, :align)
+      Placement = Data.define(:key, :offset, :x, :y, :width, :height, :line, :align)
+      attr_reader :text, :lines, :width, :height, :inline_placements
 
       def initialize(text, width:, size: 14, font: nil, wrap: :word, line_height: nil,
-        letter_spacing: 0, align: :start, ellipsis: false, kinsoku: :push, typesetter: nil)
+        letter_spacing: 0, align: :start, ellipsis: false, kinsoku: :push, typesetter: nil,
+        inline_overlays: [])
         raise ArgumentError, "text must be valid UTF-8" unless text.is_a?(String) && text.encoding == Encoding::UTF_8 && text.valid_encoding?
         raise ArgumentError, "align must be start, center, end, or justify" unless %i[start center end justify].include?(align)
         raise ArgumentError, "letter spacing must be finite" unless letter_spacing.is_a?(Numeric) && letter_spacing.finite?
@@ -17,34 +20,47 @@ module Zaniah
         raise ArgumentError, "line height must be numeric" if line_height && !line_height.is_a?(Numeric)
         @line_height = line_height ? (line_height <= 4 ? size * line_height : line_height) : size * 1.4
         raise ArgumentError, "line height must be finite and positive" unless @line_height.is_a?(Numeric) && @line_height.finite? && @line_height.positive?
+        @inline_overlays = validate_overlays(inline_overlays)
         breaker = LineBreaker.new(@text, wrap: wrap, kinsoku: kinsoku)
-        ranges = breaker.ranges(@limit) { |value| layout(value).width }
+        ranges = breaker.ranges_with_offsets(@limit) do |value, first, finish|
+          layout_with_overlays(value, first, overlays_for(first, finish)).width
+        end
+        y, @inline_placements = 0.0, []
         @lines = ranges.each_with_index.map do |range, index|
           source = @text.byteslice(range) || ""
-          source = ellipsize(source) if @ellipsis && wrap == :none
-          line = spaced(layout(source))
+          visible = source.bytesize
+          source, visible = ellipsize(source, range.begin) if @ellipsis && wrap == :none
+          overlays = overlays_for(range.begin, range.end).select { |overlay| overlay.offset - range.begin <= visible }
+          line = spaced(layout_with_overlays(source, range.begin, overlays))
           line = justified(line) if @align == :justify && index < ranges.length - 1
+          height = [@line_height, overlays.map(&:height).max || 0].max
           x = case @align
           when :center then [(@limit - line.width) / 2.0, 0].max
           when :end then [@limit - line.width, 0].max
           else 0.0
           end
           x = 0.0 if @limit.infinite?
-          Line.new(line, range.begin, range.end, x, index * @line_height, @line_height)
+          append_placements(overlays, line, range.begin, x, y, height, index)
+          Line.new(line, range.begin, range.end, x, y, height).tap { y += height }
         end.freeze
+        @inline_placements.freeze
         @width = [@lines.map { |line| line.x + line.layout.width }.max || 0, @limit].min
-        @height = @lines.length * @line_height
+        @height = y
       end
 
       def hit_test(point)
         return 0 if @lines.empty?
-        line = @lines[(point.y / @line_height).floor.clamp(0, @lines.length - 1)]
+        if (overlay = @inline_placements.find { |item| Bounds.new(item.x, item.y, item.width, item.height).contains?(point) })
+          return overlay.offset
+        end
+        line = @lines.find { |item| point.y < item.y + item.height } || @lines.last
         [line.start + line.layout.index_for_x(point.x - line.x), line.finish].min
       end
 
       def offset_to_point(offset)
         offset = Integer(offset).clamp(0, @text.bytesize)
-        line = @lines.find { |item| offset <= item.finish } || @lines.last
+        placement = @inline_placements.find { |item| item.offset == offset && item.align == :before }
+        line = placement ? @lines.fetch(placement.line) : @lines.find { |item| offset <= item.finish } || @lines.last
         Point.new(line.x + line.layout.x_for_index((offset - line.start).clamp(0, line.layout.text.bytesize)), line.y)
       end
 
@@ -55,6 +71,67 @@ module Zaniah
 
       private
 
+      def validate_overlays(overlays)
+        raise ArgumentError, "inline overlays must be an array" unless overlays.is_a?(Array)
+        overlays.map do |overlay|
+          unless overlay.is_a?(InlineOverlay) && overlay.offset.is_a?(Integer) && overlay.offset.between?(0, @text.bytesize) &&
+              Unicode.grapheme_boundary?(@text, overlay.offset) && %i[before after].include?(overlay.align) &&
+              [overlay.width, overlay.height].all? { |value| value.is_a?(Numeric) && value.finite? && !value.negative? }
+            raise ArgumentError, "invalid inline overlay"
+          end
+          overlay
+        end.sort_by { |overlay| [overlay.offset, overlay.align == :before ? 0 : 1] }.freeze
+      end
+
+      def overlays_for(first, finish)
+        @inline_overlays.select do |overlay|
+          (overlay.offset > first && overlay.offset < finish) ||
+            (overlay.offset == first && (first.zero? || @text.getbyte(first - 1) == 10 || overlay.align == :before)) ||
+            (overlay.offset == finish && (finish == @text.bytesize || @text.getbyte(finish) == 10 || overlay.align == :after))
+        end
+      end
+
+      def layout_with_overlays(value, start, overlays)
+        return layout(value) if overlays.empty?
+        boundaries = overlays.map { |overlay| overlay.offset - start }.uniq.sort
+        glyphs, carets, cursor, first = [], [[0, 0.0]], 0.0, 0
+        boundaries.each do |boundary|
+          part = layout(value.byteslice(first...boundary) || "")
+          append_layout(glyphs, carets, part, first, cursor)
+          cursor += part.width
+          at = overlays.select { |overlay| overlay.offset - start == boundary }
+          before = at.sum { |overlay| overlay.align == :before ? overlay.width : 0 }
+          carets[-1] = [boundary, cursor + before]
+          cursor += at.sum(&:width)
+          first = boundary
+        end
+        part = layout(value.byteslice(first..-1) || "")
+        append_layout(glyphs, carets, part, first, cursor)
+        cursor += part.width
+        LineLayout.new(value.dup.freeze, glyphs.freeze, cursor, part.ascent, part.descent, part.size, carets.freeze)
+      end
+
+      def append_layout(glyphs, carets, line, byte, x)
+        line.glyphs.each do |glyph|
+          glyphs << Glyph.new(glyph.font, glyph.id, glyph.start + byte, glyph.finish + byte, glyph.x + x, glyph.advance)
+        end
+        line.carets.drop(1).each { |offset, position| carets << [offset + byte, position + x] }
+      end
+
+      def append_placements(overlays, line, start, x, y, height, line_index)
+        overlays.group_by(&:offset).each do |offset, group|
+          caret = line.x_for_index(offset - start)
+          before = group.select { |overlay| overlay.align == :before }
+          after = group.select { |overlay| overlay.align == :after }
+          cursor = x + caret - before.sum(&:width)
+          (before + after).each do |overlay|
+            @inline_placements << Placement.new(overlay.key, offset, cursor,
+              y + (height - overlay.height) / 2.0, overlay.width, overlay.height, line_index, overlay.align)
+            cursor += overlay.width
+          end
+        end
+      end
+
       def layout(value)
         return @typesetter.layout_line(value, font: @font, size: @size) if @typesetter
         byte, x, carets = 0, 0.0, [[0, 0.0]]
@@ -74,7 +151,8 @@ module Zaniah
           index = line.carets.bsearch_index { |byte, _| byte >= glyph.start } || line.carets.length - 1
           Glyph.new(glyph.font, glyph.id, glyph.start, glyph.finish, glyph.x + index * @letter_spacing, glyph.advance)
         end
-        LineLayout.new(line.text, glyphs.freeze, carets.last.last, line.ascent, line.descent, line.size, carets.freeze)
+        trailing = line.width - line.carets.last.last
+        LineLayout.new(line.text, glyphs.freeze, carets.last.last + trailing, line.ascent, line.descent, line.size, carets.freeze)
       end
 
       def justified(line)
@@ -88,11 +166,80 @@ module Zaniah
         LineLayout.new(line.text, glyphs.freeze, @limit, line.ascent, line.descent, line.size, carets.freeze)
       end
 
-      def ellipsize(value)
-        return value if @limit.infinite? || layout(value).width <= @limit
+      def ellipsize(value, start)
+        overlays = overlays_for(start, start + value.bytesize)
+        return [value, value.bytesize] if @limit.infinite? || layout_with_overlays(value, start, overlays).width <= @limit
         clusters = value.grapheme_clusters
-        clusters.pop while !clusters.empty? && layout(clusters.join + "…").width > @limit
-        clusters.join + "…"
+        clusters.pop while !clusters.empty? && layout_with_overlays(clusters.join + "…", start,
+          overlays.select { |overlay| overlay.offset - start <= clusters.join.bytesize }).width > @limit
+        visible = clusters.join
+        [visible + "…", visible.bytesize]
+      end
+    end
+
+    class OverlayParagraph
+      Row = Data.define(:paragraph, :start)
+      Block = Data.define(:key, :line, :offset, :width, :height, :position)
+
+      attr_reader :text, :lines, :width, :height, :inline_placements, :block_placements
+
+      def initialize(text, rows:, blocks:, width:)
+        @text, @lines, @inline_placements, @block_placements = text.dup.freeze, [], [], []
+        y = 0.0
+        rows.each_with_index do |row, row_index|
+          y = append_blocks(blocks, row_index, :above, y)
+          first_line = @lines.length
+          row.paragraph.lines.each do |line|
+            @lines << Paragraph::Line.new(line.layout, line.start + row.start,
+              line.finish + row.start, line.x, line.y + y, line.height)
+          end
+          row.paragraph.inline_placements.each do |placement|
+            @inline_placements << placement.with(offset: placement.offset + row.start,
+              y: placement.y + y, line: placement.line + first_line)
+          end
+          y += row.paragraph.height
+          y = append_blocks(blocks, row_index, :below, y)
+        end
+        @lines.freeze
+        @inline_placements.freeze
+        @block_placements.freeze
+        @width = [[@lines.map { |line| line.x + line.layout.width }.max || 0,
+          @block_placements.map { |placement| placement.x + placement.width }.max || 0].max, width].min
+        @height = y
+      end
+
+      def hit_test(point)
+        placements = @inline_placements + @block_placements
+        if (overlay = placements.find { |item| Bounds.new(item.x, item.y, item.width, item.height).contains?(point) })
+          return overlay.offset
+        end
+        return 0 if @lines.empty?
+        line = @lines.find { |item| point.y < item.y + item.height } || @lines.last
+        [line.start + line.layout.index_for_x(point.x - line.x), line.finish].min
+      end
+
+      def offset_to_point(offset)
+        offset = Integer(offset).clamp(0, @text.bytesize)
+        placement = @inline_placements.find { |item| item.offset == offset && item.align == :before }
+        line = placement ? @lines.fetch(placement.line) : @lines.find { |item| offset <= item.finish } || @lines.last
+        Point.new(line.x + line.layout.x_for_index((offset - line.start).clamp(0, line.layout.text.bytesize)), line.y)
+      end
+
+      def line_range_at(offset)
+        line = @lines.find { |item| offset <= item.finish } || @lines.last
+        line.start...line.finish
+      end
+
+      private
+
+      def append_blocks(blocks, line, position, y)
+        blocks.each do |block|
+          next unless block.line == line && block.position == position
+          @block_placements << Paragraph::Placement.new(block.key, block.offset, 0, y,
+            block.width, block.height, line, position)
+          y += block.height
+        end
+        y
       end
     end
   end

data/lib/zaniah/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zaniah
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/sig/elements.rbs

@@ -88,6 +88,21 @@ module Zaniah
   class Div < Element
   end
   class Text < Element
+    class InlineOverlay < Data
+      attr_reader element: _Renderable
+      attr_reader offset: Integer
+      attr_reader align: :before | :after
+      def self.new: (_Renderable element, Integer offset, :before | :after align) -> InlineOverlay
+                  | (element: _Renderable, offset: Integer, align: :before | :after) -> InlineOverlay
+    end
+    class BlockOverlay < Data
+      attr_reader element: _Renderable
+      attr_reader line: Integer
+      attr_reader position: :above | :below
+      attr_reader height: Float
+      def self.new: (_Renderable element, Integer line, :above | :below position, Float height) -> BlockOverlay
+                  | (element: _Renderable, line: Integer, position: :above | :below, height: Float) -> BlockOverlay
+    end
     attr_reader text: String
     attr_reader font_size: Numeric
     attr_reader text_color: color
@@ -99,6 +114,11 @@ module Zaniah
     def on_change: () { (String value) -> void } -> self
     def placeholder: (String text, ?color: color?) -> self
     def secure: (?bool value) -> self
+    def inline_overlay: (offset: Integer, element: _Renderable, ?align: :before | :after) -> self
+    def block_overlay: (line: Integer, element: _Renderable, ?position: :above | :below, height: Numeric) -> self
+    def remove_overlay: (_Renderable element) -> self
+    def hit_test: (Point point) -> Integer
+    def offset_to_point: (Integer offset) -> Point
     def wrap: (?:none | :word | :anywhere mode, ?line_height: Numeric?, ?letter_spacing: Numeric, ?align: :start | :center | :end | :justify, ?ellipsis: bool, ?kinsoku: :hanging | :push | :none) -> self
     def selectable: (?bool value) -> self
     def editable: (?TextBuffer? buffer) -> self

data/sig/text.rbs

@@ -50,8 +50,30 @@ module Zaniah
     class LineBreaker
       def initialize: (String text, ?wrap: :none | :word | :anywhere, ?kinsoku: :hanging | :push | :none) -> void
       def ranges: (Numeric width) { (String) -> Numeric } -> Array[Range[Integer]]
+      def ranges_with_offsets: (Numeric width) { (String, Integer, Integer) -> Numeric } -> Array[Range[Integer]]
     end
     class Paragraph
+      class InlineOverlay < Data
+        attr_reader key: Object
+        attr_reader offset: Integer
+        attr_reader width: Numeric
+        attr_reader height: Numeric
+        attr_reader align: :before | :after
+        def self.new: (Object key, Integer offset, Numeric width, Numeric height, :before | :after align) -> InlineOverlay
+                    | (key: Object, offset: Integer, width: Numeric, height: Numeric, align: :before | :after) -> InlineOverlay
+      end
+      class Placement < Data
+        attr_reader key: Object
+        attr_reader offset: Integer
+        attr_reader x: Numeric
+        attr_reader y: Numeric
+        attr_reader width: Numeric
+        attr_reader height: Numeric
+        attr_reader line: Integer
+        attr_reader align: Symbol
+        def self.new: (Object key, Integer offset, Numeric x, Numeric y, Numeric width, Numeric height, Integer line, Symbol align) -> Placement
+                    | (key: Object, offset: Integer, x: Numeric, y: Numeric, width: Numeric, height: Numeric, line: Integer, align: Symbol) -> Placement
+      end
       class Line < Data
         attr_reader layout: LineLayout
         attr_reader start: Integer
@@ -66,7 +88,36 @@ module Zaniah
       attr_reader lines: Array[Line]
       attr_reader width: Numeric
       attr_reader height: Numeric
-      def initialize: (String text, width: Numeric, ?size: Numeric, ?font: _Font?, ?wrap: :none | :word | :anywhere, ?line_height: Numeric?, ?letter_spacing: Numeric, ?align: :start | :center | :end | :justify, ?ellipsis: bool, ?kinsoku: :hanging | :push | :none, ?typesetter: _LineTypesetter?) -> void
+      attr_reader inline_placements: Array[Placement]
+      def initialize: (String text, width: Numeric, ?size: Numeric, ?font: _Font?, ?wrap: :none | :word | :anywhere, ?line_height: Numeric?, ?letter_spacing: Numeric, ?align: :start | :center | :end | :justify, ?ellipsis: bool, ?kinsoku: :hanging | :push | :none, ?typesetter: _LineTypesetter?, ?inline_overlays: Array[InlineOverlay]) -> void
+      def hit_test: (Point point) -> Integer
+      def offset_to_point: (Integer offset) -> Point
+      def line_range_at: (Integer offset) -> Range[Integer]
+    end
+    class OverlayParagraph
+      class Row < Data
+        attr_reader paragraph: Paragraph
+        attr_reader start: Integer
+        def self.new: (Paragraph paragraph, Integer start) -> Row
+                    | (paragraph: Paragraph, start: Integer) -> Row
+      end
+      class Block < Data
+        attr_reader key: Object
+        attr_reader line: Integer
+        attr_reader offset: Integer
+        attr_reader width: Numeric
+        attr_reader height: Numeric
+        attr_reader position: :above | :below
+        def self.new: (Object key, Integer line, Integer offset, Numeric width, Numeric height, :above | :below position) -> Block
+                    | (key: Object, line: Integer, offset: Integer, width: Numeric, height: Numeric, position: :above | :below) -> Block
+      end
+      attr_reader text: String
+      attr_reader lines: Array[Paragraph::Line]
+      attr_reader width: Numeric
+      attr_reader height: Numeric
+      attr_reader inline_placements: Array[Paragraph::Placement]
+      attr_reader block_placements: Array[Paragraph::Placement]
+      def initialize: (String text, rows: Array[Row], blocks: Array[Block], width: Numeric) -> void
       def hit_test: (Point point) -> Integer
       def offset_to_point: (Integer offset) -> Point
       def line_range_at: (Integer offset) -> Range[Integer]
@@ -146,7 +197,7 @@ module Zaniah
       attr_reader segmenter: _Segmenter
       def initialize: (?font: _Font?, ?font_db: :native | _FontDB, ?capacity: Integer, ?shaper: :native | _Shaper, ?segmenter: :native | _Segmenter) -> void
       def layout_line: (String text, ?font: _Font?, ?size: Numeric) -> LineLayout
-      def layout_paragraph: (String text, width: Numeric, ?size: Numeric, ?font: _Font?, ?wrap: :none | :word | :anywhere, ?line_height: Numeric?, ?letter_spacing: Numeric, ?align: :start | :center | :end | :justify, ?ellipsis: bool, ?kinsoku: :hanging | :push | :none) -> Paragraph
+      def layout_paragraph: (String text, width: Numeric, ?size: Numeric, ?font: _Font?, ?wrap: :none | :word | :anywhere, ?line_height: Numeric?, ?letter_spacing: Numeric, ?align: :start | :center | :end | :justify, ?ellipsis: bool, ?kinsoku: :hanging | :push | :none, ?inline_overlays: Array[Paragraph::InlineOverlay]) -> Paragraph
       def fork: (?capacity: Integer) -> Typesetter
       def close: () -> void
     end
@@ -163,7 +214,7 @@ module Zaniah
       def initialize: (?font: _Font?, ?font_db: :native | _FontDB, ?capacity: Integer, ?font_raster: :native | :alhena | :core_text | :coretext | :freetype | _Rasterizer, ?shaper: :native | _Shaper, ?segmenter: :native | _Segmenter, ?cache_dir: String?) -> void
       def layout_line: (String text, ?font: _Font?, ?size: Numeric) -> LineLayout
       def paint_line: (Scene scene, LineLayout line, x: Numeric, y: Numeric, ?color: color, ?spans: spans?) -> void
-      def paint_paragraph: (Scene scene, Paragraph paragraph, x: Numeric, y: Numeric, ?color: color) -> Scene
+      def paint_paragraph: (Scene scene, Paragraph | OverlayParagraph paragraph, x: Numeric, y: Numeric, ?color: color) -> Scene
       def end_frame: () -> void
       def prewarm: (?String text, ?size: Numeric) -> self
       def close: () -> void

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zaniah
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
-- ydah
+- Yudai Takada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alhena
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rexml
   requirement: !ruby/object:Gem::Requirement
@@ -82,6 +82,7 @@ files:
 - docs/adr/007-text-buffer.md
 - docs/adr/008-accessibility-bridge.md
 - docs/adr/009-grid-scope.md
+- docs/adr/010-text-overlay-layout.md
 - docs/adr/README.md
 - docs/animation.md
 - docs/components.md