Refine party, timer, and Extension mechanics

Twungeon_MVP_Technical_Specification.md

@@ -246,6 +246,8 @@ interface PlayerState {
   followerVerified: boolean
   characterCreated: boolean
   extensionBound: boolean
+  partySlot: 1 | 2 | 3 | 4
+  color: 'blue' | 'green' | 'red' | 'yellow'
   connectionState: 'connected' | 'disconnected'
   position: TilePosition
   hp: 0 | 1 | 2 | 3
@@ -274,6 +276,7 @@ type PhaseState =
       startedAt: number
       deadlineAt: number
       initialEligiblePlayerIds: string[]
+      timerResetPlayerIds: string[]
     }
   | { kind: 'enemy'; phaseId: string }
   | { kind: 'transition'; reason: 'floor-advance' | 'admin-reset' }
@@ -352,6 +355,12 @@ New characters spawn on the first spawn tile chosen by deterministic ordering.
 Players may share that tile. A late join never changes the current phase timer
 or the set of players required to finish the phase.
 
+The authoritative player record is also the current-floor party roster. At
+most four records may exist. Spawn assigns the lowest open slot and its fixed
+color: Slot 1 Blue, Slot 2 Green, Slot 3 Red, and Slot 4 Yellow. Dead records
+remain in the roster and occupy their slots. A fifth spawn is rejected as
+`PARTY_FULL` without creating a character.
+
 ### 7.3 Attack range and targeting
 
 - Player and Goblin attacks target an orthogonally adjacent tile.
@@ -451,14 +460,12 @@ For every living participant present when the phase starts:
 3. set `eligibleThisPhase` to true; and
 4. include the player in `initialEligiblePlayerIds`.
 
-The duration is:
-
-```text
-min(living-player-count * 25 seconds, 120 seconds)
-```
-
-The count includes disconnected living characters, matching the PRD's AFK
-AutoGuard behavior.
+The initial deadline is five seconds after phase start. The phase begins with
+an empty `timerResetPlayerIds` list. After each player's first accepted command,
+the backend adds that Twitch user ID and moves `deadlineAt` to five seconds
+after the gateway arrival time. Later commands from that player do not move the
+deadline. Rejected, duplicate, disconnected, and AutoGuard events do not reset
+the timer.
 
 Players who spawn or resurrect after the phase starts receive 0 AP, are not
 added to the phase completion set, and may act beginning with the next Player
@@ -506,7 +513,8 @@ An accepted spawn requires:
 - a stable Twitch chat user ID;
 - verified follower status;
 - no existing character for that ID; and
-- no death marker for that ID on the current floor.
+- no death marker for that ID on the current floor; and
+- one of four party slots to be open.
 
 The backend creates one character at full HP with heal available. If the game is
 already active, the player has 0 AP until the next Player Phase.
@@ -514,6 +522,9 @@ already active, the player has 0 AP until the next Player Phase.
 Repeated `!spawn` attempts for an existing character return an informative chat
 response or log result and never create another character.
 
+The roster is first come, first served for one floor. Twitch identity sessions
+remain outside the domain roster so clearing a party does not log viewers out.
+
 ### 10.2 Heal
 
 A valid self-heal:
@@ -624,14 +635,15 @@ When a living player enters the exit:
 1. enter transition state and reject remaining old-floor commands;
 2. increment the floor counter;
 3. generate and validate a new floor and Goblin;
-4. place every participating player on the new spawn tile;
-5. restore every player to 3 HP and alive;
-6. clear death markers, AP, and Guard;
-7. refresh every self-heal;
-8. log the new floor; and
-9. begin a fresh Player Phase.
+4. clear every current party record and release all four slots;
+5. discard all previous character HP, AP, Guard, heal, death, position, slot,
+   and color state;
+6. log the new floor; and
+7. enter Dormant state for a new first-come, first-served party.
 
-The previous Goblin and map are discarded.
+The previous Goblin and map are discarded. Existing authenticated Twitch
+sessions and sockets remain valid, but previous players have no slot
+reservation or priority.
 
 ### 12.3 Total-party defeat
 
@@ -645,9 +657,10 @@ alive, the backend immediately:
 5. logs the party defeat.
 
 A valid Channel Points resurrection revives its owner and starts a fresh Player
-Phase from dormancy. A newly eligible viewer may also spawn into the current
-floor and resume play. Initial dormancy has no participants, while defeated-party
-dormancy retains dead participant records.
+Phase from dormancy. If the defeated party claimed fewer than four slots, a
+newly eligible viewer may claim an open slot and resume play. A defeated full
+party requires resurrection. Initial dormancy has no participants, while
+defeated-party dormancy retains dead participant records.
 
 ## 13. Randomness
 
@@ -747,14 +760,22 @@ The default wide layout reserves:
 - the largest upper-right area for the map; and
 - a full-width bottom area for the action log.
 
-Temporary shapes, colors, labels, and sprites are acceptable. Every required
-entity, wall, traversable path, and exit must remain distinguishable.
+Temporary shapes, labels, and sprites are acceptable. Every required entity,
+wall, traversable path, and exit must remain distinguishable. Player markers,
+visible name labels, personalized status, and adapter render data use the
+current party-slot color consistently.
 
 ### 15.2 Player status
 
 The personalized Extension status includes at least identity/binding status,
-HP, AP, Guard, heal availability, alive/dead status, current phase, and a clear
-disabled reason when controls are unavailable.
+party slot/color, HP, AP, Guard, heal availability, alive/dead status, current
+phase, and a clear disabled reason when controls are unavailable.
+
+Desktop preserves the compact information-rich overlay. Twitch context
+platform data adds an `extension-mobile` presentation flag when available, and
+a narrow-viewport media query provides the fallback. Mobile keeps identity and
+color, HP, AP, and heal availability visible, reflows the controller instead of
+scaling the desktop layout, and uses touch targets of at least 44 pixels.
 
 ### 15.3 Action log
 
@@ -872,7 +893,7 @@ Deterministic tests must cover:
 
 - all accepted and rejected command conditions;
 - AP spending and early phase completion;
-- timer duration and 120-second cap;
+- rolling five-second deadline and one reset per living player;
 - deadline boundary behavior;
 - AutoGuard conversion, hit blocking, misses, and reset;
 - player and Goblin hit probabilities through injected rolls;
@@ -910,7 +931,7 @@ At minimum, the live test plan must demonstrate:
 6. movement, two attacks, heal, pass, timer expiry, and AutoGuard;
 7. Goblin aggro, pursuit, attack, target death, and return;
 8. Channel Points resurrection of the correct dead viewer;
-9. floor escape with the Goblin alive and dead-player revival;
+9. floor escape with the Goblin alive, party clearing, and next-floor reparty;
 10. total-party defeat, dormant transition, and resurrection recovery;
 11. refresh and temporary disconnect recovery; and
 12. repetition across multiple generated floors.