anear-js-api 1.2.1 → 1.2.3

package/lib/api/ApiService.js

@@ -101,7 +101,7 @@ class ApiService {
   }
 
   prepareGetRequest(resource, params={}) {
-    const urlString = this.idParamUrlString(resource, params) 
+    const urlString = this.idParamUrlString(resource, params)
     return new fetch.Request(
       urlString, {
         method: 'GET',

package/lib/models/AnearEvent.js

@@ -97,6 +97,14 @@ class AnearEvent extends JsonApiResource {
     this.send({ type: "BOOT_PARTICIPANT", data: { participantId, reason } })
   }
 
+  cancelAllParticipantTimeouts() {
+    // Cancel all active participant-level timeouts. This sends CANCEL_TIMEOUT
+    // to all APMs, which will benignly clear any active timeout timers.
+    // Useful for scenarios where a game event (e.g., LIAR call) should immediately
+    // cancel all individual participant timeouts.
+    this.send({ type: "CANCEL_ALL_PARTICIPANT_TIMEOUTS" })
+  }
+
   render(viewPath, displayType, appContext, event, timeout = null, props = {}) {
     // Explicit render method for guaranteed rendering control
     // This complements the meta: {} approach for when you need explicit control

package/lib/state_machines/AnearEventMachine.js

@@ -162,7 +162,12 @@ const AnearEventMachineContext = (
   spectatorsDisplayChannel: null,    // display all spectators
   participants: {},
   participantMachines: {},
-  participantsActionTimeout: null
+  participantsActionTimeout: null,
+  suppressParticipantTimeouts: false,  // Flag to suppress PARTICIPANT_TIMEOUT events (cleared when new timers are set up via render)
+  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
 })
 
 const ActiveEventGlobalEvents = {
@@ -274,7 +279,7 @@ const ActiveEventStatesConfig = {
       ],
       on: {
         ACTION: {
-          actions: ['processParticipantAction']
+          actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
         },
         RENDER_DISPLAY: {
           target: '#createdRendering'
@@ -378,6 +383,7 @@ const ActiveEventStatesConfig = {
             input: ({ context, event }) => ({ context, event }),
             onDone: {
               target: 'notifyingPausedRenderComplete',
+              actions: ['clearParticipantTimeoutSuppression']
               // v5 note: internal transitions are the default (v4 had `internal: true`)
             },
             onError: {
@@ -416,6 +422,7 @@ const ActiveEventStatesConfig = {
             input: ({ context, event }) => ({ context, event }),
             onDone: {
               target: 'notifyingRenderComplete',
+              actions: ['clearParticipantTimeoutSuppression']
               // v5 note: internal transitions are the default (v4 had `internal: true`)
             },
             onError: {
@@ -441,7 +448,7 @@ const ActiveEventStatesConfig = {
       initial: 'transitioning',
       on: {
         ACTION: {
-          actions: ['processParticipantAction']
+          actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
         },
         RENDER_DISPLAY: {
           target: '#announceRendering'
@@ -484,6 +491,9 @@ const ActiveEventStatesConfig = {
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipantMachine'
         },
+        CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+          actions: 'cancelAllParticipantTimeouts'
+        },
         SPECTATOR_ENTER: {
           actions: 'sendSpectatorEnterToAppEventMachine'
         }
@@ -527,6 +537,7 @@ const ActiveEventStatesConfig = {
             input: ({ context, event }) => ({ context, event }),
             onDone: {
               target: 'notifyingRenderComplete',
+              actions: ['clearParticipantTimeoutSuppression']
               // v5 note: internal transitions are the default (v4 had `internal: true`)
             },
             onError: {
@@ -616,6 +627,14 @@ const ActiveEventStatesConfig = {
         },
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipantMachine'
+        },
+        CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+          actions: 'cancelAllParticipantTimeouts'
+        },
+        // Handle PARTICIPANT_TIMEOUT even when in liveRendering state
+        // (events bubble up from child states, so we need to handle them here)
+        PARTICIPANT_TIMEOUT: {
+          actions: ['trackParticipantTimeout', 'processParticipantTimeout']
         }
       },
       states: {
@@ -634,14 +653,49 @@ const ActiveEventStatesConfig = {
         waitingForActions: {
           id: 'waitingForActions',
           entry: () => logger.debug('[AEM] live state...waiting for actions'),
+          initial: 'idle',
+          states: {
+            idle: {},
+            waitingForCancelConfirmations: {
+              entry: ['sendCancelTimeoutToAllAPMs', 'setupPendingCancelConfirmations'],
+              on: {
+                TIMER_CANCELED: {
+                  actions: ['removeFromPendingCancelConfirmations']
+                },
+                PARTICIPANT_EXIT: {
+                  actions: ['removeFromPendingCancelConfirmations']
+                },
+                // Drop only ACTION and PARTICIPANT_TIMEOUT events during cancellation wait
+                // All other events (presence events, etc.) will bubble up to parent handlers
+                ACTION: {
+                  actions: ['dropEventDuringCancellation']
+                },
+                PARTICIPANT_TIMEOUT: {
+                  actions: ['dropEventDuringCancellation']
+                }
+              },
+              always: {
+                guard: 'allCancelConfirmationsReceived',
+                actions: ['forwardPendingCancelAction', 'clearCancelState'],
+                target: '#waitingForActions.idle'
+              }
+            }
+          },
           on: {
             ACTION: {
               actions: ['processParticipantAction']
             },
             // Forward per-participant timeouts (from APM) to the AppM
             PARTICIPANT_TIMEOUT: {
-              actions: ['processParticipantTimeout'],
+              actions: ['trackParticipantTimeout', 'processParticipantTimeout'],
               // v5 note: internal transitions are the default (v4 had `internal: true`)
+            },
+            TRIGGER_CANCEL_SEQUENCE: {
+              target: '.waitingForCancelConfirmations'
+            },
+            TIMER_CANCELED: {
+              // Ignore if not in cancellation state (defensive)
+              actions: []
             }
           }
         },
@@ -654,10 +708,11 @@ const ActiveEventStatesConfig = {
               {
                 guard: 'isParticipantsTimeoutActive',
                 target: 'notifyingRenderCompleteWithTimeout',
-                actions: 'setupParticipantsTimeout'
+                actions: ['setupParticipantsTimeout', 'setupCancelActionType', 'clearParticipantTimeoutSuppression']
               },
               {
                 target: 'notifyingRenderComplete',
+                actions: ['setupCancelActionType', 'clearParticipantTimeoutSuppression']
                 // v5 note: internal transitions are the default (v4 had `internal: true`)
               }
             ],
@@ -693,13 +748,70 @@ const ActiveEventStatesConfig = {
               target: 'handleParticipantsTimeout'
             }
           },
+          initial: 'waiting',
+          states: {
+            waiting: {
+              // The actual waiting state. Timer continues running when we transition to .rendering.
+            },
+            rendering: {
+              invoke: {
+                src: 'renderDisplay',
+                input: ({ context, event }) => ({ context, event }),
+                onDone: [
+                  {
+                    guard: 'isParticipantsTimeoutActive',
+                    target: 'notifyingRenderComplete',
+                    actions: ['setupCancelActionType', 'clearParticipantTimeoutSuppression']
+                    // Note: We do NOT call setupParticipantsTimeout here because we're already in waitAllParticipantsResponse
+                    // and the timer is still running from the parent state (preserved by nested state pattern).
+                  },
+                  {
+                    target: '#waitingForActions',
+                    actions: ['setupCancelActionType', 'clearParticipantTimeoutSuppression', 'notifyAppMachineRendered']
+                  }
+                ],
+                onError: {
+                  target: '#activeEvent.failure'
+                }
+              }
+            },
+            notifyingRenderComplete: {
+              after: {
+                timeoutRendered: {
+                  // Target sibling state (stays within parent, timer continues)
+                  target: 'waiting',
+                  actions: ['notifyAppMachineRendered']
+                }
+              }
+            }
+          },
           on: {
-            ACTION: {
-              actions: ['processAndForwardAction', 'processParticipantResponse'],
-              // v5 note: internal transitions are the default (v4 had `internal: true`)
+            ACTION: [
+              {
+                // Check if this is a cancel ACTION for allParticipants timeout
+                guard: ({ context, event }) => {
+                  const { cancelActionType } = context.participantsActionTimeout || {}
+                  if (!cancelActionType) return false
+                  const eventMessagePayload = JSON.parse(event.data.payload)
+                  const [appEventName] = Object.entries(eventMessagePayload)[0]
+                  return cancelActionType === appEventName
+                },
+                actions: ['storeCancelActionForAllParticipants'],
+                target: 'handleParticipantsTimeoutCanceled'
+              },
+              {
+                actions: ['resetParticipantTimeoutCount', 'processAndForwardAction', 'processParticipantResponse'],
+                // v5 note: internal transitions are the default (v4 had `internal: true`)
+              }
+            ],
+            CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+              actions: ['cancelAllParticipantTimeouts'],
+              target: 'handleParticipantsTimeoutCanceled'
             },
             RENDER_DISPLAY: {
-              target: '#liveRendering'
+              // Re-render without exiting waitAllParticipantsResponse.
+              // This preserves the parent's after: timer because we stay within the parent state.
+              target: '.rendering'
             },
             PARTICIPANT_LEAVE: [
               {
@@ -720,6 +832,10 @@ const ActiveEventStatesConfig = {
           entry: ['sendActionsTimeoutToAppM', 'clearParticipantsTimeout'],
           always: 'waitingForActions'
         },
+        handleParticipantsTimeoutCanceled: {
+          entry: ['sendActionsTimeoutToAppMCanceled', 'clearParticipantsTimeout', 'forwardPendingCancelActionIfExists'],
+          always: 'waitingForActions'
+        },
         participantEntering: {
           // a PARTICIPANT_ENTER received from a new user JOIN click. Unless already exists,
           // create an AnearParticipantMachine instance.
@@ -1591,6 +1707,114 @@ const AnearEventMachineFunctions = ({
     sendParticipantExitEvents: ({ context }) => {
       Object.values(context.participantMachines).forEach(pm => pm.send({ type: 'PARTICIPANT_EXIT' }))
     },
+    cancelAllParticipantTimeouts: assign(({ context }) => {
+      // Send CANCEL_TIMEOUT to all participant machines to cancel any active
+      // participant-level timeouts. This is useful when a game event (e.g., LIAR call)
+      // should immediately cancel all individual participant timeouts.
+      // APMs that are not in waitParticipantResponse state will benignly ignore this event.
+      logger.info(`[AEM] Cancelling all participant timeouts (manual) for ${Object.keys(context.participantMachines).length} participants`)
+      Object.values(context.participantMachines).forEach(pm => pm.send({ type: 'CANCEL_TIMEOUT' }))
+
+      // Note: If we're in waitAllParticipantsResponse state, the nested state's handler
+      // will also handle this event and cancel the allParticipants timeout.
+
+      // Set suppression flag to ignore stale PARTICIPANT_TIMEOUT events from cancelled timers.
+      // This flag will be cleared when new timers are set up (via render completion).
+      return {
+        suppressParticipantTimeouts: true
+      }
+    }),
+    sendCancelTimeoutToAllAPMs: ({ context }) => {
+      const participantCount = Object.keys(context.participantMachines).length
+      logger.info(`[AEM] Sending CANCEL_TIMEOUT to all ${participantCount} APMs for declarative cancel ACTION`)
+      Object.values(context.participantMachines).forEach(pm => {
+        pm.send({ type: 'CANCEL_TIMEOUT' })
+      })
+    },
+    setupPendingCancelConfirmations: assign(({ context, event }) => {
+      // Get all active participants with timers (participants in waitParticipantResponse state)
+      const activeParticipantIds = getActiveParticipantIds(context)
+      const pendingConfirmations = new Set(activeParticipantIds)
+
+      logger.info(`[AEM] Starting cancellation sequence for ACTION ${event.data.appEventName}. Waiting for ${pendingConfirmations.size} APM confirmations: ${[...pendingConfirmations].join(', ')}`)
+
+      return {
+        pendingCancelConfirmations: pendingConfirmations,
+        pendingCancelAction: {
+          participantId: event.data.participantId,
+          appEventName: event.data.appEventName,
+          payload: event.data.payload
+        },
+        suppressParticipantTimeouts: true  // Drop PARTICIPANT_TIMEOUT events
+      }
+    }),
+    removeFromPendingCancelConfirmations: assign(({ context, event }) => {
+      const participantId = event.participantId || event.data?.id
+      if (!context.pendingCancelConfirmations || !participantId) return {}
+
+      const newPending = new Set(context.pendingCancelConfirmations)
+      newPending.delete(participantId)
+      const remaining = newPending.size
+
+      logger.debug(`[AEM] TIMER_CANCELED received from ${participantId}. ${remaining} confirmations remaining.`)
+
+      return {
+        pendingCancelConfirmations: newPending
+      }
+    }),
+    forwardPendingCancelAction: ({ context }) => {
+      if (!context.pendingCancelAction) {
+        logger.warn(`[AEM] forwardPendingCancelAction called but pendingCancelAction is null`)
+        return
+      }
+
+      const { participantId, appEventName, payload } = context.pendingCancelAction
+
+      const actionEventPayload = {
+        participantId,
+        payload
+      }
+
+      logger.info(`[AEM] All cancellation confirmations received. Forwarding cancel ACTION ${appEventName} from ${participantId} to AppM and APM`)
+
+      // Forward to AppM
+      context.appEventMachine.send({ type: appEventName, ...actionEventPayload })
+
+      // Forward to APM
+      const participantMachine = context.participantMachines[participantId]
+      if (participantMachine) {
+        participantMachine.send({ type: 'ACTION', ...actionEventPayload })
+      } else {
+        logger.warn(`[AEM] Participant machine not found for ${participantId} when forwarding cancel ACTION`)
+      }
+    },
+    clearCancelState: assign({
+      pendingCancelConfirmations: null,
+      pendingCancelAction: null,
+      suppressParticipantTimeouts: false
+    }),
+    dropEventDuringCancellation: ({ context, event }) => {
+      // Drop/ignore ACTION and PARTICIPANT_TIMEOUT events received during cancellation wait
+      // All other events (presence events, etc.) are not handled here and will bubble up to parent handlers
+      logger.debug(`[AEM] Dropping ${event.type} event during cancellation wait`)
+    },
+    clearParticipantTimeoutSuppression: assign({
+      suppressParticipantTimeouts: false
+    }),
+    setupCancelActionType: assign(({ context, event }) => {
+      const cancelActionType =
+        (event && event.output && event.output.cancelActionType) ||
+        (event && event.data && event.data.cancelActionType) ||
+        null
+
+      if (cancelActionType) {
+        logger.debug(`[AEM] Setting up cancel action type for eachParticipant timeout: ${cancelActionType}`)
+      }
+
+      return {
+        eachParticipantCancelActionType: cancelActionType
+      }
+    }),
     updateParticipantPresence: ({ context, event }) => {
       const participantId = event.data.id;
       const participant = context.participants[participantId];
@@ -1613,7 +1837,18 @@ const AnearEventMachineFunctions = ({
       const eventName = getPresenceEventName(participant, 'UPDATE');
       context.appEventMachine.send({ type: eventName, data: event.data });
     },
-    processParticipantAction: ({ context, event }) => {
+    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 }
+      }
+      return {}
+    }),
+    processParticipantAction: ({ context, event, self }) => {
       // event.data.participantId,
       // event.data.payload: {"appEventMachineACTION": {action event keys and values}}
       //   e.g.  {"MOVE":{"x":1, "y":2}}
@@ -1623,7 +1858,25 @@ const AnearEventMachineFunctions = ({
       const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
 
       logger.debug(`[AEM] got Event ${appEventName} from payload from participant ${participantId}`)
+      logger.debug(`[AEM] eachParticipantCancelActionType is: ${context.eachParticipantCancelActionType}`)
+
+      // Check if this ACTION should trigger cancellation for eachParticipant timeout
+      if (context.eachParticipantCancelActionType === appEventName) {
+        logger.info(`[AEM] Intercepting cancel ACTION ${appEventName} from ${participantId} (eachParticipant timeout cancellation)`)
+        // Trigger cancellation sequence via self-send
+        self.send({
+          type: 'TRIGGER_CANCEL_SEQUENCE',
+          data: {
+            participantId,
+            appEventName,
+            payload,
+            event  // Store original event for reference
+          }
+        })
+        return  // Don't forward yet, wait for cancellation to complete
+      }
 
+      // Normal flow: forward immediately
       const actionEventPayload = {
         participantId,
         payload
@@ -1643,6 +1896,9 @@ const AnearEventMachineFunctions = ({
       // This assumes the current participant IS a non-responder.
       const isFinalAction = nonResponders.size === 1 && nonResponders.has(participantId);
 
+      if (isFinalAction) {
+        logger.debug(`[AEM] Final ACTION received from ${participantId}, allParticipants timeout cancelled (all responded)`)
+      }
       logger.info(`[AEM] Participants FINAL ACTION is ${isFinalAction}`)
 
       // Forward to AppM with the finalAction flag
@@ -1662,10 +1918,61 @@ const AnearEventMachineFunctions = ({
         participantMachine.send({ type: 'ACTION', ...apm_Payload });
       }
     },
-    processParticipantTimeout: ({ context, event }) =>
-      context.appEventMachine.send({ type: 'PARTICIPANT_TIMEOUT', participantId: event.participantId }),
+    storeCancelActionForAllParticipants: assign(({ context, event }) => {
+      const participantId = event.data.participantId
+      const eventMessagePayload = JSON.parse(event.data.payload)
+      const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
+
+      logger.info(`[AEM] Intercepting cancel ACTION ${appEventName} for allParticipants timeout from ${participantId}`)
+
+      return {
+        pendingCancelAction: {
+          participantId,
+          appEventName,
+          payload
+        }
+      }
+    }),
+    trackParticipantTimeout: assign(({ context, event }) => {
+      const participantId = event.participantId
+      const currentCount = context.consecutiveTimeoutCounts[participantId] || 0
+      const newCount = currentCount + 1
+
+      logger.debug(`[AEM] Participant ${participantId} timeout count: ${currentCount} -> ${newCount}`)
+
+      return {
+        consecutiveTimeoutCounts: {
+          ...context.consecutiveTimeoutCounts,
+          [participantId]: newCount
+        }
+      }
+    }),
+    processParticipantTimeout: ({ context, event, self }) => {
+      // Suppress PARTICIPANT_TIMEOUT events after cancelAllParticipantTimeouts() until new timers
+      // are set up via render. This handles race conditions where an APM's timer fires just
+      // before receiving CANCEL_TIMEOUT. The flag is cleared when renders complete (new timers set up).
+      if (context.suppressParticipantTimeouts) {
+        logger.debug(`[AEM] Suppressing PARTICIPANT_TIMEOUT from ${event.participantId} (cancelled timers, waiting for new render)`)
+        return
+      }
+
+      const participantId = event.participantId
+      const timeoutCount = context.consecutiveTimeoutCounts[participantId] || 0
+      const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
+
+      // Check dead-man switch: if participant has exceeded consecutive timeout threshold, cancel event
+      if (timeoutCount >= maxConsecutiveTimeouts) {
+        logger.warn(`[AEM] Dead-man switch triggered: Participant ${participantId} has ${timeoutCount} consecutive timeouts (threshold: ${maxConsecutiveTimeouts}). Auto-canceling event.`)
+        self.send({ type: 'CANCEL' })
+        return
+      }
+
+      context.appEventMachine.send({ type: 'PARTICIPANT_TIMEOUT', participantId })
+    },
     setupParticipantsTimeout: assign(({ context, event }) => {
-      // Only set up a new timeout if one is provided by the display render workflow.
+      // Only set up a new timeout if one is provided by the display render workflow
+      // AND we don't already have an active timeout (i.e., we're entering from waitingForActions,
+      // not re-rendering during waitAllParticipantsResponse).
       //
       // v5 note: `renderDisplay` is implemented as a Promise actor (fromPromise).
       // The actor's resolved value is delivered on the done event as `event.output`
@@ -1676,21 +1983,29 @@ const AnearEventMachineFunctions = ({
         (event && event.data && event.data.participantsTimeout) ||
         null
 
-      // This prevents overwriting an existing timeout during a simple re-render.
-      if (participantsTimeout) {
+      // Only set up a NEW timeout if one is provided and we don't already have an active timeout.
+      // If we're re-rendering during waitAllParticipantsResponse, the timer is still running
+      // from the parent state (preserved by nested state pattern), so we don't overwrite it.
+      if (participantsTimeout && !context.participantsActionTimeout) {
         const timeoutMsecs = participantsTimeout.msecs
         const allParticipantIds = getActiveParticipantIds(context)
-        logger.debug(`[AEM] Starting participants action timeout for ${timeoutMsecs}ms. Responders: ${allParticipantIds.join(', ')}`)
+        const cancelActionType =
+          (event && event.output && event.output.cancelActionType) ||
+          (event && event.data && event.data.cancelActionType) ||
+          null
+
+        logger.debug(`[AEM] Setting up allParticipants timeout: ${timeoutMsecs}ms for ${allParticipantIds.length} participants: ${allParticipantIds.join(', ')}${cancelActionType ? `, cancel: ${cancelActionType}` : ''}`)
 
         return {
           participantsActionTimeout: {
             msecs: timeoutMsecs,
             startedAt: Date.now(),
-            nonResponders: new Set(allParticipantIds)
+            nonResponders: new Set(allParticipantIds),
+            cancelActionType: cancelActionType
           }
         }
       }
-      // If no timeout data, return empty object to not change context
+      // If no timeout data or timeout already exists, return empty object to not change context
       return {};
     }),
     processParticipantResponse: assign(({ context, event }) => {
@@ -1698,6 +2013,9 @@ const AnearEventMachineFunctions = ({
       const { nonResponders, ...rest } = context.participantsActionTimeout
       const newNonResponders = new Set(nonResponders)
       newNonResponders.delete(participantId)
+      const remainingCount = newNonResponders.size
+
+      logger.debug(`[AEM] Participant ${participantId} responded, removing from allParticipants timeout. ${remainingCount} participants remaining.`)
 
       return {
         participantsActionTimeout: {
@@ -1726,15 +2044,53 @@ const AnearEventMachineFunctions = ({
         }
       };
     }),
-    sendActionsTimeoutToAppM: ({ context }) => {
+    sendActionsTimeoutToAppM: ({ context, self }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
-      logger.info(`[AEM] Participants action timed out. Non-responders: ${nonResponderIds.join(', ')}`)
+      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
+      }
 
       if (context.appEventMachine) {
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds })
       }
     },
+    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) {
+        context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds, canceled: true })
+      }
+    },
+    forwardPendingCancelActionIfExists: ({ context }) => {
+      if (!context.pendingCancelAction) return  // No cancel ACTION to forward
+
+      const { participantId, appEventName, payload } = context.pendingCancelAction
+      const actionEventPayload = { participantId, payload }
+
+      // Forward to AppM
+      context.appEventMachine.send({ type: appEventName, ...actionEventPayload })
+
+      // Forward to APM
+      const participantMachine = context.participantMachines[participantId]
+      if (participantMachine) {
+        participantMachine.send({ type: 'ACTION', ...actionEventPayload })
+      }
+
+      logger.info(`[AEM] Forwarded cancel ACTION ${appEventName} from ${participantId} to AppM and APM after allParticipants cancellation`)
+
+      // Clear the pending action
+      context.pendingCancelAction = null
+    },
     clearParticipantsTimeout: assign({
       participantsActionTimeout: null
     }),
@@ -1744,6 +2100,9 @@ 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
 
@@ -1766,7 +2125,8 @@ const AnearEventMachineFunctions = ({
               ...context.participants,
               [participantId]: updatedParticipant
             },
-            participantMachines: remainingMachines
+            participantMachines: remainingMachines,
+            consecutiveTimeoutCounts: remainingTimeoutCounts
           }
         } else {
           // For non-open-house events: remove both participant and machine (existing behavior)
@@ -1782,11 +2142,14 @@ const AnearEventMachineFunctions = ({
 
           return {
             participants: remainingParticipants,
-            participantMachines: remainingMachines
+            participantMachines: remainingMachines,
+            consecutiveTimeoutCounts: remainingTimeoutCounts
           }
         }
       } else {
-        return {}
+        return {
+          consecutiveTimeoutCounts: remainingTimeoutCounts
+        }
       }
     }),
     notifyCoreServiceMachineExit: ({ context }) => {
@@ -1985,8 +2348,9 @@ const AnearEventMachineFunctions = ({
     renderDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
       const displayEventProcessor = new DisplayEventProcessor(context)
+      const cancelActionType = event.cancelActionType || null
 
-      return await displayEventProcessor.processAndPublish(event.displayEvents)
+      return await displayEventProcessor.processAndPublish(event.displayEvents, cancelActionType)
     }),
     getAttachedCreatorOrHost: fromPromise(async ({ input }) => {
       const { context } = input
@@ -2162,6 +2526,9 @@ const AnearEventMachineFunctions = ({
     },
     allParticipantsResponded: ({ context }) => {
       return context.participantsActionTimeout && context.participantsActionTimeout.nonResponders.size === 0
+    },
+    allCancelConfirmationsReceived: ({ context }) => {
+      return !context.pendingCancelConfirmations || context.pendingCancelConfirmations.size === 0
     }
   },
   delays: {

package/lib/state_machines/AnearParticipantMachine.js

@@ -161,6 +161,7 @@ const AnearParticipantMachineConfig = participantId => ({
           initial: 'idle',
           states: {
             idle: {
+              entry: ['ensureTimerCleared'],
               on: {
                 RENDER_DISPLAY: {
                   target: '#renderDisplay'
@@ -168,6 +169,12 @@ const AnearParticipantMachineConfig = participantId => ({
                 PRIVATE_DISPLAY: {
                   target: '#renderDisplay'
                 },
+                CANCEL_TIMEOUT: {
+                  // Acknowledge CANCEL_TIMEOUT even when idle (no active timer).
+                  // This ensures the AEM's cancellation sequence completes for all participants.
+                  actions: ['sendTimerCanceled'],
+                  // v5 note: internal transitions are the default (v4 had `internal: true`)
+                },
                 PARTICIPANT_DISCONNECT: {
                   target: 'waitReconnect'
                 },
@@ -235,8 +242,7 @@ const AnearParticipantMachineConfig = participantId => ({
                 onDone: [
                   { guard: 'hasActionTimeout', actions: 'updateActionTimeout', target: 'waitParticipantResponse' },
                   // If this display does not configure a timeout, explicitly clear any
-                  // previously-running action timeout. Otherwise, a stale actionTimeoutStart
-                  // from an older prompt can be "resumed" later and immediately fire.
+                  // previously-running action timeout.
                   { actions: 'nullActionTimeout', target: 'idle' }
                 ],
                 onError: {
@@ -251,6 +257,7 @@ const AnearParticipantMachineConfig = participantId => ({
               }
             },
             waitParticipantResponse: {
+              entry: 'logWaitParticipantResponseEntry',
               always: {
                 guard: 'isTimeoutImmediate',
                 actions: 'logImmediateTimeout',
@@ -262,16 +269,41 @@ const AnearParticipantMachineConfig = participantId => ({
                   target: '#participantTimedOut'
                 }
               },
+              initial: 'waiting',
+              states: {
+                waiting: {
+                  // The actual waiting state. Timer continues running when we transition to .rendering.
+                },
+                rendering: {
+                  invoke: {
+                    src: 'publishPrivateDisplay',
+                    input: ({ context, event }) => ({ context, event }),
+                    onDone: {
+                      // Transition back to waiting - timer continues because we never exited waitParticipantResponse
+                      // Target sibling state (stays within parent, timer continues)
+                      target: 'waiting'
+                    },
+                    onError: {
+                      target: '#error'
+                    }
+                  },
+                  on: {
+                    PARTICIPANT_EXIT: {
+                      actions: 'logExit',
+                      target: '#cleanupAndExit'
+                    }
+                  }
+                }
+              },
               on: {
                 RENDER_DISPLAY: {
-                  // Re-render the current prompt for this participant (e.g. after reconnect)
-                  // without resetting the original timeout start. The updateActionTimeout
-                  // action will recompute the remaining time based on the original
-                  // actionTimeoutStart so the participant does not get extra time.
-                  target: '#renderDisplay'
+                  // Re-render the current prompt without exiting waitParticipantResponse.
+                  // This preserves the parent's after: timer because we stay within the parent state.
+                  target: '.rendering'
                 },
                 PRIVATE_DISPLAY: {
-                  target: '#renderDisplay'
+                  // Same as RENDER_DISPLAY - re-render without interrupting timer
+                  target: '.rendering'
                 },
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
@@ -285,6 +317,14 @@ const AnearParticipantMachineConfig = participantId => ({
                   ],
                   target: 'idle'
                 },
+                CANCEL_TIMEOUT: {
+                  // Cancel the active timeout and transition to idle. This is used
+                  // when the AppM wants to immediately cancel all participant timeouts
+                  // (e.g., when a LIAR call interrupts the wait state).
+                  // Always send TIMER_CANCELED to acknowledge, even if no timer was active.
+                  actions: ['nullActionTimeout', 'sendTimerCanceled'],
+                  target: 'idle'
+                },
                 PARTICIPANT_DISCONNECT: {
                   actions: 'updateRemainingTimeoutOnDisconnect',
                   target: 'waitReconnect'
@@ -297,7 +337,7 @@ const AnearParticipantMachineConfig = participantId => ({
             },
             participantTimedOut: {
               id: 'participantTimedOut',
-              entry: ['sendTimeoutEvents', 'nullActionTimeout'],
+              entry: ['logParticipantTimedOut', 'sendTimeoutEvents', 'nullActionTimeout'],
               always: 'idle'
             },
             cleanupAndExit: {
@@ -412,6 +452,7 @@ const AnearParticipantMachineFunctions = {
       }
     }),
     sendTimeoutEvents: ({ context }) => {
+      logger.info(`[APM] Timer expired for ${context.anearParticipant.id}, sending PARTICIPANT_TIMEOUT to AEM`)
       // AEM currently expects `event.participantId` (not nested under `data`).
       context.anearEvent.send({
         type: 'PARTICIPANT_TIMEOUT',
@@ -419,6 +460,13 @@ const AnearParticipantMachineFunctions = {
       })
       if (context.appParticipantMachine) context.appParticipantMachine.send({ type: 'PARTICIPANT_TIMEOUT' })
     },
+    sendTimerCanceled: ({ context }) => {
+      logger.debug(`[APM] Sending TIMER_CANCELED to AEM for ${context.anearParticipant.id}`)
+      context.anearEvent.send({
+        type: 'TIMER_CANCELED',
+        participantId: context.anearParticipant.id
+      })
+    },
     sendActionToAppParticipantMachine: ({ context, event }) => {
       if (context.appParticipantMachine) context.appParticipantMachine.send(event)
     },
@@ -429,34 +477,41 @@ const AnearParticipantMachineFunctions = {
       const timeoutFromEvent = event?.output?.timeout ?? event?.data?.timeout
       const now = CurrentDateTimestamp()
 
-      // If we already have a running timer (e.g. after a disconnect/reconnect
-      // cycle or a re-render), treat actionTimeoutMsecs as the remaining
-      // duration for this leg and subtract only the time since the last
-      // (re)start. This avoids double-subtracting elapsed time across
-      // multiple renders.
-      if (context.actionTimeoutStart) {
-        const elapsed = now - context.actionTimeoutStart
-        const base = context.actionTimeoutMsecs != null ? context.actionTimeoutMsecs : timeoutFromEvent
-        const remaining = base - elapsed
-        const remainingMsecs = remaining > 0 ? remaining : 0
-
-        logger.debug(`[APM] Resuming timer for ${context.anearParticipant.id} with ${remainingMsecs}ms remaining`)
-        return {
-          actionTimeoutMsecs: remainingMsecs,
-          actionTimeoutStart: now
-        }
+      // Start a new timer. This is only called when transitioning from idle to waitParticipantResponse.
+      // When RENDER_DISPLAY arrives during waitParticipantResponse, we transition to the nested
+      // .rendering state, which preserves the parent's after: timer (no resume needed).
+      const existingMsecs = context.actionTimeoutMsecs
+      const existingStart = context.actionTimeoutStart
+      if (existingMsecs != null || existingStart != null) {
+        logger.debug(`[APM] WARNING: Starting new timer for ${context.anearParticipant.id} but existing timer state found: msecs=${existingMsecs}, start=${existingStart}`)
       }
-
-      // First time this participant sees this prompt: start a fresh timer.
       logger.debug(`[APM] Starting new timer for ${context.anearParticipant.id} with ${timeoutFromEvent}ms`)
       return {
         actionTimeoutMsecs: timeoutFromEvent,
         actionTimeoutStart: now
       }
     }),
-    nullActionTimeout: assign({
-      actionTimeoutMsecs: (_args) => null,
-      actionTimeoutStart: (_args) => null
+    nullActionTimeout: assign(({ context }) => {
+      if (context.actionTimeoutMsecs != null || context.actionTimeoutStart != null) {
+        logger.debug(`[APM] Cancelling timer for ${context.anearParticipant.id} (ACTION received or timeout cleared)`)
+      }
+      return {
+        actionTimeoutMsecs: null,
+        actionTimeoutStart: null
+      }
+    }),
+    ensureTimerCleared: assign(({ context }) => {
+      // Defensive: Ensure timer state is cleared when entering idle state.
+      // This prevents stale timer state from affecting new displays, especially
+      // if a RENDER_DISPLAY arrives before timeout cleanup completes.
+      if (context.actionTimeoutMsecs != null || context.actionTimeoutStart != null) {
+        logger.debug(`[APM] Clearing stale timer state for ${context.anearParticipant.id} on idle entry (msecs=${context.actionTimeoutMsecs}, start=${context.actionTimeoutStart})`)
+        return {
+          actionTimeoutMsecs: null,
+          actionTimeoutStart: null
+        }
+      }
+      return {}
     }),
     updateRemainingTimeoutOnDisconnect: assign(({ context }) => {
       if (context.actionTimeoutStart) {
@@ -492,6 +547,8 @@ const AnearParticipantMachineFunctions = {
     },
     logAttached: ({ context }) => logger.debug(`[APM] Got ATTACHED for privateChannel for ${context.anearParticipant.id}`),
     logLive: ({ context }) => logger.debug(`[APM] Participant ${context.anearParticipant.id} is LIVE!`),
+    logWaitParticipantResponseEntry: ({ context }) => logger.debug(`[APM] ENTERING waitParticipantResponse state for ${context.anearParticipant.id} - timer will be (re)started if context provides timeout`),
+    logParticipantTimedOut: ({ context }) => logger.debug(`[APM] ENTERING participantTimedOut state for ${context.anearParticipant.id} - timeout occurred, clearing timer and sending PARTICIPANT_TIMEOUT`),
     logExit: (_args) => logger.debug('[APM] got PARTICIPANT_EXIT. Exiting...'),
     logDisconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} has DISCONNECTED`),
     logActionTimeoutWhileDisconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} timed out on action while disconnected.`),

package/lib/utils/AppMachineTransition.js

@@ -94,6 +94,7 @@ const AppMachineTransition = (anearEvent) => {
       const appStateName = _stringifiedState(value)
 
       const displayEvents = []
+      let cancelActionType = null  // Track cancel property from meta configuration
 
       // Process all meta objects to handle unpredictable AppM structures
       metaObjects.forEach(meta => {
@@ -112,6 +113,11 @@ const AppMachineTransition = (anearEvent) => {
           const { viewPath, props } = _extractViewAndProps(meta.allParticipants)
           timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.allParticipants.timeout)
 
+          // Extract cancel property if present
+          if (meta.allParticipants.cancel && !cancelActionType) {
+            cancelActionType = meta.allParticipants.cancel
+          }
+
           displayEvent = RenderContextBuilder.buildDisplayEvent(
             viewPath,
             RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
@@ -127,7 +133,8 @@ const AppMachineTransition = (anearEvent) => {
           // Check if participant is a function (new selective rendering format)
           viewer = 'eachParticipant'
           if (typeof meta.eachParticipant === 'function') {
-            // New selective participant rendering
+            // New selective participant rendering - cancel property is not supported in function format
+            // (would need to be in the object format, see legacy handling below)
             const participantRenderFunc = meta.eachParticipant
             const participantDisplays = participantRenderFunc(appContext, event)
 
@@ -165,6 +172,11 @@ const AppMachineTransition = (anearEvent) => {
             const { viewPath, props } = _extractViewAndProps(meta.eachParticipant)
             const timeoutFn = RenderContextBuilder.buildTimeoutFn('participant', meta.eachParticipant.timeout)
 
+            // Extract cancel property if present (for legacy eachParticipant format)
+            if (meta.eachParticipant.cancel && !cancelActionType) {
+              cancelActionType = meta.eachParticipant.cancel
+            }
+
             const renderContext = RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, 'eachParticipant', timeoutFn)
             displayEvent = RenderContextBuilder.buildDisplayEvent(
               viewPath,
@@ -213,7 +225,15 @@ const AppMachineTransition = (anearEvent) => {
 
       if (displayEvents.length > 0) {
         logger.debug(`[AppMachineTransition] sending RENDER_DISPLAY with ${displayEvents.length} displayEvents`)
-        anearEvent.send({ type: 'RENDER_DISPLAY', displayEvents })
+        const renderDisplayPayload = {
+          type: 'RENDER_DISPLAY',
+          displayEvents
+        }
+        // Include cancel property only if defined
+        if (cancelActionType) {
+          renderDisplayPayload.cancelActionType = cancelActionType
+        }
+        anearEvent.send(renderDisplayPayload)
       }
     }
 

package/lib/utils/Constants.js

@@ -16,6 +16,10 @@ module.exports = {
     RECONNECT: 30 * 1000, // 30 seconds
     BOOT_EXIT: 2 * 1000 // 5 seconds
   },
+  DEAD_MAN_SWITCH: {
+    // Maximum consecutive timeouts per participant before auto-canceling event
+    MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS: 4
+  },
   EventStates: {
     CREATED: 'created',
     STARTED: 'started',

package/lib/utils/DisplayEventProcessor.js

@@ -56,7 +56,7 @@ class DisplayEventProcessor {
     this.participantsIndex = this._buildParticipantsIndex(anearEventMachineContext.participants)
   }
 
-  processAndPublish(displayEvents) {
+  processAndPublish(displayEvents, cancelActionType = null) {
     let participantsTimeout = null
 
     // Pre-compute allParticipants timeout for this render batch so other viewers
@@ -88,7 +88,7 @@ class DisplayEventProcessor {
     })
 
     return Promise.all(publishPromises).then(() => {
-      return { participantsTimeout }
+      return { participantsTimeout, cancelActionType }
     })
   }
 

package/package.json

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

package/tests/JsonApiArrayResource.test.js

@@ -19,7 +19,7 @@ test('constructor', () => {
 test('attributes by index', () => {
   const tq = new TriviaQuestions(json1)
   let attr = tq.attributes(0)
-  
+
   expect(attr['question-text']).toBe("How much is 1 + 15?")
   expect(attr.category).toBe("math")