Enhance screenshot vision handling and cache management

docs/apocalypse-mode.md

@@ -12,18 +12,17 @@ not enable Apocalypse Mode, query the Kiwix catalog, or store article text.
 Open the **☢ Apocalypse Mode** link beside **Support** in the Settings header to
 opt in.
 
-On supported Chromium browsers, enabling Apocalypse Mode also enables the
-local LFM2.5-VL vision fallback and immediately starts caching its approximately
-770 MB model from Hugging Face in the background. The management page shows
-that progress, and the download continues if the page is closed as long as
-Chrome remains open. Wikipedia archives still require their own confirmation.
-The local **text** model defaults to LFM2.5 2.6B (about 1.55 GB) and that
-download starts automatically. Bonsai 27B is an opt-in second preset
-(about 3.8 GB, 16 GB+ RAM/VRAM recommended) and is never auto-downloaded.
-WebBrain checks hardware WebGPU support before selecting the local provider. If
-that check or an automatically started download fails, any configured remote
-vision provider becomes active again. Disabling local vision in Settings is an
-explicit opt-out and is not undone when the service worker restarts.
+On supported Chromium browsers, local LFM2.5-VL vision is an optional fallback.
+Apocalypse Mode never enables or downloads it. The dedicated **Use local
+fallback** control in **Settings → Multimodal → Vision** checks WebGPU support,
+records explicit consent, and starts caching the approximately 770 MB model
+from Hugging Face. The download continues in the background, but screenshot
+operations report its status and never wait for it. Wikipedia archives still
+require their own confirmation. The local **text** model defaults to LFM2.5
+2.6B (about 1.55 GB), and that download starts automatically when Apocalypse
+Mode is enabled. Bonsai 27B is an opt-in second preset (about 3.8 GB, 16 GB+
+RAM/VRAM recommended) and is never auto-downloaded. Disabling local vision
+preserves its cache and any configured remote vision provider.
 
 Archive language is selected independently from WebBrain's interface language.
 The management page reads Kiwix's current OPDS catalog and offers a language plus
@@ -72,8 +71,8 @@ current entry.
 - Catalog downloads continue in the background after the management page is
   closed. Reopen Apocalypse Mode to inspect progress or pause the download.
 - The Chromium-only local vision model uses the browser's Transformers cache.
-  After the automatic download completes, its GPU allocations are released
-  until WebBrain actually needs local screenshot analysis.
+  After its explicitly requested download completes, its GPU allocations are
+  released until WebBrain actually needs local screenshot analysis.
 - An installed archive that later becomes unreadable because of corruption,
   eviction, or a revoked file grant moves from ready to an actionable error;
   WebBrain reports the read failure instead of misreporting an empty search.

docs/providers-and-models.md

@@ -422,15 +422,19 @@ The user can configure a separate vision provider for screenshot description. Th
 
 ```js
 const vision = await providerManager.getVisionProvider();
-// Returns a dedicated OpenAI-compatible or in-browser vision provider, or null
+// Returns the explicit dedicated OpenAI-compatible vision provider, or null.
+// Screenshot callers use resolveVisionRoute(activeProvider) to consider raw
+// active-provider vision and the explicitly enabled, ready local fallback.
 ```
 
 On Chromium, **Settings -> Multimodal -> Vision** also offers a one-click
 in-browser fallback. It runs `LiquidAI/LFM2.5-VL-450M-ONNX` through WebGPU in a
 dedicated Worker with FP16 embeddings/vision encoder and a Q4 decoder. The
 model is not present in the general provider catalog and never receives agent
-tools or planning turns. First use downloads approximately 770 MB of model
-data from Hugging Face into the browser cache. That download runs in Chrome's
+tools or planning turns. Local vision is disabled by default and neither
+Apocalypse Mode nor a screenshot operation can enable it or start its download.
+The dedicated control probes WebGPU, records versioned consent, and then downloads
+approximately 770 MB of model data from Hugging Face into the browser cache. The download runs in Chrome's
 offscreen extension worker, so the user may switch tabs or close Settings while
 it continues, but must keep Chrome running. Screenshots stay on-device and
 only the generated description is passed to the active provider. The local
@@ -440,6 +444,15 @@ endpoint or its credentials. Disabling it releases the loaded model and GPU
 resources while retaining the browser-cached download. Firefox does not expose
 this option because its build has no MV3 offscreen document.
 
+Screenshot routing is deterministic: an explicit dedicated vision endpoint,
+then a vision-capable active provider receiving raw pixels, then an explicitly
+enabled and already-ready local fallback. If none is ready, inspection returns a
+recoverable availability result; automatic screenshots skip enrichment and let
+the task continue. Screenshot tools never wait for a model download. Dedicated
+and local description calls have a 90-second total deadline, worker startup has
+a 15-second deadline, and a local timeout cancels generation before recreating a
+worker that does not settle within five seconds.
+
 ### Transcription Provider
 
 Used by Tab Recorder for Whisper transcription. Falls back through configured providers in priority order: OpenAI → Groq → LM Studio → llama.cpp. Blocklist excludes providers known not to host Whisper (Anthropic, Gemini, Mistral, DeepSeek, xAI, Nvidia, Kimi), including duplicates of those providers.