anear-js-api 1.3.0 → 1.3.2

package/lib/state_machines/AnearEventMachine.js

@@ -658,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']
@@ -677,7 +678,7 @@ const ActiveEventStatesConfig = {
               },
               always: {
                 guard: 'allCancelConfirmationsReceived',
-                actions: ['forwardPendingCancelAction', 'clearCancelState'],
+                actions: ['forwardPendingCancelActionIfExists', 'clearCancelState'],
                 target: '#waitingForActions.idle'
               }
             }
@@ -691,7 +692,12 @@ const ActiveEventStatesConfig = {
               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: {
@@ -1749,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 {}

package/lib/state_machines/AnearParticipantMachine.js

@@ -23,7 +23,7 @@
  *
  *  - Enforce participant-level timeouts and activity rules:
  *      - Action timeouts:
- *          - After a PRIVATE_DISPLAY / RENDER_DISPLAY that expects input,
+ *          - After a RENDER_DISPLAY that expects input,
  *            starts a per-participant response timer.
  *          - If the timer fires before an ACTION arrives, emits PARTICIPANT_TIMEOUT
  *            back to the AEM and the appParticipantMachine.
@@ -64,7 +64,7 @@
  *        Ably wiring or lifecycle plumbing.
  *
  * Incoming events (from AEM / system) – high level:
- *  - RENDER_DISPLAY / PRIVATE_DISPLAY:
+ *  - RENDER_DISPLAY:
  *      - Prompt the participant with a new view or interaction on their private channel.
  *      - Optionally include an action timeout; APM transitions into a wait state.
  *
@@ -87,7 +87,7 @@
  *  2. It creates and attaches to the participant’s private Ably channel, then
  *     signals PARTICIPANT_MACHINE_READY back to the AEM.
  *  3. It enters the live state, handling:
- *       - PRIVATE_DISPLAY / RENDER_DISPLAY → publish UI, optionally start timeout.
+ *       - RENDER_DISPLAY → publish UI, optionally start timeout.
  *       - ACTION → forward to appParticipantMachine, clear timeout, go idle.
  *       - DISCONNECT / RECONNECT → manage reconnect windows and possible timeouts.
  *       - EXIT / BOOT → send shutdown messaging and clean up.
@@ -166,9 +166,6 @@ const AnearParticipantMachineConfig = participantId => ({
                 RENDER_DISPLAY: {
                   target: '#renderDisplay'
                 },
-                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.
@@ -215,9 +212,6 @@ const AnearParticipantMachineConfig = participantId => ({
                 RENDER_DISPLAY: {
                   target: '#renderDisplay'
                 },
-                PRIVATE_DISPLAY: {
-                  target: '#renderDisplay'
-                },
                 PARTICIPANT_EXIT: {
                   target: '#cleanupAndExit'
                 },
@@ -264,6 +258,9 @@ const AnearParticipantMachineConfig = participantId => ({
                 target: '#participantTimedOut'
               },
               after: {
+                // Note: This timer continues running even when in nested .rendering state.
+                // XState v5 handles this correctly - the timer fires from the parent state
+                // and can transition even during invoke processing.
                 actionTimeout: {
                   actions: 'nullActionTimeout',
                   target: '#participantTimedOut'
@@ -272,17 +269,27 @@ const AnearParticipantMachineConfig = participantId => ({
               initial: 'waiting',
               states: {
                 waiting: {
-                  // The actual waiting state. Timer continues running when we transition to .rendering.
+                  // The actual waiting state. RENDER_DISPLAY is blocked here
+                  // to prevent timer conflicts. AppM must cancel timers first.
                 },
                 rendering: {
+                  // NOTE: This nested state is currently unreachable as RENDER_DISPLAY
+                  // is blocked during waitParticipantResponse. Kept for potential future use or
+                  // other edge cases. The parent's `after: actionTimeout` timer continues running
+                  // during invoke if this state were to be entered.
                   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'
-                    },
+                    onDone: [
+                      {
+                        guard: 'hasActionTimeout',
+                        actions: 'updateActionTimeoutIfChanged',
+                        target: 'waiting'
+                      },
+                      {
+                        target: 'waiting'
+                      }
+                    ],
                     onError: {
                       target: '#error'
                     }
@@ -297,13 +304,11 @@ const AnearParticipantMachineConfig = participantId => ({
               },
               on: {
                 RENDER_DISPLAY: {
-                  // 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: {
-                  // Same as RENDER_DISPLAY - re-render without interrupting timer
-                  target: '.rendering'
+                  // BLOCKED: RENDER_DISPLAY during active timeout wait is not allowed.
+                  // The AppM must first cancel all participant timers (via cancelAllParticipantTimeouts()
+                  // or cancel: "ACTION" in meta) and wait for ACK before issuing new RENDER_DISPLAY
+                  // with timeouts. This prevents timer conflicts and ensures clean state transitions.
+                  actions: 'logBlockedRenderDuringWait'
                 },
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
@@ -346,7 +351,6 @@ const AnearParticipantMachineConfig = participantId => ({
               // Ignore most events during cleanup, but allow exit displays
               on: {
                 RENDER_DISPLAY: { actions: 'logIgnoringRenderDisplayCleanup' },
-                PRIVATE_DISPLAY: { actions: 'logIgnoringPrivateDisplayCleanup' },
                 PARTICIPANT_EXIT: {
                   actions: 'logIgnoringRedundantExit'
                 },
@@ -407,7 +411,6 @@ const AnearParticipantMachineConfig = participantId => ({
               // Final state - ignore all events except exit displays
               on: {
                 RENDER_DISPLAY: { actions: 'logIgnoringRenderDisplayDone' },
-                PRIVATE_DISPLAY: { actions: 'logIgnoringPrivateDisplayDone' },
                 '*': {
                   actions: 'logIgnoringEventDone'
                 }
@@ -491,6 +494,36 @@ const AnearParticipantMachineFunctions = {
         actionTimeoutStart: now
       }
     }),
+    updateActionTimeoutIfChanged: assign(({ context, event }) => {
+      const timeoutFromEvent = event?.output?.timeout ?? event?.data?.timeout
+      const now = CurrentDateTimestamp()
+
+      // When RENDER_DISPLAY arrives during waitParticipantResponse, check if the timeout has changed.
+      // If it has, update the timer. This handles state transitions where a new timeout is needed.
+      const existingMsecs = context.actionTimeoutMsecs
+      const existingStart = context.actionTimeoutStart
+
+      if (timeoutFromEvent == null || timeoutFromEvent <= 0) {
+        // New display has no timeout - preserve existing timer (this is a visual status update)
+        // Don't clear it, as we're still waiting for the original ACTION
+        logger.debug(`[APM] Preserving existing timer for ${context.anearParticipant.id} (new display has no timeout, visual status update)`)
+        return {}
+      }
+
+      // If we already have an active timer and receive a new timeout, this is a bug (detected above).
+      // Preserve the existing timer to avoid conflicts. The AppM should cancel timers first.
+      if (existingMsecs != null && existingStart != null) {
+        logger.warn(`[APM] AppM BUG: Received timeout=${timeoutFromEvent}ms while timer already active (${existingMsecs}ms) for ${context.anearParticipant.id}. Preserving existing timer. AppM should cancel timers first.`)
+        return {}
+      }
+
+      // No existing timer - start a new one (shouldn't happen in waitParticipantResponse, but handle gracefully)
+      logger.debug(`[APM] Starting new timer for ${context.anearParticipant.id} with ${timeoutFromEvent}ms`)
+      return {
+        actionTimeoutMsecs: timeoutFromEvent,
+        actionTimeoutStart: now
+      }
+    }),
     nullActionTimeout: assign(({ context }) => {
       if (context.actionTimeoutMsecs != null || context.actionTimeoutStart != null) {
         logger.debug(`[APM] Cancelling timer for ${context.anearParticipant.id} (ACTION received or timeout cleared)`)
@@ -556,13 +589,25 @@ const AnearParticipantMachineFunctions = {
     logReconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} has RECONNECTED`),
     logImmediateTimeout: ({ context }) => logger.debug(`[APM] Timeout of ${context.actionTimeoutMsecs}ms is immediate for ${context.anearParticipant.id}.`),
     logIgnoringRenderDisplayCleanup: (_args) => logger.debug('[APM] ignoring RENDER_DISPLAY during cleanup'),
-    logIgnoringPrivateDisplayCleanup: (_args) => logger.debug('[APM] ignoring PRIVATE_DISPLAY during cleanup'),
     logIgnoringRedundantExit: () => logger.debug('[APM] ignoring redundant PARTICIPIPANT_EXIT during cleanup'),
     logIgnoringReconnectCleanup: () => logger.debug('[APM] ignoring PARTICIPANT_RECONNECT during cleanup - already timed out'),
     logIgnoringActionCleanup: () => logger.debug('[APM] ignoring ACTION during cleanup'),
     logIgnoringRenderDisplayDone: () => logger.debug('[APM] ignoring RENDER_DISPLAY in final state'),
-    logIgnoringPrivateDisplayDone: () => logger.debug('[APM] ignoring PRIVATE_DISPLAY in final state'),
-    logIgnoringEventDone: ({ event }) => logger.debug('[APM] ignoring event in final state: ', event.type)
+    logIgnoringEventDone: ({ event }) => logger.debug('[APM] ignoring event in final state: ', event.type),
+    logBlockedRenderDuringWait: ({ context, event }) => {
+      const eventType = event?.type ?? 'RENDER_DISPLAY'
+      const timeout = event?.timeout ?? event?.data?.timeout
+      const participantId = context.anearParticipant.id
+      const remainingMsecs = context.actionTimeoutMsecs
+      const timeoutInfo = timeout ? ` (new timeout: ${timeout}ms)` : ''
+      
+      logger.error(`[APM] ⚠️  BLOCKED: ${eventType} received during active timeout wait for participant ${participantId}. Current timer: ${remainingMsecs}ms remaining.${timeoutInfo}`)
+      logger.error(`[APM] ⚠️  The AppM must first cancel all participant timers using one of these methods:`)
+      logger.error(`[APM] ⚠️    1. Declarative: Add cancel: "ACTION_NAME" to meta.eachParticipant or meta.allParticipants`)
+      logger.error(`[APM] ⚠️    2. Manual: Call anearEvent.cancelAllParticipantTimeouts() and wait for ACK`)
+      logger.error(`[APM] ⚠️  Only after timers are cancelled (APM transitions to idle) can new RENDER_DISPLAY with timeouts be issued.`)
+      logger.error(`[APM] ⚠️  This ${eventType} event is being IGNORED to prevent timer conflicts.`)
+    }
   },
   actors: {
     publishPrivateDisplay: fromPromise(async ({ input }) => {

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/package.json

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