fix(texture): keep coordinate UVs out of atlas regions

[snowyukitty]

Description

Numeric source-rectangle lookups currently create named regions, while addUVs() adds coordinate aliases for every frame. Cropped images and repeating patterns therefore change the same dictionary that animation consumers enumerate. Identical rectangles on different atlas pages can also reuse the previous page's UVs.

This separates numeric UV caching from named regions. Parsed frames seed the private numeric cache with their existing UV arrays; arbitrary rectangles are cached without registering frames. The last-lookup cache checks the active atlas dictionary and is invalidated when addUVs() replaces a rectangle. Both GPU pattern consumers now use numeric lookups. The batchers already receive UV values, so their interfaces stay the same.

Compatibility: getUVs(name) now throws a descriptive error for an unknown name. Use getUVs(x, y, width, height) instead of a coordinate string, or explicitly define a named region with addRegion(). Explicitly authored names containing commas still work.

13 new browser regressions cover dictionary purity, frame UV reuse, alternating crops, missing names, named-coordinate collisions, atlas page changes, replacement, intrinsic video dimensions, packed rotated/trimmed frames, and both GPU pattern consumers. Real WebGL pixel checks cover cropped images and repeating patterns; WebGPU's changed consumer is exercised with the real atlas and a recording batcher, rather than a WebGPU pixel test.

Current upstream integration at 6c5b8ee1c7af1d593becd3eed109f5536f93f2ff

Merged current master through the 20.9.0 release to resolve the changelog conflict. All released changelog text is preserved verbatim; the pending atlas entry is under the unreleased 20.10 section. The UV implementation and regression tests are unchanged, and testing/release decisions remain with the maintainer.

Fresh contained validation on Linux: pnpm lint, pnpm build, and pnpm test --run pass. The main browser suite reports 8039 passed and 11 skipped across 329 test files, including all 81 texture/atlas cases. The same focused suite with this PR's tests on current unmodified upstream gives 10 failures and 71 passes.

Original validation at cdcbecb2d1f6925b189ff9c70d81acb46dce8941

• pnpm lint
• pnpm build
• pnpm test — 7933 passed, 11 skipped
• pnpm -F @melonjs/matter-adapter test — 226 passed
• pnpm -F @melonjs/planck-adapter test — 221 passed
• pnpm -F @melonjs/debug-plugin test — 23 passed
• Focused texture/atlas suite: 81 passed. Applying the new regressions to the unmodified base gives 10 failures and 3 passes; the cropped/repeating pixel assertions already pass on the base, followed by the failing dictionary-mutation assertions.

A Chromium CPU microbenchmark interleaved the original and changed TextureAtlas.getUVs() implementations for 20 rounds of 1,000,000 lookups per workload after warm-up, alternating run order and checking equal UV checksums. Median milliseconds per round:

Workload	Base	Candidate
Same frame	3.4	7.8
Alternating 128 frames	141.6	61.7
Alternating 128 fractional crops	255.0	64.6

The same-frame path pays a few extra nanoseconds per lookup for the atlas check; alternating rectangles avoid string keys and region searches. These are lookup timings on one Chromium/Linux container, not an FPS measurement. Cache retention remains unchanged in principle: previously encountered rectangles stay cached for the atlas lifetime.

Type of change

• Bug fix

Checklist

• I have read the Contributing Guide
• pnpm lint passes
• pnpm test --run passes on the integrated source; original adapter results and CPU benchmark remain separately anchored above
• Regression tests cover the changes
• pnpm build succeeds

Related issues

Refs #1281. This addresses the remaining atlas lookup work on the current renderer, whose batchers already consume UVs directly.

The adapter-suite results and CPU microbenchmark above remain anchored to the original head named above; they were not rerun for this changelog-only conflict resolution. The current main-suite results are reported separately. Windows/macOS runtime and WebGPU pixel tests were not run locally.

[obiot]

Hi @snowyukitty, thanks for this one as well ! This is bit more tricky, so I'll keep it for the next 20.10 release as it needs proper testing and non regression test.