Phase 6: Minigames Set 2 — Fact or Friction, Undercover Editor, Minimalist Masterpiece, Emoji Cinema¶

Depends on: Phase 4 (Minigame Engine & Lifecycle), Phase 5 (first minigame set establishes implementation patterns: BaseMinigame extensions, registry registration, constants, Zod schemas, data pipelines, client components, and buildGameLog())

Parallelizable with: Phase 7, Phase 8 — after Phase 5 is complete, Phases 6, 7, and 8 can be implemented in parallel since they share no inter-dependencies. Each phase independently extends BaseMinigame, registers games in the shared registry, and follows the patterns established in Phase 5.

This phase implements the second set of four minigames for RMHbox. Each game extends BaseMinigame from Phase 4 and integrates with the existing lobby, lifecycle, scoring, and award systems established in Phases 1–4.

6.1 Fact or Friction¶

Game ID: fact-or-friction | Category: trivia | Icon: flame Players: 2–16 | Duration: ~176s (8 questions)

6.1.1 Install NPM Packages¶

No additional NPM packages required for Fact or Friction
- The question pool is a static JSON file; the Point Pot is a server-side timer. Verification: Confirm no new dependencies needed beyond those installed in Phase 1.

6.1.3 Create Static Data Files¶

Create directory data/rmhbox/fact-or-friction/ Verification: Directory exists on disk.
Create data/rmhbox/fact-or-friction/questions.json — curated trivia question pool
- Each entry follows the TriviaQuestion interface:
```
{
  question: string;
  options: string[];           // exactly 4 options (A, B, C, D)
  correctIndex: number;        // 0–3
  category: string;            // e.g., "Science", "History", "Pop Culture"
  difficulty: "easy" | "medium" | "hard";
  source: string;              // attribution / fact-check source
}
```
- Include at least 100 questions total
- Balanced difficulty: ≥30 easy, ≥30 medium, ≥30 hard
- At least 8 distinct categories represented
- All questions fact-checked; source field populated for each
- No duplicate questions
- All options arrays have exactly 4 entries
- correctIndex is 0, 1, 2, or 3 for every question Verification: Parse JSON; validate every entry against schema; confirm difficulty distribution; confirm all correctIndex values are in range 0–3; confirm no duplicate id values; confirm ≥8 unique categories.

6.1.4 Define Zod Validation Schemas¶

Create lib/rmhbox/fact-or-friction/schemas.ts
Define SubmitAnswerSchema:
```
const SubmitAnswerSchema = z.object({
  selectedIndex: z.number().int().min(0).max(3),
});
```
Verification: Valid: { selectedIndex: 0 }, { selectedIndex: 3 }. Invalid: { selectedIndex: -1 }, { selectedIndex: 4 }, { selectedIndex: 1.5 }.
Define PassQuestionSchema:
```
const PassQuestionSchema = z.object({});
```
Verification: Valid: {}. Extra fields stripped by Zod.

Define TriviaQuestionSchema for data validation at server startup:

const TriviaQuestionSchema = z.object({
  id: z.string().min(1),
  question: z.string().min(10),
  options: z.array(z.string().min(1)).length(4),
  correctIndex: z.number().int().min(0).max(3),
  category: z.string().min(1),
  difficulty: z.enum(["easy", "medium", "hard"]),
  source: z.string().min(1),
});

Verification: Validate all entries in questions.json against this schema at server startup.

6.1.5 Create Data Loader¶

Create lib/rmhbox/fact-or-friction/question-loader.ts
- Export loadQuestions(): TriviaQuestion[] — reads and parses questions.json once at server init
- Validate each question against TriviaQuestionSchema during load; skip invalid entries with a warning log
- Cache in module-level variable (singleton pattern)
- Export selectQuestionsForGame(pool: TriviaQuestion[], usedIds: Set<string>): TriviaQuestion[]
  - Select questions according to FF_QUESTION_DISTRIBUTION (3 easy, 3 medium, 2 hard)
  - Exclude questions with IDs in usedIds (prevents repeats within a lobby session)
  - Avoid consecutive questions from the same category when possible
  - Shuffle within each difficulty bucket before selection
  - Return an ordered array of 8 questions Verification: Unit test: call loadQuestions() twice → same reference returned. Call selectQuestionsForGame() with empty exclusion → 8 questions with correct distribution. Call again with previous IDs excluded → 8 different questions. Confirm no consecutive same-category when pool size allows.

6.1.6 Implement Server Handler¶

Create server/rmhbox/minigames/fact-or-friction.ts

6.1.6.1 Type Definitions¶

Define FFPhase enum:

type FFPhase = 'QUESTION_REVEAL' | 'ANSWER' | 'ANSWER_REVEAL' | 'PAUSE';

Verification: Type has exactly 4 values matching spec.

Define PlayerAnswer type:

type PlayerAnswer = {
  userId: string;
  selectedIndex: number | null;   // null = pass
  potValueAtSubmission: number;
  submittedAt: number;
  isCorrect: boolean;
  scoreChange: number;            // +pot, -pot, or 0
};

Define QuestionResult type:

type QuestionResult = {
  questionIndex: number;
  question: TriviaQuestion;
  playerAnswers: PlayerAnswer[];
  fastestCorrectUserId: string | null;
  correctCount: number;
  incorrectCount: number;
  passCount: number;
};

Define FactOrFrictionState type:

type FactOrFrictionState = {
  questions: TriviaQuestion[];
  currentQuestionIndex: number;
  totalQuestions: number;
  phase: FFPhase;
  potValue: number;
  potStartedAt: number;
  playerAnswers: Map<string, PlayerAnswer>;
  playerScores: Map<string, number>;
  questionHistory: QuestionResult[];
  phaseStartedAt: number;
  phaseEndsAt: number;
};

Verification: All types compile without errors. Cross-reference every field against design spec §1.4.

6.1.6.2 Class: `FactOrFrictionGame extends BaseMinigame`¶

Constructor: call super(context); load question pool via question loader Verification: Instantiate class; confirm no errors and question pool is loaded.

6.1.6.3 State Initialization (`start()`)¶

Retrieve usedQuestionIds from the lobby’s session context (prevents repeats across games in same lobby)
Call selectQuestionsForGame() with the pool and exclusion set
Initialize playerScores map with 0 for each player in context.players
Initialize empty playerAnswers map
Set currentQuestionIndex = -1 (will be incremented to 0 on first call)
Set totalQuestions = FF_TOTAL_QUESTIONS
Set questionHistory = []
Call startNextQuestion() Verification: Unit test: init with 4 players; confirm 8 questions selected with correct distribution, all scores = 0, no answers recorded.

6.1.6.4 Question Lifecycle¶

startNextQuestion():
- Increment currentQuestionIndex
- If currentQuestionIndex >= totalQuestions, call endGame(); return
- Set phase = 'QUESTION_REVEAL'
- Get current question from questions[currentQuestionIndex]
- Clear playerAnswers map
- Emit rmhbox:game:action with type FF_QUESTION to all lobby members:
```
{
  questionIndex: currentQuestionIndex,
  question: currentQuestion.question,
  options: currentQuestion.options,
  category: currentQuestion.category,
  difficulty: currentQuestion.difficulty,
  potStartValue: FF_POT_START_VALUE,
  answerDurationSeconds: FF_ANSWER_DURATION_SECONDS,
}
```
- Do NOT include correctIndex in this payload
- Schedule startAnswerPhase() after FF_QUESTION_REVEAL_SECONDS (2s) Verification: Unit test: call startNextQuestion() → event emitted without correctIndex. Timer scheduled for 2s. Phase is QUESTION_REVEAL.
startAnswerPhase():
- Set phase = 'ANSWER'
- Set potValue = FF_POT_START_VALUE (1000)
- Set potStartedAt = Date.now()
- Set phaseStartedAt = Date.now()
- Set phaseEndsAt = phaseStartedAt + FF_ANSWER_DURATION_SECONDS * 1000
- Start pot tick interval: every FF_POT_TICK_INTERVAL_MS (500ms):
  - potValue = Math.max(potValue - FF_POT_TICK_VALUE, FF_POT_MIN_VALUE)
  - Emit rmhbox:game:action with type FF_POT_TICK to all: { potValue }
- Start timer tick interval: every 1000ms, emit TIMER_TICK with { timeRemaining }
- Schedule endAnswerPhase() after FF_ANSWER_DURATION_SECONDS (15s) Verification: Unit test: after 1s → pot = 950 (2 ticks at 500ms). After 9s → pot = 100 (min). After 14s → pot still 100. Timer ticks emit decreasing values.
endAnswerPhase():
- Stop pot tick interval
- Stop timer tick interval
- For any player who hasn’t submitted an answer, treat as pass (scoreChange = 0)
- Call computeQuestionResult()
- Set phase = 'ANSWER_REVEAL'
- Emit rmhbox:game:action with type FF_ANSWER_REVEAL to all:
```
{
  correctIndex: currentQuestion.correctIndex,
  correctAnswer: currentQuestion.options[currentQuestion.correctIndex],
  playerResults: Array<FFPlayerQuestionResult>,
}
```
- Emit rmhbox:game:action with type FF_SCORE_UPDATE to all:
```
{
  scores: Array<{ userId, userName, totalScore, scoreChange }>,
}
```
- Schedule startPause() after FF_ANSWER_REVEAL_SECONDS (4s) Verification: Unit test: correctIndex now revealed. Player results include isCorrect, scoreChange, potValueAtSubmission. Scores updated correctly.
startPause():
- Set phase = 'PAUSE'
- Check for pending join-in-progress players; add them to playerScores with 0
- Schedule startNextQuestion() after FF_PAUSE_SECONDS (1s) Verification: JIP players added during pause. Next question starts after 1s.

6.1.6.5 Input Handling — `SUBMIT_ANSWER`¶

Validate phase is 'ANSWER'; reject if not
Parse input through SubmitAnswerSchema; reject on validation failure
Check player hasn’t already answered this question (check playerAnswers map); reject if duplicate
Record answer:
- Get current potValue from server state (NOT from client)
- Compute effective pot: floor(potValue × difficultyMultiplier) where multiplier is FF_EASY_MULTIPLIER, FF_MEDIUM_MULTIPLIER, or FF_HARD_MULTIPLIER based on question difficulty
- Determine isCorrect = (selectedIndex === currentQuestion.correctIndex)
- Compute scoreChange:
  - If correct: +effectivePot
  - If incorrect: -effectivePot
- Apply score floor: newTotal = Math.max(currentScore + scoreChange, FF_SCORE_FLOOR); adjust scoreChange if floor was hit
- Store PlayerAnswer in playerAnswers map
- Update playerScores
Emit FF_ANSWER_LOCKED to answering player ONLY: { potValueAtLock: effectivePot }
Emit FF_PLAYER_ANSWERED to ALL lobby members: { userId, userName } (NOT what they answered)
If ALL players have answered (or passed), immediately call endAnswerPhase() (skip remaining timer) Verification: Unit test: Player answers correctly at pot=800, medium difficulty → scoreChange = +800. Player answers incorrectly at pot=600, hard difficulty → scoreChange = -(600×1.5) = -900; if score would drop below -500, clamped. Duplicate submission rejected. After all players answer, phase ends early.

6.1.6.6 Input Handling — `PASS_QUESTION`¶

Validate phase is 'ANSWER'; reject if not
Parse input through PassQuestionSchema
Check player hasn’t already answered; reject if duplicate
Record pass: PlayerAnswer with selectedIndex = null, scoreChange = 0
Emit FF_PLAYER_ANSWERED to ALL lobby members: { userId, userName }
If ALL players have answered/passed, immediately call endAnswerPhase() Verification: Unit test: pass recorded with scoreChange = 0. Player count check triggers early phase end.

6.1.6.7 Scoring Computation (`computeQuestionResult()`)¶

Build QuestionResult object:
- Count correctCount, incorrectCount, passCount across all playerAnswers
- Determine fastestCorrectUserId: the player with the earliest submittedAt timestamp who answered correctly; null if no one answered correctly
- Store in questionHistory array Verification: Unit test with 4 players (1 correct, 1 incorrect, 1 pass, 1 timeout) → counts are 1/1/2. Fastest correct userId matches the first correct submitter.

6.1.6.8 `getStateForPlayer(userId)`¶

Return object:

{
  currentQuestionIndex: number;
  totalQuestions: number;
  question: string;
  options: string[];
  category: string;
  difficulty: string;
  phase: FFPhase;
  potValue: number;
  timeRemaining: number;
  myAnswer: { selectedIndex: number; potValueAtLock: number } | null;
  myHasPassed: boolean;
  playersAnswered: Array<{ userId: string; userName: string; hasAnswered: boolean }>;
  scores: Array<{ userId: string; userName: string; totalScore: number }>;
  questionHistory: QuestionResult[];  // only past revealed questions
}

During ANSWER phase: correctIndex is NOT included in the returned state
During ANSWER_REVEAL phase: include full results with correctIndex
questionHistory only includes questions where the reveal has already occurred
Other players’ individual answers are masked during ANSWER phase (only hasAnswered boolean) Verification: Unit test: during ANSWER → no correctIndex, myAnswer shows lock info. During ANSWER_REVEAL → correctIndex visible, all player results visible. Other players’ selectedIndex hidden during ANSWER.

6.1.6.9 `getStateForSpectator()`¶

Same as player view (spectators have no privileged information during answer phase since correct answers are hidden from everyone)
During ANSWER_REVEAL: same as player view with full results Verification: Spectator state matches player state structure.

6.1.6.10 Join-in-Progress Handling¶

Policy: join_next_subround
Check for pending players during startPause() transition (between ANSWER_REVEAL and next QUESTION_REVEAL)
Initialize new player in playerScores with 0
New player can interact starting from the next ANSWER phase
Send full state via getStateForPlayer() on join Verification: Unit test: player joins during question 3 → participates from question 4 onward with score 0.

6.1.6.11 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

Send full state including current question, pot value, their locked answer (if any), and score history
If ANSWER phase still active and player hasn’t answered, they can still answer
If they missed an entire question (disconnected during it), they score 0 for that question (treated as pass)
Send current TIMER_TICK with accurate timeRemaining Verification: Unit test: disconnect during ANSWER with no answer, reconnect → can still answer. Disconnect for entire question → scored as pass (0).

6.1.6.12 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

Player’s existing answer (if any) is preserved
If phase is ANSWER and player hasn’t answered, they will be treated as timeout/pass at phase end
No special behavior — unanswered questions score 0 Verification: Unit test: player disconnects mid-ANSWER without answering → scored as pass at phase end.

6.1.6.13 `computeResults()` and Awards¶

Compute final rankings by cumulative playerScores (descending)
Compute awards:
- Pot Sniper — answered correctly at the highest pot value (fastest correct answer) across all questions; icon: crosshair
- Friction Burn — lost the most points from incorrect answers (largest total negative scoreChange); icon: flame
- Cool Head — passed the most questions (risk-averse play); icon: snowflake
- Perfect Score — answered every question correctly (0 incorrect, 0 passes); icon: check-circle
- Comeback Kid — had the biggest single-question positive score swing from negative territory (was at negative score, then answered correctly for the largest positive delta); icon: trending-up
Return MinigameResults with rankings, awards, and gameSpecificData containing questionHistory Verification: Unit test: construct scoring scenarios triggering each award → all 5 awards assigned correctly to different players.

6.1.6.14 `buildGameLog()`¶

Maintain an actionLog: GameLogAction[] array on the game instance
Build GameLog conforming to core.md §13.3, including gameSettings per §12A.11

initialState (from minigames-2.md §1.15):

interface FFInitialState {
  totalQuestions: number;
  potStartValue: number;
  potDecayRate: number;
  playerIds: string[];
  categoryPool: string[];
  gameSettings: GameSettingValues;
}

Actions Logged:

Action Type	Payload	Recorded When
`question_start`	`{ questionIndex: number; questionText: string; options: string[]; category: string; potValue: number }`	Question is revealed
`player_answer`	`{ userId: string; selectedIndex: number; potValueAtSubmission: number; elapsedMs: number }`	Player locks in answer
`player_pass`	`{ userId: string; elapsedMs: number }`	Player passes or timer expires
`question_result`	`{ correctIndex: number; correctCount: number; incorrectCount: number; passCount: number; fastestUserId: string \| null }`	Answer reveal phase

In computeResults(), build GameLog with initialState, full action log, and finalResults
Return GameLog from buildGameLog() Verification: Unit test: 8-question game, verify log has 8 question_start and 8 question_result actions, player_answer and player_pass actions present, initialState has all required fields, finalResults matches player rankings.

6.1.7 Register Game in Minigame Registry¶

Add entry to lib/rmhbox/minigame-registry.ts:

{
  id: "fact-or-friction",
  displayName: "Fact or Friction",
  description: "High-stakes trivia where wrong answers cost you! Race to answer for maximum points, but one mistake deducts from your score.",
  category: "trivia",
  icon: "flame",
  minPlayers: 2,
  maxPlayers: 16,
  estimatedDurationSeconds: 176,
  supportsTeams: false,
  instructionDurationSeconds: 15,
  preloadAssets: { images: [], sounds: [], data: [], estimatedSizeBytes: 0 },
  joinInProgressPolicy: "join_next_subround",
  tags: ["trivia", "risk", "speed", "knowledge"],
}

Verification: Call registry lookup for "fact-or-friction"; confirm all metadata fields correct and handler instantiates with valid context.

Register server handler in MINIGAME_SERVER_REGISTRY (in server/rmhbox/game-coordinator.ts):
```
import { FactOrFrictionGame } from './minigames/fact-or-friction';
MINIGAME_SERVER_REGISTRY.set('fact-or-friction', FactOrFrictionGame);
```
Verification: MINIGAME_SERVER_REGISTRY.get('fact-or-friction') returns the FactOrFrictionGame class. GameCoordinator can instantiate it with a valid MinigameContext.
Add lazy-load entry in components/rmhbox/MinigameRenderer.tsx:
```
'fact-or-friction': lazy(() => import('./minigames/fact-or-friction/FactOrFrictionGame')),
```
Verification: When lobby enters PLAYING with minigameId: 'fact-or-friction', MinigameRenderer renders <FactOrFrictionGame /> inside <Suspense>. Verify code-splitting in network tab.

6.1.10 Game Settings Integration (§12A)¶

Integrate host-configurable settings using the §12A system established in Phase 5. See lib/rmhbox/game-settings.ts and BaseMinigame.getSetting() for the canonical pattern.

Registry Entry¶

Export FACT_OR_FRICTION_SETTINGS: GameSettingsSchema in lib/rmhbox/minigame-registry.ts with 5 entries:
- totalQuestions (integer, default 8, min 4, max 12, step 1)
- answerDuration (integer, default 20, min 10, max 45, step 5)
- potStartValue (integer, default 100, min 50, max 200, step 25)
- enableScoreFloor (boolean, default true)
- difficulty (select, default 'mixed', options: ['easy','medium','hard','mixed'])
Attach settingsSchema: FACT_OR_FRICTION_SETTINGS to the fact-or-friction MinigameDefinition. Verification: Registry lookup returns definition with settingsSchema containing 5 entries.

Handler `getSetting()` Integration¶

Replace hardcoded constants with this.getSetting() calls in the Fact or Friction handler:

Constant	Setting Key	Replacement
`FF_TOTAL_QUESTIONS`	`totalQuestions`	`this.getSetting('totalQuestions', FF_TOTAL_QUESTIONS)`
`FF_ANSWER_DURATION`	`answerDuration`	`this.getSetting('answerDuration', FF_ANSWER_DURATION)`
`FF_POT_START_VALUE`	`potStartValue`	`this.getSetting('potStartValue', FF_POT_START_VALUE)`
`FF_SCORE_FLOOR`	`enableScoreFloor`	`this.getSetting('enableScoreFloor', FF_SCORE_FLOOR)`
`FF_DIFFICULTY`	`difficulty`	`this.getSetting('difficulty', FF_DIFFICULTY)`

Boolean setting logic: When enableScoreFloor is false, allow player scores to go negative (remove Math.max(0, ...) guard or make it conditional).
Select setting logic: difficulty filters the question pool by tag. When 'mixed', all difficulties are included. Verification: Each constant usage replaced. Handler respects custom settings passed via MinigameContext.gameSettings.

6.1.11 History Display Configuration¶

Implement the history display config for Fact or Friction as defined in minigames-2.md §1.16.

6.1.11.1 Create Detail Component¶

Create components/rmhbox/minigames/fact-or-friction/FactOrFrictionHistoryDetail.tsx:

Render question-by-question breakdown with correct answer highlighted
Show per-player answer indicators (correct/incorrect/timeout)
Display point pot value at each player’s submission time
Show difficulty badge per question (easy/medium/hard)

6.1.11.2 Register History Display¶

Add registration in lib/rmhbox/history-display-registrations.ts:

registerHistoryDisplay({
  minigameId: 'fact-or-friction',
  DetailComponent: FactOrFrictionHistoryDetail,
  searchableFields: [
    { key: 'questions', label: 'Questions', extract: (log) => log.actions.filter(a => a.type === 'question_reveal').map(a => a.payload.question as string) },
    { key: 'categories', label: 'Categories', extract: (log) => log.actions.filter(a => a.type === 'question_reveal').map(a => a.payload.category as string) },
  ],
  filterableFields: [
    { key: 'difficulty', label: 'Difficulty', type: 'select', options: () => ['easy', 'medium', 'hard'] },
    { key: 'correctCount', label: 'Questions Correct', type: 'range', valuePath: 'correctCount' },
  ],
  getSummary: (log) => {
    const questions = log.actions.filter(a => a.type === 'question_reveal');
    return `${questions.length} questions — Trivia challenge`;
  },
});

6.1.11.3 Tests¶

Verify getHistoryDisplay('fact-or-friction') returns a valid config
Verify searchable fields extract question text and categories from a mock game log
Verify filterable fields include difficulty (select) and correctCount (range)
Verify getSummary() returns a meaningful string for a mock game log
Verify DetailComponent renders without errors when given a valid game log

6.2 Undercover Editor¶

Game ID: undercover-editor | Category: social-deduction | Icon: pencil Players: 4–10 | Duration: ~variable (parallel writing, 2 rounds)

Parallel Design: All players write sentences for ALL stories simultaneously. Each player is secretly assigned as the undercover editor of one story. After writing rounds, players review all stories and try to match each story with its undercover editor in an infinite-time review phase.

6.2.1 Install NPM Packages¶

No additional NPM packages required for Undercover Editor
- fuse.js (already in core spec) is used for keyword proximity matching. Verification: Confirm fuse.js is listed in package.json dependencies.

6.2.4 Define Zod Validation Schemas¶

Create lib/rmhbox/undercover-editor/schemas.ts

Define WriteSentenceSchema:

const WriteSentenceSchema = z.object({
  text: z.string().min(UE_MIN_SENTENCE_LENGTH).max(UE_MAX_SENTENCE_LENGTH),
});

Verification: Valid: { text: "The fog rolled in across the harbor." }. Invalid: { text: "Short." } (below 10 chars).

Define EditWordSchema:

const EditWordSchema = z.object({
  sentenceIndex: z.number().int().min(0),
  wordIndex: z.number().int().min(0),
  newWord: z.string().min(1).max(UE_MAX_EDIT_WORD_LENGTH).regex(/^\S+$/),
});

Verification: Valid: { sentenceIndex: 0, wordIndex: 3, newWord: "shadow" }. Invalid: { newWord: "two words" } (contains space).

Define SkipEditSchema:
```
const SkipEditSchema = z.object({});
```
Verification: Valid: {}.
Define CastAccusationSchema:
```
const CastAccusationSchema = z.object({
  targetUserId: z.string().min(1),
});
```
Verification: Valid: { targetUserId: "user_abc123" }. Invalid: { targetUserId: "" }.

6.2.5 Create Data Loader¶

Create lib/rmhbox/undercover-editor/data-loader.ts
- Export loadPrompts(): StoryPrompt[] — reads and parses prompts.json, caches as singleton
- Export loadKeywords(): Keyword[] — reads and parses keywords.json, caches as singleton
- Export selectPromptForGame(pool: StoryPrompt[], usedIds: Set<string>): StoryPrompt — picks a random prompt not in usedIds
- Export selectKeywordForGame(pool: Keyword[], usedIds: Set<string>): Keyword — picks a random keyword not in usedIds Verification: Unit test: call loaders twice → same reference. Selection excludes used IDs.

6.2.6 Implement Server Handler¶

Create server/rmhbox/minigames/undercover-editor.ts

6.2.6.1 Type Definitions¶

Define UEPhase type:

type UEPhase = 'SETUP' | 'WRITE' | 'EDIT' | 'REVIEW' | 'ACCUSATION' | 'REVEAL';

Verification: Type has exactly 6 values matching spec.

Define StorySentence type:

type StorySentence = {
  authorUserId: string;
  authorName: string;
  text: string;                  // current version (may have been edited)
  originalText: string;          // original as submitted
  turnNumber: number;
  words: string[];               // tokenized for editing
};

Define WordEdit type:

type WordEdit = {
  sentenceIndex: number;
  wordIndex: number;
  originalWord: string;
  newWord: string;
  editedOnTurn: number;
};

Define UndercoverEditorState type:

type UndercoverEditorState = {
  storyPrompt: string;
  keyword: string;
  editorUserId: string;
  turnOrder: string[];
  currentTurnIndex: number;
  totalTurns: number;
  phase: UEPhase;
  sentences: StorySentence[];
  edits: WordEdit[];
  editedWordPositions: Set<string>;   // "sentenceIndex:wordIndex"
  votes: Map<string, string>;         // voterId → accusedUserId
  keywordInStory: boolean;
  editorWasCaught: boolean;
  winner: 'editor' | 'writers' | null;
  playerScores: Map<string, number>;
  phaseStartedAt: number;
  phaseEndsAt: number;
};

Verification: All types compile without errors. Cross-reference every field against design spec §2.4.

6.2.6.2 Class: `UndercoverEditorGame extends BaseMinigame`¶

Constructor: call super(context); load prompts and keywords via data loader Verification: Instantiate class; confirm no errors and data pools are loaded.

6.2.6.4 Turn Lifecycle¶

startNextTurn():
- Increment currentTurnIndex
- If currentTurnIndex >= totalTurns, call startReviewPhase(); return
- Determine active player from turnOrder[currentTurnIndex % turnOrder.length]
- Set phase = 'WRITE'
- Emit UE_TURN_START to all: { turnNumber: currentTurnIndex + 1, activeUserId, activeUserName, writeDurationSeconds: UE_WRITE_TIMEOUT_SECONDS }
- Start TIMER_TICK interval (1s)
- Schedule write timeout handler after UE_WRITE_TIMEOUT_SECONDS
- If active player is disconnected, start shorter wait (UE_DISCONNECT_TURN_WAIT_SECONDS); if still disconnected, auto-complete with "..." sentence Verification: Unit test: call startNextTurn() → correct player activated. Timer starts. After timeout → auto-submit "...".
handleWriteTimeout():
- If player has not submitted a sentence, auto-submit "..." as their sentence
- Proceed to Editor edit phase (or next turn if active player IS the Editor) Verification: Timeout fires → "..." sentence added. Phase transitions correctly.
afterSentenceSubmitted():
- Tokenize sentence into words[] array (split by whitespace)
- Create StorySentence and add to sentences
- Emit UE_SENTENCE_ADDED to all: { turnNumber, authorName, sentence: text, fullStory: StorySentenceView[] }
- If active player is NOT the Editor:
  - Check if the Editor is the current turn player; if so, skip edit (Editor edits after their OWN sentence submission)
  - Transition to Editor edit phase
- If active player IS the Editor:
  - The Editor writes AND gets an edit phase on their own turn
  - Transition to edit phase for the Editor Verification: Sentence added and broadcast. Story view updated. Edit phase triggered for Editor.
startEditPhase():
- Set phase = 'EDIT'
- Build EditableStory for the Editor:
  - Include all sentences with word-level tokens
  - Mark isEditable = false for:
    - Words already edited (editedWordPositions)
    - Words in the sentence the Editor just wrote (current turn, if they’re the active player)
  - Mark isEditable = true for all other words
- Emit UE_EDIT_PROMPT to Editor ONLY: { story: EditableStory, editDurationSeconds: UE_EDIT_TIMEOUT_SECONDS }
- Start TIMER_TICK for Editor only
- Schedule edit timeout after UE_EDIT_TIMEOUT_SECONDS
- Non-Editor players see nothing during this phase — they simply see a “The story is being reviewed…” message or similar waiting indicator (no events reveal the edit phase to Writers) Verification: Unit test: Edit prompt sent to Editor only. Writers receive NO edit-related events. Editable words correctly exclude already-edited positions and current sentence.
handleEditTimeout():
- If Editor has not edited or skipped, auto-skip
- Proceed to next turn Verification: Timeout fires → auto-skip. Next turn starts.
afterEditApplied(edit: WordEdit):
- Update the target sentence’s words array with the new word
- Reconstruct text from updated words
- Add edit to edits[] array
- Add position to editedWordPositions
- Emit UE_STORY_UPDATED to ALL: { fullStory: StorySentenceView[] } — story now includes the edit but viewers don’t know which word changed
- Proceed to next turn via startNextTurn() Verification: Edit applied correctly. Story broadcast shows updated text. Old word preserved in edits array. New word visible in story.

6.2.6.5 Input Handling — `WRITE_SENTENCE`¶

Validate phase is 'WRITE'; reject if not
Validate sender is the active turn player; reject if not their turn
Parse input through WriteSentenceSchema; reject on validation failure
Sanitize sentence content (strip any HTML/script tags via sanitizeString())
Call afterSentenceSubmitted() Verification: Unit test: correct player submits valid sentence → accepted. Wrong player submits → rejected. Too-short sentence → rejected.

6.2.6.6 Input Handling — `EDIT_WORD`¶

Validate phase is 'EDIT'; reject if not
Validate sender is the Editor; reject if not
Parse input through EditWordSchema; reject on validation failure
Validate sentenceIndex is within range of sentences
Validate wordIndex is within range of target sentence’s words array
Validate position is editable (not already edited, not current sentence if Editor wrote it)
Sanitize newWord via sanitizeString()
Create WordEdit object and call afterEditApplied() Verification: Unit test: Editor edits a valid word → accepted, story updated. Editor tries to edit already-edited word → rejected. Editor tries to edit their own sentence’s word → rejected. Non-Editor tries to edit → rejected.

6.2.6.7 Input Handling — `SKIP_EDIT`¶

Validate phase is 'EDIT' and sender is the Editor
Parse through SkipEditSchema
No edit applied; emit UE_STORY_UPDATED with unchanged story (to maintain the illusion that something happened — or simply proceed)
Call startNextTurn() Verification: Unit test: Editor skips → no edit recorded, next turn starts.

6.2.6.8 Review Phase¶

startReviewPhase():
- Set phase = 'REVIEW'
- Emit UE_REVIEW_START to all: { fullStory: StorySentenceView[], reviewDurationSeconds: UE_REVIEW_DURATION_SECONDS }
- Start TIMER_TICK interval
- Schedule startAccusationPhase() after UE_REVIEW_DURATION_SECONDS Verification: Review event contains complete story. Timer runs for 20s.

6.2.6.9 Accusation Phase¶

startAccusationPhase():
- Set phase = 'ACCUSATION'
- Build player list (excluding self for each voter)
- Emit UE_ACCUSATION_START to all: { players: Array<{ userId, userName }>, accusationDurationSeconds: UE_ACCUSATION_DURATION_SECONDS }
- Start TIMER_TICK interval
- Schedule endAccusationPhase() after UE_ACCUSATION_DURATION_SECONDS Verification: Accusation event includes all players. Timer runs for 30s.

6.2.6.10 Input Handling — `CAST_ACCUSATION`¶

Validate phase is 'ACCUSATION'; reject if not
Parse through CastAccusationSchema
Validate targetUserId is a real player in the game
Validate sender is NOT voting for themselves (Editor can vote for anyone except themselves)
Update votes map (overwrites previous vote — players can change their vote)
Emit UE_VOTE_CAST to all: { voterId, hasVoted: true } — NOT who they voted for Verification: Unit test: valid vote recorded. Self-vote rejected. Vote change updates map. Other players only see that someone voted, not whom.

6.2.6.11 Reveal Phase¶

endAccusationPhase():
- Set phase = 'REVEAL'
- Tally votes: find the player with the plurality of votes
- Handle tie: if no plurality, Editor wins by default (no one accused)
- Determine editorWasCaught = (mostVotedUserId === editorUserId)
- Determine keywordInStory:
  - Tokenize entire story into individual words (lowercase)
  - Check exact match: does any word === keyword (case-insensitive)?
  - If no exact match, check proximity via fuse.js with threshold UE_KEYWORD_FUZZY_THRESHOLD (0.7) — only for proximity bonus, not for win condition
  - keywordInStory is true ONLY on exact match
- Determine winner and scores per the 4-scenario table:
  - Scenario 1: Editor caught, keyword NOT in story → Writers major win
  - Scenario 2: Editor caught, keyword IS in story → Writers minor win
  - Scenario 3: Editor not caught, keyword IS in story → Editor major win
  - Scenario 4: Editor not caught, keyword NOT in story → Editor minor win
- Apply UE_CORRECT_VOTE_BONUS (+100) to each Writer who voted correctly
- Apply UE_KEYWORD_PROXIMITY_BONUS (+50) to Editor if a fuzzy near-match exists (but no exact match)
- Update playerScores
- Emit UE_REVEAL to all:
```
{
  editorUserId, editorName, keyword, keywordInStory, editorCaught,
  edits: WordEditView[],          // all edits with original → new word
  votes: VoteResult[],            // who voted for whom
  winner: 'editor' | 'writers',
  scores: ScoreResult[],
}
```
Verification: Unit test for each of the 4 scenarios: correct scores assigned. Tie handling defaults to Editor win. Proximity bonus applied when near-match exists. Correct vote bonus applied to savvy Writers.

6.2.6.12 `getStateForPlayer(userId)`¶

If Writer:

{
  storyPrompt: string;
  myRole: 'writer';
  turnOrder: PlayerTurnInfo[];
  currentTurnIndex: number;
  totalTurns: number;
  phase: UEPhase;
  story: StorySentenceView[];      // current text only (no edit history)
  isMyTurn: boolean;
  timeRemaining: number;
  // During ACCUSATION:
  myVote: string | null;
  votedPlayers: string[];          // userIds who have voted (not who for)
}

If Editor:

{
  // All Writer fields PLUS:
  myRole: 'editor';
  keyword: string;
  myEdits: WordEdit[];
  editableStory?: EditableStory;   // only during EDIT phase
}

CRITICAL MASKING: Writer NEVER receives keyword, editorUserId, myEdits, or editableStory
During WRITE/EDIT phases: only active player’s turn info is relevant
During ACCUSATION: votedPlayers shows who has voted but NOT their targets Verification: Unit test: getState for Writer → no keyword, no editorUserId. getState for Editor → keyword present. During ACCUSATION → votes masked.

6.2.6.13 `getStateForSpectator()`¶

Omniscient view:
- Sees who the Editor is
- Sees the keyword
- Sees all edits as they happen (highlighted in story)
- Sees all votes during ACCUSATION (who voted for whom) Verification: Spectator state includes editorUserId, keyword, edits, and full votes map.

6.2.6.14 Join-in-Progress Handling¶

Policy: spectate_only
Roles and turn order are fixed at game start; adding mid-game would disrupt the social deduction
JIP players receive spectator state Verification: JIP during turn 5 → spectator only, receives omniscient state.

6.2.6.15 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

Send full state via getStateForPlayer(userId) (role-aware)
If it was their turn and the WRITE/EDIT phase is still active, they can still submit
If their turn was auto-completed (timeout → “…” sentence), they cannot redo it
Editor receives keyword and edit history on reconnect Verification: Unit test: Editor disconnects and reconnects during WRITE phase → receives keyword, edit history, can still write. Writer reconnects → no keyword in state.

6.2.6.16 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

If disconnected player’s turn arrives during grace period:
- Wait UE_DISCONNECT_TURN_WAIT_SECONDS (15s, shorter than write timeout)
- If still disconnected, auto-complete turn with "..." sentence
- If they were the Editor, auto-skip edit phase
If the Editor fully disconnects (beyond grace period):
- Game continues — Editor won’t make more edits
- If keyword isn’t in story at end, Writers win by default
- Game is NOT terminated (Writers can still play out deduction)
If total active players drop below UE_MIN_PLAYERS (4), force-end the game Verification: Unit test: disconnected player’s turn → auto “…” after 15s. Editor disconnects fully → game continues, no more edits. Below min players → force end.

6.2.6.17 `computeResults()` and Awards¶

Compute final rankings by playerScores (descending)
Compute awards:
- Master of Disguise — Editor who wasn’t caught AND got the keyword in; icon: mask
- Eagle Eye — Writer who correctly voted for the Editor; icon: eye
- Shakespeare — Player who wrote the longest sentence (by word count); icon: quill
- Smooth Operator — Editor who made the most edits without getting caught; icon: wand-2
- Red Herring — Writer who received the most accusation votes (falsely accused); icon: fish
Return MinigameResults with rankings, awards, and gameSpecificData containing edits, votes, winner, keyword Verification: Unit test: construct scenarios for each award → all 5 awards assigned correctly.

6.2.6.18 `buildGameLog()`¶

Maintain an actionLog: GameLogAction[] array on the game instance
Build GameLog conforming to core.md §13.3, including gameSettings per §12A.11

initialState (from minigames-2.md §2.15):

interface UEInitialState {
  storyTitle: string;
  originalStory: string[];
  keyword: string;
  editorUserId: string;
  writerUserIds: string[];
  turnsPerRound: number;
  gameSettings: GameSettingValues;
}

Actions Logged:

Action Type	Payload	Recorded When
`turn_start`	`{ turnNumber: number; activeUserId: string; sentenceIndex: number }`	Writer/Editor turn begins
`word_added`	`{ userId: string; sentenceIndex: number; word: string }`	Writer adds a word
`editor_swap`	`{ sentenceIndex: number; originalWord: string; replacementWord: string; position: number }`	Editor makes a substitution
`editor_skip`	`{ sentenceIndex: number }`	Editor passes on editing
`story_snapshot`	`{ sentences: string[] }`	End of each turn cycle
`accusation_vote`	`{ voterId: string; suspectedUserId: string }`	Writer casts accusation vote
`vote_result`	`{ votes: Record<string, string[]>; editorCaught: boolean }`	Voting concludes (`votes` key = suspected userId, value = array of voter userIds)
`final_reveal`	`{ editorUserId: string; keyword: string; allSwaps: Array<{ sentenceIndex: number; originalWord: string; replacementWord: string }> }`	Post-game reveal

In computeResults(), build GameLog with initialState, full action log, and finalResults
Return GameLog from buildGameLog() Verification: Unit test: 6-player game, 12 turns, verify log contains all action types, initialState has keyword and editor identity, finalResults matches player rankings.

6.2.7 Register Game in Minigame Registry¶

Add entry to lib/rmhbox/minigame-registry.ts:

{
  id: "undercover-editor",
  displayName: "Undercover Editor",
  description: "Write a collaborative story — but one player is secretly editing words to insert a hidden keyword. Can you spot the Editor?",
  category: "social-deduction",
  icon: "pencil",
  minPlayers: 4,
  maxPlayers: 10,
  estimatedDurationSeconds: 300,
  supportsTeams: false,
  instructionDurationSeconds: 20,
  preloadAssets: { images: [], sounds: [], data: [], estimatedSizeBytes: 0 },
  joinInProgressPolicy: "spectate_only",
  tags: ["social-deduction", "writing", "creative", "deception"],
}

Verification: Registry lookup for "undercover-editor" returns correct metadata and handler instantiates.

Register server handler in MINIGAME_SERVER_REGISTRY (in server/rmhbox/game-coordinator.ts):
```
import { UndercoverEditorGame } from './minigames/undercover-editor';
MINIGAME_SERVER_REGISTRY.set('undercover-editor', UndercoverEditorGame);
```
Verification: MINIGAME_SERVER_REGISTRY.get('undercover-editor') returns the UndercoverEditorGame class. GameCoordinator can instantiate it with a valid MinigameContext.
Add lazy-load entry in components/rmhbox/MinigameRenderer.tsx:
```
'undercover-editor': lazy(() => import('./minigames/undercover-editor/UndercoverEditorGame')),
```
Verification: When lobby enters PLAYING with minigameId: 'undercover-editor', MinigameRenderer renders <UndercoverEditorGame /> inside <Suspense>. Verify code-splitting in network tab.

6.2.10 Game Settings Integration (§12A)¶

Integrate host-configurable settings using the §12A system.

Registry Entry¶

Export UNDERCOVER_EDITOR_SETTINGS: GameSettingsSchema in lib/rmhbox/minigame-registry.ts with 4 entries:
- rotations (integer, default 2, min 1, max 3, step 1)
- writeTimeout (integer, default 90, min 45, max 180, step 15)
- editTimeout (integer, default 60, min 30, max 120, step 10)
- accusationDuration (integer, default 45, min 20, max 90, step 5)
Attach settingsSchema: UNDERCOVER_EDITOR_SETTINGS to the undercover-editor MinigameDefinition. Verification: Registry lookup returns definition with settingsSchema containing 4 entries.

Handler `getSetting()` Integration¶

Replace hardcoded constants with this.getSetting() calls in the Undercover Editor handler:

Constant	Setting Key	Replacement
`UE_ROTATIONS`	`rotations`	`this.getSetting('rotations', UE_ROTATIONS)`
`UE_WRITE_TIMEOUT`	`writeTimeout`	`this.getSetting('writeTimeout', UE_WRITE_TIMEOUT)`
`UE_EDIT_TIMEOUT`	`editTimeout`	`this.getSetting('editTimeout', UE_EDIT_TIMEOUT)`
`UE_ACCUSATION_DURATION`	`accusationDuration`	`this.getSetting('accusationDuration', UE_ACCUSATION_DURATION)`

Verification: Each constant usage replaced. Handler respects custom settings passed via MinigameContext.gameSettings.

6.2.11 History Display Configuration¶

Implement the history display config for Undercover Editor as defined in minigames-2.md §2.16.

6.2.11.1 Create Detail Component¶

Create components/rmhbox/minigames/undercover-editor/UndercoverEditorHistoryDetail.tsx:

Render full story text with editor’s word swaps highlighted
Show sentence-by-sentence timeline (who wrote what)
Display editor reveal with vote breakdown
Show keyword reveal and whether it made it into the story

6.2.11.2 Register History Display¶

Add registration in lib/rmhbox/history-display-registrations.ts with:

Searchable fields: sentences (story sentences), keyword (secret keyword)
Filterable fields: role (editor/writer), editorCaught (boolean), keywordInStory (boolean)
Summary: Editor {caught/escaped} — Keyword: "{keyword}"

6.2.11.3 Tests¶

Verify getHistoryDisplay('undercover-editor') returns a valid config
Verify searchable fields extract sentences and keyword from a mock game log
Verify filterable fields include role (select), editorCaught (boolean), keywordInStory (boolean)
Verify getSummary() returns a meaningful string for a mock game log
Verify DetailComponent renders without errors when given a valid game log

6.3 Minimalist Masterpiece¶

Game ID: minimalist-masterpiece | Category: creative | Icon: brush Players: 3–12 | Duration: ~148s

6.3.1 Install NPM Packages¶

Install perfect-freehand (smooth stroke rendering, ~5KB gzipped, MIT license)
```
pnpm add perfect-freehand
```
Verification: Run pnpm ls perfect-freehand and confirm version is listed.
Verify TypeScript types work: create a scratch .ts file, import getStroke from perfect-freehand, confirm no type errors Verification: tsc --noEmit passes with the import.

6.3.3 Create Static Data Files¶

Create directory public/data/rmhbox/minimalist-masterpiece/ Verification: Directory exists on disk.
Create public/data/rmhbox/minimalist-masterpiece/prompts.json — curated drawing prompts
- Each entry follows:
```
{
  id: string;
  text: string;                   // e.g., "A house on a hill"
  category: string;               // e.g., "Landscape", "Animal", "Object"
  difficulty: "easy" | "medium" | "hard";
}
```
- Include at least 80 prompts
- At least 8 distinct categories
- Balanced difficulty: ≥25 easy, ≥30 medium, ≥20 hard
- Prompts should be drawable with only 5 strokes (simple concepts)
- No duplicate prompts Verification: Parse JSON; validate all entries; confirm ≥80 entries, ≥8 categories, balanced difficulty.

6.3.4 Define Zod Validation Schemas¶

Create lib/rmhbox/minimalist-masterpiece/schemas.ts

Define PointSchema:

const PointSchema = z.object({
  x: z.number().min(0).max(MM_CANVAS_SIZE),
  y: z.number().min(0).max(MM_CANVAS_SIZE),
  pressure: z.number().min(0).max(1),
});

Define StrokeSchema:

const StrokeSchema = z.object({
  id: z.string().min(1).max(36),
  points: z.array(PointSchema).min(MM_MIN_POINTS_PER_STROKE).max(MM_MAX_POINTS_PER_STROKE),
  color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
  width: z.number().positive(),
  timestamp: z.number(),
});

Define SubmitDrawingSchema:
```
const SubmitDrawingSchema = z.object({
  strokes: z.array(StrokeSchema).max(MM_MAX_STROKES),
});
```
Verification: Valid: 5 strokes with 10+ points each, valid hex colors. Invalid: 6 strokes (exceeds max), stroke with 3 points (below min), point x=500 (out of range), color “#gggggg” (invalid hex).

Define PlaceBidSchema:

const PlaceBidSchema = z.object({
  drawingId: z.string().min(1).max(36),
  amount: z.number().int().multipleOf(MM_BID_INCREMENT),
});

Verification: Valid: { drawingId: "abc", amount: 100 }. Invalid: { amount: 75 } (not multiple of 50), { amount: 0 }.

6.3.5 Create Data Loader¶

Create lib/rmhbox/minimalist-masterpiece/data-loader.ts
- Export loadPrompts(): DrawingPrompt[] — reads and parses prompts.json, caches as singleton
- Export selectPromptForGame(pool: DrawingPrompt[], usedIds: Set<string>): DrawingPrompt — selects a random prompt not in usedIds Verification: Unit test: loader caches. Selection excludes used IDs.

6.3.6 Implement Server Handler¶

Create server/rmhbox/minigames/minimalist-masterpiece.ts

6.3.6.1 Type Definitions¶

Define MMPhase type:

type MMPhase = 'PROMPT_REVEAL' | 'DRAWING' | 'GALLERY' | 'AUCTION' | 'RESULTS';

Verification: Type has exactly 5 values matching spec.

Define PlayerDrawing type:

type PlayerDrawing = {
  drawingId: string;
  strokes: Stroke[];
  submittedAt: number | null;
  strokeCount: number;
};

Define DrawingBids type:

type DrawingBids = {
  drawingId: string;
  totalValue: number;
  bidders: Map<string, number>;   // userId → amount bid
};

Define MMRanking type:

type MMRanking = {
  drawingId: string;
  artistUserId: string;
  artistUserName: string;
  marketValue: number;
  rank: number;
  points: number;
  strokes: Stroke[];
};

Define MinimalistMasterpieceState type:

type MinimalistMasterpieceState = {
  prompt: DrawingPrompt;
  phase: MMPhase;
  drawings: Map<string, PlayerDrawing>;
  drawingIdToUserId: Map<string, string>;
  userIdToDrawingId: Map<string, string>;
  playerCurrencies: Map<string, number>;
  bids: Map<string, DrawingBids>;
  marketValues: Map<string, number>;
  rankings: MMRanking[] | null;
  phaseStartedAt: number;
  phaseEndsAt: number;
};

Verification: All types compile without errors. Cross-reference against spec §3.4.

6.3.6.2 Class: `MinimalistMasterpieceGame extends BaseMinigame`¶

Constructor: call super(context); load prompts via data loader Verification: Instantiate class; confirm no errors.

6.3.6.3 State Initialization (`start()`)¶

Select prompt via selectPromptForGame()
Generate anonymous drawingId for each player (e.g., nanoid)
Build drawingIdToUserId and userIdToDrawingId maps (randomized assignment — NOT in player order)
Initialize empty drawings map with one PlayerDrawing per player (empty strokes)
Initialize playerCurrencies = MM_STARTING_CURRENCY for each player
Initialize empty bids map with one DrawingBids per drawing (totalValue=0, empty bidders)
Set phase = 'PROMPT_REVEAL'
Emit MM_PROMPT to all: { prompt, drawingDurationSeconds: MM_DRAWING_DURATION_SECONDS, maxStrokes: MM_MAX_STROKES, colorPalette: MM_COLOR_PALETTE }
Schedule startDrawingPhase() after MM_PROMPT_REVEAL_SECONDS Verification: Unit test with 4 players: 4 drawing IDs generated, maps correct, all currencies = 1000. Prompt event emitted.

6.3.6.4 Phase Management¶

startDrawingPhase():
- Set phase = 'DRAWING'
- Start TIMER_TICK interval (1s)
- Schedule endDrawingPhase() after MM_DRAWING_DURATION_SECONDS Verification: Phase transitions. Timer ticks emit.
endDrawingPhase():
- Stop timer
- For any player who hasn’t submitted, submit their current strokes as-is (even if 0 strokes)
- Call startGalleryPhase() Verification: Unsubmitted drawings finalized. Gallery starts.
startGalleryPhase():
- Set phase = 'GALLERY'
- Build gallery view: all drawings with anonymous labels (“Artist 1”, “Artist 2”, …) and stroke data
- Emit MM_GALLERY to all: { drawings: GalleryDrawing[], galleryDurationSeconds: MM_GALLERY_DURATION_SECONDS }
- Start TIMER_TICK interval
- Schedule startAuctionPhase() after MM_GALLERY_DURATION_SECONDS Verification: Gallery includes all drawings with anonymous labels. Labels are randomized (not correlated with player order).
startAuctionPhase():
- Set phase = 'AUCTION'
- Build auction drawing list per player (mark isMine based on userIdToDrawingId)
- Emit MM_AUCTION_START to each player individually:
```
{ drawings: AuctionDrawing[], startingCurrency: MM_STARTING_CURRENCY,
  bidIncrement: MM_BID_INCREMENT, auctionDurationSeconds: MM_AUCTION_DURATION_SECONDS }
```
  - Each player’s AuctionDrawing[] has isMine = true for their own drawing
- Start TIMER_TICK interval
- Schedule endAuctionPhase() after MM_AUCTION_DURATION_SECONDS Verification: Each player sees isMine on their own drawing. Currency starts at 1000.
endAuctionPhase():
- Stop timer
- Call computeResults() Verification: Results computed after auction ends.

6.3.6.6 Input Handling — `PLACE_BID`¶

Validate phase is 'AUCTION'; reject if not
Parse input through PlaceBidSchema; reject on validation failure
Validate drawingId exists in drawings map
Check player is NOT bidding on their own drawing (via drawingIdToUserId); reject if self-bid
Calculate effective amount:
- If amount > 0 (adding bid): verify player has sufficient currency (playerCurrencies[userId] >= amount); deduct from currency
- If amount < 0 (retracting bid): verify player has bid at least |amount| on this drawing; refund to currency
Update bids map: add/subtract from bidder’s amount for this drawing; recalculate totalValue

Emit MM_BID_UPDATE to the bidding player ONLY:

{ drawingId, totalValue, myBid: updatedBidAmount, myRemainingCurrency }

Emit MM_BID_BROADCAST to ALL: { drawingId, totalValue } (public total value only — NOT who bid) Verification: Unit test: bid 200 on drawing → currency = 800, totalValue increases. Retract 100 → currency = 900. Self-bid rejected. Insufficient currency rejected. Non-multiple-of-50 rejected.

6.3.6.7 Scoring Computation (`computeResults()`)¶

Calculate marketValues: for each drawing, sum all bids (already tracked in bids map)
Rank drawings by marketValue descending
Assign points:
- Rank 1: MM_RANK_1_POINTS (500)
- Rank 2: MM_RANK_2_POINTS (350)
- Rank 3: MM_RANK_3_POINTS (250)
- Rank 4+: MM_PARTICIPATION_POINTS (100)
Handle ties: tied drawings share the higher rank (both get the higher point value)
Compute investment bonuses:
- Find the drawing with the highest market value
- For each player who bid on it: bonusPoints = floor(MM_INVESTMENT_BONUS × (playerBid / totalBid))
- Add bonus points to those players’ scores
Build MMRanking[] array
De-anonymize: reveal artist identity (drawingId → userId mapping)
Emit MM_RESULTS to all:
```
{ rankings: MMRanking[], investmentBonuses: InvestmentBonus[] }
```
Verification: Unit test: 4 drawings with market values 500, 300, 300, 100 → ranks 1, 2, 2, 4. Tied drawings both get rank 2 points (350). Investment bonus: player bid 200 of 500 total on top drawing → bonus = floor(50 × 200/500) = 20.

6.3.6.8 `getStateForPlayer(userId)`¶

During PROMPT_REVEAL:

{ prompt, phase, maxStrokes, colorPalette, timeRemaining }

During DRAWING:

{ prompt, phase, myStrokes: Stroke[], myStrokeCount, hasSubmitted, timeRemaining,
  submittedPlayers: string[] }  // who has submitted (not their drawings)

Other players’ drawings are NOT included

During GALLERY:

{ prompt, phase, drawings: GalleryDrawing[], timeRemaining }

Anonymous labels only — no player identity mapping

During AUCTION:
```
{ prompt, phase, drawings: AuctionDrawing[], myCurrency, timeRemaining }
```
- isMine flag on own drawing; myBidAmount per drawing; public currentBidTotal
- Other players’ individual bids NOT visible (only totals)
During RESULTS:
```
{ prompt, phase, rankings: MMRanking[], investmentBonuses: InvestmentBonus[] }
```
- De-anonymized: artist names revealed Verification: Unit test: during DRAWING → no other drawings. During GALLERY → anonymous. During AUCTION → own drawing flagged, only totals visible. During RESULTS → fully de-anonymized.

6.3.6.9 `getStateForSpectator()`¶

During DRAWING: sees all players’ canvases live (all strokes as they’re drawn)
During GALLERY: same as player (anonymous)
During AUCTION: sees all individual bids (who bid what on which drawing), knows which drawing belongs to which player
During RESULTS: same as player Verification: Spectator sees all canvases during drawing and all individual bids during auction.

6.3.6.10 Join-in-Progress Handling¶

Policy: spectate_only
Players who join after DRAWING cannot draw; they spectate from GALLERY onward
They cannot bid during AUCTION (no currency allocation)
Send spectator state on join Verification: JIP during AUCTION → spectator only, no bidding capability.

6.3.6.11 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

During DRAWING: send current strokes (server has any saved strokes); player can continue drawing
During GALLERY/AUCTION: send gallery data and current bid state (their currency, their bids)
Stroke data is preserved server-side even if client disconnects mid-draw Verification: Reconnect during DRAWING → strokes restored. Reconnect during AUCTION → currency and bids restored.

6.3.6.12 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

Drawing phase: whatever strokes exist are preserved; at phase end, auto-submitted as-is
Auction phase: existing bids preserved; currency frozen (can’t bid while disconnected)
No special cleanup needed Verification: Disconnect during DRAWING → strokes auto-submitted at phase end. Bids preserved.

6.3.6.13 `computeResults()` and Awards¶

Compute final rankings by market value (descending)
Compute awards:
- Minimalist Master — highest market value (winner); icon: crown
- Patron of the Arts — player who spent the most total coins across all drawings; icon: banknote
- One Stroke Wonder — drawing with highest market value that used ≤ 3 strokes; icon: star
- Undervalued Gem — drawing that received bids from the most different players; icon: gem
- Shrewd Investor — player who earned the highest investment bonus; icon: trending-up
Return MinigameResults with rankings, awards, and gameSpecificData containing drawings + bids Verification: Unit test: scenarios triggering each award → all 5 awards assigned correctly.

6.3.6.14 `buildGameLog()`¶

Maintain an actionLog: GameLogAction[] array on the game instance
Build GameLog conforming to core.md §13.3, including gameSettings per §12A.11

initialState (from minigames-2.md §3.14):

interface MMInitialState {
  prompt: string;
  maxStrokes: number;
  canvasSize: { width: number; height: number };
  playerIds: string[];
  startingCurrency: number;
  auctionTimeLimitMs: number;
  gameSettings: GameSettingValues;
}

Actions Logged:

Action Type	Payload	Recorded When
`drawing_stroke`	`{ userId: string; strokeIndex: number; points: Array<{ x: number; y: number }>; color: string; width: number }`	Player completes a stroke
`drawing_undo`	`{ userId: string; strokeIndex: number }`	Player undoes a stroke
`drawing_submit`	`{ userId: string; totalStrokes: number }`	Player submits final drawing
`gallery_view`	`{ drawingOrder: string[] }`	Gallery walk begins
`auction_bid`	`{ bidderId: string; drawingOwnerId: string; amount: number; previousBid: number }`	Player places a bid
`auction_close`	`{ drawingOwnerId: string; winnerId: string; finalPrice: number }`	Bidding closes on a piece
`market_values`	`{ rankings: Array<{ userId: string; marketValue: number; rank: number }> }`	Final valuations computed

Include all drawing stroke data in game log for gallery replay
In computeResults(), build GameLog with initialState, full action log, and finalResults
Return GameLog from buildGameLog() Verification: Unit test: 5-player game, verify all 5 drawings captured in log with stroke data, bids recorded, auction results present, initialState has prompt and canvas config.

6.3.7 Register Game in Minigame Registry¶

Add entry to lib/rmhbox/minigame-registry.ts:

{
  id: "minimalist-masterpiece",
  displayName: "Minimalist Masterpiece",
  description: "Draw with only 5 strokes, then bid on the art you think is best! The highest market value wins.",
  category: "creative",
  icon: "brush",
  minPlayers: 3,
  maxPlayers: 12,
  estimatedDurationSeconds: 148,
  supportsTeams: false,
  instructionDurationSeconds: 15,
  preloadAssets: { images: [], sounds: [], data: [], estimatedSizeBytes: 0 },
  joinInProgressPolicy: "spectate_only",
  tags: ["creative", "drawing", "auction", "competitive"],
}

Verification: Registry lookup for "minimalist-masterpiece" returns correct metadata.

Register server handler in MINIGAME_SERVER_REGISTRY (in server/rmhbox/game-coordinator.ts):
```
import { MinimalistMasterpieceGame } from './minigames/minimalist-masterpiece';
MINIGAME_SERVER_REGISTRY.set('minimalist-masterpiece', MinimalistMasterpieceGame);
```
Verification: MINIGAME_SERVER_REGISTRY.get('minimalist-masterpiece') returns the MinimalistMasterpieceGame class. GameCoordinator can instantiate it with a valid MinigameContext.
Add lazy-load entry in components/rmhbox/MinigameRenderer.tsx:
```
'minimalist-masterpiece': lazy(() => import('./minigames/minimalist-masterpiece/MinimalistMasterpieceGame')),
```
Verification: When lobby enters PLAYING with minigameId: 'minimalist-masterpiece', MinigameRenderer renders <MinimalistMasterpieceGame /> inside <Suspense>. Verify code-splitting in network tab.

6.3.10 Game Settings Integration (§12A)¶

Integrate host-configurable settings using the §12A system.

Registry Entry¶

Export MINIMALIST_MASTERPIECE_SETTINGS: GameSettingsSchema in lib/rmhbox/minigame-registry.ts with 5 entries:
- drawingDuration (integer, default 45, min 20, max 90, step 5)
- maxStrokes (integer, default 15, min 5, max 30, step 5)
- auctionDuration (integer, default 30, min 15, max 60, step 5)
- startingCurrency (integer, default 500, min 200, max 1000, step 50)
- bidIncrement (integer, default 25, min 10, max 100, step 5)
Attach settingsSchema: MINIMALIST_MASTERPIECE_SETTINGS to the minimalist-masterpiece MinigameDefinition. Verification: Registry lookup returns definition with settingsSchema containing 5 entries.

Handler `getSetting()` Integration¶

Replace hardcoded constants with this.getSetting() calls in the Minimalist Masterpiece handler:

Constant	Setting Key	Replacement
`MM_DRAWING_DURATION`	`drawingDuration`	`this.getSetting('drawingDuration', MM_DRAWING_DURATION)`
`MM_MAX_STROKES`	`maxStrokes`	`this.getSetting('maxStrokes', MM_MAX_STROKES)`
`MM_AUCTION_DURATION`	`auctionDuration`	`this.getSetting('auctionDuration', MM_AUCTION_DURATION)`
`MM_STARTING_CURRENCY`	`startingCurrency`	`this.getSetting('startingCurrency', MM_STARTING_CURRENCY)`
`MM_BID_INCREMENT`	`bidIncrement`	`this.getSetting('bidIncrement', MM_BID_INCREMENT)`

Verification: Each constant usage replaced. Handler respects custom settings passed via MinigameContext.gameSettings.

6.3.11 History Display Configuration¶

Implement the history display config for Minimalist Masterpiece as defined in minigames-2.md §3.15.

6.3.11.1 Create Detail Component¶

Create components/rmhbox/minigames/minimalist-masterpiece/MinimalistMasterpieceHistoryDetail.tsx:

Render gallery grid with drawing thumbnails (from stroke data)
Show prompt text alongside each drawing
Display gallery vote results and auction results with final bids

6.3.11.2 Register History Display¶

Add registration in lib/rmhbox/history-display-registrations.ts with:

Searchable fields: prompts (drawing prompts)
Filterable fields: auctionWin (boolean), galleryVotes (range)
Summary: Prompt: "{prompt}"

6.3.11.3 Tests¶

Verify getHistoryDisplay('minimalist-masterpiece') returns a valid config
Verify searchable fields extract prompts from a mock game log
Verify filterable fields include auctionWin (boolean) and galleryVotes (range)
Verify getSummary() returns a meaningful string for a mock game log
Verify DetailComponent renders without errors when given a valid game log

6.4 Emoji Cinema¶

Game ID: emoji-cinema | Category: word | Icon: clapperboard Players: 3–12 | Duration: ~180s (up to 6 rounds)

6.4.1 Install NPM Packages¶

Evaluate emoji picker approach — decide between emoji-mart and a custom curated subset:
- Option A: emoji-mart (~30KB gzipped) — full-featured emoji picker with search, categories, skin tones
- Option B: Custom curated 200-emoji JSON — minimal bundle, tailored palette excluding letter/flag emojis
- Recommended: Option B for tighter control over allowed emojis and smaller bundle

If Option A chosen: install emoji-mart

pnpm add emoji-mart @emoji-mart/data @emoji-mart/react

If Option B chosen: no NPM package needed; create static emoji palette JSON Verification: Chosen approach works: emoji picker renders, search/filter functional.

6.4.4 Define Zod Validation Schemas¶

Create lib/rmhbox/emoji-cinema/schemas.ts

Define AddEmojiSchema:

const AddEmojiSchema = z.object({
  emoji: z.string().min(1).max(10),
  position: z.number().int().min(0).max(EC_MAX_EMOJIS - 1),
});

Define RemoveEmojiSchema:

const RemoveEmojiSchema = z.object({
  position: z.number().int().min(0).max(EC_MAX_EMOJIS - 1),
});

Define ReorderEmojiSchema:

const ReorderEmojiSchema = z.object({
  fromIndex: z.number().int().min(0).max(EC_MAX_EMOJIS - 1),
  toIndex: z.number().int().min(0).max(EC_MAX_EMOJIS - 1),
});

Define SubmitGuessSchema:
```
const SubmitGuessSchema = z.object({
  guess: z.string().min(1).max(EC_MAX_GUESS_LENGTH).transform(s => s.trim()),
});
```
Verification: Valid: { emoji: "🦁", position: 0 }, { guess: "The Lion King" }. Invalid: { position: 12 } (out of range), { guess: "" } (empty).

6.4.5 Create Data Loader¶

Create lib/rmhbox/emoji-cinema/data-loader.ts
- Export loadMovies(): MovieEntry[] — reads and parses movies.json, caches as singleton
- Export loadEmojiPalette(): EmojiPalette — reads and parses emoji-palette.json, caches as singleton
- Export selectMoviesForGame(pool: MovieEntry[], playerCount: number, usedIds: Set<string>): ECRoundData[]
  - Select min(playerCount, EC_MAX_ROUNDS) movies
  - Mix of difficulties
  - Exclude movies with IDs in usedIds
  - Return array of ECRoundData with movie and assigned Producer per round
- Export validateEmoji(emoji: string, palette: EmojiPalette): boolean — checks emoji is in the curated palette Verification: Unit test: loader caches. Selection respects player count cap and exclusions. Emoji validation rejects non-palette emojis.

6.4.6 Implement Server Handler¶

Create server/rmhbox/minigames/emoji-cinema.ts

6.4.6.1 Type Definitions¶

Define ECPhase type:

type ECPhase = 'PRODUCER_ASSIGNMENT' | 'EMOJI_CONSTRUCTION' | 'ROUND_RESULTS' | 'TRANSITION';

Verification: Type has exactly 4 values matching spec.

Define ECRoundData type:

type ECRoundData = {
  movie: MovieEntry;
  producerUserId: string;
};

Define ECPlayerGuesses type:

type ECPlayerGuesses = {
  userId: string;
  guesses: Array<{
    text: string;
    result: 'correct' | 'close' | 'wrong';
    timestamp: number;
  }>;
};

Define CorrectGuesser type:

type CorrectGuesser = {
  userId: string;
  userName: string;
  guessText: string;
  timestamp: number;
  rank: number;
};

Define EmojiCinemaState type:

type EmojiCinemaState = {
  rounds: ECRoundData[];
  currentRound: number;
  totalRounds: number;
  producerOrder: string[];
  phase: ECPhase;
  currentProducerUserId: string;
  currentMovie: MovieEntry;
  emojiSequence: string[];
  guesses: Map<string, ECPlayerGuesses>;
  correctGuessers: CorrectGuesser[];
  closeGuessCount: number;
  playerScores: Map<string, number>;
  phaseStartedAt: number;
  phaseEndsAt: number;
};

Verification: All types compile. Cross-reference against spec §4.4.

6.4.6.2 Class: `EmojiCinemaGame extends BaseMinigame`¶

Constructor: call super(context); load movies and emoji palette via data loader Verification: Instantiate class; confirm no errors.

6.4.6.3 State Initialization (`start()`)¶

Compute producerOrder: shuffle player list
Compute totalRounds = Math.min(context.players.length, EC_MAX_ROUNDS)
Select movies via selectMoviesForGame() — one per round, assigned to the Producer in rotation
Initialize playerScores with 0 for all players
Set currentRound = -1
Call startNextRound() Verification: Unit test with 4 players: 4 rounds. With 8 players: 6 rounds (capped). Movies selected, Producer rotation set.

6.4.6.4 Round Lifecycle¶

startNextRound():
- Increment currentRound
- If currentRound >= totalRounds, call endGame(); return
- Set phase = 'PRODUCER_ASSIGNMENT'
- Get currentProducerUserId from producerOrder[currentRound]
- Get currentMovie from rounds[currentRound].movie
- Reset emojiSequence = [], guesses = new Map(), correctGuessers = [], closeGuessCount = 0
- Emit EC_PRODUCER_ASSIGNED to all: { round: currentRound + 1, producerUserId, producerName }
- Emit EC_MOVIE_ASSIGNED to Producer ONLY: { movie: currentMovie } — includes title, year
- Schedule startEmojiConstruction() after EC_PRODUCER_ASSIGNMENT_SECONDS Verification: Unit test: round starts. Producer gets movie; others do NOT. Phase is PRODUCER_ASSIGNMENT.
startEmojiConstruction():
- Set phase = 'EMOJI_CONSTRUCTION'
- Start TIMER_TICK interval (1s)
- Schedule endRound() after EC_ROUND_DURATION_SECONDS Verification: Phase transitions. Timer runs.
endRound(reason: 'timeout' | 'guessed'):
- Stop timer
- Compute round scores:
  - If at least one correct guess:
    - Producer: EC_PRODUCER_BASE_POINTS + EC_PRODUCER_SPEED_BONUS × secondsRemaining
    - 1st correct guesser: EC_FIRST_GUESS_POINTS (300)
    - 2nd correct guesser: EC_SECOND_GUESS_POINTS (150)
    - 3rd+ correct guessers: EC_OTHER_GUESS_POINTS (75)
  - If no correct guesses (timeout): Producer gets 0
- Update cumulative playerScores
- Set phase = 'ROUND_RESULTS'
- Emit EC_ROUND_OVER to all:
```
{ movieTitle: currentMovie.title, emojiSequence, correctGuessers,
  producerScore, roundScores: Array<{ userId, userName, score }> }
```
- Schedule startTransition() after EC_ROUND_RESULTS_SECONDS Verification: Scores computed correctly. Movie title revealed to all. Rankings by guess timestamp.
startTransition():
- Set phase = 'TRANSITION'
- Check for pending JIP players; add them to audience pool
- Schedule startNextRound() after EC_TRANSITION_SECONDS Verification: JIP handled. Next round starts.

6.4.6.5 Input Handling — `ADD_EMOJI`¶

Validate phase is 'EMOJI_CONSTRUCTION'; reject if not
Validate sender is the current Producer; reject if not
Parse through AddEmojiSchema; reject on validation failure
Validate emoji is in the curated palette via validateEmoji(); reject if not
Validate emojiSequence.length < EC_MAX_EMOJIS; reject if at capacity
Insert emoji at specified position (splice into array)
Emit EC_EMOJI_UPDATED to ALL: { emojiSequence } — live broadcast Verification: Unit test: Producer adds emoji → broadcast to all. 13th emoji rejected. Non-palette emoji rejected. Non-Producer rejected.

