anear-js-api 1.5.1 → 1.6.1

package/lib/state_machines/AnearEventMachine.js

@@ -134,6 +134,7 @@ const getPresenceEventName = (participant, presenceAction) => {
 };
 
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
+const EventStats = require('../utils/EventStats')
 const AppMachineTransition = require('../utils/AppMachineTransition')
 const DisplayEventProcessor = require('../utils/DisplayEventProcessor')
 const PugHelpers = require('../utils/PugHelpers')
@@ -144,6 +145,34 @@ const AnearParticipant = require('../models/AnearParticipant')
 
 const CurrentDateTimestamp = _ => new Date().getTime()
 
+// Event stats: AEM-only, for metering. Never passed to AppM. Shape matches persisted event_stats.
+// event channel: we publish and may receive → publishCount, bytesPublished, receivedCount, bytesReceived.
+// actions channel: we receive ACTIONS from clients → receivedCount, bytesReceived.
+// Other channels: we publish only → publishCount, bytesPublished.
+const CHANNEL_NAMES_PUBLISH_ONLY = ['participants', 'spectators', 'private']
+function createInitialEventStats() {
+  const channels = {}
+  CHANNEL_NAMES_PUBLISH_ONLY.forEach(name => {
+    channels[name] = { publishCount: 0, bytesPublished: 0 }
+  })
+  channels.event = { publishCount: 0, bytesPublished: 0, receivedCount: 0, bytesReceived: 0 }
+  channels.actions = { receivedCount: 0, bytesReceived: 0 }
+  return {
+    liveDurationMs: 0,
+    liveStartedAt: null,
+    channels
+  }
+}
+
+// Serializable snapshot for persistence (omit liveStartedAt).
+function serializeEventStats(eventStats) {
+  if (!eventStats || !eventStats.channels) return null
+  return {
+    liveDurationMs: eventStats.liveDurationMs ?? 0,
+    channels: { ...eventStats.channels }
+  }
+}
+
 const AnearEventMachineContext = (
   anearEvent,
   coreServiceMachine,
@@ -174,7 +203,8 @@ const AnearEventMachineContext = (
   pendingCancelConfirmations: null,  // Set of participantIds waiting for TIMER_CANCELED confirmation
   pendingCancelAction: null,  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
   consecutiveTimeoutCount: 0,  // Global counter tracking consecutive timeouts across all participants for dead-man switch
-  consecutiveAllParticipantsTimeoutCount: 0  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
+  consecutiveAllParticipantsTimeoutCount: 0,  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
+  eventStats: null  // Set on createAppEventMachine onDone (initial or rehydrated); createInitialEventStats() shape
 })
 
 const ActiveEventGlobalEvents = {
@@ -189,11 +219,12 @@ const ActiveEventGlobalEvents = {
   CLOSE: {
     // AppM has reached a final state or explicitly called closeEvent()
     // initiate orderly shutdown
+    actions: ['addLiveDurationSegment'],
     target: '#activeEvent.closeEvent'
   },
   CANCEL: {
     // appM does an abrupt shutdown of the event
-    actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} CANCEL received`),
+    actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} CANCEL received`)],
     target: '#canceled'
   },
   APPM_FINAL: {
@@ -341,7 +372,7 @@ const ActiveEventStatesConfig = {
           id: 'waitingAnnounce',
           after: {
             timeoutEventAnnounce: {
-              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for ANNOUNCE`),
+              actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for ANNOUNCE`)],
               target: '#canceled'
             }
           },
@@ -350,12 +381,15 @@ const ActiveEventStatesConfig = {
               target: '#activeEvent.announce'
             },
             START: {
+              actions: ['startLiveDuration'],
               target: '#activeEvent.live'
             },
             PAUSE: {
+              actions: ['addLiveDurationSegment'],
               target: '#pausingEvent'
             },
             SAVE: {
+              actions: ['addLiveDurationSegment'],
               target: 'savingAppEventContext'
             }
           }
@@ -528,13 +562,13 @@ const ActiveEventStatesConfig = {
           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`),
+              actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for START`)],
               target: '#canceled'
             }
           },
           on: {
             START: {
-              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} announce → live`),
+              actions: ['startLiveDuration', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} announce → live`)],
               target: '#activeEvent.live'
             }
           }
