perf(appearance): draw avatar thumbnails from images instead of live VRM previews

[AUDOSt0ck1ng]

refs #10. Measurements and the reasoning behind the approach are in
#10 (comment) — the short
version is that the previews' render loops, the extra WebGL contexts and the
drawer's backdrop-filter all measured free, and the entire cost was parsing
three full VRMs (49MB) to draw three 56px circles. That is main-thread
CPU-bound work that cannot be scheduled or parallelised away, so the issue's
"static thumbnails" alternative is the only option with a real ceiling.

On Windows 11 with an integrated GPU, blocked frame time in the 4.5s after
Appearance opens: ~3725ms on first open, ~3492ms on reopen. Both go away —
no VRM is parsed to show the picker.

Since the previews were already motionless portraits, replacing them with an
image loses nothing visually.

Approach

• Bundled avatars ship a pre-rendered PNG, generated by npm run thumbs.
• User-folder avatars render once and cache under userData/thumbnails/,
  keyed by path + mtime + size, so replacing a .vrm regenerates it.
• Generation is serialised with a yield between models, so first sight of a new
  folder fills the picker in progressively rather than freezing it.
• Generation reuses the app's own renderer rather than a separate headless-GL
  or Puppeteer pipeline, so committed thumbnails cannot drift from the ones
  generated for a user's own files.

Appearance now holds one WebGL context instead of one per avatar. That also
removes a latent failure: loadLibraryAvatars places no cap on how many .vrm
files a custom folder may contain, and browsers cap live WebGL contexts — a
large folder would have started losing thumbnails to context eviction.

Commits

Two of these are independent of the thumbnail work and can be split out if you
would rather take them separately:

• fc7ecf2 — VrmAvatar detached models without ever disposing them, so every
  avatar swap stranded a model's worth of geometries, materials and textures in
  VRAM for the rest of the session.
• 0d2ee51 — dev:desktop waited on and loaded 127.0.0.1:5173 while Vite
  binds localhost (::1 here), so wait-on never resolved and Electron was
  never launched; it silently started a bare Vite server instead. Also pins the
  port, which otherwise drifts when 5173 is taken while the script keeps
  pointing at 5173.
• d6f1261 — the thumbnail work.
• cf3acd2 — three issues found on review: a leak when a file parses but has
  no VRM payload (a .glb renamed .vrm), a stale portrait after replacing a
  file in place, and a cache-write failure discarding an already-rendered
  thumbnail.

Testing

• Verified by hand: Appearance opens without a stall.
• Bundled thumbnails regenerate byte-identically across the review refactors.
• eslint clean apart from two findings that predate the branch.

Not covered

• VRoid Hub characters use a different path and are untouched.
• The disk cache does not prune thumbnails for avatars removed from a folder.
  Bounded in practice (~10KB each) but unbounded in principle.
• The environments section is untouched. As noted in the issue, its flicker
  looks unrelated — that section has no WebGL, only <img> GIFs totalling
  ~32MB with no loading="lazy" on the built-in row.

Happy to adjust framing, thumbnail size, or the placeholder treatment.

🤖 Generated with Claude Code

[AUDOSt0ck1ng]

Demo:
https://youtube.com/shorts/MRLRtAWtW5M

[AUDOSt0ck1ng]

Potential Issue:

1. Thumbnail looks like empty when model charactor is not tall enough.
2. Choosing Custom VRM Folder at first time will lead to a thumbnails building process (still latency).
3. Thumbnail cache will not be remove when you try to remove VRM from folder.

[rosspeili]

Thanks @AUDOSt0ck1ng, strong approach on this.

Some tips before merge

• CHANGELOG.md [Unreleased] entry (perf + bundled thumbs + custom-folder cache, mention dev:desktop fix if kept here)
• Docs: short contributor note for npm run thumbs and regenerating src/assets/avatars/thumbs/ when bundled avatars change (CONTRIBUTING.md and/or docs/development/project-layout.md)
• Optional one line in docs/using-the-app.md that picker thumbs are static images (custom folder fills in progressively on first scan)

Known limits (fine to track as follow-ups)

• Short models / empty-looking portraits
• First sight of a new custom folder still builds thumbs progressively
• Cache doesn’t prune thumbs for files removed from the folder (you noted, I'd say low priority)

Demo

• Your YouTube short would be great as a GIF as with feat: link a hearted model back to its VRoid Hub page #19 in docs if you’re up for it, eg. before/after opening Appearance with a custom folder

Happy to merge once changelog + contributor docs are in. Thanks again for the thorough measurement and the self-review pass in cf3acd2. <3

[rosspeili]

Re your three follow-ups, agree they’re acceptable for merge, tracking the rest in a follow-up issue (sidecar + pre-warm on directory save + cache prune on scan #21). Short-model framing and env GIF flicker stay out of scope here and will be in #22. Thanks for calling them out explicitly.

[AUDOSt0ck1ng]

That video merely demonstrates performance improvements; there are no actual new differences, and it isn't really suitable for editing—converting it to a GIF would result in a huge file size. So, I decided to omit the GIF.

[rosspeili]

This looks good too @AUDOSt0ck1ng. Happy to merge. Again, follow-ups stay in #21/#22. Thanks! <3