Refactor: Unified column layout engine

[gregeva]

Problem

ltl's bar graph column layout evolved from a simple 3-column system to a complex multi-column layout supporting up to 9 visible columns, vertical separators, compound columns (legend), and conditional visibility. The implementation grew incrementally, resulting in 5 overlapping data structures (%graph_width, @printed_column_widths, @printed_column_names, @printed_column_spacing, and two competing count variables) populated piecemeal across ~170 lines. Graph widths use hardcoded percentage tables (65/35, 62/21/17, etc.) that must be manually authored for each column count.

This causes bugs when adding columns (#27), blocks new column types (#26), and makes the rendering code fragile through cumulative $printed_chars tracking.

Solution

Replace the fragmented layout system with a unified column layout engine where each column is defined once with all its properties: name, sizing type, width, spacing, visibility, color, and rendering behavior.

Key Requirements

• Column types: Fixed (timestamp, latency), content-driven (legend), proportional (all graph columns), separator (│), and compound (legend as counts + spacing + rates sub-columns with spanning header)
• Algorithmic width distribution: Replace hardcoded percentage tables with a focus/secondary algorithm that works for any column count
• First-class visibility: Each column carries a visible flag; hiding triggers automatic redistribution
• Fill-to-width rendering: Each column fills its allocated width independently, eliminating $printed_chars tracking
• Color as column property: Color identity carried in column definition, not derived from position
• Separators as layout elements: Modeled explicitly with adjacency visibility rules

Constraints

• Output must be pixel-identical to current behavior for all option combinations
• No Perl OO/classes — use idiomatic data structures
• No new visual features — pure structural refactor

Detailed Requirements

See features/column-layout-refactor.md for the full requirements document covering all sections: column types, layout engine, headers, separators, colors, legend decomposition, rendering, testing strategy, and risks.

Approach

1. Requirements document (this issue + feature file) ✅
2. Prototype to validate design
3. Iterate on prototype
4. Phased implementation

Related Issues

• Blocks Feature: Concurrent session metric calculated and graphed like active threads #26 — Session metric column (adding a new column type should be trivial with the new system)
• Fixes Bug: Character display wraps due to improper width calculation for additional field with -tpa https #27 — Array mismatch bug (root cause eliminated by single source of truth)
• Enables Bug: Consolidate color gradient definitions shared between heatmap and histogram #64 — Color consolidation (column-carries-color approach)

[gregeva]

Status Update - 2026-01-31

This issue was created during investigation of #27 (character display wrapping with -tpa).

Background

During debugging of #27, we discovered the root cause is architectural: the column layout system uses 5 different overlapping data structures with inconsistent indexing. A minimal fix for #27 would be fragile and likely cause regressions.

Recommended Approach

Option C: Incremental Cleanup was selected as the recommended approach:

1. Create add_column() helper function that always adds to all three arrays together
2. Replace all direct push @printed_column_* statements with add_column() calls
3. Consolidate $graph_count and $graph_column_count into one variable
4. Add validation that array lengths match before using them

Blocking

• Blocks: Bug: Character display wraps due to improper width calculation for additional field with -tpa https #27 - Cannot be properly fixed until this refactor is complete

Next Steps

When ready to implement:

1. Create feature branch 33-column-layout-refactor
2. Create features/column-layout-refactor.md with detailed plan
3. Implement Phase 1 (helper function) first with thorough testing
4. Proceed through phases incrementally with validation at each step

[gregeva]

Starting requirements analysis, prototype and implementation planning.

Branch: 33-column-layout-refactor
Feature doc: features/column-layout-refactor.md