@@ -902,25 +936,15 @@ const ActiveEventStatesConfig = {
     closeEvent: {
       id: 'closeEvent',
       entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} live → closed`),
-      initial: 'savingContextMaybe',
+      initial: 'savingAppEventContext',
       on: {
         APPM_FINAL: {
           actions: () => logger.debug('[AEM] Ignoring APPM_FINAL during closeEvent.')
         }
       },
       states: {
-        savingContextMaybe: {
-          always: [
-            {
-              guard: ({ event }) => {
-                const c = event?.appmContext?.context
-                return !!(c && typeof c === 'object')
-              },
-              target: 'savingAppEventContext'
-            },
-            { target: 'notifyingParticipants' }
-          ]
-        },
+        // Always persist event_stats on close (with full or empty app context).
+        // saveAppEventContext includes event_stats; appmContext may be {} or { context, resumeEvent }.
         savingAppEventContext: {
           invoke: {
             src: 'saveAppEventContext',
@@ -1428,6 +1452,26 @@ const AnearEventMachineFunctions = ({
       },
       appMachineTransition: ({ event }) => {
         return event?.output?.appMachineTransition ?? event?.data?.appMachineTransition ?? null
+      },
+      eventStats: ({ event, context }) => {
+        const fromOutput = event?.output?.eventStats ?? event?.data?.eventStats
+        return fromOutput ?? context.eventStats ?? createInitialEventStats()
+      }
+    }),
+    startLiveDuration: assign({
+      eventStats: ({ context }) => {
+        const s = context.eventStats
+        if (!s || !s.channels) return s
+        return { ...s, liveStartedAt: Date.now() }
+      }
+    }),
+    addLiveDurationSegment: assign({
+      eventStats: ({ context }) => {
+        const s = context.eventStats
+        if (!s || !s.channels) return s
+        const now = Date.now()
+        const add = (s.liveStartedAt != null) ? (now - s.liveStartedAt) : 0
+        return { ...s, liveDurationMs: (s.liveDurationMs || 0) + add, liveStartedAt: null }
       }
     }),
     notifyAppMachineRendered: ({ context }) => {
@@ -1486,13 +1530,21 @@ const AnearEventMachineFunctions = ({
       )
     },
     subscribeToActionMessages: ({ context, self }) => {
-      RealtimeMessaging.subscribe(
-        context.actionsChannel,
-        self,
-        'ACTION'
-      )
+      RealtimeMessaging.subscribe(context.actionsChannel, self, 'ACTION', {
+        onMessage: (message, actor) => {
+          const ctx = actor.getSnapshot().context
+          EventStats.recordReceived(ctx.eventStats, ctx.actionsChannel, message.data)
+        }
+      })
+    },
+    subscribeToEventMessages: ({ context, self }) => {
+      RealtimeMessaging.subscribe(context.eventChannel, self, null, {
+        onMessage: (message, actor) => {
+          const ctx = actor.getSnapshot().context
+          EventStats.recordReceived(ctx.eventStats, ctx.eventChannel, message.data)
+        }
+      })
     },
-    subscribeToEventMessages: ({ context, self }) => RealtimeMessaging.subscribe(context.eventChannel, self),
     createParticipantsDisplayChannel: assign({
       participantsDisplayChannel: ({ context, self }) => RealtimeMessaging.getChannel(
         context.anearEvent.participantsChannelName,
@@ -2281,14 +2333,17 @@ const AnearEventMachineFunctions = ({
   actors: {
     saveAppEventContext: fromPromise(async ({ input }) => {
       const { context, event } = input
-      // Events like PAUSE/SAVE are sent as send('PAUSE', { appmContext: {...} })
-      // event.appmContext -> { context, resumeEvent }
+      // PAUSE/SAVE/CLOSE may include appmContext: { context, resumeEvent }
+      // Always include event_stats when present (AEM flushes metering on every save)
       const appmContext = event?.appmContext || {}
       const payload = {
         eventId: context.anearEvent.id,
         savedAt: new Date().toISOString(),
         ...appmContext
       }
+      if (context.eventStats) {
+        payload.event_stats = serializeEventStats(context.eventStats)
+      }
       await AnearApi.saveAppEventContext(context.anearEvent.id, payload)
       return 'done'
     }),
@@ -2306,6 +2361,7 @@ const AnearEventMachineFunctions = ({
       let machineToStart = baseMachine
       let actorInput = undefined
       let resumeEvent = null
+      let eventStats = createInitialEventStats()
 
       if (context.rehydrate) {
         try {
@@ -2318,6 +2374,35 @@ const AnearEventMachineFunctions = ({
               // (AppM machine config should define `context: ({ input }) => ...`).
               actorInput = savedContext
             }
+            // AEM-only: restore event_stats for metering; never pass to AppM
+            if (appmContext.event_stats && typeof appmContext.event_stats === 'object') {
+              const raw = appmContext.event_stats
+              eventStats = {
+                liveDurationMs: typeof raw.liveDurationMs === 'number' ? raw.liveDurationMs : 0,
+                liveStartedAt: null,
+                channels: { ...createInitialEventStats().channels }
+              }
+              if (raw.channels && typeof raw.channels === 'object') {
+                Object.keys(raw.channels).forEach(key => {
+                  const c = raw.channels[key]
+                  if (!c) return
+                  if (key === 'actions' && typeof c.receivedCount === 'number' && typeof c.bytesReceived === 'number') {
+                    eventStats.channels[key] = { receivedCount: c.receivedCount, bytesReceived: c.bytesReceived }
+                  } else if (key === 'event') {
+                    const pub = typeof c.publishCount === 'number' && typeof c.bytesPublished === 'number'
+                    const rec = typeof c.receivedCount === 'number' && typeof c.bytesReceived === 'number'
+                    eventStats.channels[key] = {
+                      publishCount: pub ? c.publishCount : 0,
+                      bytesPublished: pub ? c.bytesPublished : 0,
+                      receivedCount: rec ? c.receivedCount : 0,
+                      bytesReceived: rec ? c.bytesReceived : 0
+                    }
+                  } else if (typeof c.publishCount === 'number' && typeof c.bytesPublished === 'number') {
+                    eventStats.channels[key] = { publishCount: c.publishCount, bytesPublished: c.bytesPublished }
+                  }
+                })
+              }
+            }
           }
         } catch (e) {
           // Log and proceed without rehydration
@@ -2335,9 +2420,11 @@ const AnearEventMachineFunctions = ({
       }
 
       // Observe AppM transitions with full event payloads.
-      // v5 note: `subscribe()` only provides snapshots, which often do not include
-      // the triggering event. We use `inspect` so AppMachineTransition always gets
-      // (snapshot, event) for meta.eachParticipant(ctx, event) and timeout payloads.
+      // inspect() is the v5 replacement for v4 onTransition for meta/view and RENDER_DISPLAY:
+      // - @xstate.snapshot: run when the AppM produces a new snapshot (typical state transitions).
+      // - @xstate.event: we defer a run for every event so internal/no-op transitions and
+      //   presence events (REFRESH_EVENT_TYPES) that may not emit a snapshot still trigger
+      //   meta scan; if a snapshot arrives for the same event, we skip the deferred run.
       const appMachineTransition = AppMachineTransition(context.anearEvent)
 
       const REFRESH_EVENT_TYPES = AppMachineTransition.REFRESH_EVENT_TYPES
@@ -2348,8 +2435,8 @@ const AnearEventMachineFunctions = ({
           : (fn) => Promise.resolve().then(fn)
 
       let appActor
-      let lastRefreshEvent = null
-      let lastRefreshHandledBySnapshot = false
+      let lastDeferredEvent = null
+      let lastDeferredHandledBySnapshot = false
       let sawAnySnapshot = false
 
       const inspect = (inspectionEvent) => {
@@ -2373,16 +2460,16 @@ const AnearEventMachineFunctions = ({
             // logging should never interrupt state processing
           }
           try {
-            appMachineTransition(snapshot, event)
+            appMachineTransition(snapshot, event, { source: 'inspect.snapshot' })
           } catch (e) {
             logger.warn('[AEM] AppMachineTransition failed during inspect snapshot', e)
           }
 
-          // If we deferred a "refresh render" for this exact event, mark it as handled
-          // so the fallback won't run and double-render.
-          if (event && lastRefreshEvent && event === lastRefreshEvent) {
-            lastRefreshHandledBySnapshot = true
-            logger.debug('[AEM][inspect] refresh event handled by snapshot (suppress fallback)', {
+          // If we deferred a run for this exact event, mark it as handled so the
+          // event_deferred callback won't run and double-invoke AppMachineTransition.
+          if (event && lastDeferredEvent && event === lastDeferredEvent) {
+            lastDeferredHandledBySnapshot = true
+            logger.debug('[AEM][inspect] event handled by snapshot (suppress event_deferred)', {
               eventType: event?.type,
               participantId: event?.participantId
             })
@@ -2393,9 +2480,13 @@ const AnearEventMachineFunctions = ({
           const ev = inspectionEvent.event
           if (!ev || !ev.type) return
 
-          // Some presence refresh events are internal/no-op transitions, which may not
-          // produce a snapshot update. Defer a refresh render and cancel it if a
-          // snapshot update for the same event happens in the same tick.
+          // Run transition callback for every event (internal and external). Defer so that
+          // if a snapshot is emitted for this event in the same tick, we use that path and
+          // skip this deferred run to avoid double-render; dedupe in AppMachineTransition
+          // handles any remaining redundancy.
+          lastDeferredEvent = ev
+          lastDeferredHandledBySnapshot = false
+
           if (REFRESH_EVENT_TYPES.has(ev.type)) {
             try {
               logger.debug('[AEM][inspect] @xstate.event (refresh candidate)', {
@@ -2406,25 +2497,23 @@ const AnearEventMachineFunctions = ({
             } catch (_e) {
               // logging should never interrupt state processing
             }
-            lastRefreshEvent = ev
-            lastRefreshHandledBySnapshot = false
+          }
 
-            defer(() => {
-              if (!appActor) return
-              if (lastRefreshEvent !== ev) return
-              if (lastRefreshHandledBySnapshot) return
+          defer(() => {
+            if (!appActor) return
+            if (lastDeferredEvent !== ev) return
+            if (lastDeferredHandledBySnapshot) return
 
-              logger.debug('[AEM][inspect] refresh fallback firing (no snapshot update)', {
-                eventType: ev?.type,
-                participantId: ev?.participantId
-              })
-              try {
-                appMachineTransition(appActor.getSnapshot(), ev)
-              } catch (e) {
-                logger.warn('[AEM] AppMachineTransition failed during inspect refresh fallback', e)
-              }
+            logger.debug('[AEM][inspect] event_deferred firing (no snapshot for this event)', {
+              eventType: ev?.type,
+              participantId: ev?.participantId
             })
-          }
+            try {
+              appMachineTransition(appActor.getSnapshot(), ev, { source: 'inspect.event_deferred' })
+            } catch (e) {
+              logger.warn('[AEM] AppMachineTransition failed during inspect event_deferred', e)
+            }
+          })
         }
       }
 
@@ -2441,7 +2530,7 @@ const AnearEventMachineFunctions = ({
         if (sawAnySnapshot) return
         try {
           logger.debug('[AEM][inspect] init snapshot fallback (no @xstate.snapshot observed yet)')
-          appMachineTransition(appActor.getSnapshot(), { type: 'xstate.init' })
+          appMachineTransition(appActor.getSnapshot(), { type: 'xstate.init' }, { source: 'inspect.init_fallback' })
         } catch (e) {
           logger.warn('[AEM] AppMachineTransition failed on initial snapshot fallback', e)
         }
@@ -2460,7 +2549,7 @@ const AnearEventMachineFunctions = ({
         appActor.send(resumeEvent)
       }
 
-      return { service: appActor, appMachineTransition }
+      return { service: appActor, appMachineTransition, eventStats }
     }),
     renderDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
@@ -2537,6 +2626,7 @@ const AnearEventMachineFunctions = ({
       // without terminating the event or detaching channels.
       await AnearApi.transitionEvent(context.anearEvent.id, 'restart')
 
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'announce' } })
       const publishPromise = RealtimeMessaging.publish(
         context.eventChannel,
         'EVENT_TRANSITION',
@@ -2559,6 +2649,7 @@ const AnearEventMachineFunctions = ({
       // Transition the event to 'live' via ANAPI and publish an EVENT_TRANSITION
       // message so ABRs can react immediately (e.g., auto-close expanded QR).
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'live')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'live' } })
       const publishPromise = RealtimeMessaging.publish(
         context.eventChannel,
         'EVENT_TRANSITION',
@@ -2575,16 +2666,23 @@ const AnearEventMachineFunctions = ({
       // and the publishing of the 'EVENT_TRANSITION' message to ABRs.
       // It's a promise that resolves when both operations are complete.
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'closed')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'closed' } })
       const publishPromise = RealtimeMessaging.publish(context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'closed' } })
       await Promise.all([transitionPromise, publishPromise])
       return 'done' // Indicate completion
     }),
     eventTransitionCanceled: fromPromise(async ({ input }) => {
       const { context } = input
-      // This service handles the transition of the event to 'canceled' via AnearApi
-      // and the publishing of the 'EVENT_TRANSITION' message to ABRs.
-      // It's a promise that resolves when both operations are complete.
+      // Persist event_stats once on cancel (no app context to save).
+      const statsPayload = context.eventStats
+        ? { eventId: context.anearEvent.id, savedAt: new Date().toISOString(), event_stats: serializeEventStats(context.eventStats) }
+        : null
+      if (statsPayload) {
+        await AnearApi.saveAppEventContext(context.anearEvent.id, statsPayload)
+      }
+      // Transition the event to 'canceled' via AnearApi and publish EVENT_TRANSITION to ABRs.
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'canceled')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'canceled' } })
       const publishPromise = RealtimeMessaging.publish(context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'canceled' } })
       await Promise.all([transitionPromise, publishPromise])
       return 'done' // Indicate completion

package/lib/state_machines/AnearParticipantMachine.js

@@ -99,10 +99,11 @@ const { assign, createMachine, createActor, fromPromise } = require('xstate')
 const C = require('../utils/Constants')
 
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
+const EventStats = require('../utils/EventStats')
 
 const CurrentDateTimestamp = _ => new Date().getTime()
 
-const AnearParticipantMachineContext = (anearParticipant, anearEvent, appParticipantMachineFactory) => ({
+const AnearParticipantMachineContext = (anearParticipant, anearEvent, appParticipantMachineFactory, eventStats = null) => ({
   anearEvent,
   anearParticipant,
   privateChannel: null,
@@ -117,7 +118,8 @@ const AnearParticipantMachineContext = (anearParticipant, anearEvent, appPartici
   // would be dropped (no handler in that state). We keep the latest and flush it
   // immediately after the current publish completes.
   queuedRenderDisplay: null,
-  lastSeen: CurrentDateTimestamp()
+  lastSeen: CurrentDateTimestamp(),
+  eventStats // AEM-only metering; optional for EventStats.recordPublish before publish
 })
 
 const AnearParticipantMachineConfig = participantId => ({
@@ -253,9 +255,19 @@ const AnearParticipantMachineConfig = participantId => ({
               on: {
                 // Buffer the latest render request if we are currently publishing.
                 // (Otherwise, RENDER_DISPLAY is unhandled in this state and gets dropped.)
-                RENDER_DISPLAY: {
-                  actions: 'queueRenderDisplay'
-                },
+                RENDER_DISPLAY: [
+                  {
+                    // If a display arrives while we're already publishing another display,
+                    // it's safe to buffer *visual-only* refreshes (no timeout). However,
+                    // buffering timed prompts can create timer/UI mismatches and indicates
+                    // an AppM/AEM sequencing bug.
+                    guard: 'incomingRenderHasTimeout',
+                    actions: 'logBlockedRenderDuringPublish'
+                  },
+                  {
+                    actions: 'queueRenderDisplay'
+                  }
+                ],
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
                   target: '#cleanupAndExit'
@@ -281,14 +293,12 @@ const AnearParticipantMachineConfig = participantId => ({
               initial: 'waiting',
               states: {
                 waiting: {
-                  // The actual waiting state. RENDER_DISPLAY is blocked here
-                  // to prevent timer conflicts. AppM must cancel timers first.
+                  // Actual waiting state. RENDER_DISPLAY (including refreshes with timeout) is
+                  // allowed; updateActionTimeoutIfChanged / timer logic handles stop/reset.
                 },
                 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.
+                  // Refreshes (e.g. PARTICIPANT_DISCONNECT/RECONNECT) are processed here while
+                  // the parent's `after: actionTimeout` timer continues running.
                   invoke: {
                     src: 'publishPrivateDisplay',
                     input: ({ context, event }) => ({ context, event }),
@@ -315,22 +325,10 @@ const AnearParticipantMachineConfig = participantId => ({
                 }
               },
               on: {
-                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'
-                  }
-                ],
+                // Allow all RENDER_DISPLAY (refreshes, timeouts). Timer logic stops/resets as needed.
+                RENDER_DISPLAY: {
+                  target: '.rendering'
+                },
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
                   target: '#cleanupAndExit'
@@ -622,19 +620,13 @@ const AnearParticipantMachineFunctions = {
     logIgnoringActionCleanup: () => logger.debug('[APM] ignoring ACTION during cleanup'),
     logIgnoringRenderDisplayDone: () => logger.debug('[APM] ignoring RENDER_DISPLAY in final state'),
     logIgnoringEventDone: ({ event }) => logger.debug('[APM] ignoring event in final state: ', event.type),
-    logBlockedRenderDuringWait: ({ context, event }) => {
-      const eventType = event?.type ?? 'RENDER_DISPLAY'
+    logBlockedRenderDuringPublish: ({ context, event }) => {
+      const participantId = context?.anearParticipant?.id
       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.`)
