anear-js-api 1.3.2 → 1.3.3

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -80,7 +80,10 @@ const AnearCoreServiceMachineConfig = appId => ({
   context: ({ input }) => input,
   states: {
     fetchAppDataWithRetry: {
-      entry: _ => logger.info('anear-js-api version: ', anearJsApiVersion),
+      entry: ({ context }) => {
+        const appId = context.appId || process.env.ANEARAPP_APP_ID || 'unknown'
+        logger.info(`[ACSM] ===== Booting App (${appId}) on anear-js-api version ${anearJsApiVersion} =====`)
+      },
       initial: 'fetchAppData',
       states: {
         fetchAppData: {
@@ -111,7 +114,7 @@ const AnearCoreServiceMachineConfig = appId => ({
       entry: ['initRealtime'],
       on: {
         CONNECTED: {
-          actions: ['createEventsCreationChannel', 'subscribeCreateEventMessages']
+          actions: ['createEventsCreationChannel', 'subscribeCreateEventMessages', ({ context }) => logger.info(`[ACSM] Realtime messaging connected for app ${context.appId}`)]
         },
         ATTACHED: 'uploadNewImageAssets'
       }
@@ -168,7 +171,11 @@ const AnearCoreServiceMachineConfig = appId => ({
       // The Anear API backend will send CREATE_EVENT or LOAD_EVENT messages with the event JSON data
       // to this createEventMessages Channel when it needs to create a new instance of an
       // Event
-      entry: ({ context }) => logger.debug(`Waiting on ${context.appData.data.attributes['short-name']} lifecycle command`),
+      entry: ({ context }) => {
+        const shortName = context.appData.data.attributes['short-name']
+        logger.info(`[ACSM] Ready to receive events for app ${shortName}`)
+        logger.debug(`Waiting on ${shortName} lifecycle command`)
+      },
       on: {
         CREATE_EVENT: {
           actions: ['startNewEventMachine']
@@ -221,6 +228,8 @@ const AnearCoreServiceMachineFunctions = {
         pugTemplates: (_args) => {
           const pugLoader = new PugLoader(DefaultTemplatesRootDir)
           const templates = pugLoader.compiledPugTemplates()
+          const templateCount = Object.keys(templates).length
+          logger.info(`[ACSM] Loaded ${templateCount} Pug template(s)`)
           logger.debug(`loaded pug templates ${Object.keys(templates)}`)
           return templates
         }
@@ -240,7 +249,9 @@ const AnearCoreServiceMachineFunctions = {
       {
         appData: ({ event }) => {
           const output = event.output
-          logger.debug(`fetched ${output.data.attributes["short-name"]} app data`)
+          const attrs = output.data.attributes
+          logger.info(`[ACSM] Loading App from API app.short_name=${attrs["short-name"]} app.slug=${attrs.slug} app.id=${output.data.id}`)
+          logger.debug(`fetched ${attrs["short-name"]} app data`)
           return output
         }
       }
@@ -264,6 +275,7 @@ const AnearCoreServiceMachineFunctions = {
         self,
         'LOAD_EVENT'
       )
+      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on events channel`)
     },
     startNewEventMachine: assign(
       {
@@ -294,7 +306,11 @@ const AnearCoreServiceMachineFunctions = {
     ),
     cleanupEventMachine: assign(({ context, event }) => {
       const { [event.eventId]: dropped, ...remaining } = context.anearEventMachines
-      logger.debug(`ACSM ${event.eventId} is ${dropped ? "done → cleaning up" : "NOT FOUND"}`)
+      if (dropped) {
+        logger.info(`[ACSM] Event ${event.eventId} closed, freeing event slot`)
+      } else {
+        logger.debug(`ACSM ${event.eventId} is NOT FOUND`)
+      }
 
       return {
         anearEventMachines: remaining

package/lib/state_machines/AnearEventMachine.js

@@ -78,6 +78,12 @@ const getAllParticipantIds = (context) => {
   return Object.keys(context.participants);
 };
 
+// Helper to get participant name from ID, fallback to ID if not found
+const getParticipantName = (context, participantId) => {
+  const participant = context.participants[participantId];
+  return participant?.name || participantId;
+};
+
 // Participant status helper functions for active/idle state management
 const getActiveParticipantIds = (context) => {
   return Object.keys(context.participants).filter(id => {
@@ -187,6 +193,7 @@ const ActiveEventGlobalEvents = {
   },
   CANCEL: {
     // appM does an abrupt shutdown of the event
+    actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} CANCEL received`),
     target: '#canceled'
   },
   APPM_FINAL: {
@@ -518,7 +525,7 @@ const ActiveEventStatesConfig = {
         },
         waitingToStart: {
           id: 'waitingToStart',
-          entry: () => logger.debug("[AEM] announce state...waiting for event START"),
+          entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} created → announce`),
           after: {
             timeoutEventStart: {
               actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for START`),
@@ -527,6 +534,7 @@ const ActiveEventStatesConfig = {
           },
           on: {
             START: {
+              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} announce → live`),
               target: '#activeEvent.live'
             }
           }
@@ -653,7 +661,13 @@ const ActiveEventStatesConfig = {
         },
         waitingForActions: {
           id: 'waitingForActions',
-          entry: () => logger.debug('[AEM] live state...waiting for actions'),
+          entry: ({ context }) => {
+            // Only log transition on initial entry to live state, not on nested state changes
+            const currentState = context.appEventMachine?.getSnapshot?.()?.value
+            if (!currentState || typeof currentState === 'string' || Object.keys(currentState).length === 0) {
+              logger.debug('[AEM] live state...waiting for actions')
+            }
+          },
           initial: 'idle',
           states: {
             idle: {},
@@ -887,6 +901,7 @@ const ActiveEventStatesConfig = {
     },
     closeEvent: {
       id: 'closeEvent',
+      entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} live → closed`),
       initial: 'notifyingParticipants',
       on: {
         APPM_FINAL: {
@@ -954,6 +969,7 @@ const ActiveEventStatesConfig = {
     },
     canceled: {
       id: 'canceled',
+      entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} → canceled`),
       initial: 'notifyingParticipants',
       on: {
         CLOSE: {
@@ -1231,7 +1247,7 @@ const CreateEventChannelsAndAppMachineConfig = {
       // get(eventChannelName) and setup state-change callbacks
       entry: [({ context }) => {
         const eventType = context.rehydrate ? 'LOAD_EVENT' : 'CREATE_EVENT'
-        logger.debug(`[AEM] === ${eventType} ${context.anearEvent.id} ===`)
+        logger.info(`[AEM] ${eventType} Event ${context.anearEvent.id}`)
       }, 'createEventChannel'],
       invoke: {
         src: 'attachToEventChannel',
@@ -1526,6 +1542,7 @@ const AnearEventMachineFunctions = ({
         userJSON => {
           if (!context.appEventMachine) return
 
+          logger.info(`[AEM] Event ${context.anearEvent.id} SPECTATOR_ENTER spectatorId=${userJSON.id}`)
           const spectatorEvent = { type: 'SPECTATOR_ENTER', data: userJSON }
           context.appEventMachine.send(spectatorEvent)
         }
@@ -1548,7 +1565,7 @@ const AnearEventMachineFunctions = ({
       const eventName = getPresenceEventName(anearParticipant, 'ENTER');
       const eventPayload = { type: eventName, participant: participantInfo };
 
-      logger.debug(`[AEM] Sending ${eventName} for ${anearParticipant.id}`);
+      logger.info(`[AEM] Event ${context.anearEvent.id} ${eventName} participantId=${anearParticipant.id} name=${participantInfo.name}`);
       context.appEventMachine.send(eventPayload);
     },
     processDisconnectEvents: ({ context, event }) => {
@@ -1556,8 +1573,9 @@ const AnearEventMachineFunctions = ({
       const participant = context.participants[participantId];
       const eventName = getPresenceEventName(participant, 'DISCONNECT');
       const participantMachine = context.participantMachines[participantId];
+      const participantName = getParticipantName(context, participantId);
 
-      logger.debug(`[AEM] processing ${eventName} for ${participantId}`);
+      logger.info(`[AEM] Event ${context.anearEvent.id} ${eventName} participantId=${participantId} name=${participantName}`);
       if (participantMachine) {
         participantMachine.send({ type: 'PARTICIPANT_DISCONNECT' });
       }
@@ -1569,7 +1587,7 @@ const AnearEventMachineFunctions = ({
       const eventName = getPresenceEventName(participant, 'RECONNECT');
       const participantMachine = context.participantMachines[participantId];
 
-      logger.debug(`[AEM] processing ${eventName} for ${participantId}`);
+      logger.info(`[AEM] Event ${context.anearEvent.id} ${eventName} participantId=${participantId}`);
       if (participantMachine) {
         participantMachine.send({ type: 'PARTICIPANT_RECONNECT' });
       }
@@ -1683,7 +1701,8 @@ const AnearEventMachineFunctions = ({
       const participant = context.participants[participantId];
       if (participant) {
         const eventName = getPresenceEventName(participant, 'EXIT');
-        logger.debug(`[AEM] sending ${eventName} to AppM for participant ${participantId}`);
+        const participantName = getParticipantName(context, participantId);
+        logger.info(`[AEM] Event ${context.anearEvent.id} ${eventName} participantId=${participantId} name=${participantName}`);
         context.appEventMachine.send({ type: eventName, participantId });
       } else {
         logger.warn(`[AEM] Participant info not found for id ${participantId} during sendExitToAppMachine`);
@@ -1719,7 +1738,7 @@ const AnearEventMachineFunctions = ({
       // 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`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} 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
@@ -1733,7 +1752,8 @@ const AnearEventMachineFunctions = ({
     }),
     sendCancelTimeoutToAllAPMs: ({ context }) => {
       const participantCount = Object.keys(context.participantMachines).length
-      logger.info(`[AEM] Sending CANCEL_TIMEOUT to all ${participantCount} APMs for declarative cancel ACTION`)
+      const actionName = context.eachParticipantCancelActionType || 'unknown'
+      logger.info(`[AEM] Event ${context.anearEvent.id} sending CANCEL_TIMEOUT to all ${participantCount} APMs for ACTION ${actionName}`)
       Object.values(context.participantMachines).forEach(pm => {
         pm.send({ type: 'CANCEL_TIMEOUT' })
       })
@@ -1743,7 +1763,8 @@ const AnearEventMachineFunctions = ({
       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(', ')}`)
+      const participantName = getParticipantName(context, event.data.participantId)
+      logger.info(`[AEM] Event ${context.anearEvent.id} starting cancellation sequence for ACTION ${event.data.appEventName} from participantId=${event.data.participantId} name=${participantName}, waiting for ${pendingConfirmations.size} confirmations`)
 
       return {
         pendingCancelConfirmations: pendingConfirmations,
@@ -1760,7 +1781,7 @@ const AnearEventMachineFunctions = ({
       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(', ')}`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} starting manual cancellation sequence, waiting for ${pendingConfirmations.size} confirmations`)
 
       return {
         pendingCancelConfirmations: pendingConfirmations,
@@ -1795,7 +1816,8 @@ const AnearEventMachineFunctions = ({
         payload
       }
 
-      logger.info(`[AEM] All cancellation confirmations received. Forwarding cancel ACTION ${appEventName} from ${participantId} to AppM and APM`)
+      const participantName = getParticipantName(context, participantId)
+      logger.info(`[AEM] Event ${context.anearEvent.id} all cancellation confirmations received, forwarding ACTION ${appEventName} from participantId=${participantId} name=${participantName}`)
 
       // Forward to AppM
       context.appEventMachine.send({ type: appEventName, ...actionEventPayload })
@@ -1879,13 +1901,14 @@ const AnearEventMachineFunctions = ({
       const participantId = event.data.participantId
       const eventMessagePayload = JSON.parse(event.data.payload) // { eventName: {eventObject} }
       const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
+      const participantName = getParticipantName(context, participantId)
 
-      logger.debug(`[AEM] got Event ${appEventName} from payload from participant ${participantId}`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} ACTION participantId=${participantId} name=${participantName} action=${appEventName}`)
       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)`)
+        logger.info(`[AEM] Event ${context.anearEvent.id} intercepting cancel ACTION ${appEventName} from participantId=${participantId} name=${participantName} (eachParticipant timeout)`)
         // Trigger cancellation sequence via self-send
         self.send({
           type: 'TRIGGER_CANCEL_SEQUENCE',
@@ -1915,6 +1938,13 @@ const AnearEventMachineFunctions = ({
       const participantId = event.data.participantId;
       const { nonResponders } = context.participantsActionTimeout;
 
+      // Forward to AppM with the finalAction flag
+      const eventMessagePayload = JSON.parse(event.data.payload);
+      const [appEventName, payload] = Object.entries(eventMessagePayload)[0];
+      const participantName = getParticipantName(context, participantId);
+
+      logger.info(`[AEM] Event ${context.anearEvent.id} ACTION participantId=${participantId} name=${participantName} action=${appEventName}`)
+
       // Check if this is the last responder before the context is updated.
       // This assumes the current participant IS a non-responder.
       const isFinalAction = nonResponders.size === 1 && nonResponders.has(participantId);
@@ -1922,11 +1952,6 @@ const AnearEventMachineFunctions = ({
       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
-      const eventMessagePayload = JSON.parse(event.data.payload);
-      const [appEventName, payload] = Object.entries(eventMessagePayload)[0];
       const appM_Payload = {
         participantId,
         payload,
@@ -1945,8 +1970,9 @@ const AnearEventMachineFunctions = ({
       const participantId = event.data.participantId
       const eventMessagePayload = JSON.parse(event.data.payload)
       const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
+      const participantName = getParticipantName(context, participantId)
 
-      logger.info(`[AEM] Intercepting cancel ACTION ${appEventName} for allParticipants timeout from ${participantId}`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} intercepting cancel ACTION ${appEventName} from participantId=${participantId} name=${participantName} (allParticipants timeout)`)
 
       return {
         pendingCancelAction: {
@@ -1968,15 +1994,17 @@ const AnearEventMachineFunctions = ({
       }
     }),
     processParticipantTimeout: ({ context, event, self }) => {
+      const participantId = event.participantId || event.data?.participantId
       // 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)`)
+        logger.debug(`[AEM] Suppressing PARTICIPANT_TIMEOUT from ${participantId} (cancelled timers, waiting for new render)`)
         return
       }
 
-      const participantId = event.participantId
+      const participantName = getParticipantName(context, participantId)
+      logger.info(`[AEM] Event ${context.anearEvent.id} PARTICIPANT_TIMEOUT participantId=${participantId} name=${participantName}`)
       const timeoutCount = context.consecutiveTimeoutCount || 0
       const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
 
@@ -2080,7 +2108,7 @@ const AnearEventMachineFunctions = ({
       const nonResponderIds = [...nonResponders]
       const allActiveParticipantIds = getActiveParticipantIds(context)
 
-      logger.info(`[AEM] allParticipants timeout expired after ${msecs}ms. Non-responders: ${nonResponderIds.join(', ')}`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} allParticipants timeout expired after ${msecs}ms, nonResponderIds=[${nonResponderIds.join(',')}]`)
 
       // Track consecutive allParticipants timeouts where ALL participants timed out
       const allTimedOut = nonResponders.size === allActiveParticipantIds.length && allActiveParticipantIds.length > 0
@@ -2109,7 +2137,7 @@ const AnearEventMachineFunctions = ({
 
       if (context.appEventMachine) {
         // Send ACTIONS_TIMEOUT when timeout expires
-        logger.info(`[AEM] Sending ACTIONS_TIMEOUT (timeout expired)`)
+        logger.info(`[AEM] Event ${context.anearEvent.id} sending ACTIONS_TIMEOUT, nonResponderIds=[${nonResponderIds.join(',')}]`)
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds })
       }
 
@@ -2118,7 +2146,7 @@ const AnearEventMachineFunctions = ({
     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(', ')}`)
+      logger.info(`[AEM] Event ${context.anearEvent.id} allParticipants timeout cancelled after ${msecs}ms, nonResponderIds=[${nonResponderIds.join(',')}]`)
 
       if (context.appEventMachine) {
         // Send ACTIONS_TIMEOUT when timeout is canceled (backward compatibility)
@@ -2147,7 +2175,8 @@ const AnearEventMachineFunctions = ({
         participantMachine.send({ type: 'ACTION', ...actionEventPayload })
       }
 
-      logger.info(`[AEM] Forwarded cancel ACTION ${appEventName} from ${participantId} to AppM and APM after allParticipants cancellation`)
+      const participantName = getParticipantName(context, participantId)
+      logger.info(`[AEM] Event ${context.anearEvent.id} forwarded cancel ACTION ${appEventName} from participantId=${participantId} name=${participantName} after allParticipants cancellation`)
 
       // Clear the pending action
       context.pendingCancelAction = null
@@ -2212,8 +2241,8 @@ const AnearEventMachineFunctions = ({
     },
     logCreatorEnter: ({ event }) => logger.debug("[AEM] got creator PARTICIPANT_ENTER: ", event.data.id),
     logAPMReady: ({ event }) => logger.debug("[AEM] PARTICIPANT_MACHINE_READY for: ", event.data.anearParticipant.id),
-    logInvalidParticipantEnter: ({ event }) => logger.info("[AEM] Error: Unexepected PARTICIPANT_ENTER with id: ", event.data.id),
-    logDeferringAppmFinal: (_c, _e) => logger.info("[AEM] Deferring APPM_FINAL event because AEM is already transitioning to terminated state."),
+    logInvalidParticipantEnter: ({ context, event }) => logger.info(`[AEM] Event ${context.anearEvent.id} unexpected PARTICIPANT_ENTER participantId=${event.data.id}`),
+    logDeferringAppmFinal: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} deferring APPM_FINAL (already transitioning to terminated)`),
     logImplicitShutdownWarning: (_c, _e) => {
       logger.error("********************************************************************************");
       logger.error("[AEM] WARNING: AppMachine reached a 'final' state without explicitly calling anearEvent.closeEvent() or anearEvent.cancelEvent().");
@@ -2633,8 +2662,16 @@ const AnearEventMachine = (anearEvent, {
   // v5 note: subscriptions do not emit the current snapshot immediately;
   // use getSnapshot() if you want the current value right away.
   service.subscribe(state => {
-    logger.debug('─'.repeat(40))
-    logger.debug(`[AEM] NEXT STATE → ${JSON.stringify(state.value)}`)
+    // Log major state transitions at INFO level, keep detailed state dumps at DEBUG
+    const stateValue = state.value
+    const stateStr = typeof stateValue === 'string' ? stateValue : JSON.stringify(stateValue)
+    // Only log if it's a major state change (not nested state transitions)
+    if (typeof stateValue === 'string' || (typeof stateValue === 'object' && Object.keys(stateValue).length === 1)) {
+      logger.debug(`[AEM] State: ${stateStr}`)
+    } else {
+      logger.debug('─'.repeat(40))
+      logger.debug(`[AEM] NEXT STATE → ${stateStr}`)
+    }
   })
 
   return service

package/lib/state_machines/AnearParticipantMachine.js

@@ -110,6 +110,7 @@ const AnearParticipantMachineContext = (anearParticipant, anearEvent, appPartici
   appParticipantMachine: null,
   actionTimeoutMsecs: null,
   actionTimeoutStart: null,
+  capturedTimeoutMsecs: null, // Captured timeout value for logging before clearing
   lastSeen: CurrentDateTimestamp()
 })
 
@@ -262,7 +263,7 @@ const AnearParticipantMachineConfig = participantId => ({
                 // XState v5 handles this correctly - the timer fires from the parent state
                 // and can transition even during invoke processing.
                 actionTimeout: {
-                  actions: 'nullActionTimeout',
+                  actions: ['captureTimeoutForLogging', 'nullActionTimeout'],
                   target: '#participantTimedOut'
                 }
               },
@@ -303,13 +304,22 @@ const AnearParticipantMachineConfig = participantId => ({
                 }
               },
               on: {
-                RENDER_DISPLAY: {
-                  // 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'
-                },
+                RENDER_DISPLAY: [
+                  {
+                    // BLOCKED: RENDER_DISPLAY that carries a NEW timeout while we're already
+                    // waiting on an ACTION is not allowed (it would reset / conflict timers).
+                    // The AppM must first cancel timers (via cancelAllParticipantTimeouts()
+                    // or cancel: "ACTION" in meta) and wait for ACK before issuing new
+                    // RENDER_DISPLAY with timeouts.
+                    guard: 'incomingRenderHasTimeout',
+                    actions: 'logBlockedRenderDuringWait'
+                  },
+                  {
+                    // Allowed: visual-only refresh (no timeout). We publish the display while
+                    // staying inside waitParticipantResponse so the parent after: timer continues.
+                    target: '.rendering'
+                  }
+                ],
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
                   target: '#cleanupAndExit'
@@ -342,7 +352,7 @@ const AnearParticipantMachineConfig = participantId => ({
             },
             participantTimedOut: {
               id: 'participantTimedOut',
-              entry: ['logParticipantTimedOut', 'sendTimeoutEvents', 'nullActionTimeout'],
+              entry: ['logParticipantTimedOut', 'sendTimeoutEvents'],
               always: 'idle'
             },
             cleanupAndExit: {
@@ -454,8 +464,15 @@ const AnearParticipantMachineFunctions = {
         return actor
       }
     }),
+    captureTimeoutForLogging: assign(({ context }) => {
+      // Capture timeout value before it's cleared by nullActionTimeout
+      return {
+        capturedTimeoutMsecs: context.actionTimeoutMsecs
+      }
+    }),
     sendTimeoutEvents: ({ context }) => {
-      logger.info(`[APM] Timer expired for ${context.anearParticipant.id}, sending PARTICIPANT_TIMEOUT to AEM`)
+      const timeoutMsecs = context.capturedTimeoutMsecs ?? context.actionTimeoutMsecs ?? 'unknown'
+      logger.info(`[APM] Timer expired participantId=${context.anearParticipant.id} timeout=${timeoutMsecs}ms, sending PARTICIPANT_TIMEOUT to AEM`)
       // AEM currently expects `event.participantId` (not nested under `data`).
       context.anearEvent.send({
         type: 'PARTICIPANT_TIMEOUT',
@@ -488,7 +505,7 @@ const AnearParticipantMachineFunctions = {
       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}`)
       }
-      logger.debug(`[APM] Starting new timer for ${context.anearParticipant.id} with ${timeoutFromEvent}ms`)
+      logger.info(`[APM] Timer started participantId=${context.anearParticipant.id} timeout=${timeoutFromEvent}ms`)
       return {
         actionTimeoutMsecs: timeoutFromEvent,
         actionTimeoutStart: now
@@ -518,7 +535,7 @@ const AnearParticipantMachineFunctions = {
       }
 
       // 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`)
+      logger.info(`[APM] Timer started participantId=${context.anearParticipant.id} timeout=${timeoutFromEvent}ms`)
       return {
         actionTimeoutMsecs: timeoutFromEvent,
         actionTimeoutStart: now
@@ -638,6 +655,12 @@ const AnearParticipantMachineFunctions = {
   },
   guards: {
     hasAppParticipantMachine: ({ context }) => context.appParticipantMachineFactory !== null,
+    incomingRenderHasTimeout: ({ event }) => {
+      // RENDER_DISPLAY events are sent directly as { type, content, timeout? }
+      // We only block when a *new* timeout is being asserted during an active wait.
+      const timeout = event?.timeout ?? event?.data?.timeout
+      return timeout != null && timeout > 0
+    },
     hasActionTimeout: ({ event }) => {
       const timeout = event?.output?.timeout ?? event?.data?.timeout
       return timeout != null && timeout > 0

package/lib/utils/AppMachineTransition.js

@@ -55,7 +55,8 @@ const AppMachineTransition = (anearEvent) => {
     const stateName = _stringifiedState(value)
     const hasMeta = rawMeta && Object.keys(rawMeta).length > 0;
 
-    logger.debug(`[AppMachineTransition] onTransition to state '${stateName}'. Meta detected: ${hasMeta}`)
+    logger.info(`[AppMachineTransition] AppM state transition to '${stateName}' event=${event.type}`)
+    logger.debug(`[AppMachineTransition] Meta detected: ${hasMeta}`)
 
     // Handle unpredictable meta structure
     const metaObjects = rawMeta ? Object.values(rawMeta) : []

package/lib/utils/CssUploader.js

@@ -27,7 +27,7 @@ class CSSUploader {
    */
   async uploadCss() {
     if (!fs.existsSync(this.cssDirPath)) {
-      logger.info(`No css directory found at ${this.cssDirPath}. Skipping CSS upload.`)
+      logger.info(`[CssUploader] No css directory found at ${this.cssDirPath}. Skipping CSS upload.`)
       return
     }
 
@@ -38,8 +38,10 @@ class CSSUploader {
 
       if (presignedUrl) {
         await this.uploadToS3(presignedUrl, css, 'text/css')
+        logger.info(`[CssUploader] CSS uploaded successfully`)
         logger.debug('Uploaded CSS file to S3.')
       } else {
+        logger.info(`[CssUploader] CSS up to date`)
         logger.debug('CSS file is up to date; no upload necessary.')
       }
 

package/lib/utils/DisplayEventProcessor.js

@@ -141,7 +141,8 @@ class DisplayEventProcessor {
 
     switch (displayViewer) {
       case 'allParticipants':
-        logger.debug(`[DisplayEventProcessor] Publishing ${viewPath} to PARTICIPANTS_DISPLAY`)
+        const templateName = normalizedPath.replace(C.PugSuffix, '')
+        logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateName} viewer=allParticipants`)
 
         // Use display timeout if available, otherwise fall back to timeoutFn
         if (displayTimeout !== null && displayTimeout > 0) {
@@ -175,7 +176,8 @@ class DisplayEventProcessor {
         break
 
       case 'spectators':
-        logger.debug(`[DisplayEventProcessor] Publishing ${viewPath} to SPECTATORS_DISPLAY`)
+        const templateNameSpectators = normalizedPath.replace(C.PugSuffix, '')
+        logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameSpectators} viewer=spectators`)
 
         // If this event/app does not support spectators, the spectatorsDisplayChannel
         // will be null. In that case, skip publishing instead of throwing.
@@ -217,13 +219,14 @@ class DisplayEventProcessor {
         break
 
       case 'eachParticipant':
+        const templateNameEach = normalizedPath.replace(C.PugSuffix, '')
         if (participantId === 'ALL_PARTICIPANTS') {
           // Legacy behavior - send to all participants (uses timeoutFn)
-          logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY ${viewPath} for all participants`)
+          logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameEach} viewer=eachParticipant participantId=ALL_PARTICIPANTS`)
           publishPromise = this._processPrivateParticipantDisplays(template, templateRenderContext, timeoutFn)
         } else if (participantId) {
           // Selective participant rendering - send to specific participant only (uses displayTimeout)
-          logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY ${viewPath} for participant ${participantId}`)
+          logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameEach} viewer=eachParticipant participantId=${participantId}`)
           publishPromise = this._processSelectiveParticipantDisplay(template, templateRenderContext, null, participantId, displayTimeout)
         } else {
           // Fallback - should not happen with unified approach
@@ -233,7 +236,8 @@ class DisplayEventProcessor {
         break
 
       case 'host':
-        logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY ${viewPath} for host`)
+        const templateNameHost = normalizedPath.replace(C.PugSuffix, '')
+        logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameHost} viewer=host`)
         // Host may optionally have a real timeout (if configured). Otherwise, host
         // mirrors the allParticipants visual timer without starting a host timeout.
         let hostOwnMsecs = null
@@ -402,21 +406,25 @@ class DisplayEventProcessor {
         const start = pat.startedAt || Date.now()
         const remainingMsecs = Math.max(0, pat.msecs - (now - start))
         visualTimeout = { msecs: pat.msecs, remainingMsecs }
-      } else if (timeout !== null) {
-        // Fallback: no global timeout; if this participant has a real timer,
-        // show a bar based on their own APM state.
+      } else {
+        // Fallback: no global timeout.
+        // If this participant currently has an active APM timer, show a bar based on that.
+        // This enables "visual-only" re-renders (timeout=null) during an active wait without
+        // attempting to restart/reset the timer.
         const state = participantMachine?.state
         const ctx = state?.context
-        let remainingMsecs = null
-        if (ctx && ctx.actionTimeoutStart && ctx.actionTimeoutMsecs != null) {
+        if (ctx && ctx.actionTimeoutStart && ctx.actionTimeoutMsecs != null && ctx.actionTimeoutMsecs > 0) {
           const now = Date.now()
           const elapsed = now - ctx.actionTimeoutStart
           const remaining = ctx.actionTimeoutMsecs - elapsed
-          remainingMsecs = remaining > 0 ? remaining : 0
-        }
-        visualTimeout = {
-          msecs: timeout,
-          remainingMsecs: remainingMsecs ?? timeout
+          const remainingMsecs = remaining > 0 ? remaining : 0
+          visualTimeout = {
+            msecs: ctx.actionTimeoutMsecs,
+            remainingMsecs
+          }
+        } else if (timeout !== null) {
+          // Backward compatibility: if we have an explicit timeout, mirror it.
+          visualTimeout = { msecs: timeout, remainingMsecs: timeout }
         }
       }
     } catch (_e) {
@@ -438,8 +446,6 @@ class DisplayEventProcessor {
       renderMessage.timeout = timeout
     }
 
-    logger.debug(`Calculated a timeout of ${renderMessage.timeout} for ${participantId}`)
-
     // v5: send events as objects
     participantMachine.send({ type: 'RENDER_DISPLAY', ...renderMessage })
   }

package/lib/utils/FontAssetsUploader.js

@@ -19,7 +19,7 @@ class FontAssetsUploader {
       await fs.stat(this.fontsDirPath)
     } catch (e) {
       if (e.code === 'ENOENT') {
-        logger.info(`assets/fonts directory not found at ${this.fontsDirPath}. Skipping font upload.`)
+        logger.info(`[FontAssetsUploader] assets/fonts directory not found at ${this.fontsDirPath}. Skipping font upload.`)
         return null
       }
       throw e
@@ -29,7 +29,7 @@ class FontAssetsUploader {
     const filesToUpload = await collector.collectFiles()
 
     if (filesToUpload.length === 0) {
-      logger.info("No font files to upload.")
+      logger.info("[FontAssetsUploader] No font files to upload.")
       return null
     }
 
@@ -42,6 +42,7 @@ class FontAssetsUploader {
       }
 
       if (presignedUrls && presignedUrls.length > 0) {
+        logger.info(`[FontAssetsUploader] Uploading ${presignedUrls.length} font asset(s)`)
         await Promise.all(presignedUrls.map(async (uploadInfo) => {
           const { path: relativePath, 'presigned-url': presignedUrl } = uploadInfo
           const fileData = filesToUpload.find(file => file.path === relativePath)
@@ -55,7 +56,9 @@ class FontAssetsUploader {
             throw new Error(`File data not found for path: ${relativePath}`)
           }
         }))
+        logger.info(`[FontAssetsUploader] Font assets uploaded successfully`)
       } else {
+        logger.info(`[FontAssetsUploader] Font assets up to date`)
         logger.debug("No new or updated font files to upload.")
       }
 

package/lib/utils/ImageAssetsUploader.js

@@ -46,6 +46,7 @@ class ImageAssetsUploader {
 
       // Step 3: For each presigned URL, upload image file content to S3
       if (presignedUrls && presignedUrls.length > 0) {
+        logger.info(`[ImageAssetsUploader] Uploading ${presignedUrls.length} image asset(s)`)
         await Promise.all(presignedUrls.map(async (uploadInfo) => {
           const { path: filePath, 'presigned-url': presignedUrl } = uploadInfo
 
@@ -64,7 +65,9 @@ class ImageAssetsUploader {
             throw new Error(`File data not found for path: ${filePath}`)
           }
         }))
+        logger.info(`[ImageAssetsUploader] Image assets uploaded successfully`)
       } else {
+        logger.info(`[ImageAssetsUploader] Image assets up to date`)
         logger.debug('No files to upload; all files are up to date.')
       }
 

package/lib/utils/RealtimeMessaging.js

@@ -7,6 +7,42 @@ const AnearApi = require('../api/AnearApi')
 const DefaultHeartbeatIntervalMsecs = 15000
 const NotableChannelEvents = ['attached', 'suspended', 'failed']
 
+/**
+ * Extracts a short channel name abbreviation from the full channel name
+ * @param {string} channelName - Full channel name (e.g., "anear:appId:e:eventId:actions")
+ * @returns {string} - Short abbreviation (e.g., "actions", "private", "participants", "spectators", "events")
+ */
+function getChannelShortName(channelName) {
+  if (!channelName) return 'unknown'
+
+  // Pattern: anear:appId:e:eventId:actions → actions
+  // Pattern: anear:appId:e:eventId:private:participantId → private
+  // Pattern: anear:appId:e:eventId:participants → participants
+  // Pattern: anear:appId:e:eventId:spectators → spectators
+  // Pattern: anear:appId:e → events
+
+  const parts = channelName.split(':')
+
+  // Check for event-scoped channels (anear:appId:e:eventId:...)
+  if (parts.length >= 4 && parts[2] === 'e') {
+    if (parts.length === 5) {
+      // anear:appId:e:eventId:channelType
+      return parts[4] // actions, participants, spectators
+    } else if (parts.length === 6 && parts[4] === 'private') {
+      // anear:appId:e:eventId:private:participantId
+      return 'private'
+    }
+  }
+
+  // Check for event creation channel (anear:appId:e)
+  if (parts.length === 3 && parts[2] === 'e') {
+    return 'events'
+  }
+
+  // Fallback: return last part or full name if pattern doesn't match
+  return parts[parts.length - 1] || channelName
+}
+
 class RealtimeMessaging {
   constructor() {
     this.ablyRealtime = null
@@ -160,7 +196,9 @@ class RealtimeMessaging {
           // Actions reference event.data to get at participantId, etc
           const { data } = message // ably presence event message from browser contains message.data.id
           const type = data.type ? data.type : 'NONE'
-          logger.debug(`[RTM] rcvd presence ${eventName}, type: ${type} from ${data.id} on ${channel.name}`)
+          const channelShortName = getChannelShortName(channel.name)
+          const channelLabel = channelShortName === 'actions' ? 'actions:presence' : channelShortName
+          logger.info(`[RTM] received presence ${eventName} participantId=${data.id} on channel ${channelLabel}`)
           actor.send({ type: eventName, data })
         }
       )
@@ -183,13 +221,18 @@ class RealtimeMessaging {
   }
 
   async publish(channel, msgType, message) {
+    const participantId = message?.data?.participantId || message?.participantId || null
+    const participantIdStr = participantId ? ` participantId=${participantId}` : ''
+    const channelShortName = getChannelShortName(channel.name)
+    logger.info(`[RTM] publishing ${msgType}${participantIdStr} on channel ${channelShortName}`)
     return channel.publish(msgType, message)
   }
 
   async setPresence(channel, data) {
     try {
       await channel.presence.enter(data)
-      logger.debug(`[RTM] presence.enter on ${channel.name} with`, data)
+      const channelShortName = getChannelShortName(channel.name)
+      logger.info(`[RTM] presence.enter participantId=${data.id} on channel ${channelShortName}`)
     } catch (e) {
       logger.warn(`[RTM] presence.enter failed on ${channel.name}`, e)
     }
@@ -223,7 +266,10 @@ class RealtimeMessaging {
     if (eventName) args.push(eventName)
     args.push(
       message => {
-        logger.debug(`message rcvd on channel ${channel.name}.  sending ${message.name}`)
+        const participantId = message.data?.participantId || null
+        const participantIdStr = participantId ? ` participantId=${participantId}` : ''
+        const channelShortName = getChannelShortName(channel.name)
+        logger.info(`[RTM] received message ${message.name}${participantIdStr} on channel ${channelShortName}`)
         actor.send({ type: message.name, data: message.data })
       }
     )

package/package.json

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