feat(animations): custom .vrma folder in Settings → Directories

[AUDOSt0ck1ng]

Implements #23, including the docs request added in the issue comment. Left for you to close — the UI extensibility point raised in the thread is unresolved and may be worth keeping the issue open for.

What

Settings → Directories → Animations is no longer greyed out. Point it at a folder of .vrma files and Gear → Animations lists those clips instead of the bundled catalog — replace semantics, matching Avatars, so the Default sequence and the VRMA Motion Pack are hidden while Custom is active.

Flat top-level scan, .vrma only, file names become labels. A folder with no .vrma is not applied (error notice, previous source kept). The selection persists as the scanned id, which hashes the file path, so it survives restarts and rescans; a clip gone since last launch falls back to the first in the folder, and returning the row to Default restores the bundled default sequence.

Why it touches more than the Directories row

The catalog was only reachable as a module singleton — getAnimationById / resolveVrmaUrl / getSelectableAnimations closed over animationCatalog, and BarCommandMenu and VrmAvatar called them with no way to inject one. They now take the catalog to read.

createVrmaResolver is not ceremony: playSequence does ids.map(resolveUrl), so handing it the now-two-arity resolveVrmaUrl would pass the array index in as the catalog and silently resolve nothing. A test maps the resolver over an array specifically to lock that.

Two leaks surfaced while testing the swap path and are fixed here: bailing out mid-load dropped the only references to blob urls already minted in that loop, and useVrmAnimation's cache keys on url — a custom folder minting fresh blob urls per rescan grew it without bound.

Test scope change

To get the lookups under test, config/animations.js is split into vrmaAssets.js (Vite-resolved .vrma imports), animationLookup.js (pure lookups), and a composing entry point that re-exports both. Public API and every call site are unchanged. The split is what makes them loadable by plain node --test, which cannot resolve a .vrma import.

npm test now also runs src/**/*.test.mjs, and CONTRIBUTING gains a Where tests go section documenting the constraint and the split pattern.

How tested

npm run lint, npm test (48 pass), npm run build — all clean, and CI green on the fork.

Automated — 13 new tests. Main process (6): .vrma filtering and sort, .vrm / .vrma isolation including case, flat scan, empty/missing/non-directory/null paths, id stability plus byte correctness, and read-throws for a vanished file. Lookups (7): catalog isolation between bundled and custom ids, never returning undefined, resolveVrmaUrl answering only for vrma entries, the .map() footgun, selectable handling, and all resolveAnimationId fallbacks.

By hand — real Electron production build against an isolated --user-data-dir so no live config was touched. Verified: scan + IPC + blob load + catalog swap + id resolution (a .vrm decoy and a nested clip correctly excluded), a custom clip actually retargeting onto the avatar, restart persistence of a mid-list clip, empty-folder rejection, per-file skip, and the bundled Default sequence still mapping all 7 pack ids to their own distinct assets after the split.

loadLibraryAnimations and the AvatarStage effect need React / DOM / URL.createObjectURL and have no automated coverage — they are covered by the manual pass above only.

Notes for review

Entering Custom commits one render with an empty catalog, so the avatar rests until the folder finishes loading. Kept deliberately — it matches Avatars (which shows no model at all while loading), and falling back to the bundled catalog meanwhile would flash the Default greeting.

One behavioural sharp edge worth knowing, documented rather than fixed: a .vrma the app cannot stat (permission-denied) is dropped by the scan itself, so a folder of only those reports "no .vrma files" rather than a read error. The per-file skip-and-count path only covers clips that vanish between the scan and the load.

Docs updated: VRMA guide (incl. the Bring your own .vrma authoring/licensing section requested in the issue), using-the-app, user-settings, manual-testing, assets-and-credits, architecture overview, project layout, roadmap, README, CHANGELOG, CONTRIBUTING, and the animation issue template.

Follow-ups (not in this PR)

Both are pre-existing and affect all three Directories rows equally:

• On launch, a bad folder correctly falls back to Default in state, but the correction is not written back to config.yaml — the hydrate skipNextSave consumes that save — so the error notice returns every launch.
• Re-picking the same folder does not rescan (the effect keys on the path), so edits on disk need a different folder or a restart. Documented as current behaviour.

🤖 Generated with Claude Code

[rosspeili]

Thanks @AUDOSt0ck1ng, this looks good for start for 23, merging as-is. Will open a follow-up to flip the menu to additive (bundled always available + custom appended, scroll, custom accent, filter) on top of this plumbing, not a change request on this PR.

[AUDOSt0ck1ng]

Demo:
https://www.youtube.com/watch?v=Ch2c5GIV3WE