anear-js-api 1.1.5 → 1.1.6

package/lib/state_machines/AnearEventMachine.js

@@ -1312,18 +1312,6 @@ const AnearEventMachineFunctions = ({
 
           const spectatorEvent = { type: 'SPECTATOR_ENTER', data: userJSON }
           context.appEventMachine.send(spectatorEvent)
-
-          // v5: AppM snapshots often don't include the triggering event, so the
-          // AppMachineTransition subscriber can't reliably "refresh render" on
-          // presence events. Explicitly invoke the transition hook here so
-          // spectators always get the current view.
-          if (typeof context.appMachineTransition === 'function') {
-            try {
-              context.appMachineTransition(context.appEventMachine.getSnapshot(), spectatorEvent)
-            } catch (e) {
-              logger.warn('[AEM] AppMachineTransition failed during SPECTATOR_ENTER refresh', e)
-            }
-          }
         }
       )
     },
@@ -1372,15 +1360,6 @@ const AnearEventMachineFunctions = ({
       if (context.appEventMachine) {
         const reconnectEvent = { type: eventName, participantId }
         context.appEventMachine.send(reconnectEvent)
-
-        // Explicitly refresh meta-driven displays on reconnect (browser refresh)
-        if (typeof context.appMachineTransition === 'function') {
-          try {
-            context.appMachineTransition(context.appEventMachine.getSnapshot(), reconnectEvent)
-          } catch (e) {
-            logger.warn('[AEM] AppMachineTransition failed during RECONNECT refresh', e)
-          }
-        }
       }
     },
     updateParticipantGeoLocation: assign({
@@ -1425,15 +1404,6 @@ const AnearEventMachineFunctions = ({
       }
       if (context.appEventMachine) {
         context.appEventMachine.send(appMPayload);
-
-        // Explicitly refresh meta-driven displays on UPDATE (e.g. geo changes)
-        if (typeof context.appMachineTransition === 'function') {
-          try {
-            context.appMachineTransition(context.appEventMachine.getSnapshot(), appMPayload)
-          } catch (e) {
-            logger.warn('[AEM] AppMachineTransition failed during UPDATE refresh', e)
-          }
-        }
       }
     },
     sendExitToAppMachine: ({ context, event }) => {
@@ -1699,19 +1669,118 @@ const AnearEventMachineFunctions = ({
         }
       }
 
-      const appActor = createActor(machineToStart, actorInput ? { input: actorInput } : undefined)
-      appActor.start()
-
-      // Observe transitions to drive rendering (meta parsing, etc.)
+      // 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.
       const appMachineTransition = AppMachineTransition(context.anearEvent)
-      // v5: subscribing does not emit the current snapshot immediately, so we
-      // manually process the initial snapshot to match v4 onTransition behavior.
-      try {
-        appMachineTransition(appActor.getSnapshot())
-      } catch (e) {
-        logger.warn('[AEM] AppMachineTransition failed on initial snapshot', e)
+
+      const REFRESH_EVENT_TYPES = AppMachineTransition.REFRESH_EVENT_TYPES
+
+      const defer =
+        (typeof queueMicrotask === 'function')
+          ? queueMicrotask
+          : (fn) => Promise.resolve().then(fn)
+
+      let appActor
+      let lastRefreshEvent = null
+      let lastRefreshHandledBySnapshot = false
+      let sawAnySnapshot = false
+
+      const inspect = (inspectionEvent) => {
+        if (!inspectionEvent || !appActor) return
+
+        // Only observe the root AppM actor; ignore child actors.
+        if (inspectionEvent.actorRef !== appActor) return
+
+        if (inspectionEvent.type === '@xstate.snapshot') {
+          const { snapshot, event } = inspectionEvent
+          sawAnySnapshot = true
+          try {
+            logger.debug('[AEM][inspect] @xstate.snapshot', {
+              eventType: event?.type,
+              participantId: event?.participantId,
+              nonResponderIds: event?.nonResponderIds,
+              value: snapshot?.value,
+              status: snapshot?.status
+            })
+          } catch (_e) {
+            // logging should never interrupt state processing
+          }
+          try {
+            appMachineTransition(snapshot, event)
+          } 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)', {
+              eventType: event?.type,
+              participantId: event?.participantId
+            })
+          }
+        }
+
+        if (inspectionEvent.type === '@xstate.event') {
+          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.
+          if (REFRESH_EVENT_TYPES.has(ev.type)) {
+            try {
+              logger.debug('[AEM][inspect] @xstate.event (refresh candidate)', {
+                eventType: ev?.type,
+                participantId: ev?.participantId,
+                nonResponderIds: ev?.nonResponderIds
+              })
+            } catch (_e) {
+              // logging should never interrupt state processing
+            }
+            lastRefreshEvent = ev
+            lastRefreshHandledBySnapshot = false
+
+            defer(() => {
+              if (!appActor) return
+              if (lastRefreshEvent !== ev) return
+              if (lastRefreshHandledBySnapshot) 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)
+              }
+            })
+          }
+        }
       }
