[Feature]: Avatar thumbnail follow-ups — sidecars, pre-warm, cache prune

[rosspeili]

One-line summary

Polish custom-folder avatar thumbnails: faster first open, optional sidecar files, cache cleanup — without extra background processes.

Problem / motivation

PR #20 replaces live VRM picker canvases with static PNGs (bundled + userData/thumbnails/ cache). That fixes the ~3.7s Appearance stall. Known follow-ups from review and contributor notes:

1. Short models can look like an empty circle (framing assumes default bust height). Acceptable edge case; optional auto-fit later.
2. First custom-folder scan still parses each .vrm once to build thumbs — progressive, but user still waits on first sight.
3. userData cache does not remove entries when a .vrm is deleted from the folder (orphans are small but unbounded in principle).

Proposed solution

A. Pre-warm on directory apply (high value, low complexity)

When Settings → Directories → Avatars saves a Custom path (and scan finds files), start the existing serial thumbnail queue in the background — do not wait for Appearance to open.

• Reuse getLibraryThumbnail / runQueued from PR perf(appearance): draw avatar thumbnails from images instead of live VRM previews #20; no new process.
• Optional: cap queue to first N visible + rest lazy (if folder is huge).
• UI: small “Building previews…” in Settings or a one-time notice; picker shows placeholders until each thumb lands.

B. Hybrid cache — sidecar + userData (medium value)

Check, in order:

1. Sidecar next to the .vrm (if present and newer than source), e.g.
   MyChar.vrm.png or MyChar.vrm.thumb.png
   — instant load, portable when user copies the folder, no orphan problem when file is deleted.
2. userData/thumbnails/ (PR perf(appearance): draw avatar thumbnails from images instead of live VRM previews #20) — fallback when folder is read-only or no sidecar.
3. Render once — then write userData; optionally write sidecar when the avatar folder is writable (Settings toggle: “Save preview images next to models”, default off or on).

Bundled avatars keep committed src/assets/avatars/thumbs/avatarN.png only (no sidecar in repo).

C. Cache prune on scan (low complexity)

On scanAvatars / library refresh:

• Drop userData PNGs whose source path no longer exists in the scan result.
• Drop in-memory urlCache entries (PR perf(appearance): draw avatar thumbnails from images instead of live VRM previews #20 already calls revokeThumbnailUrls on rescan).

D. Framing for short models (optional / low priority)

• Auto-fit camera to model bounding box (AABB) for thumbnail render only.
• Or document “drop a sidecar PNG if the auto preview looks wrong.”

Alternatives considered

Approach	Why not alone
Sidecar only	Fails on read-only folders; user must manage files
userData only (PR #20)	Orphans + not portable with folder copy
Separate headless/Puppeteer pipeline	Drifts from app renderer; extra process
Worker-thread VRM parse	No GLTF worker path in three.js today
VRoid Hub-style remote portraits	N/A for local .vrm

Primary surface

Appearance (avatars / environments)

Constraints you accept

• Should stay usable offline / local-first
• Browser-only mode may remain limited vs Electron

Mock / sketch / reference (optional)

Out of scope (separate issues)

• Environments built-in GIF flicker / lazy-load (code.gif size)
• VRoid Hub characters (already use Hub portraits)

Use template Feature request. Link PR #20 and parent #10 when opening on GitHub.

[rosspeili]

Related memory hygiene for custom libraries (same “don’t pay for what isn’t on stage” idea as thumbs):

1. Lazy VRM blobs — loadLibraryAvatars currently createObjectURLs every file in the folder up front; only the selected model needs a blob until swap. Same pattern for custom env media if we preload all GIFs.
2. Hub session blob — after switching to a local avatar, revoke the inactive Hub blobUrl and re-fetch on reactivate (today it can linger alongside the live VRM).

Pre-warm / sidecars / prune stay as written; these two avoid holding unused bytes in the renderer.