feat: add model download controller

[leehack]

Summary

• Add ModelDownloadController, a framework-agnostic app-facing helper that turns model cache/download operations into stable task snapshots.
• Support resolving, cache-check, downloading, verifying, ready, failed, and cancelled states with cooperative cancel/retry behavior.
• Redact credential-bearing URLs from error snapshots and keep cached entries validated through ensureModel() before ready.
• Document the controller in the model lifecycle guide, chat app docs, recent releases page, and changelog.

Fixes #135

Production-readiness scope

• Users can build UI download flows around ModelDownloadController.snapshots without depending on Flutter types.
• Supported paths: existing ModelDownloadManager implementations, remote cache checks, download progress callbacks, ready/failure/cancelled states, retry after failure/cancellation, and caller-visible redacted error messages.
• Unsupported path: caller-supplied ModelLoadOptions.cancelToken is rejected because the controller owns cooperative cancellation for the active task.
• Existing APIs remain compatible: the change is additive and exports the new controller through the existing download manager barrel.

Review Notes

• Independent review found and the PR fixes: URL redaction delimiter leaks, external cancel-token ownership, cache preflight validation semantics, and a docs snippet issue.
• Cancellation classification is token-based, so cancellation-like manager/server failures remain failed states unless the controller actually cancelled the task.
• No manual Copilot review was requested; relying on repository automation for initial review.
• Addressed Copilot follow-up review comments: disposed DioExceptionType.cancel now reports a paused cancellation, and the chat app adapter rejects unsupported sha256 options before cache/download success paths.
• Copilot review threads are resolved after the follow-up fix commit.

Test Plan

• dart analyze
• dart test test/unit/core/models/download --reporter compact
• dart test -p vm -j 1 --exclude-tags local-only --reporter compact — all passed, 1 skipped
• npm run build in website/
• git diff --check origin/main...HEAD
• Static scan: hardcoded secrets 0, dangerous exec 0, raw URL logs 0
• flutter analyze in example/chat_app/
• flutter test in example/chat_app/
• flutter test test/model_download_controller_adapter_test.dart test/manage_models_screen_download_test.dart in example/chat_app/
• CI on head 2e3dcfaa17cc16da4b65e3d5e904e85a89b45cb6: Analyze & Lint, Docs Build Check, Linux/Web, macOS, Windows, Native Prompt Reuse Parity

[Copilot]

Pull request overview

Adds a framework-agnostic ModelDownloadController API for turning model cache/download operations into app-facing lifecycle snapshots, with cancellation, retry, cache-hit handling, verification, and redacted failure messages.

Changes:

• Introduces ModelDownloadController, task stages, immutable snapshots, and exports them through the existing download manager barrel.
• Adds unit tests covering cache hits/misses, validation, cancellation, retry, and URL redaction.
• Documents the new controller in lifecycle, chat app, recent releases, and changelog docs.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/src/core/models/download/model_download_controller.dart	Adds the controller, snapshot model, lifecycle stage enum, cancellation/retry handling, and error URL redaction.
lib/src/core/models/download/model_download_manager.dart	Exports the new controller through the existing download manager barrel.
test/unit/core/models/download/model_download_controller_test.dart	Adds unit coverage for controller behavior and failure redaction.
website/docs/guides/model-lifecycle.md	Adds lifecycle guide documentation and usage example for the controller.
website/docs/examples/chat-app.md	Notes how the chat app download UX relates to the new controller.
website/docs/changelog/recent-releases.md	Adds recent-release documentation for the controller.
CHANGELOG.md	Adds changelog entry for the new model download UX helper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 92.56198% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.50%. Comparing base (5d0a701) to head (2e3dcfa).

Files with missing lines	Patch %	Lines
...ore/models/download/model_download_controller.dart	92.56%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #149      +/-   ##
==========================================
+ Coverage   78.32%   78.50%   +0.17%     
==========================================
  Files          75       76       +1     
  Lines        9764     9885     +121     
==========================================
+ Hits         7648     7760     +112     
- Misses       2116     2125       +9     

Flag	Coverage Δ
unittests	78.50% <92.56%> (+0.17%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.