From 8ce04be0bab0f117e4b19f93ea3fd73124a5313c Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 13:19:30 +0200
Subject: [PATCH 1/6] feat(canvas): opt-in local cache for plugin Canvases
 (#473)

---
 CLAUDE.md                                     |   2 +-
 docs/features/plugins.md                      |   2 +
 docs/features/ui.md                           |   2 +-
 src-tauri/crates/app/src/commands/canvas.rs   | 110 +++++++++++++++++-
 src-tauri/crates/app/src/lib.rs               |   3 +
 src-tauri/crates/app/src/paths.rs             |   6 +
 src-tauri/crates/app/tauri.conf.json          |   4 +-
 .../views/settings/PluginOptions.tsx          |  92 ++++++++++++---
 src/components/views/settings/PluginsCard.tsx |   5 +-
 src/i18n/locales/ar.json                      |   7 ++
 src/i18n/locales/de.json                      |   7 ++
 src/i18n/locales/en.json                      |   7 ++
 src/i18n/locales/es.json                      |   7 ++
 src/i18n/locales/fr.json                      |   7 ++
 src/i18n/locales/hi.json                      |   7 ++
 src/i18n/locales/id.json                      |   7 ++
 src/i18n/locales/it.json                      |   7 ++
 src/i18n/locales/ja.json                      |   7 ++
 src/i18n/locales/ko.json                      |   7 ++
 src/i18n/locales/nl.json                      |   7 ++
 src/i18n/locales/pt-BR.json                   |   7 ++
 src/i18n/locales/pt.json                      |   7 ++
 src/i18n/locales/ru.json                      |   7 ++
 src/i18n/locales/tr.json                      |   7 ++
 src/i18n/locales/zh-CN.json                   |   7 ++
 src/i18n/locales/zh-TW.json                   |   7 ++
 src/lib/tauri/canvas.ts                       |  31 +++++
 src/lib/tauri/plugins.ts                      |   7 ++
 28 files changed, 355 insertions(+), 28 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a94d4f87..16c04e9a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,7 +88,7 @@ These bite you if you ignore them — they're the contract the rest of the codeb
 - **Track sync emit (Phase 4.d.0.3)**: the scanner pushes `entity: "track"` ops to the server for every new + re-emit track. [`sync::track_emit::emit_track_insert_in_tx`](src-tauri/crates/app/src/sync/track_emit.rs) is the entry point; the scanner wraps it via the private `emit_track_insert_from_extracted` shim ([`commands/scan.rs`](src-tauri/crates/app/src/commands/scan.rs)) so the "Brand-new track" and "existing track re-emit" branches share one wire shape. The skip-fast-path branch (mtime + hash unchanged) also emits — but ONLY when the path actually re-normalised `track_artist` rows (multi-artist count delta from a comma-joined → `";"`-split rewrite); cover + codec backfills are server-derived and don't need to round-trip. Wire shape mirrors the server's `apply::track::insert` (phase 4.d.0.2): `entity_id` is the **file_path** (per-library natural identity — keying on file_hash would break tag-edit re-emit because lofty rewrites embedded metadata frames so the hash changes while the path doesn't). `payload.library_canonical_id` carries the tenant scope; `payload.file_hash` + `payload.file_modified` ride as fields (the latter lets a peer device that shares the same drive skip its own slow-path on the next scan). `payload.added_at` carries the row's ORIGINAL import timestamp on every re-emit (the brand-new branch uses `now`, the update + skip branches read it from the existing row) — a re-emit must NOT bump the peer's `Recently added` ordering. The full audio metadata + `album_title?` / `album_artist_name?` / `is_compilation?` / `artists?: [String]` (the desktop's `";"`-split list — position derives from array index) round-trip. User-initiated track deletes call [`emit_track_delete_in_tx`](src-tauri/crates/app/src/sync/track_emit.rs): the duplicates UI ([`commands/duplicates.rs::delete_tracks`](src-tauri/crates/app/src/commands/duplicates.rs)) AND folder removal ([`commands/library.rs::remove_folder_from_library`](src-tauri/crates/app/src/commands/library.rs)) both emit per-row inside the same SQLite tx as the local DELETE. **Folder removal is NOT a server-side cascade** — the server has no `library_folder` entity, so without per-row emits the tracks linger as ghost rows under the still-live library until the library itself is dropped. Library removal IS server-side cascade (the apply pipeline drops the tracks when the parent `library + delete` op lands) — explicit per-track emits would be redundant + race the cascade. `is_available = 0` (file vanished but not user-deleted) deliberately does NOT emit — the track resurfaces on the next scan if the file reappears, and a noisy delete-then-insert pair would just churn the apply pipeline. **Remaining accumulation path**: a permanently-gone file under a still-live folder/library leaves a ghost row server-side; v1 accepts this, a server-side TTL reaper is the proper long-term fix. Every CRUD command that enqueues track ops calls `state.drain.notify()` post-commit (`scan_folder`, `rescan_library`, `import_paths`, `delete_tracks`, `remove_folder_from_library`) — matches the existing playlist/library convention, drain is edge-triggered.
 - **Non-frontend control surfaces go through [`player_actions`](src-tauri/crates/app/src/player_actions.rs)**: the tray menu, the OS media keys and the MPD server all need the same "advance the queue → `emit_track_changed` → `emit_queue_changed` → hand the track to the decoder" sequence the frontend gets from `commands::player`. That sequence was copy-pasted in `lib.rs` and `media_controls.rs` until #471 (the second copy was literally commented "Mirror of `lib.rs::spawn_next`") and the two had already drifted. Forgetting one emit leaves a surface showing the previous track, which is exactly the bug duplication kept producing — so a new surface calls `player_actions::{next, previous, play_at_index}` rather than re-deriving it. They're `async` and await rather than spawn: sync callers (souvlaki, tray) wrap in `tauri::async_runtime::spawn` themselves, async ones report the outcome back to their client.
 - **Adding a new player-bar action**: default it into the overflow ("⋯") menu via [`MoreActionsMenu`](src/components/player/MoreActionsMenu.tsx) first; promote to primary only when usage warrants it; add a Settings pin toggle if both modes make sense. See [`docs/features/ui.md`](docs/features/ui.md#player-bar-layout).
-- **Plugins load at runtime, distribution is a separate repo**: the wasmtime host ([`waveflow_core::plugin::runtime`](src-tauri/crates/core/src/plugin/runtime.rs)) loads WASM components at runtime from `<app-data>/waveflow/plugins/` (writable sideload) + `<resource>/plugins/` (installer-bundled, re-seeded at boot). The **store** ([`commands/plugin_store.rs`](src-tauri/crates/app/src/commands/plugin_store.rs)) is the install path: it fetches the curated catalogue from a source cascade (`waveflow.app/api/plugins/registry` → `raw.githubusercontent.com/InstaZDLL/waveflow-plugins/main/registry.json` → jsDelivr — same list, first that answers wins) and installs by downloading the entry's pinned GitHub release, **verifying `plugin.wasm`'s blake3 against the registry entry** (the registry, NOT the release, is the trusted pin — a compromised release fails the hash), sanity-checking the manifest id/version/world, then stage-swapping into the sideload root. The catalogue + each plugin live in **separate repos** ([`InstaZDLL/waveflow-plugins`](https://github.com/InstaZDLL/waveflow-plugins) + per-plugin repos) — never in this repo — so grey-area plugins carry no liability for the signed core and a takedown is one registry commit. Every registry fetch honours [`offline::is_offline()`](src-tauri/crates/app/src/offline.rs). Store UI is `PluginStoreCard` above `PluginsCard` under Settings → Plugins; i18n under `settings.pluginStore.*`. The `metadata` world is wired since Phase 3 (`waveflow:metadata@1.1.0`, same `/v1` manifest label): [`commands/motion_artwork.rs::fetch_album_motion_artwork`](src-tauri/crates/app/src/commands/motion_artwork.rs) fans `album-info` out to enabled metadata plugins for Apple-style animated covers (`motion-cover-url`), rendered as a muted-loop `<video>` overlay ([`MotionCoverOverlay`](src/components/player/MotionCoverOverlay.tsx) + [`useAlbumMotionArtwork`](src/hooks/useAlbumMotionArtwork.ts)) over the static cover in ImmersiveNowPlaying + NowPlayingPanel. The metadata bindgen reuses `source`'s `waveflow:host/*` types via bindgen `with:` (one set of host impls). Plugins return a directly-playable video URL (mp4 — the desktop webview has no HLS.js). **Opt-in local motion cache** (default OFF, `app_setting['motion_artwork.cache_enabled']`): when on, [`fetch_album_motion_artwork`](src-tauri/crates/app/src/commands/motion_artwork.rs) downloads the resolved mp4 into an app-wide LRU cache (`<app-data>/waveflow/motion_cache/`, hash-addressed by source URL, 1 GB cap, mtime-based eviction) and returns the LOCAL path — `MotionCoverOverlay` runs a non-`http(s)` src through `convertFileSrc` (the asset-protocol scope for `motion_cache/**` is declared in `tauri.conf.json`). OFF relies on the webview's transient HTTP cache. Toggle + size + clear live in a **per-plugin ⚙️ options panel** ([`PluginOptions`](src/components/views/settings/PluginOptions.tsx)) revealed inline under a plugin's row in `PluginsCard` — the gear shows for plugins with manifest options OR metadata-world (motion cache). Keeps the list short vs a stacked card per plugin. i18n `settings.motionArtwork.*`. **Generic plugin options** (Phase 2): a plugin declares `[[options]]` in `manifest.toml` (`key` / `type` bool·enum·text / `label` / `default` / `choices?` / `description?`, parsed + validated in [`manifest.rs`](src-tauri/crates/core/src/plugin/manifest.rs)); the user sets them in the ⚙️ panel via `get_plugin_options` / `set_plugin_option` ([`commands/plugins.rs`](src-tauri/crates/app/src/commands/plugins.rs)); the values persist in `<state_dir>/.plugin-config.json` ([`plugin_config`](src-tauri/crates/core/src/plugin/plugin_config.rs), the single source of truth — no `app_setting` row, excluded from the scratch quota) and reach the guest through the `waveflow:host/config.get-option` host import ([`HostCtx::config`](src-tauri/crates/core/src/plugin/runtime.rs), pinned at instantiate time, read-only from the guest). The config import is additive/backward-compatible — a plugin built without it still instantiates. The Apple plugin's `prefer_hevc` option (v0.2.0) is the first consumer. **Localized manifest strings** (issue #440): `plugin.description`, each option's `label`/`description` and a registry entry's `description` are [`LocalizedString`](src-tauri/crates/core/src/plugin/manifest.rs) — a plain string (unchanged, still valid verbatim) or a `{ lang -> text }` map. **Anything published to users must carry its translations in the sibling `*_i18n` field** (`description_i18n`, `label_i18n`), folded into the base field at parse time by `merge_localized_siblings` with the plain string taking the `en` slot: an older host ignores the unknown sibling and keeps rendering English. The **inline map form is not publishable** — a host predating this feature type-errors on the table, dropping the plugin, and for `registry.json` (one document every installed version fetches) it fails the whole catalogue decode across all three sources, so the store goes dark on that build; `min_app_version` can't rescue it because it's read after the decode. The host echoes the merged value untouched; the UI resolves it against the active i18next language via [`useLocalizedText`](src/hooks/useLocalizedText.ts). The fallback chain (exact → base language → `en` → any entry) is implemented **twice**, in `LocalizedString::resolve` and [`resolveLocalizedText`](src/lib/localizedText.ts) — change them together. **The `ui` world** (`waveflow:ui/v1`, issue #443 Part 1) lets a plugin render a custom view **without shipping React**: the guest returns a **JSON view descriptor** (sections/cards/images/action buttons) the host draws with native components — never HTML/JS/React, so no code injection. Exported `extension` interface = `manifest()` (sidebar mount point) + `render(path)` + `on-event(event, payload)`, each returning the descriptor string; an action round-trips through `on-event` and the plugin returns the **next full descriptor** (no diff protocol), while an `open-url` action is handled host-side and never reaches the guest. The `ui` bindgen reuses `source`'s host types via `with:` (one impl set) and adds one fresh import — **`waveflow:host/library.list-artists`**, a **redacted** read (names + aggregate track-count + opaque id ONLY, no file paths / per-track rows) gated by manifest permission `library.read_artists`, doubly clamped ([`MAX_LIBRARY_ARTISTS`](src-tauri/crates/core/src/plugin/host_impl.rs)) and **snapshot-injected** (the host queries the active profile async-side and hands the guest a ready list, so the guest never touches SQLite; local-only ⇒ works offline). The redaction is host-enforced: a plugin without the permission gets `Err("permission denied: library.read_artists")` even with the snapshot present. Commands [`list_ui_plugins` / `plugin_ui_render` / `plugin_ui_event`](src-tauri/crates/app/src/commands/plugins.rs); sidebar entries + routing build **dynamically** off `manifest()` keyed on plugin id (a trapping `manifest()` is skipped + logged, never blanks the nav). First consumer = **Release Radar** (separate repo [`InstaZDLL/waveflow-plugin-release-radar`](https://github.com/InstaZDLL/waveflow-plugin-release-radar), listed in the registry, `min_app_version` 1.8.0); the core carries only the world surface + a test-only, never-bundled [`plugins/ui-fixture/`](src-tauri/plugins/ui-fixture/) exercised by [`tests/plugin_ui.rs`](src-tauri/crates/core/tests/plugin_ui.rs). Frontend: a generic [`PluginUIView`](src/components/views/PluginUIView.tsx) draws the descriptor with native components (open-url actions via `openUrl`, event actions re-render); the sidebar renders one dynamic entry per enabled ui plugin off [`useUiPlugins`](src/hooks/useUiPlugins.ts) → `list_ui_plugins` (icon resolved from a curated lucide allowlist [`pluginIcons`](src/lib/pluginIcons.tsx), unknown ⇒ generic glyph); routing rides a `plugin-ui` `HistoryEntry` carrying the plugin id (keyed remount per plugin in `AppLayout`). i18n `pluginView.*` + `settings.plugins.permissions.libraryReadArtists` ×17. **The `canvas` world** (`waveflow:canvas/v1`, issue #473) is a per-track backdrop source: interface `provider` = `track-canvas(artist, title, album?, duration-ms?) -> result<option<canvas{url, entity-id?}>, string>`, host imports http/log/storage/config (**no** library). [`commands/canvas.rs::fetch_track_canvas`](src-tauri/crates/app/src/commands/canvas.rs) fans out to enabled canvas plugins (per-plugin lock + 20 s timeout), returns the first URL that passes the shared `motion_cache::is_safe_motion_url` SSRF guard, and is **fail-soft** (any plugin error/panic/timeout → logged + skipped, never breaks playback — the frontend falls down the precedence chain). Bindgen [`bindings::canvas`](src-tauri/crates/core/src/plugin/bindings.rs) reuses `source`'s host types via `with:` (no new host import); [`runtime::canvas_track_canvas`](src-tauri/crates/core/src/plugin/runtime.rs) instantiates + calls it. Frontend: [`useTrackCanvas`](src/hooks/useTrackCanvas.ts) tries the manual local Canvas then this command; [`CanvasStage`](src/components/player/CanvasStage.tsx) renders a local path via `convertFileSrc` and a remote URL directly. Test-only [`plugins/canvas-fixture/`](src-tauri/plugins/canvas-fixture/) (never bundled) exercised by [`tests/plugin_canvas.rs`](src-tauri/crates/core/tests/plugin_canvas.rs). First consumer = a separate **unsigned** Spotify Canvas plugin (grey-area of Spotify's Developer Terms, isolated exactly like the excluded YouTube path).
+- **Plugins load at runtime, distribution is a separate repo**: the wasmtime host ([`waveflow_core::plugin::runtime`](src-tauri/crates/core/src/plugin/runtime.rs)) loads WASM components at runtime from `<app-data>/waveflow/plugins/` (writable sideload) + `<resource>/plugins/` (installer-bundled, re-seeded at boot). The **store** ([`commands/plugin_store.rs`](src-tauri/crates/app/src/commands/plugin_store.rs)) is the install path: it fetches the curated catalogue from a source cascade (`waveflow.app/api/plugins/registry` → `raw.githubusercontent.com/InstaZDLL/waveflow-plugins/main/registry.json` → jsDelivr — same list, first that answers wins) and installs by downloading the entry's pinned GitHub release, **verifying `plugin.wasm`'s blake3 against the registry entry** (the registry, NOT the release, is the trusted pin — a compromised release fails the hash), sanity-checking the manifest id/version/world, then stage-swapping into the sideload root. The catalogue + each plugin live in **separate repos** ([`InstaZDLL/waveflow-plugins`](https://github.com/InstaZDLL/waveflow-plugins) + per-plugin repos) — never in this repo — so grey-area plugins carry no liability for the signed core and a takedown is one registry commit. Every registry fetch honours [`offline::is_offline()`](src-tauri/crates/app/src/offline.rs). Store UI is `PluginStoreCard` above `PluginsCard` under Settings → Plugins; i18n under `settings.pluginStore.*`. The `metadata` world is wired since Phase 3 (`waveflow:metadata@1.1.0`, same `/v1` manifest label): [`commands/motion_artwork.rs::fetch_album_motion_artwork`](src-tauri/crates/app/src/commands/motion_artwork.rs) fans `album-info` out to enabled metadata plugins for Apple-style animated covers (`motion-cover-url`), rendered as a muted-loop `<video>` overlay ([`MotionCoverOverlay`](src/components/player/MotionCoverOverlay.tsx) + [`useAlbumMotionArtwork`](src/hooks/useAlbumMotionArtwork.ts)) over the static cover in ImmersiveNowPlaying + NowPlayingPanel. The metadata bindgen reuses `source`'s `waveflow:host/*` types via bindgen `with:` (one set of host impls). Plugins return a directly-playable video URL (mp4 — the desktop webview has no HLS.js). **Opt-in local motion cache** (default OFF, `app_setting['motion_artwork.cache_enabled']`): when on, [`fetch_album_motion_artwork`](src-tauri/crates/app/src/commands/motion_artwork.rs) downloads the resolved mp4 into an app-wide LRU cache (`<app-data>/waveflow/motion_cache/`, hash-addressed by source URL, 1 GB cap, mtime-based eviction) and returns the LOCAL path — `MotionCoverOverlay` runs a non-`http(s)` src through `convertFileSrc` (the asset-protocol scope for `motion_cache/**` is declared in `tauri.conf.json`). OFF relies on the webview's transient HTTP cache. Toggle + size + clear live in a **per-plugin ⚙️ options panel** ([`PluginOptions`](src/components/views/settings/PluginOptions.tsx)) revealed inline under a plugin's row in `PluginsCard` — the gear shows for plugins with manifest options OR metadata-world (motion cache). Keeps the list short vs a stacked card per plugin. i18n `settings.motionArtwork.*`. **Generic plugin options** (Phase 2): a plugin declares `[[options]]` in `manifest.toml` (`key` / `type` bool·enum·text / `label` / `default` / `choices?` / `description?`, parsed + validated in [`manifest.rs`](src-tauri/crates/core/src/plugin/manifest.rs)); the user sets them in the ⚙️ panel via `get_plugin_options` / `set_plugin_option` ([`commands/plugins.rs`](src-tauri/crates/app/src/commands/plugins.rs)); the values persist in `<state_dir>/.plugin-config.json` ([`plugin_config`](src-tauri/crates/core/src/plugin/plugin_config.rs), the single source of truth — no `app_setting` row, excluded from the scratch quota) and reach the guest through the `waveflow:host/config.get-option` host import ([`HostCtx::config`](src-tauri/crates/core/src/plugin/runtime.rs), pinned at instantiate time, read-only from the guest). The config import is additive/backward-compatible — a plugin built without it still instantiates. The Apple plugin's `prefer_hevc` option (v0.2.0) is the first consumer. **Localized manifest strings** (issue #440): `plugin.description`, each option's `label`/`description` and a registry entry's `description` are [`LocalizedString`](src-tauri/crates/core/src/plugin/manifest.rs) — a plain string (unchanged, still valid verbatim) or a `{ lang -> text }` map. **Anything published to users must carry its translations in the sibling `*_i18n` field** (`description_i18n`, `label_i18n`), folded into the base field at parse time by `merge_localized_siblings` with the plain string taking the `en` slot: an older host ignores the unknown sibling and keeps rendering English. The **inline map form is not publishable** — a host predating this feature type-errors on the table, dropping the plugin, and for `registry.json` (one document every installed version fetches) it fails the whole catalogue decode across all three sources, so the store goes dark on that build; `min_app_version` can't rescue it because it's read after the decode. The host echoes the merged value untouched; the UI resolves it against the active i18next language via [`useLocalizedText`](src/hooks/useLocalizedText.ts). The fallback chain (exact → base language → `en` → any entry) is implemented **twice**, in `LocalizedString::resolve` and [`resolveLocalizedText`](src/lib/localizedText.ts) — change them together. **The `ui` world** (`waveflow:ui/v1`, issue #443 Part 1) lets a plugin render a custom view **without shipping React**: the guest returns a **JSON view descriptor** (sections/cards/images/action buttons) the host draws with native components — never HTML/JS/React, so no code injection. Exported `extension` interface = `manifest()` (sidebar mount point) + `render(path)` + `on-event(event, payload)`, each returning the descriptor string; an action round-trips through `on-event` and the plugin returns the **next full descriptor** (no diff protocol), while an `open-url` action is handled host-side and never reaches the guest. The `ui` bindgen reuses `source`'s host types via `with:` (one impl set) and adds one fresh import — **`waveflow:host/library.list-artists`**, a **redacted** read (names + aggregate track-count + opaque id ONLY, no file paths / per-track rows) gated by manifest permission `library.read_artists`, doubly clamped ([`MAX_LIBRARY_ARTISTS`](src-tauri/crates/core/src/plugin/host_impl.rs)) and **snapshot-injected** (the host queries the active profile async-side and hands the guest a ready list, so the guest never touches SQLite; local-only ⇒ works offline). The redaction is host-enforced: a plugin without the permission gets `Err("permission denied: library.read_artists")` even with the snapshot present. Commands [`list_ui_plugins` / `plugin_ui_render` / `plugin_ui_event`](src-tauri/crates/app/src/commands/plugins.rs); sidebar entries + routing build **dynamically** off `manifest()` keyed on plugin id (a trapping `manifest()` is skipped + logged, never blanks the nav). First consumer = **Release Radar** (separate repo [`InstaZDLL/waveflow-plugin-release-radar`](https://github.com/InstaZDLL/waveflow-plugin-release-radar), listed in the registry, `min_app_version` 1.8.0); the core carries only the world surface + a test-only, never-bundled [`plugins/ui-fixture/`](src-tauri/plugins/ui-fixture/) exercised by [`tests/plugin_ui.rs`](src-tauri/crates/core/tests/plugin_ui.rs). Frontend: a generic [`PluginUIView`](src/components/views/PluginUIView.tsx) draws the descriptor with native components (open-url actions via `openUrl`, event actions re-render); the sidebar renders one dynamic entry per enabled ui plugin off [`useUiPlugins`](src/hooks/useUiPlugins.ts) → `list_ui_plugins` (icon resolved from a curated lucide allowlist [`pluginIcons`](src/lib/pluginIcons.tsx), unknown ⇒ generic glyph); routing rides a `plugin-ui` `HistoryEntry` carrying the plugin id (keyed remount per plugin in `AppLayout`). i18n `pluginView.*` + `settings.plugins.permissions.libraryReadArtists` ×17. **The `canvas` world** (`waveflow:canvas/v1`, issue #473) is a per-track backdrop source: interface `provider` = `track-canvas(artist, title, album?, duration-ms?) -> result<option<canvas{url, entity-id?}>, string>`, host imports http/log/storage/config (**no** library). [`commands/canvas.rs::fetch_track_canvas`](src-tauri/crates/app/src/commands/canvas.rs) fans out to enabled canvas plugins (per-plugin lock + 20 s timeout), returns the first URL that passes the shared `motion_cache::is_safe_motion_url` SSRF guard, and is **fail-soft** (any plugin error/panic/timeout → logged + skipped, never breaks playback — the frontend falls down the precedence chain). Bindgen [`bindings::canvas`](src-tauri/crates/core/src/plugin/bindings.rs) reuses `source`'s host types via `with:` (no new host import); [`runtime::canvas_track_canvas`](src-tauri/crates/core/src/plugin/runtime.rs) instantiates + calls it. Frontend: [`useTrackCanvas`](src/hooks/useTrackCanvas.ts) tries the manual local Canvas then this command; [`CanvasStage`](src/components/player/CanvasStage.tsx) renders a local path via `convertFileSrc` and a remote URL directly. **Opt-in local Canvas cache** (issue #473, default OFF, `app_setting['canvas.cache_enabled']`): when on, `fetch_track_canvas` downloads the resolved mp4 into an app-wide LRU (`<app-data>/waveflow/canvas_cache/`) via the **shared `motion_cache` primitives** (same download/eviction/SSRF as the motion cover, separate dir) and returns the LOCAL path — same pattern as the motion cache, toggle+size+clear in the canvas plugin's ⚙️ panel ([`PluginOptions`](src/components/views/settings/PluginOptions.tsx) `LocalCacheOption`, shared with the motion cache), asset scope `canvas_cache/**` in `tauri.conf.json`, i18n `settings.canvasCache.*`. Test-only [`plugins/canvas-fixture/`](src-tauri/plugins/canvas-fixture/) (never bundled) exercised by [`tests/plugin_canvas.rs`](src-tauri/crates/core/tests/plugin_canvas.rs). First consumer = a separate **unsigned** Spotify Canvas plugin (grey-area of Spotify's Developer Terms, isolated exactly like the excluded YouTube path).
 
 ## Feature catalogue
 
diff --git a/docs/features/plugins.md b/docs/features/plugins.md
index ddba98c2..60a5d938 100644
--- a/docs/features/plugins.md
+++ b/docs/features/plugins.md
@@ -135,6 +135,8 @@ track-canvas: func(artist: string, title: string, album: option<string>, duratio
 
 The host side mirrors the metadata fanout: [`bindings::canvas`](../../src-tauri/crates/core/src/plugin/bindings.rs) binds the world (reusing `source`'s host types via `with:`), [`runtime::canvas_track_canvas`](../../src-tauri/crates/core/src/plugin/runtime.rs) instantiates + calls it, and the Tauri command [`fetch_track_canvas`](../../src-tauri/crates/app/src/commands/canvas.rs) fans out to every enabled `canvas` plugin (per-plugin lock + blocking task + 20 s timeout), returning the **first safe hit** (an SSRF guard rejects a non-https / loopback URL before it reaches the webview). It is **fail-soft**: a plugin error, panic, or timeout is logged and skipped, never surfaced — so a misbehaving Canvas provider can never break playback; the frontend simply falls back down the precedence chain. Frontend: [`useTrackCanvas`](../../src/hooks/useTrackCanvas.ts) tries the manual local Canvas first, then this command, and [`CanvasStage`](../../src/components/player/CanvasStage.tsx) tells a local path from a remote URL (same `http(s)` split as `MotionCoverOverlay`).
 
+By default the plugin returns a remote URL the webview streams; an **opt-in local cache** (`app_setting['canvas.cache_enabled']`, default OFF) downloads the resolved mp4 into an app-wide LRU (`<app-data>/waveflow/canvas_cache/`) and serves the on-disk copy — it reuses the motion-artwork cache's `motion_cache` primitives (download + eviction + SSRF guard) with a separate dir, and its toggle + footprint + clear live in the canvas plugin's ⚙️ panel next to the motion-cache control (both rendered by a shared `LocalCacheOption`).
+
 The core carries only the world surface + a test-only `canvas-fixture` under [`plugins/canvas-fixture/`](../../src-tauri/plugins/canvas-fixture/) (never bundled), exercised by [`tests/plugin_canvas.rs`](../../src-tauri/crates/core/tests/plugin_canvas.rs). The first consumer — a Spotify Canvas plugin — lives in its own separate, **unsigned** repo, never the core (the Spotify path is a grey-area of their Developer Terms, isolated exactly like the excluded YouTube path).
 
 ## Official plugins
diff --git a/docs/features/ui.md b/docs/features/ui.md
index 355896af..c9ce4cbc 100644
--- a/docs/features/ui.md
+++ b/docs/features/ui.md
@@ -76,7 +76,7 @@ Entry points in the [`PlayerBar`](../../src/components/player/PlayerBar.tsx): cl
 
 **Sourcing — v1 is manual mp4 only** (core-only, no plugin): the user picks a local `.mp4` via the immersive top-bar "⋯" → [`CanvasPickerModal`](../../src/components/common/CanvasPickerModal.tsx) (set / remove). The file is validated by mp4 magic bytes (`ftyp`), size-capped (64 MiB), BLAKE3-hashed and **published atomically** — staged to a unique temp then `hard_link`-ed onto the target (no-replace; a concurrent importer of the same hash loses harmlessly) — into the never-evicted per-profile `canvas/` dir ([`AppPaths::profile_canvas_dir`](../../src-tauri/crates/app/src/paths.rs)), via the shared [`media_file::store_hash_addressed_mp4`](../../src-tauri/crates/app/src/commands/media_file.rs) helper the manual motion cover (#408) also uses. The row in `track_canvas` (per-profile, `ON DELETE CASCADE`) is itself the "has a manual Canvas" signal. Commands: [`commands/canvas.rs`](../../src-tauri/crates/app/src/commands/canvas.rs) (`get_track_canvas` / `set_track_canvas_from_file` / `clear_track_canvas`).
 
-**Sourcing — plugin (issue #473).** When no manual clip is set, [`useTrackCanvas`](../../src/hooks/useTrackCanvas.ts) falls back to enabled [`canvas`-world plugins](plugins.md#the-canvas-world-waveflowcanvasv1) via [`fetch_track_canvas`](../../src-tauri/crates/app/src/commands/canvas.rs), which returns a **remote** mp4 URL — [`CanvasStage`](../../src/components/player/CanvasStage.tsx) loads a local path through `convertFileSrc` and a remote URL directly (the `http(s)` prefix tells them apart). The plugin clip sits one rung below the manual one: **manual Canvas > plugin Canvas > motion cover > slideshow > static cover**. The fanout is **fail-soft** (a plugin error/panic/timeout is logged + skipped, never breaks playback), and the picker's "remove" affordance keys on the manual clip only (a plugin URL doesn't read as "a Canvas to remove"). The first consumer is a separate **unsigned** Spotify Canvas plugin — grey-area of Spotify's Developer Terms, isolated exactly like the excluded YouTube path, never the signed core.
+**Sourcing — plugin (issue #473).** When no manual clip is set, [`useTrackCanvas`](../../src/hooks/useTrackCanvas.ts) falls back to enabled [`canvas`-world plugins](plugins.md#the-canvas-world-waveflowcanvasv1) via [`fetch_track_canvas`](../../src-tauri/crates/app/src/commands/canvas.rs), which returns a **remote** mp4 URL — [`CanvasStage`](../../src/components/player/CanvasStage.tsx) loads a local path through `convertFileSrc` and a remote URL directly (the `http(s)` prefix tells them apart). The plugin clip sits one rung below the manual one: **manual Canvas > plugin Canvas > motion cover > slideshow > static cover**. The fanout is **fail-soft** (a plugin error/panic/timeout is logged + skipped, never breaks playback), and the picker's "remove" affordance keys on the manual clip only (a plugin URL doesn't read as "a Canvas to remove"). By default the webview streams the plugin's remote mp4; an **opt-in local cache** (`app_setting['canvas.cache_enabled']`, default OFF, toggle in the canvas plugin's ⚙️ panel) downloads it into an app-wide LRU (`<app-data>/waveflow/canvas_cache/`) and serves the on-disk copy instead — the same mechanism (and shared `motion_cache` primitives) as the [motion-artwork cache](plugins.md#apple-motion-artwork-metadata-world), a separate dir. The first consumer is a separate **unsigned** Spotify Canvas plugin — grey-area of Spotify's Developer Terms, isolated exactly like the excluded YouTube path, never the signed core.
 
 **"Show Canvas" toggle** — a [`CanvasToggleButton`](../../src/components/player/CanvasToggleButton.tsx) (Spotify's control) appears in the immersive top bar **and** the `NowPlayingPanel` header **only when the current track has a Canvas** and motion isn't reduced, so it is never a dead control. It drives the global [`useCanvasEnabled`](../../src/hooks/useCanvasEnabled.ts) preference (localStorage, **default OFF** — the cover shows first, the clip takes over on click, matching "click Show Canvas to reveal"). `prefers-reduced-motion` ([`usePrefersReducedMotion`](../../src/hooks/usePrefersReducedMotion.ts)) suppresses the clip and hides the toggle; radio (negative sentinel id) and Spotify tracks are excluded. Setting a Canvas is immersive-only in v1 (the panel only reflects + toggles).
 
diff --git a/src-tauri/crates/app/src/commands/canvas.rs b/src-tauri/crates/app/src/commands/canvas.rs
index 178cba57..13149d1c 100644
--- a/src-tauri/crates/app/src/commands/canvas.rs
+++ b/src-tauri/crates/app/src/commands/canvas.rs
@@ -16,7 +16,7 @@ use serde::Serialize;
 use tauri::State;
 use waveflow_core::artwork::motion_cache;
 
-use crate::error::AppResult;
+use crate::error::{AppError, AppResult};
 use crate::offline;
 use crate::state::AppState;
 
@@ -24,6 +24,11 @@ use crate::state::AppState;
 /// stall the now-playing path. Matches the motion-artwork budget.
 const CANVAS_PLUGIN_TIMEOUT: Duration = Duration::from_secs(20);
 
+/// `app_setting` key for the opt-in local Canvas cache (issue #473). Default
+/// OFF — a plugin Canvas is a remote URL the webview streams unless the user
+/// opts into caching the mp4 on disk (same shape as the motion-artwork cache).
+const CANVAS_CACHE_ENABLED_KEY: &str = "canvas.cache_enabled";
+
 /// Hard cap on a user-supplied Canvas clip, mirroring
 /// [`super::motion_artwork`]'s manual-cover cap: a deliberately-chosen file
 /// deserves a generous ceiling, but still needs *a* limit since this
@@ -152,6 +157,12 @@ pub async fn fetch_track_canvas(
         return Ok(None);
     }
 
+    // Opt-in local cache: when on, the resolved remote mp4 is downloaded into an
+    // app-wide LRU and the returned "url" is the on-disk path (offline replay,
+    // no re-stream). Read once up front; default OFF streams the remote url.
+    let cache_locally = canvas_cache_enabled(&state).await;
+    let cache_dir = state.paths.canvas_cache_dir.clone();
+
     let plugin_ids =
         super::plugins::enabled_plugin_ids_for_world(&state, "waveflow:canvas").await?;
     if plugin_ids.is_empty() {
@@ -211,10 +222,27 @@ pub async fn fetch_track_canvas(
                     tracing::warn!(plugin_id, "canvas plugin returned an unsafe url; skipping");
                     continue;
                 }
-                return Ok(Some(PluginCanvas {
-                    url: canvas.url,
-                    plugin_id,
-                }));
+                // With the local cache on, download the mp4 and point the stage
+                // at the on-disk copy; fall back to the remote url if the
+                // download fails so the feature degrades gracefully.
+                let url = if cache_locally {
+                    match motion_cache::cache_mp4(
+                        &cache_dir,
+                        &canvas.url,
+                        motion_cache::DEFAULT_MAX_CACHE_BYTES,
+                    )
+                    .await
+                    {
+                        Ok(path) => path.to_string_lossy().into_owned(),
+                        Err(e) => {
+                            tracing::warn!(plugin_id, %e, "canvas cache download failed; serving remote url");
+                            canvas.url
+                        }
+                    }
+                } else {
+                    canvas.url
+                };
+                return Ok(Some(PluginCanvas { url, plugin_id }));
             }
             Ok(Ok(Ok(None))) => { /* this plugin has no Canvas for the track */ }
             Ok(Ok(Err(e))) => tracing::warn!(plugin_id, %e, "canvas plugin failed; skipping"),
@@ -225,3 +253,75 @@ pub async fn fetch_track_canvas(
 
     Ok(None)
 }
+
+// ----- opt-in local Canvas cache (issue #473) -----------------------------
+//
+// Mirrors the motion-artwork cache: an app-wide, hash-addressed LRU of
+// downloaded Canvas mp4s, reusing the same `motion_cache` primitives (download
+// + eviction + SSRF guard) with a separate dir so the two caches size/clear
+// independently. Default OFF — a plugin Canvas streams from the CDN unless the
+// user opts in.
+
+async fn canvas_cache_enabled(state: &AppState) -> bool {
+    sqlx::query_scalar::<_, String>("SELECT value FROM app_setting WHERE key = ?")
+        .bind(CANVAS_CACHE_ENABLED_KEY)
+        .fetch_optional(&state.app_db)
+        .await
+        .ok()
+        .flatten()
+        .map(|v| v == "true" || v == "1")
+        .unwrap_or(false)
+}
+
+/// The Canvas-cache toggle state + current on-disk footprint, for the plugin
+/// options panel. Mirrors `MotionCacheInfo`.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CanvasCacheInfo {
+    pub enabled: bool,
+    pub size_bytes: u64,
+    pub file_count: u64,
+}
+
+/// Read the toggle + cache footprint for the settings UI.
+#[tauri::command]
+pub async fn get_canvas_cache_info(state: State<'_, AppState>) -> AppResult<CanvasCacheInfo> {
+    let enabled = canvas_cache_enabled(&state).await;
+    let dir = state.paths.canvas_cache_dir.clone();
+    let (size_bytes, file_count) = tokio::task::spawn_blocking(move || motion_cache::stats(&dir))
+        .await
+        .map_err(|e| AppError::Other(format!("spawn_blocking: {e}")))?;
+    Ok(CanvasCacheInfo {
+        enabled,
+        size_bytes,
+        file_count,
+    })
+}
+
+/// Toggle the opt-in local Canvas cache. Turning it OFF does not purge the
+/// existing files — that's the explicit "Clear cache" action below.
+#[tauri::command]
+pub async fn set_canvas_cache_enabled(state: State<'_, AppState>, enabled: bool) -> AppResult<()> {
+    sqlx::query(
+        "INSERT INTO app_setting (key, value, value_type, updated_at)
+         VALUES (?, ?, 'bool', ?)
+         ON CONFLICT(key) DO UPDATE
+            SET value = excluded.value, updated_at = excluded.updated_at",
+    )
+    .bind(CANVAS_CACHE_ENABLED_KEY)
+    .bind(if enabled { "true" } else { "false" })
+    .bind(chrono::Utc::now().timestamp_millis())
+    .execute(&state.app_db)
+    .await?;
+    Ok(())
+}
+
+/// Delete every cached Canvas mp4 (and any leftover `.part` temporaries).
+#[tauri::command]
+pub async fn clear_canvas_cache(state: State<'_, AppState>) -> AppResult<()> {
+    let dir = state.paths.canvas_cache_dir.clone();
+    tokio::task::spawn_blocking(move || motion_cache::clear(&dir))
+        .await
+        .map_err(|e| AppError::Other(format!("spawn_blocking: {e}")))?;
+    Ok(())
+}
diff --git a/src-tauri/crates/app/src/lib.rs b/src-tauri/crates/app/src/lib.rs
index 29bd6749..39261998 100644
--- a/src-tauri/crates/app/src/lib.rs
+++ b/src-tauri/crates/app/src/lib.rs
@@ -718,6 +718,9 @@ pub fn run() {
             commands::canvas::set_track_canvas_from_file,
             commands::canvas::clear_track_canvas,
             commands::canvas::fetch_track_canvas,
+            commands::canvas::get_canvas_cache_info,
+            commands::canvas::set_canvas_cache_enabled,
+            commands::canvas::clear_canvas_cache,
             commands::integration::get_lastfm_api_key,
             commands::integration::set_lastfm_api_key,
             commands::integration::get_bio_source,
diff --git a/src-tauri/crates/app/src/paths.rs b/src-tauri/crates/app/src/paths.rs
index efe40a27..b9fdfcf3 100644
--- a/src-tauri/crates/app/src/paths.rs
+++ b/src-tauri/crates/app/src/paths.rs
@@ -40,6 +40,10 @@ pub struct AppPaths {
     /// App-wide, opt-in LRU cache of downloaded animated-album-artwork
     /// (`.mp4`) files — shared across profiles like `metadata_artwork`.
     pub motion_cache_dir: PathBuf,
+    /// App-wide, opt-in LRU cache of downloaded per-track Canvas (`.mp4`)
+    /// files (issue #473) — same shape as `motion_cache_dir`, separate dir
+    /// so the two caches size/evict/clear independently.
+    pub canvas_cache_dir: PathBuf,
     pub profiles_dir: PathBuf,
     pub bundled_plugins_dir: Option<PathBuf>,
 }
@@ -88,6 +92,7 @@ impl AppPaths {
             avatars_dir: root.join("avatars"),
             metadata_artwork_dir: root.join("metadata_artwork"),
             motion_cache_dir: root.join("motion_cache"),
+            canvas_cache_dir: root.join("canvas_cache"),
             profiles_dir: root.join("profiles"),
             bundled_plugins_dir,
             root,
@@ -106,6 +111,7 @@ impl AppPaths {
         std::fs::create_dir_all(&self.avatars_dir)?;
         std::fs::create_dir_all(&self.metadata_artwork_dir)?;
         std::fs::create_dir_all(&self.motion_cache_dir)?;
+        std::fs::create_dir_all(&self.canvas_cache_dir)?;
         std::fs::create_dir_all(&self.profiles_dir)?;
         let plugin_paths = self.plugin_paths();
         std::fs::create_dir_all(&plugin_paths.plugins_root)?;
diff --git a/src-tauri/crates/app/tauri.conf.json b/src-tauri/crates/app/tauri.conf.json
index d892b890..5da45ded 100644
--- a/src-tauri/crates/app/tauri.conf.json
+++ b/src-tauri/crates/app/tauri.conf.json
@@ -47,7 +47,9 @@
           "$APPDATA/waveflow/metadata_artwork/**",
           "$APPLOCALDATA/waveflow/metadata_artwork/**",
           "$APPDATA/waveflow/motion_cache/**",
-          "$APPLOCALDATA/waveflow/motion_cache/**"
+          "$APPLOCALDATA/waveflow/motion_cache/**",
+          "$APPDATA/waveflow/canvas_cache/**",
+          "$APPLOCALDATA/waveflow/canvas_cache/**"
         ]
       }
     }
diff --git a/src/components/views/settings/PluginOptions.tsx b/src/components/views/settings/PluginOptions.tsx
index bf67757d..b4f1823c 100644
--- a/src/components/views/settings/PluginOptions.tsx
+++ b/src/components/views/settings/PluginOptions.tsx
@@ -9,9 +9,15 @@ import {
   getPluginOptions,
   setPluginOption,
   isMetadataPlugin,
+  isCanvasPlugin,
   type PluginInfo,
   type PluginOption,
 } from "../../../lib/tauri/plugins";
+import {
+  getCanvasCacheInfo,
+  setCanvasCacheEnabled,
+  clearCanvasCache,
+} from "../../../lib/tauri/canvas";
 import { useLocalizedText } from "../../../hooks/useLocalizedText";
 
 /** Human-readable byte size (locale-agnostic, 1 decimal for MB/GB). */
@@ -30,16 +36,17 @@ function formatBytes(bytes: number): string {
  * opened instead of stacking a card per plugin — the list stays short no
  * matter how many plugins are installed.
  *
- * For metadata-world plugins it renders the host-provided motion-artwork
- * local-cache control (toggle + footprint + clear). The motion cache is an
- * app-wide WaveFlow capability, surfaced here because it caches what these
- * plugins produce.
+ * For metadata-world plugins it renders the motion-artwork local-cache control,
+ * and for canvas-world plugins the Canvas local-cache control (toggle +
+ * footprint + clear). Both are app-wide WaveFlow capabilities, surfaced here
+ * because they cache what these plugins produce.
  */
 export function PluginOptions({ plugin }: { plugin: PluginInfo }) {
   return (
     <div className="mt-3 pt-3 border-t border-zinc-200 dark:border-zinc-800 space-y-4">
       {plugin.hasOptions && <ManifestOptions pluginId={plugin.id} />}
       {isMetadataPlugin(plugin) && <MotionCacheOption />}
+      {isCanvasPlugin(plugin) && <CanvasCacheOption />}
     </div>
   );
 }
@@ -200,7 +207,28 @@ function OptionControl({
   );
 }
 
-function MotionCacheOption() {
+/** One opt-in local mp4 cache (motion artwork or Canvas): identical host-side
+ *  shape (toggle + on-disk footprint + clear), only the backend commands + the
+ *  i18n prefix differ. */
+interface LocalCacheProps {
+  i18nPrefix: "settings.motionArtwork" | "settings.canvasCache";
+  toggleId: string;
+  getInfo: () => Promise<{
+    enabled: boolean;
+    sizeBytes: number;
+    fileCount: number;
+  }>;
+  setEnabled: (enabled: boolean) => Promise<void>;
+  clear: () => Promise<void>;
+}
+
+function LocalCacheOption({
+  i18nPrefix,
+  toggleId,
+  getInfo,
+  setEnabled: persistEnabled,
+  clear,
+}: LocalCacheProps) {
   const { t } = useTranslation();
   const [enabled, setEnabled] = useState(false);
   const [sizeBytes, setSizeBytes] = useState(0);
@@ -213,7 +241,7 @@ function MotionCacheOption() {
 
   useEffect(() => {
     let cancelled = false;
-    getMotionCacheInfo().then(
+    getInfo().then(
       (info) => {
         if (cancelled) return;
         setEnabled(info.enabled);
@@ -230,7 +258,7 @@ function MotionCacheOption() {
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [getInfo]);
 
   const onToggle = useCallback(async () => {
     // Serialise against BOTH the toggle write and the clear op — ignore clicks
@@ -241,14 +269,14 @@ function MotionCacheOption() {
     setEnabled(next); // optimistic
     setError(null);
     try {
-      await setMotionCacheEnabled(next);
+      await persistEnabled(next);
     } catch (e) {
       setEnabled(!next); // revert
       setError(e instanceof Error ? e.message : String(e));
     } finally {
       setSaving(false);
     }
-  }, [enabled, saving, busy]);
+  }, [enabled, saving, busy, persistEnabled]);
 
   const onClear = useCallback(async () => {
     // Don't start a clear while a toggle write (or another clear) is pending.
@@ -260,8 +288,8 @@ function MotionCacheOption() {
     setBusy(true);
     setError(null);
     try {
-      await clearMotionCache();
-      const info = await getMotionCacheInfo();
+      await clear();
+      const info = await getInfo();
       setSizeBytes(info.sizeBytes);
       setFileCount(info.fileCount);
     } catch (e) {
@@ -270,7 +298,7 @@ function MotionCacheOption() {
       setBusy(false);
       setConfirmingClear(false);
     }
-  }, [confirmingClear, saving, busy]);
+  }, [confirmingClear, saving, busy, getInfo, clear]);
 
   return (
     <div>
@@ -286,17 +314,17 @@ function MotionCacheOption() {
       <div className="flex items-center justify-between gap-4">
         <div className="min-w-0">
           <label
-            htmlFor="motion-cache-toggle"
+            htmlFor={toggleId}
             className="text-sm text-zinc-700 dark:text-zinc-200 select-none block"
           >
-            {t("settings.motionArtwork.cacheLabel")}
+            {t(`${i18nPrefix}.cacheLabel`)}
           </label>
           <p className="text-xs text-zinc-500 dark:text-zinc-400 mt-0.5">
-            {t("settings.motionArtwork.subtitle")}
+            {t(`${i18nPrefix}.subtitle`)}
           </p>
         </div>
         <button
-          id="motion-cache-toggle"
+          id={toggleId}
           type="button"
           role="switch"
           aria-checked={enabled}
@@ -316,7 +344,7 @@ function MotionCacheOption() {
 
       <div className="mt-2 flex items-center justify-between gap-4">
         <p className="text-xs text-zinc-500 dark:text-zinc-400">
-          {t("settings.motionArtwork.usage", {
+          {t(`${i18nPrefix}.usage`, {
             size: formatBytes(sizeBytes),
             files: fileCount,
           })}
@@ -329,10 +357,36 @@ function MotionCacheOption() {
         >
           <Trash2 size={14} aria-hidden="true" />
           {confirmingClear
-            ? t("settings.motionArtwork.clearConfirm")
-            : t("settings.motionArtwork.clear")}
+            ? t(`${i18nPrefix}.clearConfirm`)
+            : t(`${i18nPrefix}.clear`)}
         </button>
       </div>
     </div>
   );
 }
+
+/** Motion-artwork local cache (metadata plugins). */
+function MotionCacheOption() {
+  return (
+    <LocalCacheOption
+      i18nPrefix="settings.motionArtwork"
+      toggleId="motion-cache-toggle"
+      getInfo={getMotionCacheInfo}
+      setEnabled={setMotionCacheEnabled}
+      clear={clearMotionCache}
+    />
+  );
+}
+
+/** Per-track Canvas local cache (canvas plugins, issue #473). */
+function CanvasCacheOption() {
+  return (
+    <LocalCacheOption
+      i18nPrefix="settings.canvasCache"
+      toggleId="canvas-cache-toggle"
+      getInfo={getCanvasCacheInfo}
+      setEnabled={setCanvasCacheEnabled}
+      clear={clearCanvasCache}
+    />
+  );
+}
diff --git a/src/components/views/settings/PluginsCard.tsx b/src/components/views/settings/PluginsCard.tsx
index c9139ee4..549d7946 100644
--- a/src/components/views/settings/PluginsCard.tsx
+++ b/src/components/views/settings/PluginsCard.tsx
@@ -16,6 +16,7 @@ import {
   setPluginEnabled,
   uninstallPlugin,
   isMetadataPlugin,
+  isCanvasPlugin,
   type PluginInfo,
 } from "../../../lib/tauri/plugins";
 import { PLUGIN_AVAILABILITY_EVENT } from "../../../hooks/usePluginAvailability";
@@ -210,7 +211,9 @@ export function PluginsCard() {
                   </div>
                   <div className="flex flex-col items-end gap-2 shrink-0">
                     <div className="flex items-center gap-2">
-                      {(plugin.hasOptions || isMetadataPlugin(plugin)) && (
+                      {(plugin.hasOptions ||
+                        isMetadataPlugin(plugin) ||
+                        isCanvasPlugin(plugin)) && (
                         <button
                           type="button"
                           onClick={() =>
diff --git a/src/i18n/locales/ar.json b/src/i18n/locales/ar.json
index 56666cfe..99dbd972 100644
--- a/src/i18n/locales/ar.json
+++ b/src/i18n/locales/ar.json
@@ -2158,6 +2158,13 @@
       "reset": "إعادة التعيين",
       "done": "تمت إعادة التعيين",
       "error": "فشلت إعادة التعيين. يرجى المحاولة مرة أخرى."
+    },
+    "canvasCache": {
+      "cacheLabel": "حفظ مقاطع Canvas محليًا",
+      "subtitle": "ينزّل Canvas كل مقطع من الإضافة لتشغيله دون اتصال ودون إعادة بثّه.",
+      "usage": "{{size}} مستخدَمة · {{files}} Canvas في التخزين المؤقت",
+      "clear": "مسح الذاكرة المؤقتة",
+      "clearConfirm": "تأكيد؟"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/de.json b/src/i18n/locales/de.json
index 1963bac3..652d50ce 100644
--- a/src/i18n/locales/de.json
+++ b/src/i18n/locales/de.json
@@ -2003,6 +2003,13 @@
       "reset": "Zurücksetzen",
       "done": "Zurückgesetzt",
       "error": "Zurücksetzen fehlgeschlagen. Bitte erneut versuchen."
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas lokal speichern",
+      "subtitle": "Lädt das Canvas jedes Titels vom Plugin herunter, damit es offline und ohne erneutes Streaming abspielt.",
+      "usage": "{{size}} belegt · {{files}} Canvas im Cache",
+      "clear": "Cache leeren",
+      "clearConfirm": "Bestätigen?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json
index 1ec49bcc..9ed76571 100644
--- a/src/i18n/locales/en.json
+++ b/src/i18n/locales/en.json
@@ -2003,6 +2003,13 @@
       "reset": "Reset",
       "done": "Reset done",
       "error": "Reset failed. Please try again."
+    },
+    "canvasCache": {
+      "cacheLabel": "Save Canvas videos locally",
+      "subtitle": "Downloads each track's Canvas from the plugin so it plays offline and doesn't re-stream.",
+      "usage": "{{size}} used · {{files}} Canvas cached",
+      "clear": "Clear cache",
+      "clearConfirm": "Confirm?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.json
index 412af43d..72948c7a 100644
--- a/src/i18n/locales/es.json
+++ b/src/i18n/locales/es.json
@@ -2003,6 +2003,13 @@
       "reset": "Restablecer",
       "done": "Restablecido",
       "error": "No se pudo restablecer. Inténtalo de nuevo."
+    },
+    "canvasCache": {
+      "cacheLabel": "Guardar los Canvas localmente",
+      "subtitle": "Descarga el Canvas de cada pista desde el complemento para reproducirlo sin conexión y sin volver a transmitirlo.",
+      "usage": "{{size}} usados · {{files}} Canvas en caché",
+      "clear": "Vaciar caché",
+      "clearConfirm": "¿Confirmar?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/fr.json b/src/i18n/locales/fr.json
index 3f715672..c5286989 100644
--- a/src/i18n/locales/fr.json
+++ b/src/i18n/locales/fr.json
@@ -2003,6 +2003,13 @@
       "reset": "Réinitialiser",
       "done": "Réinitialisé",
       "error": "La réinitialisation a échoué. Réessayez."
+    },
+    "canvasCache": {
+      "cacheLabel": "Enregistrer les Canvas en local",
+      "subtitle": "Télécharge le Canvas de chaque piste depuis le plugin pour une lecture hors ligne, sans re-streaming.",
+      "usage": "{{size}} utilisés · {{files}} Canvas en cache",
+      "clear": "Vider le cache",
+      "clearConfirm": "Confirmer ?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/hi.json b/src/i18n/locales/hi.json
index 67e0f515..0abc407f 100644
--- a/src/i18n/locales/hi.json
+++ b/src/i18n/locales/hi.json
@@ -2003,6 +2003,13 @@
       "reset": "रीसेट करें",
       "done": "रीसेट हो गया",
       "error": "रीसेट विफल रहा। कृपया पुनः प्रयास करें।"
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas को स्थानीय रूप से सहेजें",
+      "subtitle": "प्लगइन से हर ट्रैक का Canvas डाउनलोड करता है ताकि वह ऑफ़लाइन और बिना दोबारा स्ट्रीम किए चले।",
+      "usage": "{{size}} उपयोग · {{files}} Canvas कैश किए गए",
+      "clear": "कैश साफ़ करें",
+      "clearConfirm": "पुष्टि करें?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/id.json b/src/i18n/locales/id.json
index c7d817c5..cac770f8 100644
--- a/src/i18n/locales/id.json
+++ b/src/i18n/locales/id.json
@@ -2003,6 +2003,13 @@
       "reset": "Atur ulang",
       "done": "Diatur ulang",
       "error": "Gagal mengatur ulang. Silakan coba lagi."
+    },
+    "canvasCache": {
+      "cacheLabel": "Simpan Canvas secara lokal",
+      "subtitle": "Mengunduh Canvas tiap lagu dari plugin agar bisa diputar offline tanpa streaming ulang.",
+      "usage": "{{size}} terpakai · {{files}} Canvas di cache",
+      "clear": "Bersihkan cache",
+      "clearConfirm": "Konfirmasi?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/it.json b/src/i18n/locales/it.json
index c9a2930b..f9affad6 100644
--- a/src/i18n/locales/it.json
+++ b/src/i18n/locales/it.json
@@ -2003,6 +2003,13 @@
       "reset": "Reimposta",
       "done": "Reimpostato",
       "error": "Reimpostazione non riuscita. Riprova."
+    },
+    "canvasCache": {
+      "cacheLabel": "Salva i Canvas in locale",
+      "subtitle": "Scarica il Canvas di ogni brano dal plugin per riprodurlo offline e senza rieseguire lo streaming.",
+      "usage": "{{size}} usati · {{files}} Canvas in cache",
+      "clear": "Svuota cache",
+      "clearConfirm": "Confermare?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index 1dac36c0..951aa7ca 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -2003,6 +2003,13 @@
       "reset": "リセット",
       "done": "リセット完了",
       "error": "リセットに失敗しました。もう一度お試しください。"
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas をローカルに保存",
+      "subtitle": "各トラックの Canvas をプラグインからダウンロードし、オフラインで再ストリーミングなしに再生します。",
+      "usage": "{{size}} 使用中 · {{files}} 件の Canvas をキャッシュ",
+      "clear": "キャッシュを消去",
+      "clearConfirm": "確認しますか？"
     }
   },
   "scanProgress": {
diff --git a/src/i18n/locales/ko.json b/src/i18n/locales/ko.json
index 92b624bd..24b0535b 100644
--- a/src/i18n/locales/ko.json
+++ b/src/i18n/locales/ko.json
@@ -2003,6 +2003,13 @@
       "reset": "초기화",
       "done": "초기화됨",
       "error": "초기화에 실패했습니다. 다시 시도하세요."
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas를 로컬에 저장",
+      "subtitle": "플러그인에서 각 트랙의 Canvas를 내려받아 오프라인에서 다시 스트리밍하지 않고 재생합니다.",
+      "usage": "{{size}} 사용 · {{files}}개 Canvas 캐시됨",
+      "clear": "캐시 지우기",
+      "clearConfirm": "확인할까요?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/nl.json b/src/i18n/locales/nl.json
index 18582f17..5cb5626f 100644
--- a/src/i18n/locales/nl.json
+++ b/src/i18n/locales/nl.json
@@ -2003,6 +2003,13 @@
       "reset": "Herstellen",
       "done": "Hersteld",
       "error": "Herstellen mislukt. Probeer het opnieuw."
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas lokaal opslaan",
+      "subtitle": "Downloadt de Canvas van elk nummer via de plug-in, zodat die offline en zonder opnieuw streamen speelt.",
+      "usage": "{{size}} gebruikt · {{files}} Canvas in cache",
+      "clear": "Cache wissen",
+      "clearConfirm": "Bevestigen?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/pt-BR.json b/src/i18n/locales/pt-BR.json
index c67ed32a..d3505603 100644
--- a/src/i18n/locales/pt-BR.json
+++ b/src/i18n/locales/pt-BR.json
@@ -2003,6 +2003,13 @@
       "reset": "Redefinir",
       "done": "Redefinido",
       "error": "Falha ao redefinir. Tente novamente."
+    },
+    "canvasCache": {
+      "cacheLabel": "Salvar os Canvas localmente",
+      "subtitle": "Baixa o Canvas de cada faixa pelo plugin para reproduzir offline e sem refazer o streaming.",
+      "usage": "{{size}} usados · {{files}} Canvas em cache",
+      "clear": "Limpar cache",
+      "clearConfirm": "Confirmar?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/pt.json b/src/i18n/locales/pt.json
index e907b9cd..b7e30564 100644
--- a/src/i18n/locales/pt.json
+++ b/src/i18n/locales/pt.json
@@ -2003,6 +2003,13 @@
       "reset": "Repor",
       "done": "Reposto",
       "error": "Falha ao repor. Tente novamente."
+    },
+    "canvasCache": {
+      "cacheLabel": "Guardar os Canvas localmente",
+      "subtitle": "Transfere o Canvas de cada faixa a partir do plugin para reproduzir offline e sem voltar a transmitir.",
+      "usage": "{{size}} usados · {{files}} Canvas em cache",
+      "clear": "Limpar cache",
+      "clearConfirm": "Confirmar?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.json
index f8d8c168..8bb52bfb 100644
--- a/src/i18n/locales/ru.json
+++ b/src/i18n/locales/ru.json
@@ -2099,6 +2099,13 @@
       "reset": "Сбросить",
       "done": "Сброшено",
       "error": "Не удалось сбросить. Попробуйте ещё раз."
+    },
+    "canvasCache": {
+      "cacheLabel": "Сохранять Canvas локально",
+      "subtitle": "Загружает Canvas каждого трека через плагин, чтобы он воспроизводился офлайн без повторной загрузки.",
+      "usage": "{{size}} использовано · {{files}} Canvas в кэше",
+      "clear": "Очистить кэш",
+      "clearConfirm": "Подтвердить?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/tr.json b/src/i18n/locales/tr.json
index aa6fa002..6a528987 100644
--- a/src/i18n/locales/tr.json
+++ b/src/i18n/locales/tr.json
@@ -2003,6 +2003,13 @@
       "reset": "Sıfırla",
       "done": "Sıfırlandı",
       "error": "Sıfırlama başarısız. Lütfen tekrar deneyin."
+    },
+    "canvasCache": {
+      "cacheLabel": "Canvas videolarını yerel olarak kaydet",
+      "subtitle": "Her parçanın Canvas'ını eklentiden indirir; çevrimdışı ve yeniden akış olmadan oynatılır.",
+      "usage": "{{size}} kullanıldı · {{files}} Canvas önbellekte",
+      "clear": "Önbelleği temizle",
+      "clearConfirm": "Onaylıyor musunuz?"
     }
   },
   "spotify": {
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index b3116172..3e3636d0 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -2003,6 +2003,13 @@
       "reset": "重置",
       "done": "已重置",
       "error": "重置失败，请重试。"
+    },
+    "canvasCache": {
+      "cacheLabel": "在本地保存 Canvas",
+      "subtitle": "通过插件下载每首曲目的 Canvas，可离线播放且无需重新缓冲。",
+      "usage": "已用 {{size}} · 已缓存 {{files}} 个 Canvas",
+      "clear": "清除缓存",
+      "clearConfirm": "确认？"
     }
   },
   "scanProgress": {
diff --git a/src/i18n/locales/zh-TW.json b/src/i18n/locales/zh-TW.json
index c224ff64..26848619 100644
--- a/src/i18n/locales/zh-TW.json
+++ b/src/i18n/locales/zh-TW.json
@@ -2003,6 +2003,13 @@
       "reset": "重設",
       "done": "已重設",
       "error": "重設失敗，請重試。"
+    },
+    "canvasCache": {
+      "cacheLabel": "在本機儲存 Canvas",
+      "subtitle": "透過外掛下載每首曲目的 Canvas，可離線播放且無需重新串流。",
+      "usage": "已用 {{size}} · 已快取 {{files}} 個 Canvas",
+      "clear": "清除快取",
+      "clearConfirm": "確認？"
     }
   },
   "scanProgress": {
diff --git a/src/lib/tauri/canvas.ts b/src/lib/tauri/canvas.ts
index b1811a30..583a00ce 100644
--- a/src/lib/tauri/canvas.ts
+++ b/src/lib/tauri/canvas.ts
@@ -51,6 +51,9 @@ export interface PluginCanvas {
  * Resolves `null` when offline, when no canvas plugin is installed, or when
  * none has a Canvas for this track. Fail-soft backend-side: a plugin
  * error/timeout is logged and skipped, never thrown.
+ *
+ * With the local cache on (see {@link setCanvasCacheEnabled}) `url` is an
+ * on-disk path instead of a remote URL — `isRemoteCanvasUrl` tells them apart.
  */
 export function fetchTrackCanvas(
   artist: string,
@@ -66,6 +69,34 @@ export function fetchTrackCanvas(
   });
 }
 
+/**
+ * Opt-in local Canvas cache state (issue #473). When enabled, the backend
+ * downloads each resolved plugin Canvas mp4 into an app-wide LRU cache
+ * (`<app-data>/waveflow/canvas_cache/`) and serves the local copy — offline
+ * replay, no re-stream. Mirrors `commands::canvas::CanvasCacheInfo`. Default
+ * OFF; the plugin Canvas streams from the CDN otherwise.
+ */
+export interface CanvasCacheInfo {
+  enabled: boolean;
+  sizeBytes: number;
+  fileCount: number;
+}
+
+/** Read the Canvas-cache toggle + current on-disk footprint. */
+export function getCanvasCacheInfo(): Promise<CanvasCacheInfo> {
+  return invoke<CanvasCacheInfo>("get_canvas_cache_info");
+}
+
+/** Toggle the local Canvas cache. Turning it off does NOT purge existing files. */
+export function setCanvasCacheEnabled(enabled: boolean): Promise<void> {
+  return invoke<void>("set_canvas_cache_enabled", { enabled });
+}
+
+/** Delete every cached Canvas mp4. */
+export function clearCanvasCache(): Promise<void> {
+  return invoke<void>("clear_canvas_cache");
+}
+
 /**
  * A resolved Canvas source is **remote** (a plugin's `https` URL the webview
  * `<video>` loads directly) when it starts with `http(s)://`; otherwise it's
diff --git a/src/lib/tauri/plugins.ts b/src/lib/tauri/plugins.ts
index 3350af23..5c72ddc8 100644
--- a/src/lib/tauri/plugins.ts
+++ b/src/lib/tauri/plugins.ts
@@ -614,3 +614,10 @@ export async function pluginUiEvent(
 export function isUiPlugin(plugin: Pick<PluginInfo, "world">): boolean {
   return plugin.world.startsWith("waveflow:ui");
 }
+
+/** `true` for a canvas-world plugin (issue #473). Like {@link isMetadataPlugin}
+ *  gates the motion cache, this gates the opt-in local Canvas-cache control in
+ *  the plugin's ⚙️ options panel. */
+export function isCanvasPlugin(plugin: Pick<PluginInfo, "world">): boolean {
+  return plugin.world.startsWith("waveflow:canvas");
+}

From 10f904b2e0ad99a840100dd3ae6184bd17ed4d35 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 15:31:57 +0200
Subject: [PATCH 2/6] fix(canvas): re-validate cache-download redirects (SSRF)
 + doc canvas world

---
 src-tauri/crates/core/src/artwork/motion_cache.rs | 13 +++++++++++++
 src/lib/tauri/plugins.ts                          |  2 +-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/src-tauri/crates/core/src/artwork/motion_cache.rs b/src-tauri/crates/core/src/artwork/motion_cache.rs
index 9393d258..912dd017 100644
--- a/src-tauri/crates/core/src/artwork/motion_cache.rs
+++ b/src-tauri/crates/core/src/artwork/motion_cache.rs
@@ -114,8 +114,21 @@ pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<Pa
         return Ok(path);
     }
 
+    // Follow redirects, but re-validate EVERY hop against the SSRF guard: the
+    // caller only checked the initial `url`, and reqwest's default policy would
+    // otherwise chase a 3xx to an internal / loopback / non-https target and
+    // slip a request past that check.
     let client = reqwest::Client::builder()
         .timeout(Duration::from_secs(30))
+        .redirect(reqwest::redirect::Policy::custom(|attempt| {
+            if attempt.previous().len() >= 10 {
+                attempt.error("too many redirects")
+            } else if is_safe_motion_url(attempt.url().as_str()) {
+                attempt.follow()
+            } else {
+                attempt.error("unsafe redirect target")
+            }
+        }))
         .build()
         .map_err(|e| format!("http client: {e}"))?;
     let mut resp = client
diff --git a/src/lib/tauri/plugins.ts b/src/lib/tauri/plugins.ts
index 5c72ddc8..e3078291 100644
--- a/src/lib/tauri/plugins.ts
+++ b/src/lib/tauri/plugins.ts
@@ -16,7 +16,7 @@ export interface PluginInfo {
   version: string;
   author: string;
   /** Manifest world label — one of `waveflow:source/v1`,
-   *  `waveflow:metadata/v1`, `waveflow:ui/v1`. */
+   *  `waveflow:metadata/v1`, `waveflow:ui/v1`, `waveflow:canvas/v1`. */
   world: string;
   /** Manifest-authored: a plain string, or a `{ lang: text }` map.
    *  Resolve with `useLocalizedText()` before rendering. */

From fff142d4e8228de620a3d93db20b2b5903b341dc Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 16:01:30 +0200
Subject: [PATCH 3/6] fix(motion-cache): strip trailing-dot hosts in SSRF guard
 + allow 10 redirects

---
 src-tauri/crates/core/src/artwork/motion_cache.rs | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src-tauri/crates/core/src/artwork/motion_cache.rs b/src-tauri/crates/core/src/artwork/motion_cache.rs
index 912dd017..d5675eb9 100644
--- a/src-tauri/crates/core/src/artwork/motion_cache.rs
+++ b/src-tauri/crates/core/src/artwork/motion_cache.rs
@@ -54,6 +54,11 @@ pub fn is_safe_motion_url(url: &str) -> bool {
     } else {
         host_port.split(':').next().unwrap_or(host_port)
     };
+    // Strip a trailing FQDN dot: `localhost.` / `127.0.0.1.` resolve to the
+    // same target but would otherwise slip past the `localhost` + IP-literal
+    // checks below (`"localhost."` != `"localhost"`, and `127.0.0.1.` fails to
+    // parse as an IP so it'd read as a harmless hostname).
+    let host = host.trim_end_matches('.');
     if host.is_empty() {
         return false;
     }
@@ -121,7 +126,9 @@ pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<Pa
     let client = reqwest::Client::builder()
         .timeout(Duration::from_secs(30))
         .redirect(reqwest::redirect::Policy::custom(|attempt| {
-            if attempt.previous().len() >= 10 {
+            // Match reqwest's default of 10 redirects: `previous()` counts the
+            // hops already taken, so allow up to 10 and reject the 11th.
+            if attempt.previous().len() > 10 {
                 attempt.error("too many redirects")
             } else if is_safe_motion_url(attempt.url().as_str()) {
                 attempt.follow()
@@ -302,6 +309,10 @@ mod tests {
         assert!(!is_safe_motion_url("https://localhost/a.mp4"));
         assert!(!is_safe_motion_url("https://127.0.0.1/a.mp4"));
         assert!(!is_safe_motion_url("https://[::1]:8443/a.mp4"));
+        // Trailing FQDN dot must not bypass the loopback checks — these
+        // resolve to the same targets as above.
+        assert!(!is_safe_motion_url("https://localhost./a.mp4"));
+        assert!(!is_safe_motion_url("https://127.0.0.1./a.mp4"));
         // private / link-local / cloud-metadata
         assert!(!is_safe_motion_url("https://10.0.0.5/a.mp4"));
         assert!(!is_safe_motion_url("https://192.168.1.1/a.mp4"));

From 198ba47591e55da1352fb4e97ba8fa955df4b8f4 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 17:43:53 +0200
Subject: [PATCH 4/6] fix(motion-cache): validate the initial url inside
 cache_mp4 (defence-in-depth)

---
 .../crates/core/src/artwork/motion_cache.rs   | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src-tauri/crates/core/src/artwork/motion_cache.rs b/src-tauri/crates/core/src/artwork/motion_cache.rs
index d5675eb9..938e7f5e 100644
--- a/src-tauri/crates/core/src/artwork/motion_cache.rs
+++ b/src-tauri/crates/core/src/artwork/motion_cache.rs
@@ -106,6 +106,13 @@ fn is_internal_v4(v4: std::net::Ipv4Addr) -> bool {
 /// under `max_cache_bytes`. Caller MUST have validated the URL with
 /// [`is_safe_motion_url`] first.
 pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<PathBuf, String> {
+    // Defence-in-depth: the doc says the caller must have validated `url`, but
+    // re-check the initial URL here so `cache_mp4` can't be made to fetch an
+    // unsafe target by a caller that forgot — rejected before any filesystem or
+    // network work. The redirect policy below covers hops 2+; this covers hop 1.
+    if !is_safe_motion_url(url) {
+        return Err(format!("refusing unsafe url: {url}"));
+    }
     let hash = blake3::hash(url.as_bytes()).to_hex().to_string();
     let path = dir.join(format!("{hash}.mp4"));
 
@@ -332,6 +339,25 @@ mod tests {
         assert!(!is_safe_motion_url("https://[::192.168.0.1]/a.mp4"));
     }
 
+    #[tokio::test]
+    async fn cache_mp4_refuses_unsafe_url_before_network() {
+        // The in-function guard rejects an unsafe initial URL before any
+        // filesystem/network work — no reliance on the caller validating it.
+        let tmp = tempfile::tempdir().expect("tempdir");
+        assert!(
+            cache_mp4(tmp.path(), "https://127.0.0.1/x.mp4", DEFAULT_MAX_CACHE_BYTES)
+                .await
+                .is_err(),
+            "loopback url must be refused"
+        );
+        assert!(
+            cache_mp4(tmp.path(), "http://example.com/x.mp4", DEFAULT_MAX_CACHE_BYTES)
+                .await
+                .is_err(),
+            "non-https url must be refused"
+        );
+    }
+
     #[test]
     fn ipv4_embedded_loopback_is_internal() {
         use std::net::Ipv6Addr;

From 8d87e8c24e26f416e5acb844ac412d72f5eb3553 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 18:08:50 +0200
Subject: [PATCH 5/6] fix(canvas): treat an unsafe cache redirect as a hard
 security failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit round on #479. Three hardening fixes to the shared motion/canvas
mp4 cache:

- `cache_mp4` now returns a typed `CacheError { UnsafeUrl, Other }` instead of
  a bare String. An `UnsafeUrl` (initial url or a redirect hop failing the SSRF
  guard, or the redirect chain aborting) is a security rejection; `Other` is an
  ordinary failure (network / HTTP / oversize / disk). Previously both callers
  fell back to streaming the raw remote url on ANY cache error — so an unsafe
  redirect the per-hop guard refused was handed straight to the webview
  `<video>`, which would follow it unchecked, fully defeating the guard. Both
  `fetch_track_canvas` and the motion-cover fanout now skip the plugin on an
  `UnsafeUrl` and only degrade to streaming on an `Other` failure.

- Redact plugin-supplied urls in logged error strings (drop userinfo / query /
  fragment via `redact_url`) so a signed-token CDN url can't leak into logs;
  the `UnsafeUrl` message interpolates no url at all.

- Strengthen `cache_mp4_refuses_unsafe_url_before_network` to assert the typed
  `UnsafeUrl` variant and that no file is staged before the rejection; add a
  `redact_url` unit test.

Cache-off still streams the (initial-validated) remote url to `<video>`: a
redirect after that point is the same documented accepted residual as DNS
rebinding (initial url validated, `<video>` can't read cross-origin bodies,
plugins are curated/user-installed).
---
 src-tauri/crates/app/src/commands/canvas.rs   |  14 +-
 .../crates/app/src/commands/motion_artwork.rs |  12 +-
 .../crates/core/src/artwork/motion_cache.rs   | 145 ++++++++++++++----
 3 files changed, 139 insertions(+), 32 deletions(-)

diff --git a/src-tauri/crates/app/src/commands/canvas.rs b/src-tauri/crates/app/src/commands/canvas.rs
index 13149d1c..5c5f74e4 100644
--- a/src-tauri/crates/app/src/commands/canvas.rs
+++ b/src-tauri/crates/app/src/commands/canvas.rs
@@ -223,8 +223,7 @@ pub async fn fetch_track_canvas(
                     continue;
                 }
                 // With the local cache on, download the mp4 and point the stage
-                // at the on-disk copy; fall back to the remote url if the
-                // download fails so the feature degrades gracefully.
+                // at the on-disk copy.
                 let url = if cache_locally {
                     match motion_cache::cache_mp4(
                         &cache_dir,
@@ -234,6 +233,17 @@ pub async fn fetch_track_canvas(
                     .await
                     {
                         Ok(path) => path.to_string_lossy().into_owned(),
+                        // Security rejection (unsafe initial url or unsafe
+                        // redirect hop): must NOT degrade to streaming the raw
+                        // url — that would hand the webview <video> the very
+                        // target the cache path just refused to follow. Skip
+                        // this plugin and keep looking.
+                        Err(motion_cache::CacheError::UnsafeUrl) => {
+                            tracing::warn!(plugin_id, "canvas cache refused an unsafe url/redirect; skipping");
+                            continue;
+                        }
+                        // Ordinary failure (network / HTTP / disk): degrade to
+                        // streaming the remote url, same posture as cache-off.
                         Err(e) => {
                             tracing::warn!(plugin_id, %e, "canvas cache download failed; serving remote url");
                             canvas.url
diff --git a/src-tauri/crates/app/src/commands/motion_artwork.rs b/src-tauri/crates/app/src/commands/motion_artwork.rs
index d4d53ee5..98d3e8d2 100644
--- a/src-tauri/crates/app/src/commands/motion_artwork.rs
+++ b/src-tauri/crates/app/src/commands/motion_artwork.rs
@@ -161,8 +161,7 @@ pub async fn fetch_album_motion_artwork(
                         continue;
                     }
                     // When the local cache is on, download the mp4 and point the
-                    // overlay at the on-disk copy; fall back to the remote URL if
-                    // the download fails so the feature degrades gracefully.
+                    // overlay at the on-disk copy.
                     let square_url = if cache_locally {
                         match motion_cache::cache_mp4(
                             &cache_dir,
@@ -172,6 +171,15 @@ pub async fn fetch_album_motion_artwork(
                         .await
                         {
                             Ok(path) => path.to_string_lossy().into_owned(),
+                            // Security rejection (unsafe initial url or unsafe
+                            // redirect hop): must NOT degrade to streaming the
+                            // raw url — that would hand the webview <video> the
+                            // target the cache path just refused. Skip.
+                            Err(motion_cache::CacheError::UnsafeUrl) => {
+                                tracing::warn!(plugin_id, "motion cache refused an unsafe url/redirect; skipping");
+                                continue;
+                            }
+                            // Ordinary failure: degrade to the remote URL.
                             Err(e) => {
                                 tracing::warn!(%e, "motion cache download failed; serving remote url");
                                 remote_square
diff --git a/src-tauri/crates/core/src/artwork/motion_cache.rs b/src-tauri/crates/core/src/artwork/motion_cache.rs
index 938e7f5e..435f9ffe 100644
--- a/src-tauri/crates/core/src/artwork/motion_cache.rs
+++ b/src-tauri/crates/core/src/artwork/motion_cache.rs
@@ -99,19 +99,72 @@ fn is_internal_v4(v4: std::net::Ipv4Addr) -> bool {
     v4.is_loopback() || v4.is_private() || v4.is_link_local() || v4.is_unspecified()
 }
 
+/// Redact a plugin-supplied URL for a logged error message: keep the scheme,
+/// host and path but drop any userinfo, query and fragment. Those can carry
+/// credentials or signed tokens on a CDN URL, and every failure string here is
+/// logged. Not a validator — purely cosmetic redaction for the error text.
+fn redact_url(url: &str) -> String {
+    let no_query = url.split(['?', '#']).next().unwrap_or(url);
+    match no_query.split_once("://") {
+        Some((scheme, rest)) => {
+            let (authority, path) = match rest.split_once('/') {
+                Some((a, p)) => (a, Some(p)),
+                None => (rest, None),
+            };
+            // Drop `user:pass@` — the host is everything after the last `@`.
+            let host = authority.rsplit('@').next().unwrap_or(authority);
+            match path {
+                Some(p) => format!("{scheme}://{host}/{p}"),
+                None => format!("{scheme}://{host}"),
+            }
+        }
+        None => no_query.to_string(),
+    }
+}
+
+/// Why [`cache_mp4`] failed. The distinction is security-relevant to callers:
+/// [`CacheError::UnsafeUrl`] means the initial url OR a redirect hop failed the
+/// SSRF guard (or the redirect chain was aborted) — a hard rejection the caller
+/// MUST NOT paper over by streaming the raw url to a `<video>`, which would
+/// follow that same unsafe redirect unchecked. [`CacheError::Other`] is an
+/// ordinary failure (network, HTTP status, oversize, disk) the caller may
+/// degrade past by streaming the (already initial-validated) url.
+#[derive(Debug)]
+pub enum CacheError {
+    /// The initial url or a redirect target failed [`is_safe_motion_url`], or
+    /// the redirect chain was aborted. Never stream the url after this.
+    UnsafeUrl,
+    /// Any other failure. Carries a redacted, human-readable message.
+    Other(String),
+}
+
+impl std::fmt::Display for CacheError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            // No url interpolation — an unsafe url can carry credentials.
+            CacheError::UnsafeUrl => f.write_str("refusing unsafe url"),
+            CacheError::Other(m) => f.write_str(m),
+        }
+    }
+}
+
+impl std::error::Error for CacheError {}
+
 /// Return the local path of `url`'s cached mp4, downloading it first if absent.
 /// Hash-addressed by the (stable, per-album) source URL. On a hit the mtime is
 /// bumped for access-LRU; on a miss the body is streamed under [`MAX_MP4_BYTES`],
 /// staged through a unique temp then renamed, and the cache is evicted back
 /// under `max_cache_bytes`. Caller MUST have validated the URL with
-/// [`is_safe_motion_url`] first.
-pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<PathBuf, String> {
+/// [`is_safe_motion_url`] first. On failure the [`CacheError`] variant tells the
+/// caller whether it was a security rejection (never stream the url) or an
+/// ordinary failure it may degrade past.
+pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<PathBuf, CacheError> {
     // Defence-in-depth: the doc says the caller must have validated `url`, but
     // re-check the initial URL here so `cache_mp4` can't be made to fetch an
     // unsafe target by a caller that forgot — rejected before any filesystem or
     // network work. The redirect policy below covers hops 2+; this covers hop 1.
     if !is_safe_motion_url(url) {
-        return Err(format!("refusing unsafe url: {url}"));
+        return Err(CacheError::UnsafeUrl);
     }
     let hash = blake3::hash(url.as_bytes()).to_hex().to_string();
     let path = dir.join(format!("{hash}.mp4"));
@@ -144,37 +197,49 @@ pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<Pa
             }
         }))
         .build()
-        .map_err(|e| format!("http client: {e}"))?;
-    let mut resp = client
-        .get(url)
-        .send()
-        .await
-        .map_err(|e| format!("download {url}: {e}"))?;
+        .map_err(|e| CacheError::Other(format!("http client: {e}")))?;
+    let mut resp = match client.get(url).send().await {
+        Ok(r) => r,
+        // The redirect policy aborts (unsafe hop or too many hops) as a
+        // `reqwest::Error` flagged `is_redirect()` — treat it as a security
+        // rejection, not an ordinary failure the caller may stream past.
+        Err(e) if e.is_redirect() => return Err(CacheError::UnsafeUrl),
+        Err(e) => {
+            return Err(CacheError::Other(format!(
+                "download {}: {e}",
+                redact_url(url)
+            )))
+        }
+    };
     if !resp.status().is_success() {
-        return Err(format!("download {url}: HTTP {}", resp.status()));
+        return Err(CacheError::Other(format!(
+            "download {}: HTTP {}",
+            redact_url(url),
+            resp.status()
+        )));
     }
     if let Some(len) = resp.content_length() {
         if len > MAX_MP4_BYTES {
-            return Err(format!(
+            return Err(CacheError::Other(format!(
                 "motion mp4 too large: {len} bytes (max {MAX_MP4_BYTES})"
-            ));
+            )));
         }
     }
     let mut bytes: Vec<u8> = Vec::new();
     while let Some(chunk) = resp
         .chunk()
         .await
-        .map_err(|e| format!("read motion mp4 body: {e}"))?
+        .map_err(|e| CacheError::Other(format!("read motion mp4 body: {e}")))?
     {
         if bytes.len() as u64 + chunk.len() as u64 > MAX_MP4_BYTES {
-            return Err(format!(
+            return Err(CacheError::Other(format!(
                 "motion mp4 exceeds {MAX_MP4_BYTES} bytes — refusing"
-            ));
+            )));
         }
         bytes.extend_from_slice(&chunk);
     }
 
-    std::fs::create_dir_all(dir).map_err(|e| format!("create cache dir: {e}"))?;
+    std::fs::create_dir_all(dir).map_err(|e| CacheError::Other(format!("create cache dir: {e}")))?;
     // Unique temp per attempt (pid + monotonic seq) so concurrent downloads of
     // the SAME url can't clobber each other's partial write. Each stages its
     // own complete file then renames over the shared final name (a file rename
@@ -183,11 +248,11 @@ pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<Pa
     let tmp = dir.join(format!(".{hash}.{}.{seq}.part", std::process::id()));
     if let Err(e) = std::fs::write(&tmp, &bytes) {
         let _ = std::fs::remove_file(&tmp);
-        return Err(format!("write motion mp4: {e}"));
+        return Err(CacheError::Other(format!("write motion mp4: {e}")));
     }
     if let Err(e) = std::fs::rename(&tmp, &path) {
         let _ = std::fs::remove_file(&tmp);
-        return Err(format!("publish motion mp4: {e}"));
+        return Err(CacheError::Other(format!("publish motion mp4: {e}")));
     }
     evict_lru(dir, max_cache_bytes);
     Ok(path)
@@ -342,20 +407,44 @@ mod tests {
     #[tokio::test]
     async fn cache_mp4_refuses_unsafe_url_before_network() {
         // The in-function guard rejects an unsafe initial URL before any
-        // filesystem/network work — no reliance on the caller validating it.
+        // filesystem/network work — no reliance on the caller validating it —
+        // and flags it `UnsafeUrl` (a security rejection) so the caller skips
+        // rather than streaming the raw url.
         let tmp = tempfile::tempdir().expect("tempdir");
-        assert!(
-            cache_mp4(tmp.path(), "https://127.0.0.1/x.mp4", DEFAULT_MAX_CACHE_BYTES)
+        for url in ["https://127.0.0.1/x.mp4", "http://example.com/x.mp4"] {
+            let err = cache_mp4(tmp.path(), url, DEFAULT_MAX_CACHE_BYTES)
                 .await
-                .is_err(),
-            "loopback url must be refused"
-        );
+                .expect_err("unsafe url must be refused");
+            assert!(
+                matches!(err, CacheError::UnsafeUrl),
+                "{url} must be a security failure, got {err:?}"
+            );
+        }
+        // The guard rejected before touching the filesystem: no `.mp4` cached
+        // and no `.part` temp staged.
+        let leftovers: Vec<String> = std::fs::read_dir(tmp.path())
+            .expect("read tempdir")
+            .flatten()
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .collect();
         assert!(
-            cache_mp4(tmp.path(), "http://example.com/x.mp4", DEFAULT_MAX_CACHE_BYTES)
-                .await
-                .is_err(),
-            "non-https url must be refused"
+            leftovers.is_empty(),
+            "guard must reject before any file is created; found {leftovers:?}"
+        );
+    }
+
+    #[test]
+    fn redact_url_drops_userinfo_query_and_fragment() {
+        // Credentials / signed tokens must never reach a logged error string.
+        assert_eq!(
+            redact_url("https://user:pass@cdn.example.com/a.mp4?sig=secret#frag"),
+            "https://cdn.example.com/a.mp4"
+        );
+        assert_eq!(
+            redact_url("https://cdn.example.com/a.mp4"),
+            "https://cdn.example.com/a.mp4"
         );
+        assert_eq!(redact_url("https://cdn.example.com"), "https://cdn.example.com");
     }
 
     #[test]

From b5beee66c2f2c884825844311446861de22c4e12 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Sun, 2 Aug 2026 18:37:33 +0200
Subject: [PATCH 6/6] test(canvas): regression-test the cache_mp4 redirect hop
 limit

CodeRabbit round on #479. Extract the redirect-policy decision into a pure
`redirect_decision(previous_hops, url)` -> `RedirectDecision` and unit-test the
"10 hops allowed, 11th rejected" boundary + per-hop SSRF re-validation.

A live mock-server test is infeasible here: `is_safe_motion_url` refuses
loopback, so every hop to a 127.0.0.1 mock is rejected as unsafe before the
count matters (and the initial request to it is refused up front). Splitting the
decision out makes the limit deterministically testable with no network.
---
 .../crates/core/src/artwork/motion_cache.rs   | 68 ++++++++++++++++---
 1 file changed, 60 insertions(+), 8 deletions(-)

diff --git a/src-tauri/crates/core/src/artwork/motion_cache.rs b/src-tauri/crates/core/src/artwork/motion_cache.rs
index 435f9ffe..774cac04 100644
--- a/src-tauri/crates/core/src/artwork/motion_cache.rs
+++ b/src-tauri/crates/core/src/artwork/motion_cache.rs
@@ -150,6 +150,35 @@ impl std::fmt::Display for CacheError {
 
 impl std::error::Error for CacheError {}
 
+/// Decision for a single redirect hop, split out of the [`cache_mp4`] redirect
+/// policy so the hop budget + per-hop SSRF re-validation are unit-testable
+/// without a live server. (A local mock server can't exercise this path: every
+/// hop to `127.0.0.1` is refused as [`RedirectDecision::Unsafe`] by the SSRF
+/// guard before the count ever matters, and the initial request to it is
+/// rejected up front — so the limit is only reachable as pure logic.)
+#[derive(Debug, PartialEq, Eq)]
+enum RedirectDecision {
+    /// Safe target within the hop budget — follow it.
+    Follow,
+    /// Hop budget exhausted (matches reqwest's default of 10). Abort.
+    TooMany,
+    /// Target failed [`is_safe_motion_url`]. Abort.
+    Unsafe,
+}
+
+/// `previous_hops` counts redirects already followed. Allow up to 10 and reject
+/// the 11th (reqwest's default), and re-validate each hop's target — the hop
+/// limit is checked first so an over-long chain fails closed regardless.
+fn redirect_decision(previous_hops: usize, url: &str) -> RedirectDecision {
+    if previous_hops > 10 {
+        RedirectDecision::TooMany
+    } else if is_safe_motion_url(url) {
+        RedirectDecision::Follow
+    } else {
+        RedirectDecision::Unsafe
+    }
+}
+
 /// Return the local path of `url`'s cached mp4, downloading it first if absent.
 /// Hash-addressed by the (stable, per-album) source URL. On a hit the mtime is
 /// bumped for access-LRU; on a miss the body is streamed under [`MAX_MP4_BYTES`],
@@ -186,14 +215,10 @@ pub async fn cache_mp4(dir: &Path, url: &str, max_cache_bytes: u64) -> Result<Pa
     let client = reqwest::Client::builder()
         .timeout(Duration::from_secs(30))
         .redirect(reqwest::redirect::Policy::custom(|attempt| {
-            // Match reqwest's default of 10 redirects: `previous()` counts the
-            // hops already taken, so allow up to 10 and reject the 11th.
-            if attempt.previous().len() > 10 {
-                attempt.error("too many redirects")
-            } else if is_safe_motion_url(attempt.url().as_str()) {
-                attempt.follow()
-            } else {
-                attempt.error("unsafe redirect target")
+            match redirect_decision(attempt.previous().len(), attempt.url().as_str()) {
+                RedirectDecision::Follow => attempt.follow(),
+                RedirectDecision::TooMany => attempt.error("too many redirects"),
+                RedirectDecision::Unsafe => attempt.error("unsafe redirect target"),
             }
         }))
         .build()
@@ -433,6 +458,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn redirect_decision_allows_ten_hops_then_rejects() {
+        let safe = "https://cdn.example.com/a.mp4";
+        // Up to 10 previously-followed hops with a safe target: keep following.
+        for hops in 0..=10 {
+            assert_eq!(
+                redirect_decision(hops, safe),
+                RedirectDecision::Follow,
+                "hop {hops} within budget must follow"
+            );
+        }
+        // The 11th redirect (and beyond) is refused regardless of target.
+        assert_eq!(redirect_decision(11, safe), RedirectDecision::TooMany);
+        assert_eq!(redirect_decision(50, safe), RedirectDecision::TooMany);
+        // A safe hop count but an internal target is refused as unsafe...
+        assert_eq!(
+            redirect_decision(0, "https://127.0.0.1/a.mp4"),
+            RedirectDecision::Unsafe
+        );
+        // ...and the hop limit takes precedence over the SSRF check (both
+        // fail closed, but an over-long chain reports `TooMany`).
+        assert_eq!(
+            redirect_decision(11, "https://127.0.0.1/a.mp4"),
+            RedirectDecision::TooMany
+        );
+    }
+
     #[test]
     fn redact_url_drops_userinfo_query_and_fragment() {
         // Credentials / signed tokens must never reach a logged error string.