| name | spirit-ring-ui |
| description | ElderGPT Spirit Ring UI skill. Activate for persistent overlay, chat panel, settings UI, injected Consult Spirit Ring button, harness validation, session management, pointer isolation, or src/ui changes. |
Spirit Ring UI
The main UI is a persistent body-mounted React/MUI overlay plus targeted injectUI() entry points.
Activate When
- Editing
src/ui/*, src/config/settings.ts, or src/integration/uiBridge.tsx
- Changing chat sessions, unread state, settings, markdown rendering, streaming display, or injected buttons
- Verifying visual behavior in harness or installed client
Overlay Rules
- Keep the persistent root mounted to
document.body until a deliberate architecture change replaces it.
- Use the installed runtime's
window.React and window.ReactDOM.createRoot() surface where bootstrap code expects it.
- Preserve native capture-phase event isolation for mouse, pointer, keyboard, input, focus, and wheel events.
- Use
injectUI() for targeted affordances like the combat-victory Consult Spirit Ring button, not as a full overlay replacement yet.
State Boundaries
- Local open/minimized/drag UI state stays in React components.
- Chat/session persistence lives in
src/ui/chatSession.ts and src/ui/sessionManager.ts.
- Persisted configuration lives in
src/config/settings.ts.
- Game state comes from the integration snapshot/subscription bridge.
Validation
bun run ui:harness:build
bun run ui:harness:serve
Use the harness for open/close behavior, unread badges, session switching, settings layout, markdown rendering, and simulated proactive messages. Live game checks are only for runtime-specific overlay/injected UI behavior.
Gotchas
- Game panels can steal events: preserve capture-phase event stopping on the overlay root.
- ReactDOM import paths can differ: keep bootstrap aligned with installed runtime globals.
- Session pruning is intentional: max 20 sessions; don't remove without UX/storage rationale.
- Injected button opens the same overlay: avoid duplicate chat roots.
References
docs/project/UI_ARCHITECTURE.mddocs/project/LIVE_GAME_TESTING.mdsrc/ui/ElderGPTApp.tsxsrc/ui/components/ChatPanel.tsxsrc/ui/sessionManager.tssrc/integration/uiBridge.tsx
