tuile 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffd96aaba12d84ccc9f3417db01f75b3b91f0f89cd7358864fdfd1b0dcaa778b
-  data.tar.gz: fdbc08c48e4b908ee8b3cebc7bf949e88cf6cc2a1bb58260b53c8612bc6060cc
+  metadata.gz: 3e4cd91c879f7eea941fd0a60a453a69de1f672a4907269282a0964645d919f8
+  data.tar.gz: c5f6b3124a64904cf606cfd4bc8a28409e7335b2b52c45bc99c67844f2b7de41
 SHA512:
-  metadata.gz: bc286448b580b3978de8652088f491e989618e0fb63c6063035f8f284ae8b57a2192a3fea7913cb26cfee1147e1bc7108e2288da53a1676acf874a069c8c0249
-  data.tar.gz: 20aa07e2b6b53ed16e55211401277b1d97a87bc47e4fda07d7d0f8d642a36b3238ec46495262541f6b5e164d6fcde7bcf5b574a7cd22fc41f38eec9724a3e76c
+  metadata.gz: 0c2d866c691d81685c3db892f933ce094fa9f770c8b7394a652f4344975595ec53acea525f05f1528ddcc934ce9a966ff631be9bf1292d58651c2606dd22fdaa
+  data.tar.gz: 87889c8181d1da7c477678456a3eee02dcd3abcf553b162c9cc1b560856228a8e65f062dc46c6d0c0a1edff5a892dd3b295e506f509698bc5a5142925b5c9663

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-06-11
+
+- Render through a back buffer: `Screen#buffer` is now a `Tuile::Buffer` cell grid sized to the viewport. Components paint into it; `Screen#repaint` flushes only the cells that changed since the last frame, wrapped with the cursor move in one synchronized-output batch (DEC mode 2026). Repaint is flicker-free on **any** terminal regardless of mode-2026 support, because an unchanged cell is never rewritten — the full-scene overdraw a shrinking popup forces no longer reaches the wire. `FakeScreen` exposes the populated buffer for content assertions (`row_text`/`row_ansi`/`region_text`/`region_ansi`/`cell`); `prints` now holds only the assembled frame and cursor housekeeping.
+- Add non-modal popups: `Component::Popup.new(modal: false)` still paints on top and auto-sizes to its content, but does not center, grab focus, capture keys, or block clicks — the focused component keeps the cursor and keeps receiving keys. This is the building block for autocomplete / slash-command menus anchored to a text input's caret. `Popup#modal?` exposes the mode; `ScreenPane#modal_popup` is the topmost *modal* popup (or nil), through which all "modal owner" reads (key scope, mouse fall-through, focus repair, Tab scope, global-shortcut gate) now route.
+- Add `Component::TextInput#on_key` — an interceptor consulted before the input's own key handling (a truthy return consumes the key); the keyboard analog of `on_change`, for both `TextField` and `TextArea`. Lets app code layer Up/Down/Enter/ESC handling onto a field without subclassing.
+- Add `Component#popup_min_height` / `popup_max_height` — content components can advise a wrapping `Popup` of preferred height bounds. `Component::LogWindow` uses them to stay readable at half-screen height when nearly empty and grow to full-screen for busy logs.
+- `Component::LogWindow` now renders through a `TextView`, so long log lines wrap instead of being ellipsized.
+- Add `examples/sampler.rb` "Slash menu" demo: a `TextArea` whose `on_change` refills a non-modal `Popup`-wrapped `List` anchored to the caret, with `on_key` forwarding navigation and ESC dismissing — focus and caret stay in the field throughout.
+- **Breaking:** components paint into `Screen#buffer` via `set_line` / `fill` / `set_char` (handing the surface a `StyledString`) instead of writing escape sequences through `screen.print`. Custom components that drew via `screen.print(move_to, ansi)` must migrate to the buffer API.
+- **Breaking:** key dispatch is centralized into a capture + bubble model in `ScreenPane#handle_key` (a `key_shortcut` match anywhere in scope focuses that component; the key is then delivered to `Screen#focused` and bubbles up its ancestor chain). A component's `handle_key` now acts on the key alone and never gates on its own `active?` state. `Layout#handle_key`, `Window#handle_key`, and `HasContent#handle_key` are removed (routing is the dispatcher's job), and the `active?` guards in `TextInput` / `List` / `Button` are dropped.
+
 ## [0.7.0] - 2026-06-09
 
 - Lower the Ruby floor to 3.3 (was 3.4): replaced the `it` implicit block parameter (3.4+) with `_1` throughout, and added 3.3 to the CI matrix.

