anear-js-api 2.1.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/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

@@ -82,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,
@@ -493,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)