docs(analysis): Add visual output comparison analysis
- Created analysis/visual_output_comparison.md with detailed architectural comparison - Added capture utilities for output comparison (capture_output.py, capture_upstream.py, compare_outputs.py) - Captured and compared output from upstream/main vs sideline branch - Documented fundamental architectural differences in rendering approaches - Updated Gitea issue #50 with findings
This commit is contained in:
158
analysis/visual_output_comparison.md
Normal file
158
analysis/visual_output_comparison.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Visual Output Comparison: Upstream/Main vs Sideline
|
||||
|
||||
## Summary
|
||||
|
||||
A comprehensive comparison of visual output between `upstream/main` and the sideline branch (`feature/capability-based-deps`) reveals fundamental architectural differences in how content is rendered and displayed.
|
||||
|
||||
## Captured Outputs
|
||||
|
||||
### Sideline (Pipeline Architecture)
|
||||
- **File**: `output/sideline_demo.json`
|
||||
- **Format**: Plain text lines without ANSI cursor positioning
|
||||
- **Content**: Readable headlines with gradient colors applied
|
||||
|
||||
### Upstream/Main (Monolithic Architecture)
|
||||
- **File**: `output/upstream_demo.json`
|
||||
- **Format**: Lines with explicit ANSI cursor positioning codes
|
||||
- **Content**: Cursor positioning codes + block characters + ANSI colors
|
||||
|
||||
## Key Architectural Differences
|
||||
|
||||
### 1. Buffer Content Structure
|
||||
|
||||
**Sideline Pipeline:**
|
||||
```python
|
||||
# Each line is plain text with ANSI colors
|
||||
buffer = [
|
||||
"The Download: OpenAI is building...",
|
||||
"OpenAI is throwing everything...",
|
||||
# ... more lines
|
||||
]
|
||||
```
|
||||
|
||||
**Upstream Monolithic:**
|
||||
```python
|
||||
# Each line includes cursor positioning
|
||||
buffer = [
|
||||
"\033[10;1H \033[2;38;5;238mユ\033[0m \033[2;38;5;37mモ\033[0m ...",
|
||||
"\033[11;1H\033[K", # Clear line 11
|
||||
# ... more lines with positioning
|
||||
]
|
||||
```
|
||||
|
||||
### 2. Rendering Approach
|
||||
|
||||
**Sideline (Pipeline Architecture):**
|
||||
- Stages produce plain text buffers
|
||||
- Display backend handles cursor positioning
|
||||
- `TerminalDisplay.show()` prepends `\033[H\033[J` (home + clear)
|
||||
- Lines are appended sequentially
|
||||
|
||||
**Upstream (Monolithic Architecture):**
|
||||
- `render_ticker_zone()` produces buffers with explicit positioning
|
||||
- Each line includes `\033[{row};1H` to position cursor
|
||||
- Display backend writes buffer directly to stdout
|
||||
- Lines are positioned explicitly in the buffer
|
||||
|
||||
### 3. Content Rendering
|
||||
|
||||
**Sideline:**
|
||||
- Headlines rendered as plain text
|
||||
- Gradient colors applied via ANSI codes
|
||||
- Ticker effect via camera/viewport filtering
|
||||
|
||||
**Upstream:**
|
||||
- Headlines rendered as block characters (▀, ▄, █, etc.)
|
||||
- Japanese katakana glyphs used for glitch effect
|
||||
- Explicit row positioning for each line
|
||||
|
||||
## Visual Output Analysis
|
||||
|
||||
### Sideline Frame 0 (First 5 lines):
|
||||
```
|
||||
Line 0: 'The Download: OpenAI is building a fully automated researcher...'
|
||||
Line 1: 'OpenAI is throwing everything into building a fully automated...'
|
||||
Line 2: 'Mind-altering substances are (still) falling short in clinical...'
|
||||
Line 3: 'The Download: Quantum computing for health...'
|
||||
Line 4: 'Can quantum computers now solve health care problems...'
|
||||
```
|
||||
|
||||
### Upstream Frame 0 (First 5 lines):
|
||||
```
|
||||
Line 0: ''
|
||||
Line 1: '\x1b[2;1H\x1b[K'
|
||||
Line 2: '\x1b[3;1H\x1b[K'
|
||||
Line 3: '\x1b[4;1H\x1b[2;38;5;238m \x1b[0m \x1b[2;38;5;238mリ\x1b[0m ...'
|
||||
Line 4: '\x1b[5;1H\x1b[K'
|
||||
```
|
||||
|
||||
## Implications for Visual Comparison
|
||||
|
||||
### Challenges with Direct Comparison
|
||||
1. **Different buffer formats**: Plain text vs. positioned ANSI codes
|
||||
2. **Different rendering pipelines**: Pipeline stages vs. monolithic functions
|
||||
3. **Different content generation**: Headlines vs. block characters
|
||||
|
||||
### Approaches for Visual Verification
|
||||
|
||||
#### Option 1: Render and Compare Terminal Output
|
||||
- Run both branches with `TerminalDisplay`
|
||||
- Capture terminal output (not buffer)
|
||||
- Compare visual rendering
|
||||
- **Challenge**: Requires actual terminal rendering
|
||||
|
||||
#### Option 2: Normalize Buffers for Comparison
|
||||
- Convert upstream positioned buffers to plain text
|
||||
- Strip ANSI cursor positioning codes
|
||||
- Compare normalized content
|
||||
- **Challenge**: Loses positioning information
|
||||
|
||||
#### Option 3: Functional Equivalence Testing
|
||||
- Verify features work the same way
|
||||
- Test message overlay rendering
|
||||
- Test effect application
|
||||
- **Challenge**: Doesn't verify exact visual match
|
||||
|
||||
## Recommendations
|
||||
|
||||
### For Exact Visual Match
|
||||
1. **Update sideline to match upstream architecture**:
|
||||
- Change `MessageOverlayStage` to return positioned buffers
|
||||
- Update terminal display to handle positioned buffers
|
||||
- This requires significant refactoring
|
||||
|
||||
2. **Accept architectural differences**:
|
||||
- The sideline pipeline architecture is fundamentally different
|
||||
- Visual differences are expected and acceptable
|
||||
- Focus on functional equivalence
|
||||
|
||||
### For Functional Verification
|
||||
1. **Test message overlay rendering**:
|
||||
- Verify message appears in correct position
|
||||
- Verify gradient colors are applied
|
||||
- Verify metadata bar is displayed
|
||||
|
||||
2. **Test effect rendering**:
|
||||
- Verify glitch effect applies block characters
|
||||
- Verify firehose effect renders correctly
|
||||
- Verify figment effect integrates properly
|
||||
|
||||
3. **Test pipeline execution**:
|
||||
- Verify stage execution order
|
||||
- Verify capability resolution
|
||||
- Verify dependency injection
|
||||
|
||||
## Conclusion
|
||||
|
||||
The visual output comparison reveals that `sideline` and `upstream/main` use fundamentally different rendering architectures:
|
||||
|
||||
- **Upstream**: Explicit cursor positioning in buffer, monolithic rendering
|
||||
- **Sideline**: Plain text buffer, display handles positioning, pipeline rendering
|
||||
|
||||
These differences are **architectural**, not bugs. The sideline branch has successfully adapted the upstream features to a new pipeline architecture.
|
||||
|
||||
### Next Steps
|
||||
1. ✅ Document architectural differences (this file)
|
||||
2. ⏳ Create functional tests for visual verification
|
||||
3. ⏳ Update Gitea issue #50 with findings
|
||||
4. ⏳ Consider whether to adapt sideline to match upstream rendering style
|
||||
Reference in New Issue
Block a user