data/examples/sampler.rb

@@ -67,6 +67,7 @@ module SamplerExample
       ["Label",        :build_label],
       ["TextField",    :build_text_field],
       ["TextArea",     :build_text_area],
+      ["Slash menu",   :build_slash_demo],
       ["TextView",     :build_text_view],
       ["Button",       :build_buttons],
       ["List",         :build_list],
@@ -87,6 +88,11 @@ module SamplerExample
     end
 
     def load_entry(idx)
+      # The slash-menu demo parks a non-modal overlay on the pane (it lives
+      # outside the right pane's content tree), so close it before swapping
+      # demos or it would linger over the next one.
+      @slash_overlay.close if @slash_overlay&.open?
+      @slash_overlay = nil
       caption, builder = ENTRIES[idx]
       @right_window.caption = caption
       @right_window.content = send(builder)
@@ -135,6 +141,64 @@ module SamplerExample
       end
     end
 
+    # Slash commands the demo offers; the menu filters these by what's typed.
+    SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
+
+    # A non-modal Popup used as an autocomplete menu. Focus (and the caret)
+    # stays in the TextArea the whole time: an `on_change` listener refills the
+    # menu, an `on_key` interceptor forwards Up/Down/Enter/ESC to it while it's
+    # open, and the menu floats above the field, anchored to the caret. None of
+    # this is baked into TextArea — it's all assembled here from stock hooks.
+    def build_slash_demo
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Non-modal Popup as an autocomplete menu. Type a slash command\n" \
+                    "(try \"/\" or \"/s\"). The menu floats above the field without taking\n" \
+                    "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
+                    "ordinary typing keeps editing the field and refilters the menu."
+      area = Tuile::Component::TextArea.new
+
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.show_cursor_when_inactive = true # highlight the selection though focus stays in the field
+      window = Tuile::Component::Window.new("Commands").tap { _1.content = list }
+      overlay = Tuile::Component::Popup.new(content: window, modal: false)
+      @slash_overlay = overlay
+
+      refill = lambda do
+        matches = slash_matches(area)
+        if matches.empty?
+          overlay.close if overlay.open?
+        else
+          overlay.open unless overlay.open?
+          list.lines = matches
+          anchor_overlay(overlay, area)
+        end
+      end
+
+      area.on_change = ->(_text) { refill.call }
+      list.on_item_chosen = ->(_idx, line) { accept_slash_command(area, line.to_s) }
+      area.on_key = lambda do |key|
+        next false unless overlay.open?
+
+        case key
+        when Tuile::Keys::UP_ARROW, Tuile::Keys::DOWN_ARROW, Tuile::Keys::ENTER
+          list.handle_key(key) # works though the list is unfocused — dispatch gates on focus, not the list
+        when Tuile::Keys::ESC
+          overlay.close
+          true
+        else
+          false
+        end
+      end
+
+      panel(prompt, area) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 4)
+        area_height = [inner.height - 7, 4].max
+        area.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, area_height)
+      end
+    end
+
     def build_text_view
       prompt = Tuile::Component::Label.new
       prompt.text = "Read-only viewer for prose. Word-wraps to width; ANSI formatting passes through.\n" \
@@ -301,6 +365,51 @@ module SamplerExample
       end
     end
 
+    # The run of non-space characters ending at the caret, when it starts with
+    # "/" — i.e. the slash command being typed — or nil.
+    def slash_token(area)
+      text = area.text
+      caret = area.caret
+      start = caret
+      start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
+      token = text[start...caret].to_s
+      token.start_with?("/") ? token : nil
+    end
+
+    # Commands matching the slash token at the caret (empty when not in one).
+    def slash_matches(area)
+      token = slash_token(area)
+      return [] if token.nil?
+
+      SLASH_COMMANDS.select { _1.start_with?(token) }
+    end
+
+    # Replaces the slash token at the caret with `command` plus a trailing
+    # space, then drops the caret after it (which re-fires on_change → refill,
+    # so the now-tokenless text closes the menu).
+    def accept_slash_command(area, command)
+      text = area.text
+      caret = area.caret
+      start = caret
+      start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
+      area.text = "#{text[0...start]}#{command} #{text[caret..]}"
+      area.caret = start + command.length + 1
+    end
+
+    # Positions the overlay just below the caret, flipping above when there's
+    # no room beneath, and clamps it to the screen.
+    def anchor_overlay(overlay, area)
+      caret = area.cursor_position
+      return if caret.nil?
+
+      screen_size = Tuile::Screen.instance.size
+      size = overlay.rect
+      top = caret.y + 1
+      top = [caret.y - size.height, 0].max if top + size.height > screen_size.height - 1
+      left = caret.x.clamp(0, [screen_size.width - size.width, 0].max)
+      overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
+    end
+
     # Carves a 2-column padding out of the panel rect so the demo content
     # doesn't run flush to the window border.
     def inner_rect(rect)

data/ideas/back-buffer.md

