anear-js-api 2.0.1 → 2.2.0

package/EACH_PARTICIPANT_LIFECYCLE.md

@@ -1,5 +1,7 @@
 # The `eachParticipant` Display Lifecycle
 
+> Breaking vNext note: `AnearParticipantMachine` has been removed. `AnearEventMachine` now owns participant private channel lifecycle and `DisplayEventProcessor` publishes `PRIVATE_DISPLAY` directly to participant private channels.
+
 This document provides a detailed, step-by-by-step breakdown of how a display targeted at `eachParticipant` travels from the application's state machine (AppM) to an individual participant's browser client.
 
 ### The Goal
@@ -10,7 +12,7 @@ We want to render a specific view (`QuestionScreen.pug`) for a single user (`par
 
 The core idea is to translate a declarative `meta` block in your application's state machine (AppM) into concrete HTML content that gets delivered to a specific participant's device. This process involves a chain of components:
 
-`AppMachineTransition` -> `AnearEventMachine` -> `DisplayEventProcessor` -> `AnearParticipantMachine` -> **Ably Message**
+`AppMachineTransition` -> `AnearEventMachine` -> `DisplayEventProcessor` -> **Ably Message**
 
 Let's break down each step.
 

package/README.md

@@ -18,7 +18,7 @@ The anear-js-api abstracts away:
 - Participant presence tracking and coordination
 - Display rendering and template compilation
 - Asset management (CSS, images) and CDN uploads
-- Timeout management for participant actions
+- Timeout orchestration for `allParticipants` action windows
 - Reconnection handling and error recovery
 
 ## Architecture
@@ -28,9 +28,7 @@ The anear-js-api abstracts away:
 ```
 AnearCoreServiceMachine (Root)
 ├── AnearEventMachine (Per Event)
-│   ├── AnearParticipantMachine (Per Participant)
 │   └── AppEventMachine (Developer's App Logic)
-└── AppParticipantMachine (Optional, Per Participant)
 ```
 
 ### Core Components
@@ -52,30 +50,26 @@ AnearCoreServiceMachine (Root)
   - Route messages between participants and app logic
   - Manage participant presence (enter/leave/exit)
   - Coordinate display rendering for all channels
-  - Handle individual participant timeouts
+  - Handle allParticipants timeout orchestration
 - **Key States**: `registerCreator` → `eventCreated` → `announce` → `live` → `closeEvent`
 
-#### AnearParticipantMachine (APM)
-- **Purpose**: Manages individual participant state and private communications
-- **Responsibilities**:
-  - Handle participant private channel communications
-  - Manage participant timeouts and reconnection logic
-  - Track participant activity and idle states
-  - Route participant-specific actions to app logic
-- **Key States**: `setup` → `live` → `waitReconnect` → `cleanupAndExit`
+#### Breaking vNext: APM Removed
+- Participant-machine orchestration is removed from JSAPI.
+- AEM now manages participant private channel lifecycle and private display publishing directly.
+- JSAPI no longer emits `PARTICIPANT_TIMEOUT`; participant-local timeout UX is owned by browser runtime (`<anear-timeout>`).
 
 ### Separation of Concerns: JSAPI vs. AppM
 
 A key architectural principle is the clear separation of concerns between the Anear JSAPI (the "engine") and the App Event Machine (the "application").
 
-#### JSAPI (AEM & APM): The Engine Room
+#### JSAPI (AEM): The Engine Room
 
 The JSAPI is responsible for all the underlying infrastructure and communication mechanics. Its concerns are purely technical:
 
 - **Event Lifecycle & State:** Manages the low-level state transitions of an event (`created` → `announce` → `live` → `closed`) and the lifecycle of participants.
 - **Real-time Communication:** Handles all Ably channel setup, messaging, presence events, and connection state.
 - **Orderly Operations:** Ensures smooth, reliable startup and shutdown of all services and participant connections.
-- **Notifier:** The JSAPI acts as a notifier. It informs the AppM of important events (`PARTICIPANT_ENTER`, `PARTICIPANT_DISCONNECT`, `ACTION`, `PARTICIPANT_TIMEOUT`) but does not decide what these events mean for the application.
+- **Notifier:** The JSAPI acts as a notifier. It informs the AppM of important events (`PARTICIPANT_ENTER`, `PARTICIPANT_DISCONNECT`, `ACTION`, `ACTIONS_TIMEOUT`) but does not decide what these events mean for the application.
 
 #### AppM: The Application & User Experience
 
@@ -185,7 +179,6 @@ The JSAPI handles participant lifecycle through presence events:
 | `PARTICIPANT_RECONNECT` | Participant rejoins after disconnect | `HOST_RECONNECT` or `PARTICIPANT_RECONNECT` |
 | `PARTICIPANT_EXIT` | Participant permanently leaves | `HOST_EXIT` or `PARTICIPANT_EXIT` |
 | `PARTICIPANT_DISCONNECT` | Temporary connection loss | `HOST_DISCONNECT` or `PARTICIPANT_DISCONNECT` |
-| `PARTICIPANT_TIMEOUT` | Participant fails to respond in time | `PARTICIPANT_TIMEOUT` |
 | `ACTION` | Participant performs an action | Custom event (e.g., `MOVE`, `ANSWER`) |
 
 **Key Point**: The AEM uses role-specific events (`HOST_*` vs `PARTICIPANT_*`) based on whether the user is the event creator/host. Your AppM never needs to check `isHost` - it just reacts to the specific events it receives.
@@ -236,9 +229,9 @@ PUG templates receive rich context including:
 
 ## Timeout Management
 
-### Individual Timeouts
+### Participant-local Timeouts
 
-For turn-based actions where each participant has their own timer:
+Participant-local timeout UX is handled by browser runtime (`<anear-timeout>`). JSAPI does not emit `PARTICIPANT_TIMEOUT`.
 
 ```javascript
 meta: {
@@ -251,8 +244,7 @@ meta: {
   }
 },
 on: {
-  MOVE: 'nextTurn',
-  PARTICIPANT_TIMEOUT: 'handleTimeout'
+  MOVE: 'nextTurn'
 }
 ```
 
@@ -287,6 +279,7 @@ The JSAPI automatically handles asset management:
 1. **CSS Upload**: All CSS files in `assets/css/` are uploaded to CloudFront
 2. **Image Upload**: All images in `assets/images/` are uploaded to CloudFront
 3. **Template Preloading**: All PUG templates are preloaded and cached
+4. **Hash-based dedupe**: Asset uploads are decided by SHA-256 content hash comparison against S3 metadata (not file timestamps)
 
 ### CI-Managed Assets Mode
 

package/lib/AnearService.js

@@ -1,12 +1,12 @@
 const AnearCoreServiceMachine = require('./state_machines/AnearCoreServiceMachine')
 
-const AnearService = (appEventMachineFactory, appParticipantMachineFactory = null) => {
+const AnearService = (appEventMachineFactory) => {
   //
   // developer provides appEventMachineFactory:
   //
   //    appEventMachineFactory = anearEvent => { returns XState Machine) }
-  //    optional appParticipantMachineFactory = anearParticipant => { returns XState Machine) }
+  //    participant-level machines are no longer managed by JSAPI.
   //
-  return AnearCoreServiceMachine(appEventMachineFactory, appParticipantMachineFactory)
+  return AnearCoreServiceMachine(appEventMachineFactory)
 }
 module.exports = AnearService

package/lib/ci/registerAppVersion.js

@@ -8,6 +8,9 @@ async function registerAppVersionFromCi({
   gitSha = process.env.GITHUB_SHA,
   imageUri = process.env.IMAGE_URI,
   assetManifestHash = process.env.ASSET_MANIFEST_HASH,
+  imageAssetsUrl = process.env.IMAGE_ASSETS_URL,
+  fontAssetsUrl = process.env.FONT_ASSETS_URL,
+  cssUrl = process.env.CSS_URL,
   status = 'building'
 } = {}) {
   if (!appId || !version) {
@@ -19,7 +22,10 @@ async function registerAppVersionFromCi({
     status,
     git_sha: gitSha,
     image_uri: imageUri,
-    asset_manifest_hash: assetManifestHash
+    asset_manifest_hash: assetManifestHash,
+    image_assets_url: imageAssetsUrl,
+    font_assets_url: fontAssetsUrl,
+    css_url: cssUrl
   })
 
   return data

package/lib/models/AnearEvent.js

@@ -111,10 +111,8 @@ class AnearEvent extends JsonApiResource {
   }
 
   cancelAllParticipantTimeouts() {
-    // Cancel all active participant-level timeouts. This sends CANCEL_TIMEOUT
-    // to all APMs, which will benignly clear any active timeout timers.
-    // Useful for scenarios where a game event (e.g., LIAR call) should immediately
-    // cancel all individual participant timeouts.
+    // Cancels active allParticipants timeout tracking in AEM.
+    // Participant-local timeout ownership now lives in the browser runtime.
     this.send({ type: "CANCEL_ALL_PARTICIPANT_TIMEOUTS" })
   }
 

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -61,6 +61,8 @@ const C = require('../utils/Constants')
 const CreateVersionedEventChannelNameTemplate = (appId, appVersion) => `anear:${appId}:v:${normalizeVersionToken(appVersion)}:e`
 const DefaultTemplatesRootDir = "./views"
 const SkipRuntimeAssetSync = process.env.ANEARAPP_SKIP_RUNTIME_ASSET_SYNC === 'true'
+const FallbackImageAssetsUrl = process.env.ANEARAPP_IMAGE_ASSETS_URL || null
+const FallbackFontAssetsUrl = process.env.ANEARAPP_FONT_ASSETS_URL || null
 
 // Process-wide signal handling.
 // We install exactly once per process to avoid duplicate handlers in reconnect/restart scenarios.
@@ -80,11 +82,10 @@ function scheduleExit(code, message) {
   setTimeout(() => process.exit(code), delayMs)
 }
 
-const AnearCoreServiceMachineContext = (appId, appEventMachineFactory, appParticipantMachineFactory) => ({
+const AnearCoreServiceMachineContext = (appId, appEventMachineFactory) => ({
   appId,
   appData: null,
   appEventMachineFactory,
-  appParticipantMachineFactory,
   anearEventMachines: {}, // All concurrent anear events handled by this core service
   pugTemplates: {},
   imageAssetsUrl: null,
@@ -161,13 +162,27 @@ const AnearCoreServiceMachineConfig = appId => ({
         {
           guard: 'runtimeAssetSyncDisabled',
           actions: () => logger.info('[ACSM] Runtime asset sync disabled; assuming CI has already published assets'),
-          target: 'loadAndCompilePugTemplates'
+          target: 'resolveVersionAssetUrls'
         },
         {
           target: 'uploadNewImageAssets'
         }
       ]
     },
+    resolveVersionAssetUrls: {
+      invoke: {
+        src: 'fetchLatestAppVersionAssets',
+        input: ({ context }) => ({ appId: context.appId }),
+        onDone: {
+          actions: assign({
+            imageAssetsUrl: ({ event }) => event.output.imageAssetsUrl,
+            fontAssetsUrl: ({ event }) => event.output.fontAssetsUrl
+          }),
+          target: 'loadAndCompilePugTemplates'
+        },
+        onError: '#failure'
+      }
+    },
     uploadNewImageAssets: {
       invoke: {
         src: 'uploadNewImageAssets',
@@ -255,6 +270,19 @@ const AnearCoreServiceMachineFunctions = {
     // v5 pattern: async "services" become Promise Actors via `fromPromise`.
     // The invoked actor receives `input` from the invoking state's `invoke.input`.
     fetchAppData: fromPromise(({ input }) => AnearApi.getApp(input.appId)),
+    fetchLatestAppVersionAssets: fromPromise(async ({ input }) => {
+      const latestVersion = await AnearApi.getLatestAppVersion(input.appId)
+      const attrs = latestVersion?.attributes || {}
+      const imageAssetsUrl = attrs['image-assets-url'] || FallbackImageAssetsUrl
+      const fontAssetsUrl = attrs['font-assets-url'] || FallbackFontAssetsUrl
+
+      if (!imageAssetsUrl) {
+        throw new Error('[ACSM] Missing image-assets-url for latest app version; set app_version image_assets_url in ANAPI or ANEARAPP_IMAGE_ASSETS_URL env var')
+      }
+
+      logger.info(`[ACSM] Using pre-published version assets image_base=${imageAssetsUrl}`)
+      return { imageAssetsUrl, fontAssetsUrl }
+    }),
     uploadNewImageAssets: fromPromise(({ input }) => {
       const uploader = new ImageAssetsUploader(C.ImagesDirPath, input.appId)
       return uploader.uploadAssets()
@@ -464,14 +492,13 @@ function normalizeVersionToken(value) {
   return String(value).replace(/[^A-Za-z0-9_.-]/g, '_')
 }
 
-const AnearCoreServiceMachine = (appEventMachineFactory, appParticipantMachineFactory = null) => {
+const AnearCoreServiceMachine = (appEventMachineFactory) => {
   const appId = process.env.ANEARAPP_APP_ID
   const machineConfig = AnearCoreServiceMachineConfig(appId)
 
   const anearCoreServiceMachineContext = AnearCoreServiceMachineContext(
     appId,
-    appEventMachineFactory,
-    appParticipantMachineFactory
+    appEventMachineFactory
   )
 
   const coreServiceMachine = createMachine(machineConfig, AnearCoreServiceMachineFunctions)