Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

verifying-rendering-changes

Proves that a change to a renderer did what was meant and nothing else, when a refactor or a speed-up must not change a pixel, a change is meant to change the rendered image, a history-dependent or temporal effect is added, a screenshot or golden-image test fails, or "did this change anything on screen?" is asked. Names the kind of change, captures the same views before it, compares decoded pixels byte for byte where frames are deterministic and elsewhere within a tolerance set from the build's own run-to-run variation, keys stored references by everything their pixels depend on, captures only paused, settled frames, and reports measured differences with crops. Use with three.js WebGPU renderers, or any renderer with screenshot tests, whenever rendering code, a shader, a pass, a material, lighting or a capture tool changes. It hands a build that disagrees with itself to diagnosing-nondeterministic-frames, a defect of unknown cause to diagnosing-visual-defects and frame time to measurin

HuberyLL · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add HuberyLL/ponlai --skill verifying-rendering-changes

About this skill


name: verifying-rendering-changes description: Proves that a change to a renderer did what was meant and nothing else, when a refactor or a speed-up must not change a pixel, a change is meant to change the rendered image, a history-dependent or temporal effect is added, a screenshot or golden-image test fails, or "did this change anything on screen?" is asked. Names the kind of change, captures the same views before it, compares decoded pixels byte for byte where frames are deterministic and elsewhere within a tolerance set from the build's own run-to-run variation, keys stored references by everything their pixels depend on, captures only paused, settled frames, and reports measured differences with crops. Use with three.js WebGPU renderers, or any renderer with screenshot tests, whenever rendering code, a shader, a pass, a material, lighting or a capture tool changes. It hands a build that disagrees with itself to diagnosing-nondeterministic-frames, a defect of unknown cause to diagnosing-visual-defects and frame time to measuring-performance-changes.

Verifying rendering changes

The rendered image can change for many reasons besides the change under test: a frame that has not settled, another browser build, a tool that changed together with the code, or noise that the GPU adds. A comparison that cannot tell these apart either passes a regression or fails a correct change, and both end up waved through. This skill fixes what the comparison means before you make the change, so you can trust its answer.

Rules most often broken without notice

  • Name the kind of change before you edit (step 1). The kind decides the comparison. If you choose the comparison after you see the result, you fit the test to the answer.
  • Capture "before" from the commit that the change starts from. Use the same views, size, pixel ratio, quality, browser build and capture tools as "after". A capture taken later, on another build or with a changed tool, is not "before".
  • A change that must not alter the rendered image is byte-exact wherever frames are deterministic. "Looks the same" or "only a few pixels" is a failure: either the change has a bug, or it changes the image and that part belongs in its own commit.
  • Use a tolerance only for frames that cannot be deterministic by construction, such as temporal accumulation, or the GPU splitting work on its own. Set the tolerance by comparing the same build with itself, and prove that it fails planted regressions (step 4). Never widen a tolerance, or recapture until a run passes, to make a failure go away.
  • Capture a frame only when the app reports that the frame is final (paused and settled). A fixed wait or frame count passes or fails by chance on a busy GPU.
  • Compare decoded pixels, never image files: encoders differ.
  • Read crops of the subjects as well as the whole frame. Report a mean over the frame (including a perceptual metric's mean), but never use it to pass a change: it hides a missing small object.
  • A view proves nothing about what it does not show. Zero difference counts only in views that show what the change touches.
  • Report numbers: the pixel count over each level, the largest difference, and where it lies, per view and per crop.
  • If the same build disagrees with itself, this skill does not apply: stop and use diagnosing-nondeterministic-frames.

The project's facts: the binding

Steps marked "(binding: X)" need facts about the project: which checks follow which kind of change, its views and test scenes, its capture, comparison and reference tools, its test mode, how a history-dependent effect is registered, and how results are reported. When you reach the step, read section X of docs/bindings/verifying-rendering-changes.md. If the project's AGENTS.md or CLAUDE.md names another file for this skill, that file wins.

If there is no binding, find each fact in the project: its screenshot or golden-image tests, a paused or test mode in its URL options or debug globals, its image-diff tool, and the checks its commit hooks run. Ask the user for what you cannot find, above all whether frames are deterministic and who accepts new reference images. When the work ends, offer to write what you found as the binding, one section per step.

Workflow

Copy this checklist and keep it up to date:

- [ ] 1. Name the kind of change
- [ ] 2. Choose the views and checks, cheapest first
- [ ] 3. Capture before
- [ ] 4. Compare
- [ ] 5. Judge a change meant to change the rendered image
- [ ] 6. A history-dependent or temporal effect
- [ ] 7. Run the regular checks and report

1. Name the kind of change (binding: Kinds)

KindExamplesWhat proves it
Must not change a pixelA refactor, a rename, a move between files, a speed-up, a tool change, a cleanupBit-identical frames in views that show the changed code; evidence that needs no GPU first (identical generated shader text, CPU checks)
Meant to change the rendered imageA new effect, a material, a light or look value, a defect fixThe intended difference, measured where it was meant; bit-identical frames elsewhere
Different contentNew random seeds, a regenerated or grown world, other geometryPixels cannot line up: judge by eye and by region statistics, not by pixel difference
History-dependent or temporalAccumulation over frames, exposure adaptation, temporal anti-aliasing, a simulation stepped per frameStep 6, then the comparison of the kind above that it falls under

If a change is of two kinds (a speed-up that also changes the image), split it into two commits and verify each as its kind. Some correct changes can alter a few pixels on some GPUs: a change to how work is split into draws, or to the order in which shaders are first built. The binding names these cases. Measure and report them; do not call them identical.

2. Choose the views and checks, cheapest first (binding: Views

Read the complete source ↗