@@ -0,0 +1,217 @@
+# Back-buffer cell diff (flicker-free rendering)
+
+Status: **proposal, for review**. Supersedes the stop-gap synchronized-output
+commit (`23b4e71`), which we keep as a bonus but which only works where the
+whole terminal stack implements DEC mode 2026 (notably *not* under tmux < 3.4).
+
+## Problem
+
+Components paint by emitting escape sequences straight to the terminal:
+
+```ruby
+screen.print TTY::Cursor.move_to(x, y), styled_string.to_ansi
+```
+
+When a frame redraws a large region — e.g. the full-scene repaint a shrinking
+non-modal popup forces via `Screen#needs_full_repaint` — the terminal shows the
+clear-then-redraw in progress. On the slash-command demo this flickers on every
+keystroke. Mode 2026 hides it on capable stacks but is best-effort: one old
+layer (tmux < 3.4, Alacritty < 0.13) silently swallows the private-mode set and
+the flicker returns.
+
+The durable fix is stack-independent: **never write a cell whose final value
+equals what's already on screen.** Flicker comes from overwriting a cell with a
+space and then the glyph; if the result is unchanged, emit nothing. This is why
+ncurses, tmux, and Ratatui never flicker on any terminal.
+
+## Approach P — single cell buffer + dirty-cell diff
+
+Two stages, kept distinct:
+
+- **Composite** (in memory): components write into a back buffer. Driven by the
+  *existing* invalidation engine — only invalidated components repaint, so cost
+  stays proportional to what changed.
+- **Flush** (to terminal): walk the cells that actually changed, group them into
+  runs, and emit `move_to` + minimal SGR per run. Only changed cells reach the
+  wire.
+
+Crucially this **keeps almost the entire current architecture** and swaps only
+the output sink. We do *not* rip out invalidation or the z-order overdraw rule.
+
+### What stays (deliberately)
+
+- **`invalidate` / the `@invalidated` set.** Dedup, paint-at-most-once-per-frame,
+  decides *who* repaints. Unchanged.
+- **The z-order overdraw rule** (`repaint` partitioning tiled vs popup,
+  `collect_subtree`, "repaint occluders on top in stacking order"). It orders
+  writes into the shared buffer so a popup wins where it overlaps content.
+  Unchanged.
+- **`needs_full_repaint`.** Still called on popup close / shrink / move. It stops
+  being a flicker source *because the diff filters it*: every component rewrites
+  its cells, the vast majority equal what's already there → not marked dirty →
+  not emitted. Only the newly-exposed region differs and gets flushed. So
+  "invalidate everything" becomes cheap without deleting it.
+
+### What changes
+
+- New `Tuile::Buffer` (cell grid) — the screen mirror that components paint into.
+- `Component#repaint` methods call `buffer.set_line(x, y, styled)` instead of
+  `screen.print(move_to(x, y), styled.to_ansi)`. Mechanical, ~8 files.
+- `Screen` flushes by diffing dirty cells instead of accumulating a
+  `@frame_buffer` of escape strings.
+
+### What it kills
+
+- The whole class of clear-then-redraw flicker, on **every** terminal,
+  independent of mode-2026 support.
+
+## Cell & Buffer model
+
+Reuse `StyledString::Style` as the per-cell style — it is already a frozen value
+type (`fg/bg/bold/italic/underline/strikethrough`) and already knows how to diff
+itself into minimal SGR (`StyledString#sgr_diff`, lifted into a shared helper).
+This is the single biggest reason the refactor is tractable rather than a
+from-scratch styling layer.
+
+```
+Cell = (grapheme: String, style: Style)
+```
+
+- Normal cell = one display column.
+- A 2-column glyph (CJK/emoji) occupies cell `x` (glyph) and `x+1` (a
+  continuation sentinel; the flush skips it since the glyph already advanced the
+  cursor two columns, and overwriting either half clears both). `StyledString`
+  already computes correct widths via `Unicode::DisplayWidth` and already drops
+  half-overlapping wide chars on `slice` boundaries, so the hard Unicode work is
+  done.
+
+### `Buffer` API (new file `lib/tuile/buffer.rb`)
+
+One top-level constant per file per the Zeitwerk rule; `Buffer::Cell` nested.
+
+```ruby
+buffer.set_line(x, y, styled_string)   # write a row, clipped to bounds — workhorse
+buffer.set_char(x, y, grapheme, style) # primitive; marks the cell dirty iff it changed
+buffer.fill(rect, style)               # clear_background's replacement
+buffer.resize(size)                    # on WINCH; forces full redraw
+buffer.flush -> String                 # emit minimal escapes for dirty cells, clear dirty
+```
+
+`set_line` is a near-mechanical replacement for today's
+`screen.print(move_to(x, y), styled.to_ansi)`: walk the styled string with
+`each_char_with_style`, place graphemes at successive columns, handle wide-char
+continuations + clipping.
+
+### Dirty tracking — proportional, no whole-buffer sweep
+
+`set_char` compares the incoming `(grapheme, style)` against the current cell; on
+a difference it overwrites and records the cell (or its row range) as dirty.
+There is **no per-frame whole-buffer clear or copy** — un-repainted cells simply
+retain last frame's value. So both composite and flush cost scale with what
+actually changed, which is the efficiency property we want at large sizes
+(210×79 ≈ 16.6k cells).
+
+Minor accepted imperfection: a component that writes a cell away from and back to
+its original value within one frame leaves it marked dirty, so the flush
+re-emits an identical glyph to that one cell — imperceptible (same value, no
+flash), and rare. Avoiding it would need a second buffer + full diff; not worth
+the per-frame whole-buffer touch.
+
+### Flush — reuse `StyledString` for the run emitter
+
+Walk dirty cells in row order, group maximal horizontal runs, build a
+`StyledString` from each run's `(grapheme, style)` cells, and emit
+`move_to(run.x, run.y)` + `run.to_ansi`. `StyledString` already collapses
+adjacent same-styled characters and emits minimal-diff SGR, so the run encoder is
+nearly free. Wrap the whole flush in `Ansi::SYNC_BEGIN`/`SYNC_END` (belt and
+suspenders where supported).
+
+## Performance
+
+With composite proportional to invalidation, a keystroke that changes one widget
+touches a few hundred `set_char` and emits a few runs — sub-millisecond. The only
+potentially full-width operation is the dirty scan on flush; track dirty as row
+ranges (or a dirty-row set) so it stays proportional. No C sidecar now; if the
+diff scan ever shows in a profile it is the most mechanical thing to drop into C
+later, but it is unlikely to matter at keystroke cadence.
+
+## Deferred: per-component back buffers + compositor
+
+A later optimization, **not** in this plan. Each component would own a buffer;
+the screen is composited by walking a z-stack over dirty regions. Honest
+assessment of why it waits:
+
+- It does **not** avoid clipping — it adopts clipping's tamer cousin
+  (z-compositing) and forces a **transparency model** (components don't tile
+  their rect — see the "not required to fully tile" invariant — so cells need
+  set-vs-transparent so lower layers show through). That's *more* model
+  complexity than Approach P, where the parent's clear-fill + shared buffer
+  already handles gaps.
+- The waste it would save is mostly already gone. Obscured-component-under-dialog
+  splits two ways under Approach P:
+  - *Only the dialog changes* (the actual slash-menu case): only the dialog is
+    invalidated, so the obscured component is **not repainted at all**.
+  - *The obscured component changes*: the overdraw rule repaints the dialog on
+    top, but only its `repaint()` **CPU** — the diff drops its unchanged cells
+    from the wire.
+  Per-component buffers would shave only that residual CPU, by copying the
+  dialog's buffer cells instead of re-running its `repaint`.
+
+It genuinely pays in exactly one regime: high repeat-rate scroll (held arrow /
+mouse wheel) of a large component on a large screen, where re-rendering content
+each repeat is the cost. Keep the door open: design `Buffer`'s API so components
+paint through a drawing surface (`set_line`/`set_char`) without knowing whether
+it is the global buffer or their own — then a compositor becomes a drop-in if
+profiling ever demands it.
+
+## Migration surface
+
+Eight files emit paint output today: `component.rb` (base `clear_background`),
+`label`, `button`, `list`, `text_field`, `text_area`, `text_view`, `window`.
+Each has 1–3 `screen.print(move_to, ansi)` sites. Rewrite is mechanical:
+`screen.print(move_to(x, y), styled.to_ansi)` → `buffer.set_line(x, y, styled)`.
+Borders (Window) and row highlights (List `with_bg`) remain per-row styled
+strings, so they compose unchanged.
+
+## Test-suite impact (the bulk of the human effort)
+
+`FakeScreen` captures emitted bytes in `@prints`; many specs assert
+`screen.prints.join.include?("hi")`. After the change components write to a
+buffer, not `print`. So:
+
+- `FakeScreen` exposes the back buffer; new idiom
+  `assert_includes screen.buffer.row_text(2), "hi"` — cleaner than scanning
+  escape soup.
+- Specs asserting raw `prints` (a meaningful fraction across the 8 component
+  specs) migrate to buffer queries. Add `Buffer#row_text(y)` / `#cell(x, y)`.
+- New `spec/tuile/buffer_spec.rb` covers the cell model, wide-char
+  continuations, clipping, and the diff — including the load-bearing property:
+  **an unchanged cell emits nothing**.
+
+This test migration is larger than the production rewrite.
+
+## Phasing (keep `rake spec` green at each step)
+
+1. **`Buffer` + `Cell` + flush, standalone.** New files + full unit spec. Zero
+   integration. Lift `StyledString#sgr_diff` into a shared SGR helper both use.
+   *Lands green, touches nothing else.*
+2. **Wire `Screen` to composite into the buffer and flush by diff.** Keep
+   `Component#repaint` writing through a thin `set_line` shim so the change is
+   one layer. Switch `FakeScreen` to expose the buffer.
+3. **Migrate component `repaint`s** to `set_line`, one file at a time, migrating
+   each mirrored spec alongside.
+4. **Simplify `Screen#repaint`'s output path** (drop `@frame_buffer`
+   accumulation; the partition/overdraw logic and `needs_full_repaint` stay).
+   Update the AGENTS.md "Invalidation + repaint" section to describe the
+   buffer + diff sink.
+5. Re-profile; confirm no flicker on Alacritty **and under tmux** (the acceptance
+   test the mode-2026 stop-gap fails).
+
+## Open decisions (resolved during design discussion)
+
+- **Keep `invalidate`** — yes. Composite proportional to change; lower-risk
+  refactor than full recomposite.
+- **Flush emits only changed runs** — yes; reuse `StyledString.to_ansi`.
+- **Per-component buffers** — deferred; API kept open (see above).
+- **`Style` location** — reuse `StyledString::Style` as the cell style, one
+  styling vocabulary across the framework.

data/lib/tuile/ansi.rb

@@ -11,5 +11,21 @@ module Tuile
     # background, and text attributes.
     # @return [String]
     RESET = "\e[0m"
+
+    # Begin Synchronized Update (DEC private mode 2026, "Synchronized
+    # Output"). The terminal stops refreshing its display and buffers every
+    # subsequent write until {SYNC_END}, then composites the whole batch
+    # atomically — so a multi-cell repaint is never shown half-drawn. This is
+    # what stops flicker when a frame redraws a large region (e.g. the
+    # full-scene repaint a shrinking popup forces). Terminals without support
+    # ignore the private-mode set, so it's a safe no-op there. {Screen#repaint}
+    # wraps its single frame-buffer flush in this pair.
+    # @return [String]
+    SYNC_BEGIN = "\e[?2026h"
+
+    # End Synchronized Update — see {SYNC_BEGIN}. Releases the buffered frame
+    # and lets the terminal repaint.
+    # @return [String]
+    SYNC_END = "\e[?2026l"
   end
 end