cached_video_thumbnail 0.1.1

High-performance video thumbnail engine: cached, scheduled, cancellable thumbnail generation from asset, file, and network videos.

0.1.1

No changes to the Dart/native runtime; this release adds repo-distributed AI coding-assistant support and maintainer tooling.

• Installable agent plugin for Claude Code and OpenAI Codex, hosted in this repository (agent-plugin/cached-video-thumbnail, one shared skills tree, dual manifests, repo-root marketplace catalogs for both clients). Install commands are in the README.
• Four package-specific skills: integrate-feed-thumbnails (feed wiring, physical-pixel specs, priorities, prefetch, audit checklist), diagnose-thumbnail-issues (error codes, negative cache, platform quirks, metrics triage), mock-thumbnail-engine (hermetic tests with an injectable fake extractor), and migrate-from-video-thumbnail (video_thumbnail / flutter_video_thumbnail_plus / get_thumbnail_video / fc_native_video_thumbnail conversions), plus a read-only thumbnail-integration-auditor agent for Claude Code.
• Repository guidance for coding agents (AGENTS.md, imported by CLAUDE.md) covering validation gates, generated-file rules, the error-code contract, and the release process.
• CI now validates the plugin tree and version sync (tool/validate_agent_plugin.dart); the plugin tree is excluded from the pub archive (.pubignore), which is why the package itself is unchanged.

0.1.0

Initial release: a disk-cached, scheduled, cancellable video thumbnail engine for Android and iOS, designed for infinite feeds on low-end devices.

• Thumbnails from Flutter bundle assets, local files, and http(s) URLs (with optional request headers), requested with getThumbnail (a plain Future) or thumbnail (a cancellable request handle).
• ThumbnailSpec controls the output: fit-within sizing that preserves aspect ratio and never upscales, frame position (clamped into the video's duration), nearest-keyframe or exact-frame seeking, JPEG or PNG encoding, and JPEG quality.
• Persistent disk cache with deterministic keys, atomic writes, and LRU eviction capped by total bytes and entry count; hits are served from an in-memory index with no decoding and no platform-channel round trip. A file's cache identity includes its size and modification time, so editing a local video invalidates its thumbnails automatically.
• Request scheduling built for scroll performance: visible, normal, and prefetch priority bands, newest-first dispatch within a band, a bounded number of concurrent native extractions, coalescing of identical requests, per-request cancellation, priority bumping, and per-request timeouts.
• Negative caching: recent failures are remembered for a configurable TTL and fail fast instead of re-hammering a broken source during scroll.
• VideoThumbnailImage, an ImageProvider for any Image widget: its identity covers source and spec so Flutter's ImageCache deduplicates identical tiles, generation is cancelled when the last listener detaches, and externally purged or corrupted cache files are evicted and regenerated on the next resolve.
• Cache management: prefetch for warming, evict for a single source, and clearCache for everything.
• Every failure is a ThumbnailException carrying a classified ThumbnailErrorCode (asset/file not found, network, unsupported media, timeout, cancelled, ...); failures are never silently swallowed into nulls or booleans.
• Observability: a metrics snapshot (requests, cache hits, coalesced joins, extractions, failures, queue depth, and extraction and queue-wait percentiles) plus an onEvent hook for structured engine events.
• Engine tuning through ThumbnailEngineConfig: extraction concurrency, default timeout, negative-cache TTL, cache size caps, and the default spec.
• Hermetic test support: ThumbnailEngine.forTesting with an injectable ThumbnailExtractor and cache directory, so app tests run without native code.