a73x

12bf992b

Add text coverage comparison design

a73x   2026-04-09 07:43

Commit message
Add text coverage comparison design
docs/superpowers/specs/2026-04-09-text-coverage-comparison-design.md
Old New
@@ -0,0 +1,97 @@
1 # Text Coverage Comparison Design
2
3 ## Goal
4
5 Add a dedicated comparison mode that renders the same text specimen across multiple coverage variants in one window so text sharpness can be judged visually before changing the default renderer.
6
7 ## Scope
8
9 This change only adds a comparison tool for evaluating text-edge rendering.
10
11 It does not change:
12 - the default terminal rendering path,
13 - the configured font family or size,
14 - glyph rasterization mode,
15 - atlas packing,
16 - terminal behavior outside the comparison mode.
17
18 ## Requirements
19
20 - Add a new explicit comparison mode, launched by CLI flag.
21 - Reuse the existing Vulkan/font/atlas path instead of building a second renderer.
22 - Render the same specimen text in multiple side-by-side panels within one window.
23 - Include the current rendering as a baseline panel.
24 - Include at least three non-default coverage variants for comparison.
25 - Keep the font family and size sourced from the existing config module.
26 - Restrict the first pass to shader-side coverage shaping only.
27
28 ## Design
29
30 ### Comparison Mode
31
32 Add a new command-line mode such as `--text-compare`.
33
34 This mode should reuse the existing smoke-test style startup path in `src/main.zig`: create a Wayland window, initialize the Vulkan context, load the configured font, build the glyph atlas, upload instances, and render a fixed frame for inspection.
35
36 ### Panel Layout
37
38 Render a four-panel layout in one window.
39
40 Panels:
41 - baseline: current shader behavior,
42 - mild coverage shaping,
43 - medium coverage shaping,
44 - near-crisp coverage shaping.
45
46 Each panel should show the same specimen text and use the same background, foreground, font family, and font size.
47
48 ### Specimen Text
49
50 Use a fixed specimen that exercises common terminal shapes:
51
52 ```text
53 abcdefghijklmnopqrstuvwxyz
54 ABCDEFGHIJKLMNOPQRSTUVWXYZ
55 0123456789
56 {}[]()/\|,.;:_-=+
57 ~/code/rad/waystty $ zig build test
58 ```
59
60 This keeps the comparison focused on edge quality, density, punctuation, and mixed terminal-like content.
61
62 ### Coverage Variants
63
64 Implement the comparison by adding a small shader control path that adjusts how atlas coverage maps to visible alpha.
65
66 The initial set should remain coverage-only:
67 - identity,
68 - mild steepening,
69 - medium steepening,
70 - near-crisp thresholded curve.
71
72 Do not add alternate FreeType load flags or bitmap-generation modes in this first pass.
73
74 ### Renderer Integration
75
76 The comparison mode should stay on the existing renderer pipeline. The preferred mechanism is a small per-panel parameter passed into the fragment path so the same glyph atlas and instance format can be reused.
77
78 This keeps the experiment close to production behavior and makes later adoption of one chosen curve straightforward.
79
80 ## Error Handling
81
82 If the configured font cannot be resolved, comparison mode should fail the same way as normal startup.
83
84 If shader plumbing for coverage variants fails to compile or initialize, the build should fail rather than silently falling back to the current shader.
85
86 ## Risks
87
88 - Adding shader controls may require a small renderer interface change, even though the mode is experimental.
89 - A side-by-side tool can make panel layout logic larger than the actual coverage experiment if not kept narrow.
90 - Visual comparison still depends on compositor scaling and display settings, so results are comparative rather than absolute.
91
92 ## Validation
93
94 - `zig build test --summary all`
95 - `zig build`
96 - Manual launch of the comparison mode
97 - Visual comparison of the four panels in one window