[benchmark] benchmarking tools, component benchmarks README.md: (benchmarking) describes our approach to benchmarking the TUI, including a variety of models-under-test for comparison. Basic metrics: time/op, heap-allocs/op. Main rendering models under test: * Scribe-based (our new and improved) -- directly writing to Canvas/FrameBuffer, using pull-driven viewports. * Stitch-based (semi-old) -- composition based on returned []string * includes variants with and without adaptation to tea.Model.View() Adaptation includes the cost of flattening representations to monolithic string. tuitest/benchmark_harness.go: - BenchmarkHarness provides a simulation environment for measuring update-render event sequences. - Workloads are expressed as BenchmarkSchedule of BenchmarkSteps, including time-tick events, triggered updates, render cycles. - Use RunAllModels() on each component-workload combination. Benchmarked components: - Atom-level benchmarks (atoms_benchmark_test.go): measures: text segments, spacers, and animated marquees. - Compose-level benchmarks (compose_benchmark_test.go): measures: tiling (BoxRow, BoxColumn, StaticRow) and layering (OverlayBox, TableBlock) layout. Bug: 487240814 Change-Id: I757058b6b316bfb3e9a710d42734f0b4d8be5144 Reviewed-on: https://fuchsia-review.googlesource.com/c/rsclient/+/1754352 Reviewed-by: David Turner <digit@google.com> Reviewed-by: Jay Zhuang <jayzhuang@google.com> Commit-Queue: David Fang <fangism@google.com>
diff --git a/internal/pkg/tui2/README.md b/internal/pkg/tui2/README.md index c196eb0..9867e66 100644 --- a/internal/pkg/tui2/README.md +++ b/internal/pkg/tui2/README.md
@@ -724,3 +724,141 @@ * `BoxGrid`: A general-purpose stateful 2D container managing a matrix of cell components. * `OverlayBox`: Contains a foreground view over a background view within a rectangular boundary. * `TransparentLayers`: A general-purpose Z-axis layout container that stacks and projects multiple overlapping layers. + +--- + +## Rendering Benchmarking + +This section details how we benchmark the TUI rendering engine, our +models-under-test, the simulation harness, and what the comparative metrics +reveal. + +To isolate the exact CPU and memory costs of the rendering pipeline, our suite +tests pure update-render event schedules completely isolated from external +factors (like terminal I/O, OS process scheduling, or screen refreshing). +We execute pre-allocated sequences of mutations and redraws +(`BenchmarkSchedule`) on in-memory buffers (like `FrameBuffer` and raw line +slices) in a tight, allocation-free loop under Go's `testing.B`. + +### Production Rendering Overhead + +While our benchmarks isolate pure algorithmic and computational costs, a +production application also pays external systems-level costs outside the +rendering engine's control: + +Framework-level overhead (managed by Bubble Tea): +1. Input Multiplexing: Spawning concurrent goroutines to poll stdin and parse + raw ANSI escape streams into Go messages. +2. Signal Interception: Intercepting OS signals (e.g., SIGWINCH) to translate + them into standard messages. +3. Output Flushing: Managing standard output (stdout) write frequency and + throttling frames to avoid I/O saturation. + +System-level overhead (completely outside software control): +1. OS Process Scheduling: Kernel-to-userland scheduling, context switching, and + thread wake-ups. +2. Terminal Hardware Sync: The terminal emulator's screen refresh cycle and + alignment with the monitor's VSync to display the raster. + +### Rendering Models Under Test + +To evaluate the trade-offs of different rendering paradigms, we test the same +component under five configurations (the `TUIBenchmarkModels`): + +1. `ScribePureModel` (Scribe-to-Canvas): Writes directly to coordinate-mapped + `FrameBuffer` without adapting to `tea.Model.View()`. This isolates the + raw performance of 2D layouts, spatial clipping, and coordinate drawing, + free of string-serialization or terminal-joining overhead. +2. `ScribeAdaptedModel` (Scribe-to-String): Uses the `tui2.Adapt` bridge to + fit Scribe into a standard Bubble Tea loop. This represents our production- + ready integration, capturing the cost of 2D painting and serializing the + final grid into a single contiguous string for `View()`. +3. `StitchPureModel` (Stitch-to-Slices): Stateless layout compiling that + returns raw slices of unjoined lines (`[]string`). This measures stateless, + line-stretching performance isolated from the cost of final root-level + joining. +4. `StitchAdaptedModel` (Unmemoized): Traditional stateless string-stitching + where the layout is re-compiled and joined on every frame. This serves + as our unoptimized baseline. +5. `StitchAdaptedModel` (Memoized): Stateless string-stitching with our + thread-safe `tui2.Memo` cache enabled, measuring the efficacy of stable- + frame cache hits under stateless composition. + +Comparing these models helps isolate deep-seated architectural costs: + +* *The "Adaptation/String-Join Tax":* Comparing pure and adapted models isolates + the CPU and memory cost of flattening structured data (2D grids or line + slices) into a single newline-joined string, highlighting the physical limits + of traditional string-based rendering loops. +* *Viewport Culling (`O(viewport)` vs. `O(content)`):* Comparing Scribe against + Stitch over varying dataset sizes (e.g., 10- vs. 1,000-row tables) highlights + Scribe's pull-based, coordinate-aware optimization: + * `StitchPureModel` degrades linearly (`O(N)`) because push-based children + are evaluated bottom-up, forcing full compilation before parent-level + truncation. + * `ScribePureModel` remains flat (`O(viewport)`) because top-down bounding + boxes immediately short-circuit off-screen children, making it ideal for + large virtualized grids. +* *Selective Invalidation & Memoization:* Comparing unmemoized vs. memoized + Stitch models profiles CPU and GC savings from revision-summed dirty culling. + On stable frames, memoization provides `O(1)` frame-skipping with zero heap + allocations. + +### Workload Simulation + +Workload simulation is managed by utilities in +`internal/pkg/tui2/tuitest/benchmark_harness.go`: + +* `BenchmarkHarness`: Configures viewport size (`layout.Size`) and drives + execution via `Run` or `RunSchedule`. +* `TUIBenchmarkModel`: Unified interface for all five models under test and + standard `tea.Model`s (via `NewTeaModelTarget`). +* `BenchmarkSchedule`: A pre-allocated, zero-allocation sequence of steps + modeling state updates (`Mutate`), clock ticks (`Tick`), and draws (`Render`). + +The harness's `RunAllModels` utility runs a single simulation schedule across +all five configurations as automated sub-benchmarks. + +```go +package compose_test + +import ( + "testing" + "github.com/bazelbuild/rsclient/internal/pkg/layout" + "github.com/bazelbuild/rsclient/internal/pkg/tui2" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/compose" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/tuitest" +) + +func BenchmarkMyDashboard(b *testing.B) { + // 1. Initialize the harness with a fixed viewport size + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + // 2. Instantiate and wrap your component + db := tui2.NewComponent(compose.NewBoxColumn(...)) + + // 3. Define a simulation schedule (e.g. mutate state, then trigger a + // redraw) + sched := tuitest.BenchmarkSchedule{ + tuitest.Mutate(func() { + // Apply some state updates to the component here... + }), + tuitest.Render(), + } + + // 4. Run all 5 model variants as sub-benchmarks automatically! + harness.RunAllModels(b, db, sched) +} +``` + +### Run the Benchmarks + +To run and analyze the benchmark suite under Bazel: + +```bash +./bazel test //internal/pkg/tui/... \ + --test_arg=-test.bench=. \ + --test_arg=-test.benchtime=1x \ + --test_output=all +```
diff --git a/internal/pkg/tui2/atoms/BUILD.bazel b/internal/pkg/tui2/atoms/BUILD.bazel index acaee72..15d4a28 100644 --- a/internal/pkg/tui2/atoms/BUILD.bazel +++ b/internal/pkg/tui2/atoms/BUILD.bazel
@@ -38,6 +38,7 @@ go_test( name = "atoms_test", srcs = [ + "atoms_benchmark_test.go", "marquee_test.go", "rule_test.go", "spacer_test.go", @@ -53,5 +54,6 @@ "//internal/pkg/text", "//internal/pkg/tui2", "//internal/pkg/tui2/tuitest", + "@com_github_charmbracelet_bubbletea//:bubbletea", ], )
diff --git a/internal/pkg/tui2/atoms/atoms_benchmark_test.go b/internal/pkg/tui2/atoms/atoms_benchmark_test.go new file mode 100644 index 0000000..0a8bc95 --- /dev/null +++ b/internal/pkg/tui2/atoms/atoms_benchmark_test.go
@@ -0,0 +1,279 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package atoms_test + +import ( + "strconv" + "strings" + "testing" + "time" + + "github.com/bazelbuild/rsclient/internal/pkg/layout" + "github.com/bazelbuild/rsclient/internal/pkg/tui2" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/atoms" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/tuitest" + + tea "github.com/charmbracelet/bubbletea" + + _ "github.com/bazelbuild/rsclient/internal/pkg/testsetup" +) + +// BenchmarkAtom_WrappedText profiles a simple paragraph wrapping atom. +func BenchmarkAtom_WrappedText(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + para := "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: para, + }) + comp := tui2.NewComponent(w) + + harness.Run(b, tuitest.NewScribePureModel(comp, size), tuitest.BenchmarkSchedule{tuitest.Render()}) +} + +// BenchmarkAdaptedAtom_WrappedText profiles an adapted paragraph wrapping atom under the bubbletea Model.View contract. +func BenchmarkAdaptedAtom_WrappedText(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + para := "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: para, + }) + comp := tui2.NewComponent(w) + + harness.Run(b, tuitest.NewScribeAdaptedModel(comp, size), tuitest.BenchmarkSchedule{tuitest.Render()}) +} + +// BenchmarkRenderTo_WrappedText profiles the absolute redraw cost of a WrappedText atom writing directly to a stream. +func BenchmarkRenderTo_WrappedText(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + para := "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: para, + }) + comp := tui2.NewComponent(w) + + harness.RunTUIRenderTo(b, comp) +} + +// BenchmarkTUIMutation_WrappedText_ParamJitter profiles high-frequency parameter mutations (jittering) +// on a WrappedText atom, forcing continuous cache invalidation and layout reflow. +func BenchmarkTUIMutation_WrappedText_ParamJitter(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: "Initial Text", + }) + comp := tui2.NewComponent(w) + + // Mutate function that updates the text value on every iteration, + // triggering cache invalidation. + var currentI int + sched := tuitest.BenchmarkSchedule{ + tuitest.Mutate(func() { + p := w.Params() + // Injecting dynamic variations to prevent compilers from optimization-bypassing + if currentI%2 == 0 { + p.TextValue = "Even Iteration Text: Lorem Ipsum" + } else { + p.TextValue = "Odd Iteration Text: Dolor Sit Amet" + } + w.Set(p) + currentI++ + }), + tuitest.Render(), + } + + harness.Run(b, tuitest.NewScribePureModel(comp, size), sched) +} + +// BenchmarkAnimation_Marquee profiles real-time scrolling animations on a Marquee atom, +// simulating the passage of time on every frame (tick updates). +func BenchmarkAnimation_Marquee(b *testing.B) { + size := layout.Size{Width: 20, Height: 1} // Limit viewport to 20 columns so it must scroll! + harness := tuitest.NewBenchmarkHarness(size) + + // Long text that exceeds the 20-character viewport width + m := atoms.NewMarquee("SCROLLING TEST OF REACTION ANIMATION ENGINE") + comp := tui2.NewComponent(m) + + // Base start time + baseTime := time.Date(2026, 8, 6, 12, 0, 0, 0, time.UTC) + + // Mutate function simulates a ticker that updates the animation clock + // by 100 milliseconds on every frame, forcing marquee movement. + var currentI int + sched := tuitest.BenchmarkSchedule{ + tuitest.Mutate(func() { + tickTime := baseTime.Add(time.Duration(currentI) * 100 * time.Millisecond) + m.Update(tui2.TickMsg(tickTime)) + currentI++ + }), + tuitest.Render(), + } + + harness.Run(b, tuitest.NewScribePureModel(comp, size), sched) +} + +// BenchmarkSchedule_WrappedText_BurstLog runs a schedule-based benchmark simulating a bursty logger: +// 100 state mutations interleaved with periodic (20%) redraw passes and ticking clock advancement. +func BenchmarkSchedule_WrappedText_BurstLog(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: "Initial Log Message", + }) + comp := tui2.NewComponent(w) + + // Pre-build a schedule of 100 steps + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + textValue := "Burst log line " + strconv.Itoa(i%10) + ": Lorem ipsum dolor sit amet..." + sched = append(sched, tuitest.Mutate(func() { + p := w.Params() + p.TextValue = textValue + w.Set(p) + })) + // Render/Tick once every 5 mutations (20 FPS throttle) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + sched = append(sched, tuitest.Tick(50*time.Millisecond)) + } + } + + harness.Run(b, tuitest.NewScribePureModel(comp, size), sched) +} + +// BenchmarkSchedule_Marquee_InteractiveScroll runs a schedule-based benchmark simulating real-time interactive scrolling: +// 100 steps of interleaved Tick and Render operations. +func BenchmarkSchedule_Marquee_InteractiveScroll(b *testing.B) { + size := layout.Size{Width: 20, Height: 1} + harness := tuitest.NewBenchmarkHarness(size) + + m := atoms.NewMarquee("SCROLLING TEST OF REACTION ANIMATION ENGINE") + comp := tui2.NewComponent(m) + + // Pre-build a schedule of 100 steps of synchronized ticks and repaints + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + sched = append(sched, tuitest.Tick(30*time.Millisecond)) + sched = append(sched, tuitest.Render()) + } + + harness.Run(b, tuitest.NewScribePureModel(comp, size), sched) +} + +// naiveWrappedTextModel serves as a traditional, stateless Bubble Tea control-group baseline. +// It word-wraps its text parameter on every single View() pass without any spatial or 2D memoization caching, +// representing traditional, un-optimized Bubble Tea development. +type naiveWrappedTextModel struct { + text string + width int +} + +func (m *naiveWrappedTextModel) Init() tea.Cmd { return nil } + +func (m *naiveWrappedTextModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { + return m, nil +} + +func (m *naiveWrappedTextModel) View() string { + lines := naiveWrapText(m.text, m.width) + return strings.Join(lines, "\n") +} + +func naiveWrapText(s string, limit int) []string { + words := strings.Fields(s) + if len(words) == 0 { + return nil + } + var lines []string + current := words[0] + for _, w := range words[1:] { + if len(current)+1+len(w) > limit { + lines = append(lines, current) + current = w + } else { + current += " " + w + } + } + lines = append(lines, current) + return lines +} + +// BenchmarkSchedule_NaiveWrappedText_BurstLog runs a schedule-based benchmark simulating a bursty logger on a naive Bubble Tea model: +// 100 state mutations interleaved with periodic (20%) View rendering passes and ticking clock advancement. +func BenchmarkSchedule_NaiveWrappedText_BurstLog(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + naiveModel := naiveWrappedTextModel{ + text: "Initial Log Message", + width: 80, + } + + // Pre-build a schedule of 100 steps + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + textValue := "Burst log line " + strconv.Itoa(i%10) + ": Lorem ipsum dolor sit amet..." + sched = append(sched, tuitest.Mutate(func() { + naiveModel.text = textValue + })) + // Render/Tick once every 5 mutations (20 FPS throttle) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + sched = append(sched, tuitest.Tick(50*time.Millisecond)) + } + } + + harness.Run(b, tuitest.NewTeaModelTarget(&naiveModel), sched) +} + +// BenchmarkSchedule_AdaptedWrappedText_BurstLog runs a schedule-based benchmark simulating a bursty logger +// on our modernized TUI component adapted to Bubble Tea (tui2.Adapt), reflecting top-most production reality: +// 100 state mutations interleaved with periodic (20%) View rendering passes and ticking clock advancement. +func BenchmarkSchedule_AdaptedWrappedText_BurstLog(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: "Initial Log Message", + }) + comp := tui2.NewComponent(w) + + // Pre-build a schedule of 100 steps + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + textValue := "Burst log line " + strconv.Itoa(i%10) + ": Lorem ipsum dolor sit amet..." + sched = append(sched, tuitest.Mutate(func() { + p := w.Params() + p.TextValue = textValue + w.Set(p) + })) + // Render/Tick once every 5 mutations (20 FPS throttle) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + sched = append(sched, tuitest.Tick(50*time.Millisecond)) + } + } + + harness.Run(b, tuitest.NewScribeAdaptedModel(comp, size), sched) +}
diff --git a/internal/pkg/tui2/compose/BUILD.bazel b/internal/pkg/tui2/compose/BUILD.bazel index 2ea41fb..18f9d3d 100644 --- a/internal/pkg/tui2/compose/BUILD.bazel +++ b/internal/pkg/tui2/compose/BUILD.bazel
@@ -51,6 +51,7 @@ "box_grid_test.go", "box_row_test.go", "clipping_box_test.go", + "compose_benchmark_test.go", "composition_test.go", "distribution_memo_test.go", "framed_window_test.go",
diff --git a/internal/pkg/tui2/compose/compose_benchmark_test.go b/internal/pkg/tui2/compose/compose_benchmark_test.go new file mode 100644 index 0000000..fa40cc7 --- /dev/null +++ b/internal/pkg/tui2/compose/compose_benchmark_test.go
@@ -0,0 +1,195 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package compose + +import ( + "fmt" + "testing" + + "github.com/bazelbuild/rsclient/internal/pkg/layout" + "github.com/bazelbuild/rsclient/internal/pkg/tui2" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/atoms" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/tuitest" + + _ "github.com/bazelbuild/rsclient/internal/pkg/testsetup" +) + +// --- Helper Functions --- + +func buildNestedTUIOverlay(depth int, leaf *atoms.WrappedText) tui2.Component { + // Wrap the static background in a Component wrapper to enable immediate, O(1) short-circuit caching! + bg := tui2.NewComponent(atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: "STATIC BACKGROUND LAYER OF COMPLEX OVERLAY SECTIONS", + })) + + var current tui2.BoxView = leaf + for i := 0; i < depth; i++ { + area := layout.Rect{ + X: layout.Span{Offset: 2, Size: 40}, + Y: layout.Span{Offset: 1, Size: 10}, + } + // Wrap each nested layer in a Component node to grant it independent revision frame-caching. + current = tui2.NewComponent(NewOverlayBox(current, bg, area)) + } + return current.(tui2.Component) +} + +// --- Large Grid Layout (Layout Complexity) --- + +// BenchmarkTableBlock_StaticGrid profiles the full set of TUI models on a 100x10 table. +func BenchmarkTableBlock_StaticGrid(b *testing.B) { + rows := generateMockRows(100, 10) + size := layout.Size{Width: 120, Height: 100} + h := tuitest.NewBenchmarkHarness(size) + tb := NewTableBlock(rows) + + h.RunAllModels(b, tui2.NewComponent(tb), tuitest.BenchmarkSchedule{tuitest.Render()}) +} + +// --- Viewport Scaling & Boundary Culling --- + +// BenchmarkTableBlock_ViewportCulling profiles boundary culling performance scaling over different row counts. +func BenchmarkTableBlock_ViewportCulling(b *testing.B) { + for _, rows := range []int{10, 100, 1000} { + b.Run(fmt.Sprintf("%dRows", rows), func(b *testing.B) { + mockRows := generateMockRows(rows, 10) + size := layout.Size{Width: 80, Height: 24} + h := tuitest.NewBenchmarkHarness(size) + tb := NewTableBlock(mockRows) + + h.RunAllModels(b, tui2.NewComponent(tb), tuitest.BenchmarkSchedule{tuitest.Render()}) + }) + } +} + +// --- High-Frequency Partial Cache Invalidation --- + +// BenchmarkBoxColumn_SelectiveInvalidation profiles TUI cache invalidation and redraw overhead under partial dirty updates. +func BenchmarkBoxColumn_SelectiveInvalidation(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + + wTextSlice := make([]*atoms.WrappedText, 50) + var children []tui2.BoxView + for i := 0; i < 50; i++ { + w := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: fmt.Sprintf("Log row %d: OK", i), + }) + wTextSlice[i] = w + children = append(children, w) + } + col := NewBoxColumn(children...) + + // Pre-build a schedule of 100 simulation steps + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + idx := i % 50 + counter := 0 + sched = append(sched, tuitest.Mutate(func() { + counter++ + textValue := fmt.Sprintf("Log row %d: CRITICAL UPDATE %d", idx, counter) + p := wTextSlice[idx].Params() + p.TextValue = textValue + wTextSlice[idx].Set(p) + })) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + } + } + + harness.RunAllModels(b, tui2.NewComponent(col), sched) +} + +// --- Depth-Based Hierarchy Scaling (Nested Overlay Boxes) --- + +// BenchmarkTUIOverlay_Mutation profiles TUI's depth-based scaling under leaf mutations across different hierarchy depths. +func BenchmarkTUIOverlay_Mutation(b *testing.B) { + for _, depth := range []int{2, 5, 10} { + b.Run(fmt.Sprintf("Depth%d", depth), func(b *testing.B) { + size := layout.Size{Width: 80, Height: 24} + harness := tuitest.NewBenchmarkHarness(size) + leaf := atoms.NewWrappedText(atoms.TextSegmentParams{TextValue: "Initial Leaf Text"}) + comp := buildNestedTUIOverlay(depth, leaf) + + var sched tuitest.BenchmarkSchedule + for i := 0; i < 100; i++ { + textValue := fmt.Sprintf("Leaf Mutation Iteration: %d", i) + sched = append(sched, tuitest.Mutate(func() { + p := leaf.Params() + p.TextValue = textValue + leaf.Set(p) + })) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + } + } + harness.RunAllModels(b, comp, sched) + }) + } +} + +// --- Dynamic Area Occlusion Culling (Transparent Layers) --- + +// BenchmarkTransparentLayers_Culling profiles the dynamic area occlusion culling and stacking throughput +// of TransparentLayers under varying numbers of floating layers. +func BenchmarkTransparentLayers_Culling(b *testing.B) { + for _, layerCount := range []int{1, 3, 5} { + b.Run(fmt.Sprintf("%dLayers", layerCount), func(b *testing.B) { + size := layout.Size{Width: 100, Height: 40} + harness := tuitest.NewBenchmarkHarness(size) + + // 1. Static background filling the canvas + bg := tui2.NewComponent(atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: "STATIC PROJECTOR BED BACKGROUND ZONE FILLING THE ENTIRE CANVAS MULTIPLE TIMES OVER", + })) + + tl := NewTransparentLayers(bg) + + // 2. Create overlapping floating layers + layerLeaves := make([]*atoms.WrappedText, layerCount) + for i := 0; i < layerCount; i++ { + leaf := atoms.NewWrappedText(atoms.TextSegmentParams{ + TextValue: fmt.Sprintf("Floating Layer Opaque Modal Element %d", i), + }) + layerLeaves[i] = leaf + comp := tui2.NewComponent(leaf) + // Overlapping rectangles + area := layout.Rect{ + X: layout.Span{Offset: 5 + i*2, Size: 40}, + Y: layout.Span{Offset: 2 + i*2, Size: 10}, + } + tl.AddLayer(comp, area) + } + + // 3. Sequential top-most layer mutations and redraw triggers + var sched tuitest.BenchmarkSchedule + topLeaf := layerLeaves[layerCount-1] + counter := 0 + for i := 0; i < 100; i++ { + sched = append(sched, tuitest.Mutate(func() { + counter++ + p := topLeaf.Params() + p.TextValue = fmt.Sprintf("Top Layer Mutated Step: %d", counter) + topLeaf.Set(p) + })) + if i%5 == 0 { + sched = append(sched, tuitest.Render()) + } + } + + harness.RunAllModels(b, tui2.NewComponent(tl), sched) + }) + } +}
diff --git a/internal/pkg/tui2/tuitest/BUILD.bazel b/internal/pkg/tui2/tuitest/BUILD.bazel index 5675948..1ff861b 100644 --- a/internal/pkg/tui2/tuitest/BUILD.bazel +++ b/internal/pkg/tui2/tuitest/BUILD.bazel
@@ -18,6 +18,7 @@ name = "tuitest", srcs = [ "assert.go", + "benchmark_harness.go", "interactive_assert.go", "mocks.go", "revision_harness.go", @@ -40,6 +41,7 @@ name = "tuitest_test", srcs = [ "assert_test.go", + "benchmark_harness_test.go", "interactive_assert_test.go", "mocks_test.go", "revision_harness_test.go",
diff --git a/internal/pkg/tui2/tuitest/benchmark_harness.go b/internal/pkg/tui2/tuitest/benchmark_harness.go new file mode 100644 index 0000000..e0cd9ff --- /dev/null +++ b/internal/pkg/tui2/tuitest/benchmark_harness.go
@@ -0,0 +1,326 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package tuitest provides declarative, sequence-based testing tools for TUI components. +// +// BenchmarkHarness provides a specialized, ultra-high-speed simulation environment +// optimized for Go testing.B micro-benchmarks. By pre-allocating execution schedules +// and running Scribe drawing passes directly on memory buffers, it measures layout +// and drawing throughput with absolute microsecond accuracy. +package tuitest + +import ( + "io" + "testing" + "time" + + "github.com/bazelbuild/rsclient/internal/pkg/layout" + "github.com/bazelbuild/rsclient/internal/pkg/tui2" + + tea "github.com/charmbracelet/bubbletea" +) + +// opCode defines the schedule operation type. +type opCode int + +const ( + // opMutate triggers a custom pre-compiled state mutation closure. + opMutate opCode = iota + // opRender triggers a full Scribe drawing pass. + opRender + // opTick advances the simulation clock and dispatches a TickMsg. + opTick +) + +// BenchmarkStep represents a single, highly-optimized step in a simulation schedule. +// +// Performance and Design Note: +// Unlike TestStep (which uses functional closures for maximum expressive power in unit tests), +// BenchmarkStep uses an opcode-based enum (opCode) and a flat struct. +// This choice is critical for high-resolution benchmarking for three reasons: +// 1. Avoids Indirect Calls: Invoking a function closure prevents Go compiler inlining +// and adds 1-3ns of indirect call overhead, which would distort micro-benchmarks. +// The opcode switch is optimized by the compiler into direct branches or jump tables. +// 2. Zero Heap Allocations: Functional closures often cause captured variables to escape +// to the heap. The opcode design ensures 0 allocations inside the b.N loop. +// 3. Deterministic Clock: The virtual clock advancement (opTick) is centrally managed +// within the interpreter loop, guaranteeing uniform and correct time-stepping. +type BenchmarkStep struct { + op opCode + duration time.Duration // Duration to advance the clock for opTick + mutate func() // Pre-allocated state mutation closure for opMutate +} + +// TUIBenchmarkModel represents a specific TUI model representation configured for benchmarking, +// exposing the execution hooks required by the simulation loop. +// +// Benchmarking Note: +// This abstraction is intended solely for benchmarking purposes under testing.B. It +// allows the benchmark suite to take a common, base TUI Component and dynamically +// configure and construct the desired "variant of the thing-under-test" (e.g., pure +// Scribe, adapted Scribe, pure Stitch, or traditional stitched model) so they can +// be executed head-to-head under the exact same simulation schedule. +type TUIBenchmarkModel interface { + // Render executes the layout, compilation, and drawing phases for the target. + // Depending on the implementation, this either paints cells to a 2D FrameBuffer (Scribe), + // compiles stateless line slices (StitchLines), or flattens the result into a fully + // serialized string (adapted tea.Model.View()). + Render() + + // Tick advances the virtual clock and propagates a TickMsg through the target's update/behavior loop. + Tick(clock time.Time) +} + +// ScribePureModel (Alternative A) implements TUIBenchmarkModel for pure Scribe 2D painting to a FrameBuffer. +type ScribePureModel struct { + comp tui2.Component + sCtx *tui2.ScribeContext +} + +var _ TUIBenchmarkModel = (*ScribePureModel)(nil) + +func (t *ScribePureModel) Render() { + t.comp.Scribe(*t.sCtx) +} + +func (t *ScribePureModel) Tick(clock time.Time) { + if t.comp.Behavior != nil { + t.comp.Behavior.Update(tui2.TickMsg(clock)) + } + t.sCtx.WallClock = clock +} + +// NewScribePureModel constructs a ScribePureModel for pure 2D Scribe painting to a canvas. +// It bypasses the entire string-serialization layer, measuring raw coordinate-level +// painting, clipping, and drawing directly onto the 2D FrameBuffer. +func NewScribePureModel(comp tui2.Component, size layout.Size) *ScribePureModel { + canvas := tui2.NewFrameBuffer(size) + sCtx := tui2.ScribeContext{Canvas: canvas} + comp.Scribe(sCtx) // Prime cache + return &ScribePureModel{comp: comp, sCtx: &sCtx} +} + +// ScribeAdaptedModel (Alternative B) implements TUIBenchmarkModel for Scribe adapted to standard TEA View(). +type ScribeAdaptedModel struct { + model tea.Model +} + +var _ TUIBenchmarkModel = (*ScribeAdaptedModel)(nil) + +func (t *ScribeAdaptedModel) Render() { + _ = t.model.View() +} + +func (t *ScribeAdaptedModel) Tick(clock time.Time) { + t.model, _ = t.model.Update(tui2.TickMsg(clock)) +} + +// NewScribeAdaptedModel constructs a ScribeAdaptedModel for Scribe adapted to standard TEA View(). +// It measures the realistic, end-to-end performance of Scribe inside a standard +// Bubble Tea application loop, including the complete FrameBuffer-to-string serialization tax. +func NewScribeAdaptedModel(comp tui2.Component, size layout.Size) *ScribeAdaptedModel { + model := tui2.Adapt(comp) + model, _ = model.Update(tea.WindowSizeMsg{Width: size.Width, Height: size.Height}) + return &ScribeAdaptedModel{model: model} +} + +// StitchPureModel (Alternative C) implements TUIBenchmarkModel for pure stateless StitchLines compilation. +type StitchPureModel struct { + comp tui2.Component + size layout.Size +} + +var _ TUIBenchmarkModel = (*StitchPureModel)(nil) + +func (t *StitchPureModel) Render() { + _ = tui2.StitchLines(t.comp, t.size) +} + +func (t *StitchPureModel) Tick(clock time.Time) { + if t.comp.Behavior != nil { + t.comp.Behavior.Update(tui2.TickMsg(clock)) + } +} + +// NewStitchPureModel constructs a StitchPureModel for pure stateless StitchLines compilation. +// It compiles the stateless TUI layout and returns raw line slices ([]string) directly, +// measuring pure stateless rendering without the final root-level strings.Join overhead. +func NewStitchPureModel(comp tui2.Component, size layout.Size) *StitchPureModel { + return &StitchPureModel{comp: comp, size: size} +} + +// StitchAdaptedModel (Alternative D) implements TUIBenchmarkModel for StitchLines with root-level strings.Join. +type StitchAdaptedModel struct { + model tea.Model +} + +var _ TUIBenchmarkModel = (*StitchAdaptedModel)(nil) + +func (t *StitchAdaptedModel) Render() { + _ = t.model.View() +} + +func (t *StitchAdaptedModel) Tick(clock time.Time) { + t.model, _ = t.model.Update(tui2.TickMsg(clock)) +} + +// NewStitchAdaptedModel constructs a StitchAdaptedModel for StitchLines with root-level strings.Join. +// It measures the realistic, end-to-end performance of a traditional, stateless +// string-stitching layout model adapted to a standard TEA View() string loop. +func NewStitchAdaptedModel(comp tui2.Component, size layout.Size, memoized bool) *StitchAdaptedModel { + model := tui2.NewStitchedModel(comp, tui2.StitchParams{Size: size, Memoized: memoized}) + return &StitchAdaptedModel{model: model} +} + +// TeaModelTarget adapts a standard, traditional bubbletea tea.Model +// to the TUIBenchmarkModel interface, managing its state updates and string rasterization. +type TeaModelTarget struct { + model tea.Model +} + +var _ TUIBenchmarkModel = (*TeaModelTarget)(nil) + +// Render executes a View call on the standard Bubble Tea model. +func (t *TeaModelTarget) Render() { + _ = t.model.View() +} + +// Tick advances the virtual clock and updates the Bubble Tea model with a TickMsg. +func (t *TeaModelTarget) Tick(clock time.Time) { + t.model, _ = t.model.Update(tui2.TickMsg(clock)) +} + +// NewTeaModelTarget adapts a standard, traditional bubbletea tea.Model to the TUIBenchmarkModel interface. +func NewTeaModelTarget(model tea.Model) *TeaModelTarget { + return &TeaModelTarget{model: model} +} + +// run executes the instruction's operations against the given target. +func (inst *BenchmarkStep) run(target TUIBenchmarkModel, clock *time.Time) { + switch inst.op { + case opMutate: + if inst.mutate != nil { + inst.mutate() + } + case opRender: + target.Render() + case opTick: + *clock = clock.Add(inst.duration) + target.Tick(*clock) + } +} + +// BenchmarkSchedule is a pre-allocated sequence of simulation steps. +type BenchmarkSchedule []BenchmarkStep + +// Mutate creates a BenchmarkStep that executes the given closure. +// +// Typical examples of mutations/updates to pass to Mutate include: +// - Mutating an atomic state parameter (e.g., advancing a progress bar's percentage, or changing a status text): +// Mutate(func() { +// progressBar.SetPercent(0.75) +// }) +// - Appending or updating data in a list or table (e.g., adding a new log row): +// Mutate(func() { +// logList.Append("New log event") +// }) +// - Simulating user-driven selection/navigation (e.g., moving the active row in a spreadsheet): +// Mutate(func() { +// spreadsheet.SelectRow(4) +// }) +func Mutate(fn func()) BenchmarkStep { + return BenchmarkStep{op: opMutate, mutate: fn} +} + +// Render creates a BenchmarkStep that triggers the target's active layout, compilation, +// and rendering pipeline (e.g., Scribe's 2D canvas drawing, Stitch's stateless line-slice +// generation, or full adapted string serialization). +func Render() BenchmarkStep { + return BenchmarkStep{op: opRender} +} + +// Tick creates a BenchmarkStep that advances the clock and triggers an update. +func Tick(d time.Duration) BenchmarkStep { + return BenchmarkStep{op: opTick, duration: d} +} + +// BenchmarkHarness standardizes performance and heap allocation testing of TUI components +// under Go's testing.B framework. It eliminates repetitive boilerplate for setting up +// mock canvases, ScribeContexts, and adapter bridges on hot paths. +type BenchmarkHarness struct { + size layout.Size +} + +// NewBenchmarkHarness creates a new harness configured with the specified terminal rendering size. +func NewBenchmarkHarness(size layout.Size) *BenchmarkHarness { + return &BenchmarkHarness{size: size} +} + +// RunAllModels executes the given simulation schedule against all five standard TUI benchmark models +// (ScribePure, ScribeAdapted, StitchPure, StitchAdapted, and StitchAdaptedMemoized) as sub-benchmarks under b. +func (h *BenchmarkHarness) RunAllModels(b *testing.B, comp tui2.Component, sched BenchmarkSchedule) { + b.Run("ScribePure", func(b *testing.B) { + h.Run(b, NewScribePureModel(comp, h.size), sched) + }) + b.Run("ScribeAdapted", func(b *testing.B) { + h.Run(b, NewScribeAdaptedModel(comp, h.size), sched) + }) + b.Run("StitchPure", func(b *testing.B) { + h.Run(b, NewStitchPureModel(comp, h.size), sched) + }) + b.Run("StitchAdapted", func(b *testing.B) { + h.Run(b, NewStitchAdaptedModel(comp, h.size, false), sched) + }) + b.Run("StitchAdaptedMemoized", func(b *testing.B) { + h.Run(b, NewStitchAdaptedModel(comp, h.size, true), sched) + }) +} + +// Run executes a pre-allocated simulation schedule against any TUIBenchmarkModel. +// It manages virtual time advancement (dispatching TickMsg to Update) and rendering +// completely allocation-free. It initializes the virtual clock outside the benchmark +// loop to ensure monotonic time progression across all iterations. +func (h *BenchmarkHarness) Run(b *testing.B, target TUIBenchmarkModel, sched BenchmarkSchedule) { + b.ResetTimer() + b.ReportAllocs() + + clock := time.Date(2026, 8, 6, 12, 0, 0, 0, time.UTC) + for i := 0; i < b.N; i++ { + for j := range sched { + inst := &sched[j] + inst.run(target, &clock) + } + } +} + +// RunTeaView measures the rendering throughput of a standard bubbletea tea.Model. +// This allows for head-to-head benchmarking of modernized components (bridged via tui2.Adapt) +// against traditional, pure tea.Model implementations using the exact same Bubble Tea signature. +func (h *BenchmarkHarness) RunTeaView(b *testing.B, model tea.Model) { + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + _ = model.View() + } +} + +// RunTUIRenderTo measures the absolute throughput of our zero-allocation output path +// using the tui2.RenderTo utility, writing directly to io.Discard. +func (h *BenchmarkHarness) RunTUIRenderTo(b *testing.B, root tui2.Component) { + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + _ = tui2.RenderTo(io.Discard, root, h.size) + } +}
diff --git a/internal/pkg/tui2/tuitest/benchmark_harness_test.go b/internal/pkg/tui2/tuitest/benchmark_harness_test.go new file mode 100644 index 0000000..8d74789 --- /dev/null +++ b/internal/pkg/tui2/tuitest/benchmark_harness_test.go
@@ -0,0 +1,91 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package tuitest_test + +import ( + "testing" + + "github.com/bazelbuild/rsclient/internal/pkg/layout" + "github.com/bazelbuild/rsclient/internal/pkg/tui2" + "github.com/bazelbuild/rsclient/internal/pkg/tui2/tuitest" + + _ "github.com/bazelbuild/rsclient/internal/pkg/testsetup" +) + +// BenchmarkBenchmarkHarness_RunScribe verifies that our BenchmarkHarness +// can successfully run scribe passes under the Go benchmark loop. +func BenchmarkBenchmarkHarness_RunScribe(b *testing.B) { + mock := &tuitest.MockBoxView{ + X: layout.Fixed(5), + Y: layout.Fixed(5), + } + size := layout.Size{Width: 10, Height: 5} + h := tuitest.NewBenchmarkHarness(size) + h.Run(b, tuitest.NewScribePureModel(tui2.NewComponent(mock), size), tuitest.BenchmarkSchedule{tuitest.Render()}) +} + +// BenchmarkBenchmarkHarness_RunMutation verifies that our BenchmarkHarness +// can successfully run dynamic mutation loops under the Go benchmark loop. +func BenchmarkBenchmarkHarness_RunMutation(b *testing.B) { + mock := &tuitest.MockBoxView{ + X: layout.Fixed(5), + Y: layout.Fixed(5), + } + size := layout.Size{Width: 10, Height: 5} + h := tuitest.NewBenchmarkHarness(size) + + var currentI int + sched := tuitest.BenchmarkSchedule{ + tuitest.Mutate(func() { + mock.SetRevision(uint64(currentI + 1)) + currentI++ + }), + tuitest.Render(), + } + h.Run(b, tuitest.NewScribePureModel(tui2.NewComponent(mock), size), sched) +} + +// BenchmarkBenchmarkHarness_RunTeaAdaptedScribe verifies that our BenchmarkHarness +// can successfully run Scribe passes adapted to the Bubble Tea View loop. +func BenchmarkBenchmarkHarness_RunTeaAdaptedScribe(b *testing.B) { + mock := &tuitest.MockBoxView{ + X: layout.Fixed(5), + Y: layout.Fixed(5), + } + size := layout.Size{Width: 10, Height: 5} + h := tuitest.NewBenchmarkHarness(size) + h.Run(b, tuitest.NewScribeAdaptedModel(tui2.NewComponent(mock), size), tuitest.BenchmarkSchedule{tuitest.Render()}) +} + +// BenchmarkBenchmarkHarness_RunTeaAdaptedMutation verifies that our BenchmarkHarness +// can successfully run dynamic mutation loops adapted to the Bubble Tea View loop. +func BenchmarkBenchmarkHarness_RunTeaAdaptedMutation(b *testing.B) { + mock := &tuitest.MockBoxView{ + X: layout.Fixed(5), + Y: layout.Fixed(5), + } + size := layout.Size{Width: 10, Height: 5} + h := tuitest.NewBenchmarkHarness(size) + + var currentI int + sched := tuitest.BenchmarkSchedule{ + tuitest.Mutate(func() { + mock.SetRevision(uint64(currentI + 1)) + currentI++ + }), + tuitest.Render(), + } + h.Run(b, tuitest.NewScribeAdaptedModel(tui2.NewComponent(mock), size), sched) +}