Skip to content

docs: add a README product shot and regenerate the screenshot set - #111

Merged
prokopto-dev merged 2 commits into
masterfrom
ao/nparseplus-28/readme-product-shot
Aug 14, 2026
Merged

docs: add a README product shot and regenerate the screenshot set#111
prokopto-dev merged 2 commits into
masterfrom
ao/nparseplus-28/readme-product-shot

Conversation

@prokopto-dev

Copy link
Copy Markdown
Owner

Two jobs: give README.md a real product shot, and work out which of the
existing screenshots are still true.

Refs #110 (the remaining human-only shots).

1. The README product shot

cap_product_shot composes the Event Overlay alert banner, the maps window,
spell timers and the DPS meter onto one canvas. It lives in phase B, where
create_app already builds all four, and it is a normal target — --only readme--product-shot works, and it regenerates with everything else rather
than rotting as a hand-assembled one-off.

The synthetic data is now shared with the individual shots rather than
duplicated: seed_spell_timers, seed_fights and seed_alert were lifted
out of their cap_* functions and are called by both paths, so the product
shot and window--spell-timers.png cannot drift apart.

Layout notes: each window keeps its own natural height and the row is
top-aligned. Stretching them to a common height padded the panels with empty
chrome that read as a rendering fault; unequal heights over the backdrop read
as what they are, separate windows. The banner is 215px because below ~200
the overlay has room for the headline only and the timer bars silently
vanish from the shot.

It is not the hero, and the checklist now says so in both places.
home--overview.png stays manual — it is a photograph over a live client,
which is the one claim a composed image cannot make. Neither should be used
to "fix" the other.

README gets the image plus a one-line caption and nothing else (another
worker owns README prose).

2. The audit — one real bug

The settings pages were captured by hardcoded sidebar row index. A
"DPS Meter" page landed at row 5 after those indices were written, shifting
every later one by one. Rerunning the tool as it stood would have written the
DPS page as settings--maps.png, Maps as settings--windows.png, … Sharing
as settings--advanced.png, and never captured Advanced at all — each saved
under a filename that lies about its contents. A missing screenshot degrades
to an honest placeholder; a mislabelled one does not.

Pages are selected by title now, and an unknown title raises instead of
silently capturing whatever page happened to be showing.
settings--dps-meter.png is captured for the first time.

Everything automatable was regenerated and looked at. The five oldest
(window--console, window--trigger-editor, window--macro-editor,
window--trigger-activity, window--update-available) dated from before the
chrome layer and still showed default-Fusion blue selection bands against the
current gold. The rest predated the DPS Meter sidebar row, the new app mark,
or the #103/#108 alert work.

Two content fixes found on the way:

  • window--update-available.png advertised v1.12.0 over v1.10.0 — nine
    releases stale, reading as a screenshot of some other program. It uses real
    2.9.x release notes now.
  • settings--general.png published the generating machine's worktree path
    (…/worktrees/nparseplus/nparseplus-24/.screenshots-scratch) as the EQ Logs
    directory. Shows an example path now. The install dir is deliberately left
    empty: filling it sends Advanced's Night Vision panel into
    Not a directory: …, and a docs screenshot of an error state is worse than
    one of a neutral first run.

On #107

#107 (alerts rendering blank) is closed — fixed by be1a9b1 (#108), which
is in master at v2.9.2. I verified it in the pixels rather than taking the
label's word: window--event-overlay.png and the product shot both render
kicker, headline, rule and both draining bars. The overlay shots are safe to
publish. The alert sample deliberately uses the split
"Gorenaire — ENRAGED" form, which exercises the exact path that regressed.

Checklist

docs/dev-notes/screenshot-checklist.md was internally inconsistent — it
claimed "29 of 31 automated" in one paragraph and "30 wanted, 28 captured"
two sections later, and its settings table listed neither Appearance nor DPS
Meter. Rewritten: 35 wanted, 33 automated and current, 2 manual, plus the two
staleness traps recorded so the next person hits neither.

It also flags that settings--appearance.png and settings--dps-meter.png
are captured but referenced by no docs page, so nothing renders them — a
prose gap for whoever owns those pages, not a capture gap.

Verification

  • QT_QPA_PLATFORM=offscreen uv run pytest2516 passed, 2 deselected
  • uv run ruff check . — clean; uv run ruff format . — 419 files unchanged
  • Every regenerated PNG opened and inspected; before/after compared for the
    pre-chrome ones

Risks / follow-ups

  • Qt's rasterizer is not byte-stable across PySide6 versions, so all 32
    existing PNGs show as modified even where the pixels are near-identical.
    The diff is large by nature.
  • Expect a small rebase against the parallel README-prose work; this touches
    only the image + caption lines.

🤖 Generated with Claude Code

Two things, both about the screenshots telling the truth.

A composed product shot for README.md. `cap_product_shot` lays the Event
Overlay alert banner, the maps window, spell timers and the DPS meter onto
one canvas in phase B, where the full app already has all four. It is a new
target like any other, so it regenerates with the rest and cannot end up
depicting a UI that no longer ships. The synthetic data is shared with the
individual shots rather than copied — `seed_spell_timers`, `seed_fights` and
`seed_alert` are now called by both — so the two can never disagree.

This is NOT the docs hero. `home--overview.png` stays manual: it is a
photograph over a live client, which is the one claim a composed image
cannot make. The checklist says so, so neither gets "fixed" with the other.

Then the audit. The settings pages were captured by hardcoded sidebar ROW
INDEX. A "DPS Meter" page landed at row 5 after those indices were written,
shifting every later one: rerunning the tool would have saved the DPS page
as settings--maps.png and Sharing as settings--advanced.png, and never
captured Advanced at all — each under a filename that lied about it. They
are selected by page title now, and an unknown title stops the run instead
of silently capturing whatever was showing. settings--dps-meter.png is new.

Every automated shot was regenerated and looked at. The oldest five
(console, trigger editor, macro editor, trigger activity, update dialog)
predated the chrome layer and still showed default-Fusion blue selection
bands. Also fixed en route: the update dialog advertised v1.12.0 over
v1.10.0 nine releases after the fact (real 2.9.x notes now), and
settings--general leaked the generating machine's worktree path as the EQ
Logs directory. The install dir is deliberately left empty — filling it
sends Advanced's Night Vision panel into "Not a directory: …", and a docs
screenshot of an error state is worse than one of a neutral first run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@prokopto-dev prokopto-dev left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved — I found no correctness, security, or maintainability issues in the README product shot, regenerated screenshot set, and capture-tool updates. I did not run the screenshot generator or test suite, per review constraints.

@prokopto-dev
prokopto-dev merged commit f51b643 into master Aug 14, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant