[jonluca]

Summary

Requesting another size from the same still extractor can return the first image's dimensions, and nearby snapshot requests can return a cached frame from the wrong side of a frame boundary. Cache keys now include requested dimensions and preserve exact snapshot request times.

What changed

• Include thumbnail width and both snapshot bounds in the cache key.
• Keep thumbnail position buckets and existing per-mode LRU count limits.
• Reuse snapshots only for an identical requested time; any fixed time bucket can cross a frame boundary.
• Add regression coverage for dimensions, adjacent requests, mode isolation and size-variant eviction; document the cache contract.

Test plan

• Device / OS: Apple M4 Max, macOS 27.0.1, Xcode 27.1.
• Source media: deterministic CGImage cache payloads; related frame/still/scrub tests include their embedded and generated local media fixtures.
• Results: focused FrameCache tests passed (9 tests); related frame/still/scrub/documentation selection passed (326 Swift Testing cases in 138 suites plus 78 XCTest cases). The regression tests fail in four cases with upstream cache behavior (9 assertions) and pass after the fix. The final focused run also passed 26 documentation XCTest cases.
• swift build --target AetherEngine -Xswiftc -warnings-as-errors, the documentation link checker and git diff --check passed.

Related: #871 adds a preview mode independently; both PRs touch the shared cache implementation and may need a small reconciliation depending on merge order.

Checklist

• CHANGELOG.md updated
• Commit follows Conventional Commits
• The fix lives in the engine
• Public API is unchanged; cache behavior is documented

[Copilot]

🟢 Approval recommended

The cache keys consistently reflect extraction parameters, preserve existing limits, and have focused regression coverage with no blocking issues identified.

No open issues 🎉

What changed in this PR

Fixes still-extraction cache reuse so one FrameExtractor can serve multiple sizes without returning incorrectly sized images, while keeping adjacent snapshot requests distinct.

Changes:

• Include requested dimensions and exact snapshot times in cache keys.
• Preserve thumbnail time buckets and existing per-mode cache limits.
• Add regression tests and document the corrected cache behavior.

File	Description
Tests/​AetherEngineTests/​FrameCacheTests.swift	Tests exact snapshot times, dimension variants, and shared-limit eviction.
Sources/​AetherEngine/​FrameExtractor/​FrameExtractor.swift	Passes dimensions to cache lookups and inserts; clarifies a cache-bypass comment.
Sources/​AetherEngine/​FrameExtractor/​FrameCache.swift	Adds dimension-aware keys and exact snapshot-time matching.
docs/​api.md	Documents size-aware caching and per-mode time matching.
CHANGELOG.md	Records the still-extraction cache fixes.

_{Review effort: Balanced}