-      appActor.subscribe(appMachineTransition)
+
+      const actorOptions = actorInput
+        ? { input: actorInput, inspect }
+        : { inspect }
+
+      appActor = createActor(machineToStart, actorOptions)
+      appActor.start()
+
+      // v5: inspection generally emits an init snapshot, but keep a safe fallback
+      // to match v4 onTransition behavior in case an init snapshot isn't observed.
+      defer(() => {
+        if (sawAnySnapshot) return
+        try {
+          logger.debug('[AEM][inspect] init snapshot fallback (no @xstate.snapshot observed yet)')
+          appMachineTransition(appActor.getSnapshot(), { type: 'xstate.init' })
+        } catch (e) {
+          logger.warn('[AEM] AppMachineTransition failed on initial snapshot fallback', e)
+        }
+      })
 
       // Auto-cleanup when AppM reaches done.
       appActor.subscribe((snapshot) => {

package/lib/utils/AppMachineTransition.js

@@ -3,6 +3,23 @@
 const logger = require('./Logger')
 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.).
+const REFRESH_EVENT_TYPES = new Set([
+  'SPECTATOR_ENTER',
+  'PARTICIPANT_ENTER',
+  'HOST_ENTER',
+  // Browser refresh / quick leave+rejoin cases:
+  'PARTICIPANT_RECONNECT',
+  'HOST_RECONNECT',
+  // Temporary disconnects (useful for "halt/pause" and UI indicators):
+  'PARTICIPANT_DISCONNECT',
+  'HOST_DISCONNECT',
+  // Location/heartbeat updates can also want a "refresh current view":
+  'PARTICIPANT_UPDATE',
+  'HOST_UPDATE'
+])
+
 /**
  * AppMachineTransition:
  *  - Runs inside your appEventMachine onTransition.
@@ -19,17 +36,6 @@ const AppMachineTransition = (anearEvent) => {
   // - Never re-render on the RENDERED ack (prevents ping-pong loops)
   let lastBaseSignature = null
 
-  const REFRESH_EVENT_TYPES = new Set([
-    'SPECTATOR_ENTER',
-    'PARTICIPANT_ENTER',
-    // Browser refresh / quick leave+rejoin cases:
-    'PARTICIPANT_RECONNECT',
-    'HOST_RECONNECT',
-    // Location/heartbeat updates can also want a "refresh current view":
-    'PARTICIPANT_UPDATE',
-    'HOST_UPDATE'
-  ])
-
   return (appEventMachineState, triggeringEvent = null) => {
     // Handle potential XState version differences and missing properties
     const stateObj = appEventMachineState || {}
@@ -156,7 +162,7 @@ const AppMachineTransition = (anearEvent) => {
             const { viewPath, props } = _extractViewAndProps(meta.eachParticipant)
             const timeoutFn = RenderContextBuilder.buildTimeoutFn('participant', meta.eachParticipant.timeout)
 
-            const renderContext = RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, 'eachParticipant', timeoutFn),
+            const renderContext = RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, 'eachParticipant', timeoutFn)
             displayEvent = RenderContextBuilder.buildDisplayEvent(
               viewPath,
               renderContext,
@@ -237,4 +243,7 @@ const _stringifiedState = (stateValue) => {
   return Object.entries(stateValue).map(([k, v]) => `${k}.${_stringifiedState(v)}`).join('.')
 }
 
+// Export the refresh-event allowlist so AEM can share it (prevents drift).
+AppMachineTransition.REFRESH_EVENT_TYPES = REFRESH_EVENT_TYPES
+
 module.exports = AppMachineTransition

package/package.json

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