OpenSpec Change: enterprise-gaming-react-dialogue

Change ID: enterprise-gaming-react-dialogue
Package: @suaveplan/react-dialogue
Category: gaming/react
Target path: gaming/react/react-dialogue
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-dialogue.md

Summary

Deliver @suaveplan/react-dialogue on the genesis branch from scratch at enterprise quality. The package is the headless React layer around @suaveplan/dialogue. A DialogueUIStateManager wraps a ConversationSession; useDialogue() provides access via useSyncExternalStore; typed components display the current node text, speaker name, typewriter text animation, and choice buttons with condition-gated disabled state. Genesis adds Storybook stories, Vitest DOM tests, and 100% coverage.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/dialogue` (`workspace:^`)	`ConversationSession`, `DialogueTree`
`@suaveplan/events` (`workspace:^`)	Dialogue event subscriptions
`react` (`catalog:react`)	React 18

Public API surface

function createDialogueUIStateManager(session: ConversationSession): DialogueUIStateManager
function useDialogue(): DialogueUIState

// Components
function DialogueBox(props: DialogueBoxProps): JSX.Element         // speaker + text
function DialogueChoices(props: DialogueChoicesProps): JSX.Element // choice buttons
function TypewriterText(props: TypewriterTextProps): JSX.Element   // animated reveal
function SpeakerPortrait(props: SpeakerPortraitProps): JSX.Element // optional avatar

File layout

gaming/react/react-dialogue/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    types/common.ts
    types/common.md
    state/
      dialogue-ui-state-manager.ts
      dialogue-ui-state-manager.md
      dialogue-ui-state-manager.test.ts
    hooks/
      use-dialogue.ts
      use-dialogue.md
      use-dialogue.test.ts
    components/
      dialogue-box/ (tsx + md + test + stories + index)
      dialogue-choices/ (tsx + md + test + stories + index)
      typewriter-text/ (tsx + md + test + stories + index)
      speaker-portrait/ (tsx + md + test + stories + index)

Impact

Downstream: game apps compose dialogue UI over R3F scene. Prerequisites: @suaveplan/dialogue, @suaveplan/events, react.

2.5 KiB Raw Blame History