+      logger.error(
+        `[APM] ⚠️  BLOCKED: RENDER_DISPLAY (timeout=${timeout}ms) received while already publishing PRIVATE_DISPLAY for participant ${participantId}. ` +
+        `This indicates an AppM/AEM sequencing bug (timed prompts must not overlap in publish).`,
+      )
     }
     ,
     queueRenderDisplay: assign(({ context, event }) => {
@@ -663,6 +655,7 @@ const AnearParticipantMachineFunctions = {
     publishPrivateDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
       const displayMessage = { content: event.content }
+      EventStats.recordPublish(context.eventStats, context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       await RealtimeMessaging.publish(context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       return { timeout: event.timeout }
     }),
@@ -674,6 +667,7 @@ const AnearParticipantMachineFunctions = {
           reason: reason || 'You have been removed from the event.'
         }
       }
+      EventStats.recordPublish(context.eventStats, context.privateChannel, 'FORCE_SHUTDOWN', payload)
       await RealtimeMessaging.publish(context.privateChannel, 'FORCE_SHUTDOWN', payload)
       return 'done'
     }),
@@ -724,7 +718,7 @@ const AnearParticipantMachineFunctions = {
 //   4. handles activity state, response timeouts, idle state
 //   5. receives ACTION events relayed by the AnearEventMachine
 //   6. relays all relevant events to the participant XState Machine for Application-specific handling
-const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantMachineFactory }) => {
+const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantMachineFactory, eventStats }) => {
   const anearParticipantMachine = createMachine(
     {
       ...AnearParticipantMachineConfig(anearParticipant.id),
@@ -737,7 +731,8 @@ const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantM
   const anearParticipantMachineContext = AnearParticipantMachineContext(
     anearParticipant,
     anearEvent,
-    appParticipantMachineFactory
+    appParticipantMachineFactory,
+    eventStats
   )
 
   const actor = createActor(anearParticipantMachine, { input: anearParticipantMachineContext })

package/lib/utils/AppMachineTransition.js

@@ -5,6 +5,9 @@ const RenderContextBuilder = require('./RenderContextBuilder')
 
 // Events that should force a "refresh render" even if the AppM did not
 // transition (no-op/internal transitions, presence refreshes, etc.).
+// These are presence-related events the AEM forwards to the AppM; they may not
+// produce an @xstate.snapshot (no-op on AppM), so the inspect event_deferred
+// path in AnearEventMachine ensures meta is still scanned and RENDER_DISPLAY can run.
 const REFRESH_EVENT_TYPES = new Set([
   'SPECTATOR_ENTER',
   'PARTICIPANT_ENTER',
@@ -62,6 +65,15 @@ const _safeSignatureStringify = (value) => {
  *  - Display events are content-only.
  *  - Emits displayEvents → sends to AnearEventMachine for rendering.
  */
+const VIEW_META_KEYS = ['allParticipants', 'eachParticipant', 'host', 'spectators']
+
+const _hasViewMeta = (metaObjects) => {
+  if (!metaObjects || metaObjects.length === 0) return false
+  return metaObjects.some(meta =>
+    VIEW_META_KEYS.some(key => meta && meta[key] !== undefined && meta[key] !== null)
+  )
+}
+
 const AppMachineTransition = (anearEvent) => {
   // v5 strategy:
   // - Render meta "once per stable meta state" (dedupe by state+meta+context)
@@ -69,8 +81,9 @@ const AppMachineTransition = (anearEvent) => {
   // - Never re-render on the RENDERED ack (prevents ping-pong loops)
   let lastBaseSignature = null
 
-  return (appEventMachineState, triggeringEvent = null) => {
-    // Handle potential XState version differences and missing properties
+  return (appEventMachineState, triggeringEvent = null, invocationContext = {}) => {
+    // Handle potential XState version differences and missing properties.
+    // In XState v5, getMeta() returns merged meta for the active state node (including parent states).
     const stateObj = appEventMachineState || {}
     const rawMeta = typeof stateObj.getMeta === 'function' ? stateObj.getMeta() : stateObj.meta
     const { context: appContext, value } = stateObj
@@ -83,197 +96,200 @@ const AppMachineTransition = (anearEvent) => {
           ? stateObj.event
           : { type: 'xstate.init' }
     const stateName = _stringifiedState(value)
-    const hasMeta = rawMeta && Object.keys(rawMeta).length > 0;
+    const source = invocationContext.source || 'unknown'
 
-    logger.info(`[AppMachineTransition] AppM state transition to '${stateName}' event=${event.type}`)
-    logger.debug(`[AppMachineTransition] Meta detected: ${hasMeta}`)
+    logger.info(`[AppMachineTransition] transition callback invoked stateName='${stateName}' event=${event.type} source=${source}`)
 
     // Handle unpredictable meta structure
     const metaObjects = rawMeta ? Object.values(rawMeta) : []
+    const hasViewMeta = _hasViewMeta(metaObjects)
+
+    if (!hasViewMeta) {
+      logger.debug(`[AppMachineTransition] no meta view in current state; skipping RENDER_DISPLAY`)
+      return
+    }
 
     // Check if AppM has reached a final state (handle different XState versions)
     const isDone = stateObj?.status === 'done' || stateObj?.done || stateObj?.value === 'done'
 
-    // Process meta FIRST (including exit displays) before sending CLOSE.
-    // Do not re-process meta on the RENDERED event from AEM to avoid an infinite loop.
-    if (metaObjects.length > 0 && event.type !== 'RENDERED') {
-      // Dedupe render emission:
-      // - By default, only render once per stable meta state (state+meta+context).
-      // - But if this was triggered by a refresh event (e.g. SPECTATOR_ENTER), allow
-      //   re-rendering even if the AppM state didn't change.
-      let baseSignature
-      try {
-        baseSignature = _safeSignatureStringify({ stateName, meta: rawMeta, context: appContext })
-      } catch (_e) {
-        baseSignature = `${stateName}|${rawMeta ? Object.keys(rawMeta).join(',') : ''}`
-      }
+    // Compute signature for dedupe. Re-examine on RENDERED but only send when signature changed.
+    let baseSignature
+    try {
+      baseSignature = _safeSignatureStringify({ stateName, meta: rawMeta, context: appContext })
+    } catch (_e) {
+      baseSignature = `${stateName}|${rawMeta ? Object.keys(rawMeta).join(',') : ''}`
+    }
 
+    if (event.type === 'RENDERED') {
+      // Re-examine meta on RENDERED; send RENDER_DISPLAY only when state/context actually changed.
+      if (baseSignature === lastBaseSignature) {
+        logger.debug(`[AppMachineTransition] RENDERED re-examination: no change, skipping RENDER_DISPLAY stateName='${stateName}'`)
+        return
+      }
+      lastBaseSignature = baseSignature
+    } else {
+      // Non-RENDERED: dedupe by default; refresh events (e.g. SPECTATOR_ENTER) may re-render even when stable.
       const isRefresh = REFRESH_EVENT_TYPES.has(event.type)
-      if (!isRefresh && baseSignature === lastBaseSignature) return
-
-      // Update the "last rendered" marker for stable-state dedupe. Even on refresh,
-      // we want to consider this state "rendered" so that later no-op snapshots
-      // (e.g. the RENDERED ack lacking event metadata) don't re-trigger rendering.
+      if (!isRefresh && baseSignature === lastBaseSignature) {
+        logger.debug(`[AppMachineTransition] meta view present; skipping RENDER_DISPLAY (dedupe, no change) stateName='${stateName}' event=${event.type}`)
+        return
+      }
       lastBaseSignature = baseSignature
+    }
 
-      // For refresh triggers, allow re-rendering even when stable.
-      // No additional dedupe needed; repeated presence events can legitimately re-render.
-      if (isRefresh) {
-        // fallthrough to rendering below
+    // Process meta and build display events (shared path for RENDERED with change and non-RENDERED).
+    const appStateName = _stringifiedState(value)
+    const isRefresh = event.type !== 'RENDERED' && REFRESH_EVENT_TYPES.has(event.type)
+
+    const displayEvents = []
+    let cancelActionType = null  // Track cancel property from meta configuration
+
+    // Process all meta objects to handle unpredictable AppM structures
+    metaObjects.forEach(meta => {
+      let viewer
+      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
       }
 
-      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 => {
-        let viewer
-        let timeoutFn
-        let displayEvent
+      // 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.`)
+        return // Skip processing this meta object
+      }
 
-        // 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
-        }
+      if (meta.allParticipants) {
+        viewer = 'allParticipants'
+        const { viewPath, props } = _extractViewAndProps(meta.allParticipants)
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.allParticipants.timeout)
 
-        // 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.`)
-          return // Skip processing this meta object
+        // Extract cancel property if present
+        if (meta.allParticipants.cancel && !cancelActionType) {
+          cancelActionType = meta.allParticipants.cancel
         }
 
-        if (meta.allParticipants) {
-          viewer = 'allParticipants'
-          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),
-            viewer,
-            null,
-            null,
-            props
-          )
-          displayEvents.push(displayEvent)
-        }
+        displayEvent = RenderContextBuilder.buildDisplayEvent(
+          viewPath,
+          RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+          viewer,
+          null,
+          null,
+          props
+        )
+        displayEvents.push(displayEvent)
+      }
 
-        if (meta.eachParticipant) {
-          // Check if participant is a function (new selective rendering format)
-          viewer = 'eachParticipant'
-          if (typeof meta.eachParticipant === 'function') {
-            // 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)
-
-            if (Array.isArray(participantDisplays)) {
-              // Build the base render context once and reuse it for all participant displays
-              // This avoids redundant context building when multiple participants receive different views
-              const baseAppRenderContext = RenderContextBuilder.buildAppRenderContext(
-                appContext,
-                appStateName,
-                event.type,
-                viewer,
-                null
-              )
-
-              participantDisplays.forEach(participantDisplay => {
-                if (participantDisplay && participantDisplay.participantId && participantDisplay.view) {
-                  // For selective rendering, timeout is handled directly in the participant display object
-                  const timeout = participantDisplay.timeout || null
-                  const props = participantDisplay.props || {}
-
-                  displayEvent = RenderContextBuilder.buildDisplayEvent(
-                    participantDisplay.view,
-                    baseAppRenderContext, // Reuse the same base context
-                    viewer,
-                    participantDisplay.participantId,
-                    timeout,
-                    props
-                  )
-                  displayEvents.push(displayEvent)
-                }
-              })
-            }
-          } else {
-            // Legacy participant rendering - normalize to selective format
-            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,
-              renderContext,
+      if (meta.eachParticipant) {
+        // Check if participant is a function (new selective rendering format)
+        viewer = 'eachParticipant'
+        if (typeof meta.eachParticipant === 'function') {
+          // 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)
+
+          if (Array.isArray(participantDisplays)) {
+            // Build the base render context once and reuse it for all participant displays
+            // This avoids redundant context building when multiple participants receive different views
+            const baseAppRenderContext = RenderContextBuilder.buildAppRenderContext(
+              appContext,
+              appStateName,
+              event.type,
               viewer,
-              'ALL_PARTICIPANTS', // Special marker for "all participants"
-              null,
-              props
+              null
             )
-            displayEvents.push(displayEvent)
-          }
-        }
 
-        if (meta.host) {
-          viewer = 'host'
-          const { viewPath, props } = _extractViewAndProps(meta.host)
-          timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.host.timeout)
+            participantDisplays.forEach(participantDisplay => {
+              if (participantDisplay && participantDisplay.participantId && participantDisplay.view) {
+                // For selective rendering, timeout is handled directly in the participant display object
+                const timeout = participantDisplay.timeout || null
+                const props = participantDisplay.props || {}
+
+                displayEvent = RenderContextBuilder.buildDisplayEvent(
+                  participantDisplay.view,
+                  baseAppRenderContext, // Reuse the same base context
+                  viewer,
+                  participantDisplay.participantId,
+                  timeout,
+                  props
+                )
+                displayEvents.push(displayEvent)
+              }
+            })
+          }
+        } else {
+          // Legacy participant rendering - normalize to selective format
+          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,
-            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            renderContext,
             viewer,
-            null,
+            'ALL_PARTICIPANTS', // Special marker for "all participants"
             null,
             props
           )
           displayEvents.push(displayEvent)
         }
+      }
 
-        if (meta.spectators) {
-          viewer = 'spectators'
-          const { viewPath, props } = _extractViewAndProps(meta.spectators)
-          timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.spectators.timeout)
+      if (meta.host) {
+        viewer = 'host'
+        const { viewPath, props } = _extractViewAndProps(meta.host)
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.host.timeout)
+
+        displayEvent = RenderContextBuilder.buildDisplayEvent(
+          viewPath,
+          RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+          viewer,
+          null,
+          null,
+          props
+        )
+        displayEvents.push(displayEvent)
+      }
 
-          displayEvent = RenderContextBuilder.buildDisplayEvent(
-            viewPath,
-            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
-            viewer,
-            null,
-            null,
-            props
-          )
-          displayEvents.push(displayEvent)
-        }
-      })
+      if (meta.spectators) {
+        viewer = 'spectators'
+        const { viewPath, props } = _extractViewAndProps(meta.spectators)
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.spectators.timeout)
+
+        displayEvent = RenderContextBuilder.buildDisplayEvent(
+          viewPath,
+          RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+          viewer,
+          null,
+          null,
+          props
+        )
+        displayEvents.push(displayEvent)
+      }
+    })
 
-      if (displayEvents.length > 0) {
-        logger.debug(`[AppMachineTransition] sending RENDER_DISPLAY with ${displayEvents.length} displayEvents`)
-        const renderDisplayPayload = {
-          type: 'RENDER_DISPLAY',
-          displayEvents
-        }
-        // Include cancel property only if defined
-        if (cancelActionType) {
-          renderDisplayPayload.cancelActionType = cancelActionType
-        }
-        anearEvent.send(renderDisplayPayload)
+    if (displayEvents.length > 0) {
+      logger.info(`[AppMachineTransition] sending RENDER_DISPLAY stateName='${stateName}' event=${event.type} isRefresh=${isRefresh} displayEventsCount=${displayEvents.length}`)
+      const renderDisplayPayload = {
+        type: 'RENDER_DISPLAY',
+        displayEvents
+      }
+      // Include cancel property only if defined
+      if (cancelActionType) {
+        renderDisplayPayload.cancelActionType = cancelActionType
       }
+      anearEvent.send(renderDisplayPayload)
     }
 
     // Note: When AppM reaches a final state, the service.onDone() callback

package/lib/utils/DisplayEventProcessor.js

@@ -40,6 +40,7 @@
 
 const logger = require('./Logger')
 const RealtimeMessaging = require('./RealtimeMessaging')
+const EventStats = require('./EventStats')
 const C = require('./Constants')
 
 class DisplayEventProcessor {
@@ -54,6 +55,7 @@ class DisplayEventProcessor {
     this.spectatorsDisplayChannel = anearEventMachineContext.spectatorsDisplayChannel
     this.participants = anearEventMachineContext.participants
     this.participantsIndex = this._buildParticipantsIndex(anearEventMachineContext.participants)
+    this.eventStats = anearEventMachineContext.eventStats ?? null
   }
 
   processAndPublish(displayEvents, cancelActionType = null) {
@@ -168,6 +170,7 @@ class DisplayEventProcessor {
           logger.debug(`[DisplayEventProcessor] no allParticipants timeout resolved`)
         }
 
+        EventStats.recordPublish(this.eventStats, this.participantsDisplayChannel, 'PARTICIPANTS_DISPLAY', formattedDisplayMessage())
         publishPromise = RealtimeMessaging.publish(
           this.participantsDisplayChannel,
           'PARTICIPANTS_DISPLAY',
@@ -211,11 +214,12 @@ class DisplayEventProcessor {
           logger.debug(`[DisplayEventProcessor] spectators visual timeout set to msecs=${specTimeout.msecs}, remaining=${specTimeout.remainingMsecs}`)
         }
 
+        EventStats.recordPublish(this.eventStats, this.spectatorsDisplayChannel, 'SPECTATORS_DISPLAY', formattedDisplayMessage())
         publishPromise = RealtimeMessaging.publish(
           this.spectatorsDisplayChannel,
-                  'SPECTATORS_DISPLAY',
-        formattedDisplayMessage()
-      )
+          'SPECTATORS_DISPLAY',
+          formattedDisplayMessage()
+        )
         break
 
       case 'eachParticipant':

package/lib/utils/EventStats.js

@@ -0,0 +1,119 @@
+"use strict"
+
+/**
+ * Event stats metering for realtime publishes. Invoke recordPublish before each
+ * RealtimeMessaging.publish so the event's stats (per-channel publish count and
+ * bytes) are updated. RealtimeMessaging does not know about event stats.
+ */
+
+/**
+ * Extracts a short channel name from the full channel name (same mapping as RTM).
+ * @param {string} channelName - Full channel name (e.g. "anear:appId:e:eventId:actions")
+ * @returns {string} - Short key (e.g. "actions", "private", "participants", "spectators", "event")
+ */
+function getChannelShortName(channelName) {
+  if (!channelName) return 'unknown'
+
+  const parts = channelName.split(':')
+
+  if (parts.length >= 4 && parts[2] === 'e') {
+    if (parts.length === 5) return parts[4]
+    if (parts.length === 6 && parts[4] === 'private') return 'private'
+  }
+
+  if (parts.length === 3 && parts[2] === 'e') return 'events'
+
+  return parts[parts.length - 1] || channelName
+}
+
+const ACTIONS_CHANNEL_KEY = 'actions'
+const EVENT_CHANNEL_KEY = 'event'
+
+/**
+ * Default shape for a channel that receives messages (e.g. actions channel).
+ * Server receives ACTIONS from clients on the actions channel; we track receivedCount/bytesReceived.
+ */
+function defaultReceivedChannelShape() {
+  return { receivedCount: 0, bytesReceived: 0 }
+}
+
+/**
+ * Default shape for a channel we publish to (participants, spectators, private).
+ */
+function defaultPublishChannelShape() {
+  return { publishCount: 0, bytesPublished: 0 }
+}
+
+/**
+ * Default shape for a channel that both publishes and receives (e.g. event channel).
+ */
+function defaultDualChannelShape() {
+  return { publishCount: 0, bytesPublished: 0, receivedCount: 0, bytesReceived: 0 }
+}
+
+/**
+ * Record one publish for event stats. Call before RealtimeMessaging.publish.
+ * No-op if eventStats is null/undefined or missing channels.
+ * Not used for the actions channel (server does not publish to actions).
+ *
+ * @param {{ channels: Record<string, { publishCount: number, bytesPublished: number } | { receivedCount: number, bytesReceived: number }> } | null | undefined} eventStats - AEM context.eventStats
+ * @param {{ name: string } | string} channel - Ably channel (with .name) or channel name string
+ * @param {string} msgType - Message type (for consistency; bytes are from message payload)
+ * @param {object} message - The message object being published (stringified for byte count)
+ */
+function recordPublish(eventStats, channel, msgType, message) {
+  if (!eventStats || !eventStats.channels || typeof eventStats.channels !== 'object') return
+
+  const channelName = typeof channel === 'string' ? channel : (channel && channel.name)
+  const shortName = getChannelShortName(channelName)
+
+  if (!eventStats.channels[shortName]) {
+    eventStats.channels[shortName] = shortName === EVENT_CHANNEL_KEY ? defaultDualChannelShape() : defaultPublishChannelShape()
+  }
+  const ch = eventStats.channels[shortName]
+  if ('publishCount' in ch && 'bytesPublished' in ch) {
+    ch.publishCount += 1
+    const payload = typeof message === 'string' ? message : JSON.stringify(message)
+    const bytes = typeof Buffer !== 'undefined' ? Buffer.byteLength(payload, 'utf8') : new TextEncoder().encode(payload).length
+    ch.bytesPublished += bytes
+  }
+}
+
+/**
+ * Record one received message on a channel. Used for actions channel (ACTION from clients) and
+ * event channel (any message received on the event channel). No-op if eventStats is null/undefined.
+ *
+ * @param {{ channels: Record<string, object> } | null | undefined} eventStats - AEM context.eventStats
+ * @param {{ name: string } | string} channel - Ably channel (or channel short name)
+ * @param {object} message - The received message payload (e.g. event.data or message.data)
+ */
+function recordReceived(eventStats, channel, message) {
+  if (!eventStats || !eventStats.channels || typeof eventStats.channels !== 'object') return
+
+  const channelName = typeof channel === 'string' ? channel : (channel && channel.name)
+  const shortName = getChannelShortName(channelName)
+  // Only actions and event channels track receives (event can have both publish and receive).
+  if (shortName !== ACTIONS_CHANNEL_KEY && shortName !== EVENT_CHANNEL_KEY) return
+
+  if (!eventStats.channels[shortName]) {
+    eventStats.channels[shortName] = shortName === EVENT_CHANNEL_KEY ? defaultDualChannelShape() : defaultReceivedChannelShape()
+  }
+  const ch = eventStats.channels[shortName]
+  if (!('receivedCount' in ch)) ch.receivedCount = 0
+  if (!('bytesReceived' in ch)) ch.bytesReceived = 0
+  ch.receivedCount += 1
+  const payload = typeof message === 'string' ? message : JSON.stringify(message)
+  const bytes = typeof Buffer !== 'undefined' ? Buffer.byteLength(payload, 'utf8') : new TextEncoder().encode(payload).length
+  ch.bytesReceived += bytes
+}
+
+module.exports = {
+  ACTIONS_CHANNEL_KEY,
+  EVENT_CHANNEL_KEY,
+  getChannelShortName,
+  recordPublish,
+  recordReceived,
+  defaultReceivedChannelShape,
+  defaultPublishChannelShape,
+  defaultDualChannelShape
+}

package/lib/utils/RealtimeMessaging.js

@@ -255,17 +255,26 @@ class RealtimeMessaging {
     await Promise.all(detachPromises)
   }
 
-  subscribe(channel, actor, eventName = null) {
+  /**
+   * @param {Channel} channel
+   * @param {Actor} actor
+   * @param {string | null} eventName - If set, only subscribe to this message name
+   * @param {{ onMessage?: (message: object, actor: Actor) => void }} [options] - Optional; onMessage(message, actor) is called before forwarding to actor (e.g. for receive stats)
+   */
+  subscribe(channel, actor, eventName = null, options = null) {
     // Note: subscribing to an Ably channel will implicitly attach()
     const key = `${actor.id}::${channel.name}::subscribe::${eventName || '*'}`
     if (this._messageListenerKeys.has(key)) return
     this._messageListenerKeys.add(key)
 
+    const onMessage = options?.onMessage
+
     const args = []
 
     if (eventName) args.push(eventName)
     args.push(
       message => {
+        if (typeof onMessage === 'function') onMessage(message, actor)
         const participantId = message.data?.participantId || null
         const participantIdStr = participantId ? ` participantId=${participantId}` : ''
         const channelShortName = getChannelShortName(channel.name)

package/package.json

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