6.4.6.6 Input Handling — `REMOVE_EMOJI`¶

Validate phase is 'EMOJI_CONSTRUCTION' and sender is Producer
Parse through RemoveEmojiSchema
Validate position is within current sequence bounds
Remove emoji at position (splice from array)
Emit EC_EMOJI_UPDATED to ALL: { emojiSequence } Verification: Unit test: remove valid position → sequence shrinks. Out-of-bounds position rejected.

6.4.6.7 Input Handling — `REORDER_EMOJI`¶

Validate phase is 'EMOJI_CONSTRUCTION' and sender is Producer
Parse through ReorderEmojiSchema
Validate both indices are within sequence bounds
Perform array reorder (remove from fromIndex, insert at toIndex)
Emit EC_EMOJI_UPDATED to ALL: { emojiSequence } Verification: Reorder works correctly. Out-of-bounds indices rejected.

6.4.6.9 `getStateForPlayer(userId)`¶

If Producer:

{
  phase, currentRound, totalRounds,
  movieTitle: currentMovie.title,
  movieYear: currentMovie.year,
  emojiSequence,
  timeRemaining,
  correctGuessers,
  closeGuessCount,
  guessCountsPerPlayer: Array<{ userId, userName, count }>,
  scores: Array<{ userId, userName, totalScore }>,
}

Movie title IS visible to Producer

If Audience:

{
  phase, currentRound, totalRounds,
  producerUserId, producerName,
  emojiSequence,
  timeRemaining,
  myGuesses: Array<{ text, result }>,
  correctGuessers,
  closeGuessCount,
  guessCountsPerPlayer: Array<{ userId, userName, count }>,
  scores: Array<{ userId, userName, totalScore }>,
}

Movie title is NOT visible
Other players’ guess text NOT visible (only counts)

During ROUND_RESULTS: movie title revealed to all Verification: Producer gets movie title. Audience does not (until ROUND_RESULTS). Other players’ guess text never visible.

6.4.6.10 `getStateForSpectator()`¶

Omniscient view: movie title visible, all guess text from all players visible, emoji sequence visible
Full experience: spectators see the movie title and watch guesses roll in — “omniscient director” experience Verification: Spectator state includes movie title and all guesses.

6.4.6.11 Join-in-Progress Handling¶

Policy: join_next_subround
JIP players join as audience at the start of the next round (during TRANSITION)
They do NOT get a Producer turn unless the rotation hasn’t passed them yet
If all original players have been Producer, JIP players are audience-only for remaining rounds
Send full state on join Verification: JIP during round 3 → joins audience at round 4. Does not become Producer.

6.4.6.12 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

Producer: receives movie title, current emoji sequence, guess status
Audience: receives emoji sequence, own guesses, timer
All state preserved server-side Verification: Producer reconnects → movie title and emoji sequence restored. Audience reconnects → guesses restored.

6.4.6.13 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

If Producer disconnects:
- Wait EC_PRODUCER_DISCONNECT_WAIT_SECONDS (10s)
- If not reconnected, skip the round (no points awarded to anyone for this round)
- Move to next round
If audience member disconnects:
- No impact on round; they miss guessing opportunity Verification: Producer disconnect → round skipped after 10s. Audience disconnect → no effect.

6.4.6.14 `computeResults()` and Awards¶

Compute final rankings by cumulative playerScores (descending)
Compute awards:
- Movie Buff — most correct guesses across all rounds; icon: film
- Emoji Picasso — Producer whose round was guessed the fastest (best emoji description); icon: palette
- Stumper — Producer whose movie was never guessed (timeout); icon: lock
- Speed Guesser — fastest correct guess (earliest timestamp across all rounds); icon: zap
- Close but No Cigar — player with the most “close” guesses that never converted to correct in the same round; icon: cigarette
Return MinigameResults with rankings, awards, and gameSpecificData containing rounds summary Verification: Unit test: scenarios triggering each award → all 5 awards assigned correctly.

6.4.6.15 `buildGameLog()`¶

Maintain an actionLog: GameLogAction[] array on the game instance
Build GameLog conforming to core.md §13.3, including gameSettings per §12A.11

initialState (from minigames-2.md §4.16):

interface ECInitialState {
  totalRounds: number;
  maxEmojis: number;
  maxGuessesPerPlayer: number;
  playerIds: string[];
  moviePool: string[];
  gameSettings: GameSettingValues;
}

Actions Logged:

Action Type	Payload	Recorded When
`round_start`	`{ roundNumber: number; producerUserId: string; movieTitle: string }`	Round begins (title logged server-side)
`emoji_placed`	`{ producerUserId: string; emoji: string; position: number; currentSequence: string[] }`	Producer places an emoji
`close_guess`	`{ guesserId: string; guessText: string; similarity: number }`	A guess is flagged as close
`correct_guess`	`{ guesserId: string; guessText: string; elapsedMs: number }`	Someone guesses correctly
`round_timeout`	`{ finalSequence: string[]; totalGuesses: number }`	Round ends with no correct guess
`round_result`	`{ movieTitle: string; emojiSequence: string[]; correctGuesserId: string \| null; producerScore: number; guesserScores: Record<string, number> }`	Round scoring summary

In computeResults(), build GameLog with initialState, full action log, and finalResults
Return GameLog from buildGameLog() Verification: Unit test: 4-round game, verify log contains round_start/round_result per round with movie titles and emoji sequences, initialState has movie pool and round config.

6.4.7 Register Game in Minigame Registry¶

Add entry to lib/rmhbox/minigame-registry.ts:

{
  id: "emoji-cinema",
  displayName: "Emoji Cinema",
  description: "Describe movies using only emojis! Race to guess what film the Producer is depicting.",
  category: "word",
  icon: "clapperboard",
  minPlayers: 3,
  maxPlayers: 12,
  estimatedDurationSeconds: 180,
  supportsTeams: false,
  instructionDurationSeconds: 15,
  preloadAssets: { images: [], sounds: [], data: [], estimatedSizeBytes: 0 },
  joinInProgressPolicy: "join_next_subround",
  tags: ["word", "creative", "speed", "movies", "guessing"],
}

Verification: Registry lookup for "emoji-cinema" returns correct metadata.

Register server handler in MINIGAME_SERVER_REGISTRY (in server/rmhbox/game-coordinator.ts):
```
import { EmojiCinemaGame } from './minigames/emoji-cinema';
MINIGAME_SERVER_REGISTRY.set('emoji-cinema', EmojiCinemaGame);
```
Verification: MINIGAME_SERVER_REGISTRY.get('emoji-cinema') returns the EmojiCinemaGame class. GameCoordinator can instantiate it with a valid MinigameContext.
Add lazy-load entry in components/rmhbox/MinigameRenderer.tsx:
```
'emoji-cinema': lazy(() => import('./minigames/emoji-cinema/EmojiCinemaGame')),
```
Verification: When lobby enters PLAYING with minigameId: 'emoji-cinema', MinigameRenderer renders <EmojiCinemaGame /> inside <Suspense>. Verify code-splitting in network tab.

6.4.10 Game Settings Integration (§12A)¶

Integrate host-configurable settings using the §12A system.

Registry Entry¶

Export EMOJI_CINEMA_SETTINGS: GameSettingsSchema in lib/rmhbox/minigame-registry.ts with 4 entries:
- maxRounds (integer, default 4, min 2, max 6, step 1)
- roundDuration (integer, default 45, min 20, max 90, step 5)
- maxEmojis (integer, default 5, min 3, max 8, step 1)
- maxGuessesPerPlayer (integer, default 3, min 1, max 5, step 1)
Attach settingsSchema: EMOJI_CINEMA_SETTINGS to the emoji-cinema MinigameDefinition. Verification: Registry lookup returns definition with settingsSchema containing 4 entries.

Handler `getSetting()` Integration¶

Replace hardcoded constants with this.getSetting() calls in the Emoji Cinema handler:

Constant	Setting Key	Replacement
`EC_MAX_ROUNDS`	`maxRounds`	`this.getSetting('maxRounds', EC_MAX_ROUNDS)`
`EC_ROUND_DURATION`	`roundDuration`	`this.getSetting('roundDuration', EC_ROUND_DURATION)`
`EC_MAX_EMOJIS`	`maxEmojis`	`this.getSetting('maxEmojis', EC_MAX_EMOJIS)`
`EC_MAX_GUESSES_PER_PLAYER`	`maxGuessesPerPlayer`	`this.getSetting('maxGuessesPerPlayer', EC_MAX_GUESSES_PER_PLAYER)`

Verification: Each constant usage replaced. Handler respects custom settings passed via MinigameContext.gameSettings.

6.4.11 History Display Configuration¶

Implement the history display config for Emoji Cinema as defined in minigames-2.md §4.17.

6.4.11.1 Create Detail Component¶

Create components/rmhbox/minigames/emoji-cinema/EmojiCinemaHistoryDetail.tsx:

Render round-by-round review with emoji sequences and target movie titles
Show guessing timeline with each player’s guesses and correctness
Display difficulty rating and creator identity per round

6.4.11.2 Register History Display¶

Add registration in lib/rmhbox/history-display-registrations.ts with:

Searchable fields: movieTitles, guesses, emojiSequences
Filterable fields: wasCreator (boolean), guessedCorrectly (boolean), difficulty (select)
Summary: {rounds} rounds — Movie emoji challenge

6.4.11.3 Tests¶

Verify getHistoryDisplay('emoji-cinema') returns a valid config
Verify searchable fields extract movie titles, guesses, and emoji sequences from a mock game log
Verify filterable fields include wasCreator (boolean), guessedCorrectly (boolean), difficulty (select)
Verify getSummary() returns a meaningful string for a mock game log
Verify DetailComponent renders without errors when given a valid game log

6.6 Game Settings Test Plan (§12A)¶

All tests go in testing/rmhbox/phase-6/game-settings.test.ts (or integrated into the phase-6 test suite). Follow the Phase 5 test patterns in testing/rmhbox/phase-5/6-game-settings.test.ts.

6.6.1 Schema Completeness Tests¶

Each of the 4 exported settings arrays has the expected number of entries (FF: 5, UE: 4, MM: 5, EC: 4).
Every setting has key, type, label, default defined.
Integer/float settings have min, max, step defined.
Select settings have a non-empty options array.
Default values fall within declared constraints.

6.6.2 Fact or Friction Settings Tests¶

Test Case	Description
`default totalQuestions`	With no custom settings, handler uses `FF_TOTAL_QUESTIONS` (8)
`custom totalQuestions = 12`	Handler plays 12 question rounds
`custom answerDuration = 30`	Timer broadcasts use 30s instead of default 20s
`custom potStartValue = 150`	Starting pot is 150 per question
`enableScoreFloor = false`	Player score can go below 0
`enableScoreFloor = true (default)`	Player score floors at 0
`difficulty = 'hard'`	Only hard-tagged questions are selected
`difficulty = 'mixed' (default)`	Mixed difficulty pool

6.6.3 Undercover Editor Settings Tests¶

Test Case	Description
`default rotations`	With no custom settings, handler uses `UE_ROTATIONS` (2)
`custom rotations = 3`	Handler runs 3 write-edit cycles
`custom writeTimeout = 120`	Write phase timer is 120s
`custom editTimeout = 90`	Edit phase timer is 90s
`custom accusationDuration = 60`	Accusation timer is 60s

6.6.4 Minimalist Masterpiece Settings Tests¶

Test Case	Description
`default maxStrokes`	Uses `MM_MAX_STROKES` (15)
`custom maxStrokes = 5`	Only 5 strokes allowed; extras rejected
`custom drawingDuration = 60`	Drawing timer is 60s
`custom auctionDuration = 45`	Auction timer is 45s
`custom startingCurrency = 800`	Players start with 800 currency
`custom bidIncrement = 50`	Minimum bid step is 50

6.6.5 Emoji Cinema Settings Tests¶

Test Case	Description
`default maxRounds`	Uses `EC_MAX_ROUNDS` (4)
`custom maxRounds = 6`	Handler plays 6 rounds
`custom roundDuration = 60`	Encoding timer is 60s
`custom maxEmojis = 3`	Only 3 emojis allowed; extras rejected
`custom maxGuessesPerPlayer = 1`	Each player gets only 1 guess per round

6.6.6 getSetting() Fallback Tests¶

Calling getSetting('totalQuestions', FF_TOTAL_QUESTIONS) with empty gameSettings returns the fallback.
Calling getSetting('totalQuestions', FF_TOTAL_QUESTIONS) with gameSettings: { totalQuestions: 10 } returns 10.
Calling getSetting('unknownKey', 42) returns 42.

Phase 6: Minigames Set 2 — Fact or Friction, Undercover Editor, Minimalist Masterpiece, Emoji Cinema¶

Table of Contents¶

6.1 Fact or Friction¶

6.1.1 Install NPM Packages¶

6.1.2 Add Constants to lib/rmhbox/constants.ts¶

6.1.3 Create Static Data Files¶

6.1.4 Define Zod Validation Schemas¶

6.1.5 Create Data Loader¶

6.1.6 Implement Server Handler¶

6.1.6.1 Type Definitions¶

6.1.6.2 Class: FactOrFrictionGame extends BaseMinigame¶

6.1.6.3 State Initialization (start())¶

6.1.6.4 Question Lifecycle¶

6.1.6.5 Input Handling — SUBMIT_ANSWER¶

6.1.6.6 Input Handling — PASS_QUESTION¶

6.1.6.7 Scoring Computation (computeQuestionResult())¶

6.1.6.8 getStateForPlayer(userId)¶

6.1.6.9 getStateForSpectator()¶

6.1.6.10 Join-in-Progress Handling¶

6.1.6.11 Reconnection Handling (handlePlayerReconnect(userId))¶

6.1.6.12 Disconnect Handling (handlePlayerDisconnect(userId))¶

6.1.6.13 computeResults() and Awards¶

6.1.6.14 buildGameLog()¶

6.1.7 Register Game in Minigame Registry¶

6.1.8 Build Client Components¶

6.1.8.1 components/rmhbox/minigames/fact-or-friction/FactOrFrictionGame.tsx¶

6.1.8.2 components/rmhbox/minigames/fact-or-friction/PointPotDisplay.tsx¶

6.1.8.3 components/rmhbox/minigames/fact-or-friction/QuestionCard.tsx¶

6.1.8.4 components/rmhbox/minigames/fact-or-friction/OptionButton.tsx¶

6.1.8.5 components/rmhbox/minigames/fact-or-friction/AnswerReveal.tsx¶

6.1.8.6 components/rmhbox/minigames/fact-or-friction/ScoreRibbon.tsx¶

6.1.8.7 Sound Effect Integration¶

6.1.8.8 Zustand Store Integration¶

6.1.9 Integration Testing¶

6.1.10 Game Settings Integration (§12A)¶

Registry Entry¶

Handler getSetting() Integration¶

6.1.11 History Display Configuration¶

6.1.11.1 Create Detail Component¶

6.1.11.2 Register History Display¶

6.1.11.3 Tests¶

6.2 Undercover Editor¶

6.2.1 Install NPM Packages¶

6.2.2 Add Constants to lib/rmhbox/constants.ts¶

6.2.3 Create Static Data Files¶

6.2.4 Define Zod Validation Schemas¶

6.2.5 Create Data Loader¶

6.2.6 Implement Server Handler¶

6.2.6.1 Type Definitions¶

6.2.6.2 Class: UndercoverEditorGame extends BaseMinigame¶

6.2.6.3 State Initialization (start())¶

6.2.6.4 Turn Lifecycle¶

6.2.6.5 Input Handling — WRITE_SENTENCE¶

6.2.6.6 Input Handling — EDIT_WORD¶

6.2.6.7 Input Handling — SKIP_EDIT¶

6.2.6.8 Review Phase¶

6.2.6.9 Accusation Phase¶

6.2.6.10 Input Handling — CAST_ACCUSATION¶

6.2.6.11 Reveal Phase¶

6.2.6.12 getStateForPlayer(userId)¶

6.2.6.13 getStateForSpectator()¶

6.2.6.14 Join-in-Progress Handling¶

6.2.6.15 Reconnection Handling (handlePlayerReconnect(userId))¶

6.2.6.16 Disconnect Handling (handlePlayerDisconnect(userId))¶

6.2.6.17 computeResults() and Awards¶

6.2.6.18 buildGameLog()¶

6.2.7 Register Game in Minigame Registry¶

6.2.8 Build Client Components¶

6.2.8.1 components/rmhbox/minigames/undercover-editor/UndercoverEditorGame.tsx¶

6.2.8.2 components/rmhbox/minigames/undercover-editor/StoryDisplay.tsx¶

6.2.8.3 components/rmhbox/minigames/undercover-editor/WriteInput.tsx¶

6.2.8.4 components/rmhbox/minigames/undercover-editor/StoryEditor.tsx¶

6.2.8.5 components/rmhbox/minigames/undercover-editor/AccusationPanel.tsx¶

6.2.8.6 components/rmhbox/minigames/undercover-editor/RevealScreen.tsx¶

6.2.8.7 components/rmhbox/minigames/undercover-editor/RoleBadge.tsx¶

6.2.8.8 components/rmhbox/minigames/undercover-editor/TurnIndicator.tsx¶

6.2.8.9 Sound Effect Integration¶

6.2.8.10 Zustand Store Integration¶

6.2.9 Integration Testing¶

6.2.10 Game Settings Integration (§12A)¶

6.1.2 Add Constants to `lib/rmhbox/constants.ts`¶

6.1.6.2 Class: `FactOrFrictionGame extends BaseMinigame`¶

6.1.6.3 State Initialization (`start()`)¶

6.1.6.5 Input Handling — `SUBMIT_ANSWER`¶

6.1.6.6 Input Handling — `PASS_QUESTION`¶

6.1.6.7 Scoring Computation (`computeQuestionResult()`)¶

6.1.6.8 `getStateForPlayer(userId)`¶

6.1.6.9 `getStateForSpectator()`¶

6.1.6.11 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

6.1.6.12 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

6.1.6.13 `computeResults()` and Awards¶

6.1.6.14 `buildGameLog()`¶

6.1.8.1 `components/rmhbox/minigames/fact-or-friction/FactOrFrictionGame.tsx`¶

6.1.8.2 `components/rmhbox/minigames/fact-or-friction/PointPotDisplay.tsx`¶

6.1.8.3 `components/rmhbox/minigames/fact-or-friction/QuestionCard.tsx`¶

6.1.8.4 `components/rmhbox/minigames/fact-or-friction/OptionButton.tsx`¶

6.1.8.5 `components/rmhbox/minigames/fact-or-friction/AnswerReveal.tsx`¶

6.1.8.6 `components/rmhbox/minigames/fact-or-friction/ScoreRibbon.tsx`¶

Handler `getSetting()` Integration¶

6.2.2 Add Constants to `lib/rmhbox/constants.ts`¶

6.2.6.2 Class: `UndercoverEditorGame extends BaseMinigame`¶

6.2.6.3 State Initialization (`start()`)¶

6.2.6.5 Input Handling — `WRITE_SENTENCE`¶

6.2.6.6 Input Handling — `EDIT_WORD`¶

6.2.6.7 Input Handling — `SKIP_EDIT`¶

6.2.6.10 Input Handling — `CAST_ACCUSATION`¶

6.2.6.12 `getStateForPlayer(userId)`¶

6.2.6.13 `getStateForSpectator()`¶

6.2.6.15 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

6.2.6.16 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

6.2.6.17 `computeResults()` and Awards¶

6.2.6.18 `buildGameLog()`¶

6.2.8.1 `components/rmhbox/minigames/undercover-editor/UndercoverEditorGame.tsx`¶

6.2.8.2 `components/rmhbox/minigames/undercover-editor/StoryDisplay.tsx`¶

6.2.8.3 `components/rmhbox/minigames/undercover-editor/WriteInput.tsx`¶

6.2.8.4 `components/rmhbox/minigames/undercover-editor/StoryEditor.tsx`¶

6.2.8.5 `components/rmhbox/minigames/undercover-editor/AccusationPanel.tsx`¶

6.2.8.6 `components/rmhbox/minigames/undercover-editor/RevealScreen.tsx`¶

6.2.8.7 `components/rmhbox/minigames/undercover-editor/RoleBadge.tsx`¶

6.2.8.8 `components/rmhbox/minigames/undercover-editor/TurnIndicator.tsx`¶

Handler `getSetting()` Integration¶

6.3.2 Add Constants to `lib/rmhbox/constants.ts`¶

6.3.6.2 Class: `MinimalistMasterpieceGame extends BaseMinigame`¶

6.3.6.3 State Initialization (`start()`)¶

6.3.6.5 Input Handling — `SUBMIT_DRAWING`¶

6.3.6.6 Input Handling — `PLACE_BID`¶

6.3.6.7 Scoring Computation (`computeResults()`)¶

6.3.6.8 `getStateForPlayer(userId)`¶

6.3.6.9 `getStateForSpectator()`¶

6.3.6.11 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

6.3.6.12 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

6.3.6.13 `computeResults()` and Awards¶

6.3.6.14 `buildGameLog()`¶

6.3.8.1 `components/rmhbox/minigames/minimalist-masterpiece/MinimalistMasterpieceGame.tsx`¶

6.3.8.2 `components/rmhbox/minigames/minimalist-masterpiece/DrawingCanvas.tsx`¶

6.3.8.3 `components/rmhbox/minigames/minimalist-masterpiece/ColorPalette.tsx`¶

6.3.8.4 `components/rmhbox/minigames/minimalist-masterpiece/StrokeCounter.tsx`¶

6.3.8.5 `components/rmhbox/minigames/minimalist-masterpiece/GalleryCarousel.tsx`¶

6.3.8.6 `components/rmhbox/minigames/minimalist-masterpiece/DrawingCard.tsx`¶

6.3.8.7 `components/rmhbox/minigames/minimalist-masterpiece/AuctionPanel.tsx`¶

6.3.8.8 `components/rmhbox/minigames/minimalist-masterpiece/BidControls.tsx`¶

6.3.8.9 `components/rmhbox/minigames/minimalist-masterpiece/MarketResultsScreen.tsx`¶

Handler `getSetting()` Integration¶

6.4.2 Add Constants to `lib/rmhbox/constants.ts`¶

6.4.6.2 Class: `EmojiCinemaGame extends BaseMinigame`¶

6.4.6.3 State Initialization (`start()`)¶

6.4.6.5 Input Handling — `ADD_EMOJI`¶

6.4.6.6 Input Handling — `REMOVE_EMOJI`¶

6.4.6.7 Input Handling — `REORDER_EMOJI`¶

6.4.6.8 Input Handling — `SUBMIT_GUESS`¶

6.4.6.9 `getStateForPlayer(userId)`¶

6.4.6.10 `getStateForSpectator()`¶

6.4.6.12 Reconnection Handling (`handlePlayerReconnect(userId)`)¶

6.4.6.13 Disconnect Handling (`handlePlayerDisconnect(userId)`)¶

6.4.6.14 `computeResults()` and Awards¶

6.4.6.15 `buildGameLog()`¶