anear-js-api 1.2.3 → 1.3.1

package/lib/state_machines/AnearEventMachine.js

@@ -167,7 +167,8 @@ const AnearEventMachineContext = (
   eachParticipantCancelActionType: null,  // ACTION type that triggers cancellation for eachParticipant timeouts
   pendingCancelConfirmations: null,  // Set of participantIds waiting for TIMER_CANCELED confirmation
   pendingCancelAction: null,  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
-  consecutiveTimeoutCounts: {}  // { participantId: count } tracking consecutive timeouts per participant for dead-man switch
+  consecutiveTimeoutCount: 0,  // Global counter tracking consecutive timeouts across all participants for dead-man switch
+  consecutiveAllParticipantsTimeoutCount: 0  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
 })
 
 const ActiveEventGlobalEvents = {
@@ -657,7 +658,8 @@ const ActiveEventStatesConfig = {
           states: {
             idle: {},
             waitingForCancelConfirmations: {
-              entry: ['sendCancelTimeoutToAllAPMs', 'setupPendingCancelConfirmations'],
+              // Note: Setup actions are called in the transitions that lead here, not in entry
+              // This allows different setup for declarative cancel (TRIGGER_CANCEL_SEQUENCE) vs manual cancel (CANCEL_ALL_PARTICIPANT_TIMEOUTS)
               on: {
                 TIMER_CANCELED: {
                   actions: ['removeFromPendingCancelConfirmations']
@@ -676,21 +678,26 @@ const ActiveEventStatesConfig = {
               },
               always: {
                 guard: 'allCancelConfirmationsReceived',
-                actions: ['forwardPendingCancelAction', 'clearCancelState'],
+                actions: ['forwardPendingCancelActionIfExists', 'clearCancelState'],
                 target: '#waitingForActions.idle'
               }
             }
           },
           on: {
             ACTION: {
-              actions: ['processParticipantAction']
+              actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
             },
             // Forward per-participant timeouts (from APM) to the AppM
             PARTICIPANT_TIMEOUT: {
               actions: ['trackParticipantTimeout', 'processParticipantTimeout'],
               // v5 note: internal transitions are the default (v4 had `internal: true`)
             },
+            CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+              actions: ['setupPendingCancelConfirmationsForManualCancel', 'sendCancelTimeoutToAllAPMs'],
+              target: '.waitingForCancelConfirmations'
+            },
             TRIGGER_CANCEL_SEQUENCE: {
+              actions: ['sendCancelTimeoutToAllAPMs', 'setupPendingCancelConfirmations'],
               target: '.waitingForCancelConfirmations'
             },
             TIMER_CANCELED: {
@@ -741,7 +748,7 @@ const ActiveEventStatesConfig = {
           always: {
             guard: 'allParticipantsResponded',
             target: 'waitingForActions',
-            actions: ['clearParticipantsTimeout']
+            actions: ['sendActionsCompleteToAppM', 'clearParticipantsTimeout']
           },
           after: {
             participantsActionTimeout: {
@@ -1748,6 +1755,19 @@ const AnearEventMachineFunctions = ({
         suppressParticipantTimeouts: true  // Drop PARTICIPANT_TIMEOUT events
       }
     }),
+    setupPendingCancelConfirmationsForManualCancel: assign(({ context }) => {
+      // Get all active participants (for manual cancelAllParticipantTimeouts call)
+      const activeParticipantIds = getActiveParticipantIds(context)
+      const pendingConfirmations = new Set(activeParticipantIds)
+
+      logger.info(`[AEM] Starting manual cancellation sequence (cancelAllParticipantTimeouts). Waiting for ${pendingConfirmations.size} APM confirmations: ${[...pendingConfirmations].join(', ')}`)
+
+      return {
+        pendingCancelConfirmations: pendingConfirmations,
+        pendingCancelAction: null, // No ACTION to forward for manual cancel
+        suppressParticipantTimeouts: true  // Drop PARTICIPANT_TIMEOUT events
+      }
+    }),
     removeFromPendingCancelConfirmations: assign(({ context, event }) => {
       const participantId = event.participantId || event.data?.id
       if (!context.pendingCancelConfirmations || !participantId) return {}
@@ -1839,14 +1859,17 @@ const AnearEventMachineFunctions = ({
     },
     resetParticipantTimeoutCount: assign(({ context, event }) => {
       const participantId = event.data.participantId
-      // Reset consecutive timeout count when participant sends an action
-      if (context.consecutiveTimeoutCounts[participantId]) {
-        logger.debug(`[AEM] Resetting timeout count for participant ${participantId} (action received)`)
-        const newCounts = { ...context.consecutiveTimeoutCounts }
-        delete newCounts[participantId]
-        return { consecutiveTimeoutCounts: newCounts }
+      // Reset global consecutive timeout counts when ANY participant sends an action
+      const updates = {}
+      if (context.consecutiveTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting global timeout count from ${context.consecutiveTimeoutCount} to 0 (action received from ${participantId})`)
+        updates.consecutiveTimeoutCount = 0
       }
-      return {}
+      if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (action received from ${participantId})`)
+        updates.consecutiveAllParticipantsTimeoutCount = 0
+      }
+      return updates
     }),
     processParticipantAction: ({ context, event, self }) => {
       // event.data.participantId,
@@ -1935,16 +1958,13 @@ const AnearEventMachineFunctions = ({
     }),
     trackParticipantTimeout: assign(({ context, event }) => {
       const participantId = event.participantId
-      const currentCount = context.consecutiveTimeoutCounts[participantId] || 0
+      const currentCount = context.consecutiveTimeoutCount || 0
       const newCount = currentCount + 1
 
-      logger.debug(`[AEM] Participant ${participantId} timeout count: ${currentCount} -> ${newCount}`)
+      logger.debug(`[AEM] Global timeout count (any participant): ${currentCount} -> ${newCount} (timeout from ${participantId})`)
 
       return {
-        consecutiveTimeoutCounts: {
-          ...context.consecutiveTimeoutCounts,
-          [participantId]: newCount
-        }
+        consecutiveTimeoutCount: newCount
       }
     }),
     processParticipantTimeout: ({ context, event, self }) => {
@@ -1957,12 +1977,13 @@ const AnearEventMachineFunctions = ({
       }
 
       const participantId = event.participantId
-      const timeoutCount = context.consecutiveTimeoutCounts[participantId] || 0
+      const timeoutCount = context.consecutiveTimeoutCount || 0
       const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
 
-      // Check dead-man switch: if participant has exceeded consecutive timeout threshold, cancel event
+      // Check dead-man switch: if global consecutive timeout threshold reached, cancel event
+      // This detects when the game is "dead" (no actions happening) across all participants
       if (timeoutCount >= maxConsecutiveTimeouts) {
-        logger.warn(`[AEM] Dead-man switch triggered: Participant ${participantId} has ${timeoutCount} consecutive timeouts (threshold: ${maxConsecutiveTimeouts}). Auto-canceling event.`)
+        logger.warn(`[AEM] Dead-man switch triggered: ${timeoutCount} consecutive timeouts across all participants (threshold: ${maxConsecutiveTimeouts}). Auto-canceling event.`)
         self.send({ type: 'CANCEL' })
         return
       }
@@ -2044,30 +2065,70 @@ const AnearEventMachineFunctions = ({
         }
       };
     }),
-    sendActionsTimeoutToAppM: ({ context, self }) => {
+    sendActionsCompleteToAppM: assign(({ context }) => {
+      // When all participants respond, the final ACTION already has finalAction: true
+      // No need to send a separate ACTIONS_COMPLETE event - the finalAction flag handles it
+      // Reset allParticipants timeout counter when all participants respond
+      if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (all participants responded)`)
+        return { consecutiveAllParticipantsTimeoutCount: 0 }
+      }
+      return {}
+    }),
+    sendActionsTimeoutToAppM: assign(({ context, self }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
       const allActiveParticipantIds = getActiveParticipantIds(context)
 
       logger.info(`[AEM] allParticipants timeout expired after ${msecs}ms. Non-responders: ${nonResponderIds.join(', ')}`)
 
-      // Dead-man switch: if all participants timed out, auto-cancel the event
-      if (nonResponders.size === allActiveParticipantIds.length && allActiveParticipantIds.length > 0) {
-        logger.warn(`[AEM] Dead-man switch triggered: All ${allActiveParticipantIds.length} participants timed out in allParticipants timeout. Auto-canceling event.`)
-        self.send({ type: 'CANCEL' })
-        return
+      // Track consecutive allParticipants timeouts where ALL participants timed out
+      const allTimedOut = nonResponders.size === allActiveParticipantIds.length && allActiveParticipantIds.length > 0
+      const updates = {}
+
+      if (allTimedOut) {
+        const currentCount = context.consecutiveAllParticipantsTimeoutCount || 0
+        const newCount = currentCount + 1
+        logger.debug(`[AEM] All participants timed out in allParticipants timeout. Count: ${currentCount} -> ${newCount}`)
+        updates.consecutiveAllParticipantsTimeoutCount = newCount
+
+        // Dead-man switch: if 4 consecutive allParticipants timeouts where all timed out, cancel event
+        const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
+        if (newCount >= maxConsecutiveTimeouts) {
+          logger.warn(`[AEM] Dead-man switch triggered: ${maxConsecutiveTimeouts} consecutive allParticipants timeouts where all participants timed out. Auto-canceling event.`)
+          self.send({ type: 'CANCEL' })
+          return updates
+        }
+      } else {
+        // Not all timed out - reset the counter
+        if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+          logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (not all participants timed out)`)
+          updates.consecutiveAllParticipantsTimeoutCount = 0
+        }
       }
 
       if (context.appEventMachine) {
+        // Send ACTIONS_TIMEOUT when timeout expires
+        logger.info(`[AEM] Sending ACTIONS_TIMEOUT (timeout expired)`)
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds })
       }
-    },
+
+      return updates
+    }),
     sendActionsTimeoutToAppMCanceled: ({ context }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
       logger.info(`[AEM] allParticipants timeout cancelled after ${msecs}ms. Non-responders at cancellation: ${nonResponderIds.join(', ')}`)
 
       if (context.appEventMachine) {
+        // Send ACTIONS_TIMEOUT when timeout is canceled (backward compatibility)
+        context.appEventMachine.send({
+          type: 'ACTIONS_TIMEOUT',
+          timeout: msecs,
+          nonResponderIds,
+          canceled: true
+        })
+        // Keep ACTIONS_TIMEOUT for backward compatibility (deprecated)
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds, canceled: true })
       }
     },
@@ -2100,9 +2161,6 @@ const AnearEventMachineFunctions = ({
 
       logger.debug(`[AEM] cleaning up exiting participant ${participantId}`)
 
-      // Clean up timeout counts for exiting participant
-      const { [participantId]: removedTimeoutCount, ...remainingTimeoutCounts } = context.consecutiveTimeoutCounts
-
       if (participant) {
         const isOpenHouse = context.anearEvent.openHouse || false
 
@@ -2125,8 +2183,7 @@ const AnearEventMachineFunctions = ({
               ...context.participants,
               [participantId]: updatedParticipant
             },
-            participantMachines: remainingMachines,
-            consecutiveTimeoutCounts: remainingTimeoutCounts
+            participantMachines: remainingMachines
           }
         } else {
           // For non-open-house events: remove both participant and machine (existing behavior)
@@ -2142,14 +2199,11 @@ const AnearEventMachineFunctions = ({
 
           return {
             participants: remainingParticipants,
-            participantMachines: remainingMachines,
-            consecutiveTimeoutCounts: remainingTimeoutCounts
+            participantMachines: remainingMachines
           }
         }
       } else {
-        return {
-          consecutiveTimeoutCounts: remainingTimeoutCounts
-        }
+        return {}
       }
     }),
     notifyCoreServiceMachineExit: ({ context }) => {

package/lib/utils/AppMachineTransition.js

@@ -102,6 +102,14 @@ const AppMachineTransition = (anearEvent) => {
         let timeoutFn
         let displayEvent
 
+        // Extract cancel from meta level (for function-based eachParticipant or top-level cancel)
+        // Supports both "cancel" (developer-friendly) and "cancelActionType" (internal)
+        if (meta.cancel && !cancelActionType) {
+          cancelActionType = meta.cancel
+        } else if (meta.cancelActionType && !cancelActionType) {
+          cancelActionType = meta.cancelActionType
+        }
+
         // Validate that participants: and participant: are not both defined
         if (meta.allParticipants && meta.eachParticipant) {
           logger.error(`[AppMachineTransition] Invalid meta configuration: both 'allParticipants' and 'eachParticipant' are defined. Only one can be used per state.`)

package/lib/utils/DisplayEventProcessor.js

@@ -365,9 +365,20 @@ class DisplayEventProcessor {
     if (timeoutFn) {
       // For participant displays, any non-null / positive timeout value should
       // start a real per-participant timer on that participant's APM.
-      const msecs = timeoutFn(appCtx, participantStruct)
-      if (typeof msecs === 'number' && msecs > 0) {
-        timeout = msecs
+      if (!participantStruct) {
+        logger.warn(`[DisplayEventProcessor] Participant struct not found for ${participantId}, skipping timeout calculation`)
+      } else {
+        try {
+          const msecs = timeoutFn(appCtx, participantStruct)
+          if (typeof msecs === 'number' && msecs > 0) {
+            timeout = msecs
+          } else {
+            // Log when timeout function returns null/undefined to help diagnose issues
+            logger.debug(`[DisplayEventProcessor] Timeout function returned ${msecs === null ? 'null' : msecs === undefined ? 'undefined' : `non-numeric value: ${msecs}`} for ${participantId}`)
+          }
+        } catch (error) {
+          logger.warn(`[DisplayEventProcessor] Error calculating timeout for ${participantId}: ${error.message}`)
+        }
       }
     }
     const privateRenderContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {