feat: cost-aware Flutter decoding and request-scoped Surface teardown

[q760440238]

Refs #62.

Summary

• keep ordinary PNG/GIF/WebP on Flutter's codec; native remains for custom Drawable/private decoders
• add encoded-byte single-flight and deterministic disk-key lookup before index scan completion
• reserve visible scheduler slots and budget network/decode work by encoded bytes / decoded pixels
• add pending cache-write byte limits and atomic temporary landing for one oversized entry
• add decodeFit (contain, cover, exact) and configurable decode-size buckets
• defer cache writes and LRU touches until after the first frame and batch maintenance
• narrow waitForPresent to teardown and scope release generations by engine + request
• remove the global completer-release dependency so native resources follow the final listener
• add a natural-size Wrap benchmark, native Glide baseline, 20 GIPHY WebPs, scripts, and raw results

Measured results

Huawei VOG-AL10, Android 10 / SDK 29.

• cold first-frame P50/P95: PowerImage 41.967/46.382 ms, ExtendedImage 42.390/63.427 ms, CachedNetworkImage 75.667/78.328 ms
• 20 animated WebPs, 3 isolated runs: PowerImage CPU P50 132.824% vs ExtendedImage 134.780% (-1.45%); PSS 158,923 vs 160,596 KB (-1.04%); frame P95 18.126 vs 18.293 ms (-0.91%)
• Native Glide remains well ahead: 81.431% CPU P50, 55,144 KB PSS, 7,580 KB Graphics; this gap is documented rather than hidden
• 100-Surface release/rebuild P50: 962.568 -> 448.988 ms (-53.36%); maximum 2,337.305 -> 464.893 ms (-80.11%)

The GPU field is a DVFS-frequency proxy only; this device kernel does not expose GPU utilization.

Rejected experiment

A short-loop decoded-frame-cache prototype increased CPU P50 from 125.670% to 137.177% (+9.16%, worse). It was removed from production code; the smoke data remains in the PR for auditability.

Validation

• flutter test: 90 passed
• flutter test test/file_raw_bytes_cache_test.dart: 16 passed
• Android :power_image:testDebugUnitTest: passed
• Android macrobenchmark releaseAndRebuild100NativeSurfaces: 5/5 iterations passed
• flutter build apk --release: passed
• git diff --check: clean
• flutter analyze --no-fatal-warnings: no errors (existing warnings/info remain)

Raw benchmark JSON and the PowerShell sampling harness are under example/android/macrobenchmark/results/2026-08-04-VOG-AL10/ and example/tool/steady20_benchmark.ps1.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

YuQian seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}