anear-js-api 1.2.0 → 1.2.2

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,11 @@ 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 }
 })
 
 const ActiveEventGlobalEvents = {
@@ -378,6 +382,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 +421,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: {
@@ -484,6 +490,9 @@ const ActiveEventStatesConfig = {
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipantMachine'
         },
+        CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+          actions: 'cancelAllParticipantTimeouts'
+        },
         SPECTATOR_ENTER: {
           actions: 'sendSpectatorEnterToAppEventMachine'
         }
@@ -527,6 +536,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 +626,9 @@ const ActiveEventStatesConfig = {
         },
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipantMachine'
+        },
+        CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
+          actions: 'cancelAllParticipantTimeouts'
         }
       },
       states: {
@@ -634,6 +647,34 @@ 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']
@@ -642,6 +683,13 @@ const ActiveEventStatesConfig = {
             PARTICIPANT_TIMEOUT: {
               actions: ['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 +702,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 +742,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: ['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 +826,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 +1701,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 +1831,7 @@ const AnearEventMachineFunctions = ({
       const eventName = getPresenceEventName(participant, 'UPDATE');
       context.appEventMachine.send({ type: eventName, data: event.data });
     },
-    processParticipantAction: ({ context, event }) => {
+    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 +1841,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 +1879,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 +1901,35 @@ 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
+        }
+      }
+    }),
+    processParticipantTimeout: ({ context, event }) => {
+      // 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
+      }
+      context.appEventMachine.send({ type: 'PARTICIPANT_TIMEOUT', participantId: event.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 +1940,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 +1970,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: {
@@ -1729,12 +2004,41 @@ const AnearEventMachineFunctions = ({
     sendActionsTimeoutToAppM: ({ context }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
-      logger.info(`[AEM] Participants action timed out. Non-responders: ${nonResponderIds.join(', ')}`)
+      logger.info(`[AEM] allParticipants timeout expired after ${msecs}ms. Non-responders: ${nonResponderIds.join(', ')}`)
 
       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
     }),
@@ -1985,8 +2289,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 +2467,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

@@ -15,6 +15,9 @@ const REFRESH_EVENT_TYPES = new Set([
   // Temporary disconnects (useful for "halt/pause" and UI indicators):
   'PARTICIPANT_DISCONNECT',
   'HOST_DISCONNECT',
+  // Permanent exits (should update participant counts and UI):
+  'PARTICIPANT_EXIT',
+  'HOST_EXIT',
   // Location/heartbeat updates can also want a "refresh current view":
   'PARTICIPANT_UPDATE',
   'HOST_UPDATE'
@@ -91,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 => {
@@ -109,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),
@@ -124,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)
 
@@ -162,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,
@@ -210,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/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/lib/utils/PugHelpers.js

@@ -19,6 +19,81 @@ const PugHelpers = s3ImageAssetsUrl => ({
     } catch (error) {
       throw new Error("Invalid JSON for data-click-action:", finalPayload);
     }
+  },
+  /**
+   * Format a timestamp in the event's timezone (or fallback to local time)
+   * General-purpose helper that works for both time and date formatting.
+   *
+   * @param {number|Date} timestamp - Timestamp in milliseconds or Date object
+   * @param {string|null} timezone - IANA timezone ID (e.g., 'America/New_York') or null for local time
+   * @param {object} options - Intl.DateTimeFormat options
+   *   - For time: { hour: 'numeric', minute: '2-digit', hour12: true }
+   *   - For date: { weekday: 'short', month: 'short', day: 'numeric' }
+   *   - For both: { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit', hour12: true }
+   * @returns {string} Formatted date/time string
+   *
+   * @example
+   *   // Format time only
+   *   formatDateTime(timestamp, app.eventTimezone)
+   *   // => "3:08 PM"
+   *
+   *   // Format date only
+   *   formatDateTime(timestamp, app.eventTimezone, { weekday: 'short', month: 'short', day: 'numeric' })
+   *   // => "Thu, Jan 1"
+   *
+   *   // Format date and time
+   *   formatDateTime(timestamp, app.eventTimezone, { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' })
+   *   // => "Jan 1, 3:08 PM"
+   */
+  formatDateTime: (timestamp, timezone, options = { hour: 'numeric', minute: '2-digit', hour12: true }) => {
+    const date = timestamp instanceof Date ? timestamp : new Date(timestamp)
+
+    if (timezone && typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
+      const formatter = new Intl.DateTimeFormat('en-US', { ...options, timeZone: timezone })
+      return formatter.format(date)
+    }
+
+    // Fallback: format based on what options were requested
+    const hasTimeOptions = options.hour !== undefined || options.minute !== undefined
+    const hasDateOptions = options.weekday !== undefined || options.month !== undefined || options.day !== undefined || options.year !== undefined
+
+    // If only time options, use simple time fallback
+    if (hasTimeOptions && !hasDateOptions) {
+      const hours = date.getHours()
+      const minutes = date.getMinutes()
+      const ampm = hours >= 12 ? 'PM' : 'AM'
+      const displayHours = hours % 12 || 12
+      return `${displayHours}:${minutes.toString().padStart(2, '0')} ${ampm}`
+    }
+
+    // If date options (with or without time), use UTC fallback for consistency
+    const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+    const parts = []
+
+    if (options.weekday === 'short' || options.weekday === 'long') {
+      parts.push(days[date.getUTCDay()])
+    }
+    if (options.month === 'short' || options.month === 'long') {
+      parts.push(months[date.getUTCMonth()])
+    }
+    if (options.day === 'numeric') {
+      parts.push(date.getUTCDate())
+    }
+    if (options.year === 'numeric') {
+      parts.push(date.getUTCFullYear())
+    }
+
+    // Add time if requested
+    if (hasTimeOptions) {
+      const hours = date.getUTCHours()
+      const minutes = date.getUTCMinutes()
+      const ampm = hours >= 12 ? 'PM' : 'AM'
+      const displayHours = hours % 12 || 12
+      parts.push(`${displayHours}:${minutes.toString().padStart(2, '0')} ${ampm}`)
+    }
+
+    return parts.join(' ')
   }
 })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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")