12bf992b

Add text coverage comparison design

a73x   2026-04-09 07:43

---

diff --git a/docs/superpowers/specs/2026-04-09-text-coverage-comparison-design.md b/docs/superpowers/specs/2026-04-09-text-coverage-comparison-design.md
new file mode 100644
index 0000000..36c96c7
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-09-text-coverage-comparison-design.md
@@ -0,0 +1,97 @@
# Text Coverage Comparison Design

## Goal

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.

## Scope

This change only adds a comparison tool for evaluating text-edge rendering.

It does not change:
- the default terminal rendering path,
- the configured font family or size,
- glyph rasterization mode,
- atlas packing,
- terminal behavior outside the comparison mode.

## Requirements

- Add a new explicit comparison mode, launched by CLI flag.
- Reuse the existing Vulkan/font/atlas path instead of building a second renderer.
- Render the same specimen text in multiple side-by-side panels within one window.
- Include the current rendering as a baseline panel.
- Include at least three non-default coverage variants for comparison.
- Keep the font family and size sourced from the existing config module.
- Restrict the first pass to shader-side coverage shaping only.

## Design

### Comparison Mode

Add a new command-line mode such as `--text-compare`.

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.

### Panel Layout

Render a four-panel layout in one window.

Panels:
- baseline: current shader behavior,
- mild coverage shaping,
- medium coverage shaping,
- near-crisp coverage shaping.

Each panel should show the same specimen text and use the same background, foreground, font family, and font size.

### Specimen Text

Use a fixed specimen that exercises common terminal shapes:

```text
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
{}[]()/\|,.;:_-=+
~/code/rad/waystty $ zig build test
```

This keeps the comparison focused on edge quality, density, punctuation, and mixed terminal-like content.

### Coverage Variants

Implement the comparison by adding a small shader control path that adjusts how atlas coverage maps to visible alpha.

The initial set should remain coverage-only:
- identity,
- mild steepening,
- medium steepening,
- near-crisp thresholded curve.

Do not add alternate FreeType load flags or bitmap-generation modes in this first pass.

### Renderer Integration

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.

This keeps the experiment close to production behavior and makes later adoption of one chosen curve straightforward.

## Error Handling

If the configured font cannot be resolved, comparison mode should fail the same way as normal startup.

If shader plumbing for coverage variants fails to compile or initialize, the build should fail rather than silently falling back to the current shader.

## Risks

- Adding shader controls may require a small renderer interface change, even though the mode is experimental.
- A side-by-side tool can make panel layout logic larger than the actual coverage experiment if not kept narrow.
- Visual comparison still depends on compositor scaling and display settings, so results are comparative rather than absolute.

## Validation

- `zig build test --summary all`
- `zig build`
- Manual launch of the comparison mode
- Visual comparison of the four panels in one window