refactor(stage): single validated command layer for animation, avatar, environment and audio

[AUDOSt0ck1ng]

What

Gives the stage a single validated entry point for the state changes an external trigger can ask for, replacing the pattern of handing panels AvatarStage's useState setters.

• src/lib/stageCommands.js — resolveStageCommand(command, payload, context) returns either an action or { code, error }. Pure, React- and asset-free, so node --test loads it directly.
• src/hooks/useStageCommands.js — the only place an action is applied.
• src/config/environmentSelection.js — the selection shape, defaultColor and a normalizer, extracted from environments.js so it is reachable without pulling in the bundled GIFs. normalizeUserSettings now shares it instead of parsing the selection inline.
• findAnimation(catalog, query) — matches an id, then a label, and returns null on a miss.

v1 vocabulary matches the bus proposal in #6: animation.play, animation.default, avatar.set, environment.set, audio.source.

Carries one bug fix that the refactor surfaced — see Behaviour changes below.

Why

#6's discussion settled on the local bus first and MCP later as a thin adapter, with the explicit constraint that keyword triggers (#7) and hotkeys (#24) drive the same play/set paths rather than each reimplementing them. That surface did not exist: the only way to change animation, avatar or environment was a React prop, and the handlers behind them were multi-setter sequences spelled out inline.

Two of those sequences are easy to get wrong and neither is obvious from the call site:

• animation.play needs the animationRequest counter as well as the id — re-selecting the clip that is already playing has to restart it, and VrmAvatar's effect keys off the counter for exactly that case.
• avatar.set needs setAvatarReady(false), but only when the model path will actually change — which is where the bug below was hiding.

Resolving separately from applying is what lets a caller be told why a request failed, which a bus needs and a click does not.

avatar.set deliberately takes ids only: bundled labels are Avatar 1…Avatar 3 and a custom folder's labels are filenames, so matching them buys ambiguity and no expressiveness. Animations are the opposite — the label is the meaningful name — so they match both.

Resolution is synchronous and reports acceptance only; a VRM or an environment image may still be loading when a command returns. That will shape the bus's response semantics.

Not in scope

No HTTP server, no preload channel, no settings schema change — those are #6 itself. Camera, light and avatar transform stay on raw setters, as they are not part of the v1 vocabulary. AvatarStage's internal invalidation paths (a custom folder that disappears mid-session) also stay on direct setters: that is not a user request and must not be validated against a catalog it has just left.

Behaviour changes

Fixed: clicking the avatar already on stage made the companion disappear. handleAvatarChange cleared avatarReady on every click, but re-picking the current character leaves modelPath unchanged, so VrmAvatar's load effect never re-ran and onLoaded never fired to set it back — the canvas stayed visibility: hidden until you picked a different avatar or restarted. Pre-existing on main; handleResetAllSettings already guards against the identical hazard, with a comment noting it "looked like a crash". The flag is now cleared only when the model actually reloads, with an active VRoid Hub character counting as one since it owns modelPath while loaded.

Changed: a malformed environment in a hand-edited config.yaml — an env with no id, a non-hex colour, a value with no type — now falls back to the default colour instead of being half-accepted (previously: silently stars, stored as-is, and treated as a colour respectively). This matches how every other unreadable field in the schema is treated, and it is what makes the same validator safe to point at bus input.

Nothing else changes.

Testing

npm run lint, npm test (69 passing, 24 new) and npm run build all pass.

Smoke-tested in dev:desktop, covering what the unit tests cannot:

• re-selecting the current animation restarts it; the Default sequence plays through
• re-selecting the current avatar is a no-op; a different avatar fades correctly; swapping away from a VRoid Hub character and back
• all seven environment paths (built-ins, None, colour picker, Use color, Reset, custom tiles)
• custom .vrma / .vrm / image folders — selection, and Clear back to the bundled catalogs
• persistence across restart, and Reset all settings

Follow-ups

• [Feature]: Configurable hotkeys to trigger animations (one-shot, return to selection) #24 animation hotkeys — a keydown listener calling runCommand
• [Feature]: Local agent/event bus so external tools can drive the avatar #6 the bus itself — electron/vroid-oauth-server.cjs is a working loopback-server precedent; needs a preload channel and a bus block in the settings schema
• [Feature]: Keyword → animation mapping table #7 keyword triggers — text → findAnimation → runCommand

🤖 Generated with Claude Code

[AUDOSt0ck1ng]

I've tested related functions:
Animations

• Pick Peace Sign from the bar menu
• Pick the same animation twice — it restarts (covers the replay counter)
• Pick Default — the full sequence plays through
• Pick any clip after Rest

Avatars

• Switch between Avatar 1 / 2 / 3
• Load a VRoid Hub character, then pick a bundled avatar — the Hub character stands down
• Reactivate the Hub character afterwards

Environments

• Stars / Code / Bloom
• None
• Drag the colour picker
• Use color
• Reset
• Expand Custom and pick a tile

[rosspeili]

Thanks a lot @AUDOSt0ck1ng, this is the right groundwork for #6 / #7 / #24. and thanks for the incosistency fixes at the same time, could be a good idea to name the command layer in docs/architecture/overview.md but can be done in a later pr <3 Merging this as is. Top PR as always <3