anear-js-api 0.5.2 → 0.5.4

package/lib/state_machines/AnearParticipantMachine.js

@@ -109,6 +109,10 @@ const AnearParticipantMachineConfig = participantId => ({
                 PARTICIPANT_RECONNECT: {
                   actions: 'logReconnected',
                   internal: true
+                },
+                BOOT_PARTICIPANT: {
+                  actions: 'logBooted',
+                  target: '#cleanupAndExit'
                 }
               }
             },
@@ -151,11 +155,17 @@ const AnearParticipantMachineConfig = participantId => ({
                 src: 'publishPrivateDisplay',
                 onDone: [
                   { cond: 'hasActionTimeout', actions: 'updateActionTimeout', target: 'waitParticipantResponse' },
-                  { target: 'idle', internal: true }
+                  { target: 'idle' }
                 ],
                 onError: {
                   target: '#error'
                 }
+              },
+              on: {
+                PARTICIPANT_EXIT: {
+                  actions: 'logExit',
+                  target: '#cleanupAndExit'
+                }
               }
             },
             waitParticipantResponse: {
@@ -223,6 +233,35 @@ const AnearParticipantMachineConfig = participantId => ({
                 }
               }
             },
+            booting: {
+              initial: 'publishingShutdown',
+              states: {
+                publishingShutdown: {
+                  invoke: {
+                    id: 'publishBootMessage',
+                    src: 'publishBootMessageService',
+                    onDone: 'waitingForClientExit',
+                    onError: '#cleanupAndExit'
+                  }
+                },
+                waitingForClientExit: {
+                  after: {
+                    bootCleanupTimeout: {
+                      target: '#cleanupAndExit'
+                    }
+                  },
+                  on: {
+                    PARTICIPANT_EXIT: '#cleanupAndExit',
+                    ACTION: {
+                      internal: true
+                    },
+                    PARTICIPANT_DISCONNECT: {
+                      internal: true
+                    }
+                  }
+                }
+              }
+            },
             done: {
               id: 'done',
               entry: ['notifyEventMachineExit'],
@@ -356,6 +395,20 @@ const AnearParticipantMachineFunctions = {
 
       return { timeout: event.timeout }
     },
+    publishBootMessageService: async (context, event) => {
+      const { reason } = event.data;
+      const payload = {
+        content: {
+          reason: reason || 'You have been removed from the event.'
+        }
+      }
+
+      await RealtimeMessaging.publish(
+        context.privateChannel,
+        'FORCE_SHUTDOWN',
+        payload
+      )
+    },
     attachToPrivateChannel: (context, event) => RealtimeMessaging.attachTo(context.privateChannel),
     detachPrivateChannel: async (context, event) => {
       return context.privateChannel ? RealtimeMessaging.detachAll([context.privateChannel]) : Promise.resolve()
@@ -368,6 +421,7 @@ const AnearParticipantMachineFunctions = {
     wasMidTurnOnDisconnect: context => context.actionTimeoutMsecs !== null && context.actionTimeoutMsecs > 0
   },
   delays: {
+    bootCleanupTimeout: () => C.TIMEOUT_MSECS.BOOT_EXIT,
     actionTimeout: context => context.actionTimeoutMsecs,
     dynamicReconnectTimeout: context => {
       // If an action timeout is active, use its remaining time.

package/lib/utils/AppMachineTransition.js

@@ -37,7 +37,6 @@ const AppMachineTransition = (anearEvent) => {
       // Process all meta objects to handle unpredictable AppM structures
       metaObjects.forEach(meta => {
         let viewer
-        let viewPath
         let timeoutFn
         let displayEvent
 
@@ -49,18 +48,23 @@ const AppMachineTransition = (anearEvent) => {
 
         if (meta.allParticipants) {
           viewer = 'allParticipants'
-          viewPath = _getViewPath(meta.allParticipants)
+          const { viewPath, props } = _extractViewAndProps(meta.allParticipants)
           timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.allParticipants.timeout)
 
           displayEvent = RenderContextBuilder.buildDisplayEvent(
             viewPath,
-            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn)
+            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
             const participantRenderFunc = meta.eachParticipant
@@ -73,7 +77,7 @@ const AppMachineTransition = (anearEvent) => {
                 appContext,
                 appStateName,
                 event.type,
-                'eachParticipant',
+                viewer,
                 null
               )
 
@@ -81,13 +85,15 @@ const AppMachineTransition = (anearEvent) => {
                 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
-                    'eachParticipant',
+                    viewer,
                     participantDisplay.participantId,
-                    timeout
+                    timeout,
+                    props
                   )
                   displayEvents.push(displayEvent)
                 }
@@ -95,15 +101,17 @@ const AppMachineTransition = (anearEvent) => {
             }
           } else {
             // Legacy participant rendering - normalize to selective format
-            const viewPath = _getViewPath(meta.eachParticipant)
+            const { viewPath, props } = _extractViewAndProps(meta.eachParticipant)
             const timeoutFn = RenderContextBuilder.buildTimeoutFn('participant', meta.eachParticipant.timeout)
 
             const renderContext = RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, 'eachParticipant', timeoutFn),
             displayEvent = RenderContextBuilder.buildDisplayEvent(
               viewPath,
               renderContext,
-              'eachParticipant',
-              'ALL_PARTICIPANTS' // Special marker for "all participants"
+              viewer,
+              'ALL_PARTICIPANTS', // Special marker for "all participants"
+              null,
+              props
             )
             displayEvents.push(displayEvent)
           }
@@ -111,24 +119,32 @@ const AppMachineTransition = (anearEvent) => {
 
         if (meta.host) {
           viewer = 'host'
-          viewPath = _getViewPath(meta.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),
-            'host'
+            viewer,
+            null,
+            null,
+            props
           )
           displayEvents.push(displayEvent)
         }
 
         if (meta.spectators) {
           viewer = 'spectators'
-          viewPath = _getViewPath(meta.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)
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null,
+            props
           )
           displayEvents.push(displayEvent)
         }
@@ -140,28 +156,28 @@ const AppMachineTransition = (anearEvent) => {
       }
     }
 
-    // Send CLOSE AFTER processing meta (including exit displays)
-    if (isDone) {
-      logger.debug('[AppMachineTransition] AppM reached final state, sending CLOSE')
-      anearEvent.send('CLOSE')
-    }
+    // Note: When AppM reaches a final state, the service.onDone() callback
+    // in AnearEventMachine.js will fire and send APPM_FINAL to trigger cleanup.
+    // Apps should explicitly call anearEvent.closeEvent() or anearEvent.cancelEvent()
+    // as entry actions in final states if they need API state transitions.
   }
 }
 
-const _getViewPath = (config) => {
-  if (!config) return null
-  if (typeof config === 'string') return config
+const _extractViewAndProps = (config) => {
+  if (!config) return { viewPath: null, props: {} }
+
+  if (typeof config === 'string') {
+    return { viewPath: config, props: {} }
+  }
+
   if (typeof config === 'object') {
-    // Handle various possible view path formats
-    if (config.view) return config.view
-    if (config.template) return config.template
-    if (config.path) return config.path
-    // If no view path found, log warning but don't throw
-    logger.warn(`[AppMachineTransition] No view path found in config: ${JSON.stringify(config)}`)
-    return null
+    const viewPath = config.view
+    const props = config.props || {}
+    return { viewPath, props }
   }
+
   logger.warn(`[AppMachineTransition] Unknown meta format: ${JSON.stringify(config)}`)
-  return null
+  return { viewPath: null, props: {} }
 }
 
 const _stringifiedState = (stateValue) => {

package/lib/utils/Constants.js

@@ -13,7 +13,8 @@ module.exports = {
     ANNOUNCE: 5 * 60 * 1000, // 5 minutes
     START: 5 * 60 * 1000,    // 5 minutes
     RENDERED_EVENT_DELAY: 100, // 100 milliseconds
-    RECONNECT: 30 * 1000 // 30 seconds
+    RECONNECT: 30 * 1000, // 30 seconds
+    BOOT_EXIT: 2 * 1000 // 5 seconds
   },
   EventStates: {
     CREATED: 'created',

package/lib/utils/DisplayEventProcessor.js

@@ -6,10 +6,17 @@
  * {
  *   app: application XState context
  *   meta: {
- *     viewer:  // 'eachParticipant', 'allParticipants', 'spectators'
+ *     viewer:  // 'eachParticipant', 'allParticipants', 'spectators', 'host'
  *     state:   // Stringified state name (e.g., 'live.registration.waitForOpponentToJoin')
- *     event:   // The triggering event for this transition ('PARTICIPANT_ENTER')
- *     timeout: // null|| func}
+ *     event:   // The triggering event for this transition ('PARTIPANT_ENTER')
+ *     // timeout exposed to views for display purposes only; actual timers are attached
+ *     // only to the viewer that configured a timeout in AppM meta.
+ *     // Shape: { msecs: number, remainingMsecs: number }
+ *     timeout: // optional
+ *   }
+ *   props: {
+ *     // All properties from the `props` object in the AppM's meta block.
+ *     // e.g., meta: { view: 'foo', props: { title: 'Hello' } } -> `props.title`
  *   }
  *
  *   // When 'eachParticipant' displayType
@@ -38,6 +45,8 @@ const C = require('./Constants')
 class DisplayEventProcessor {
   constructor(anearEventMachineContext) {
     this.anearEvent = anearEventMachineContext.anearEvent
+    // Snapshot of current AEM timeout context for this render
+    this.participantsActionTimeout = anearEventMachineContext.participantsActionTimeout
     this.pugTemplates = anearEventMachineContext.pugTemplates
     this.pugHelpers = anearEventMachineContext.pugHelpers
     this.participantMachines = anearEventMachineContext.participantMachines
@@ -50,6 +59,26 @@ class DisplayEventProcessor {
   processAndPublish(displayEvents) {
     let participantsTimeout = null
 
+    // Pre-compute allParticipants timeout for this render batch so other viewers
+    // (host/spectators) can mirror it visually even before AEM context is updated
+    try {
+      const allEvent = displayEvents.find(e => (e.viewer || e.appRenderContext?.meta?.viewer) === 'allParticipants')
+      if (allEvent) {
+        const { timeout: displayTimeout, appRenderContext } = allEvent
+        const timeoutFn = appRenderContext?.meta?.timeoutFn
+        if (displayTimeout !== null && displayTimeout > 0) {
+          this.precomputedParticipantsTimeout = { msecs: displayTimeout, startedAt: Date.now() }
+        } else if (timeoutFn) {
+          const msecs = timeoutFn(appRenderContext.app)
+          if (typeof msecs === 'number' && msecs > 0) {
+            this.precomputedParticipantsTimeout = { msecs, startedAt: Date.now() }
+          }
+        }
+      }
+    } catch (_e) {
+      // ignore precompute errors; fall back to runtime values
+    }
+
     const publishPromises = displayEvents.map(event => {
       const { publishPromise, timeout } = this._processSingle(event)
       if (timeout) {
@@ -77,7 +106,7 @@ class DisplayEventProcessor {
   }
 
   _processSingle(displayEvent) {
-    const { viewPath, appRenderContext, target, participantId, timeout: displayTimeout } = displayEvent
+    const { viewPath, appRenderContext, viewer, participantId, timeout: displayTimeout, props } = displayEvent
     const timeoutFn = appRenderContext.meta.timeoutFn
 
     const normalizedPath = viewPath.endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`
@@ -93,7 +122,8 @@ class DisplayEventProcessor {
       ...appRenderContext,
       anearEvent: this.anearEvent,
       participants: this.participantsIndex,
-      ...this.pugHelpers
+      ...this.pugHelpers,
+      props
     }
 
     const formattedDisplayMessage = () => {
@@ -104,11 +134,11 @@ class DisplayEventProcessor {
       return displayMessage
     }
 
-    // The target determines who sees the view. It defaults to the 'viewer'
-    // from the meta block, but can be overridden (e.g., for 'host').
-    const displayTarget = target || appRenderContext.meta.viewer
+    // The viewer determines who sees the view. It can be set directly on the
+    // display event, but if not, it falls back to the viewer from the meta block.
+    const displayViewer = viewer || appRenderContext.meta.viewer
 
-    switch (displayTarget) {
+    switch (displayViewer) {
       case 'allParticipants':
         logger.debug(`[DisplayEventProcessor] Publishing ${viewPath} to PARTICIPANTS_DISPLAY`)
 
@@ -122,6 +152,20 @@ class DisplayEventProcessor {
           }
         }
 
+        // Expose timeout to template context for countdown bars
+        if (timeout) {
+          const startedAt = (this.participantsActionTimeout && this.participantsActionTimeout.startedAt) || (this.precomputedParticipantsTimeout && this.precomputedParticipantsTimeout.startedAt)
+          const now = Date.now()
+          const remainingMsecs = startedAt ? Math.max(0, timeout.msecs - (now - startedAt)) : timeout.msecs
+          templateRenderContext.meta = {
+            ...templateRenderContext.meta,
+            timeout: { msecs: timeout.msecs, remainingMsecs }
+          }
+          logger.debug(`[DisplayEventProcessor] allParticipants timeout resolved to ${timeout.msecs}ms (remaining ${remainingMsecs}ms)`)
+        } else {
+          logger.debug(`[DisplayEventProcessor] no allParticipants timeout resolved`)
+        }
+
         publishPromise = RealtimeMessaging.publish(
           this.participantsDisplayChannel,
           'PARTICIPANTS_DISPLAY',
@@ -132,6 +176,30 @@ class DisplayEventProcessor {
       case 'spectators':
         logger.debug(`[DisplayEventProcessor] Publishing ${viewPath} to SPECTATORS_DISPLAY`)
 
+        // Spectators never have action timeouts; they can display a visual bar only.
+        // Prefer their own configured timeout for visuals, otherwise mirror the
+        // allParticipants collective timeout (remaining time) if one is running.
+        let specTimeout = null
+        if (timeoutFn) {
+          const msecs = timeoutFn(appRenderContext.app)
+          if (typeof msecs === 'number' && msecs > 0) {
+            specTimeout = { msecs, remainingMsecs: msecs }
+          }
+        }
+        if (!specTimeout) {
+          const pat = this.precomputedParticipantsTimeout || this.participantsActionTimeout
+          if (pat && typeof pat.msecs === 'number') {
+            const now = Date.now()
+            const start = pat.startedAt || Date.now()
+            const remainingMsecs = Math.max(0, pat.msecs - (now - start))
+            specTimeout = { msecs: pat.msecs, remainingMsecs }
+          }
+        }
+        if (specTimeout) {
+          templateRenderContext.meta = { ...templateRenderContext.meta, timeout: specTimeout }
+          logger.debug(`[DisplayEventProcessor] spectators visual timeout set to msecs=${specTimeout.msecs}, remaining=${specTimeout.remainingMsecs}`)
+        }
+
         publishPromise = RealtimeMessaging.publish(
           this.spectatorsDisplayChannel,
                   'SPECTATORS_DISPLAY',
@@ -157,12 +225,45 @@ class DisplayEventProcessor {
 
       case 'host':
         logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY ${viewPath} for 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
+        if (timeoutFn) {
+          const msecs = timeoutFn(appRenderContext.app)
+          if (typeof msecs === 'number' && msecs > 0) hostOwnMsecs = msecs
+        }
+        if (hostOwnMsecs !== null) {
+          templateRenderContext.meta = {
+            ...templateRenderContext.meta,
+            timeout: { msecs: hostOwnMsecs, remainingMsecs: hostOwnMsecs }
+          }
+          logger.debug(`[DisplayEventProcessor] host timeout resolved to ${hostOwnMsecs}ms`)
+        } else {
+          // Visual-only: mirror participants timeout if it exists
+          const pat = this.precomputedParticipantsTimeout || this.participantsActionTimeout
+          if (pat && typeof pat.msecs === 'number') {
+            const now = Date.now()
+            const start = pat.startedAt || Date.now()
+            const remainingMsecs = Math.max(0, pat.msecs - (now - start))
+            templateRenderContext.meta = {
+              ...templateRenderContext.meta,
+              timeout: { msecs: pat.msecs, remainingMsecs }
+            }
+            logger.debug(`[DisplayEventProcessor] host visual timeout from allParticipants msecs=${pat.msecs}, remaining=${remainingMsecs}`)
+          } else {
+            logger.debug(`[DisplayEventProcessor] host timeout not set`)
+          }
+        }
 
-        publishPromise = this._processHostDisplay(template, templateRenderContext, timeoutFn)
+        publishPromise = this._processHostDisplay(
+          template,
+          templateRenderContext,
+          hostOwnMsecs !== null ? (() => hostOwnMsecs) : null
+        )
         break
 
       default:
-        throw new Error(`Unknown display target: ${displayTarget}`)
+        throw new Error(`Unknown display viewer: ${displayViewer}`)
     }
     return { publishPromise, timeout }
   }
@@ -245,7 +346,8 @@ class DisplayEventProcessor {
     }
 
     if (timeout !== null) {
-      privateRenderContext.timeout = timeout
+      // APM will compute remaining on its own; start remaining at full msecs here
+      privateRenderContext.timeout = { msecs: timeout, remainingMsecs: timeout }
     }
 
     const privateHtml = template(privateRenderContext)

package/lib/utils/RealtimeMessaging.js

@@ -85,6 +85,15 @@ class RealtimeMessaging {
     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)
+    } catch (e) {
+      logger.warn(`[RTM] presence.enter failed on ${channel.name}`, e)
+    }
+  }
+
   /**
    * Detach a list of Ably channels.
    * If any detach fails, Promise.all will reject.

package/lib/utils/RenderContextBuilder.js

@@ -59,19 +59,21 @@ class RenderContextBuilder {
    * Build display event object
    * @param {string} viewPath - Template/view path
    * @param {Object} appRenderContext - Context object
-   * @param {string} target - Optional target (host, participant, etc.)
+   * @param {string} viewer - Optional viewer type (host, participant, etc.)
    * @param {string} participantId - Optional participant ID for selective rendering
    * @param {number} timeout - Optional timeout in milliseconds
+   * @param {Object} props - Optional arguments for the view
    * @returns {Object} Display event object
    */
-  static buildDisplayEvent(viewPath, appRenderContext, target = null, participantId = null, timeout = null) {
+  static buildDisplayEvent(viewPath, appRenderContext, viewer = null, participantId = null, timeout = null, props = {}) {
     const displayEvent = {
       viewPath,
-      appRenderContext
+      appRenderContext,
+      props
     }
 
-    if (target) {
-      displayEvent.target = target
+    if (viewer) {
+      displayEvent.viewer = viewer
     }
 
     if (participantId) {

package/package.json

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