anear-js-api 1.6.6 → 2.0.1

package/README.md

@@ -115,6 +115,31 @@ ANEARAPP_API_VERSION=v1
 ANEARAPP_API_URL=http://api.lvh.me:3001/developer  # Optional, for local development
 ```
 
+### Local Dev Quickstart (no Docker)
+
+To keep development behavior close to today:
+
+1. Keep runtime asset publishing enabled (default):
+
+```bash
+unset ANEARAPP_SKIP_RUNTIME_ASSET_SYNC
+```
+
+2. Start your app process normally:
+
+```bash
+npm install
+node index.js
+```
+
+3. If your ANAPI environment is not Rails `development`, set:
+
+```bash
+export ANEARAPP_SINGLE_LATEST_VERSION=true
+```
+
+This preserves a single mutable `latest` app version for iterative development.
+
 ### Developer API Authentication
 
 `anear-js-api` communicates with the **ANAPI Developer API** (`/developer/v1/*` endpoints) using JWT authentication:
@@ -263,6 +288,29 @@ The JSAPI automatically handles asset management:
 2. **Image Upload**: All images in `assets/images/` are uploaded to CloudFront
 3. **Template Preloading**: All PUG templates are preloaded and cached
 
+### CI-Managed Assets Mode
+
+For containerized deployments, you can publish assets during CI and skip runtime asset sync:
+
+```bash
+ANEARAPP_SKIP_RUNTIME_ASSET_SYNC=true
+```
+
+When this variable is enabled, `AnearCoreServiceMachine` skips image/font/CSS upload states and proceeds directly to template compilation and event lifecycle listening.
+
+CI helpers are available under:
+
+- `anear-js-api/lib/ci/publishAssets.js`
+- `anear-js-api/lib/ci/registerAppVersion.js`
+
+### Versioned Lifecycle Channels
+
+ACSM subscribes to versioned lifecycle channels derived from ANAPI app metadata:
+
+`anear:<appId>:v:<appVersion>:e`
+
+ANAPI must return `latest_app_version` in developer app payloads for startup channel resolution.
+
 ### Asset Structure
 
 ```

package/lib/api/AnearApi.js

@@ -80,6 +80,24 @@ class AnearApi extends ApiService {
     return attrs
   }
 
+  async createAppVersion(appId, attrs) {
+    logger.debug(`API: POST app_versions for app ${appId}`)
+    const json = await this.post("app_versions", attrs, { app: appId })
+    return json.data
+  }
+
+  async updateAppVersion(appVersionId, attrs) {
+    logger.debug(`API: PUT app_versions/${appVersionId}`)
+    const json = await this.put("app_versions", appVersionId, attrs)
+    return json.data
+  }
+
+  async getLatestAppVersion(appId) {
+    logger.debug(`API: GET apps/${appId}/latest_app_version`)
+    const json = await this.get(`apps/${appId}/latest_app_version`)
+    return json.data
+  }
+
   async saveAppEventContext(eventId, appmContext) {
     logger.debug(`API: POST developer events/${eventId}/app_event_context`)
     const path = `events/${eventId}/app_event_context`

package/lib/ci/publishAssets.js

@@ -0,0 +1,35 @@
+"use strict"
+
+const C = require('../utils/Constants')
+const ImageAssetsUploader = require('../utils/ImageAssetsUploader')
+const FontAssetsUploader = require('../utils/FontAssetsUploader')
+const CssUploader = require('../utils/CssUploader')
+
+async function publishAssetsFromCi(appId = process.env.ANEARAPP_APP_ID) {
+  if (!appId) {
+    throw new Error('ANEARAPP_APP_ID must be set to publish assets from CI')
+  }
+
+  const imageAssetsUploader = new ImageAssetsUploader(C.ImagesDirPath, appId)
+  const imageAssetsUrl = await imageAssetsUploader.uploadAssets()
+
+  const fontAssetsUploader = new FontAssetsUploader(C.FontsDirPath, appId)
+  const fontAssetsUrl = await fontAssetsUploader.uploadAssets()
+
+  const cssUploader = new CssUploader(
+    C.CssDirPath,
+    imageAssetsUrl,
+    fontAssetsUrl,
+    appId
+  )
+  const cssUrl = await cssUploader.uploadCss()
+
+  return {
+    appId,
+    imageAssetsUrl,
+    fontAssetsUrl,
+    cssUrl
+  }
+}
+
+module.exports = { publishAssetsFromCi }

package/lib/ci/registerAppVersion.js

@@ -0,0 +1,43 @@
+"use strict"
+
+const AnearApi = require('../api/AnearApi')
+
+async function registerAppVersionFromCi({
+  appId = process.env.ANEARAPP_APP_ID,
+  version = process.env.APP_VERSION,
+  gitSha = process.env.GITHUB_SHA,
+  imageUri = process.env.IMAGE_URI,
+  assetManifestHash = process.env.ASSET_MANIFEST_HASH,
+  status = 'building'
+} = {}) {
+  if (!appId || !version) {
+    throw new Error('ANEARAPP_APP_ID and APP_VERSION are required to register an app version')
+  }
+
+  const data = await AnearApi.createAppVersion(appId, {
+    version,
+    status,
+    git_sha: gitSha,
+    image_uri: imageUri,
+    asset_manifest_hash: assetManifestHash
+  })
+
+  return data
+}
+
+async function markAppVersionStatus(appVersionId, status, extraAttrs = {}) {
+  if (!appVersionId || !status) {
+    throw new Error('appVersionId and status are required to update app version status')
+  }
+
+  const data = await AnearApi.updateAppVersion(appVersionId, {
+    status,
+    ...extraAttrs
+  })
+  return data
+}
+
+module.exports = {
+  registerAppVersionFromCi,
+  markAppVersionStatus
+}

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -58,8 +58,9 @@ const ImageAssetsUploader = require('../utils/ImageAssetsUploader')
 const FontAssetsUploader = require('../utils/FontAssetsUploader')
 const C = require('../utils/Constants')
 
-const CreateEventChannelNameTemplate = appId => `anear:${appId}:e`
+const CreateVersionedEventChannelNameTemplate = (appId, appVersion) => `anear:${appId}:v:${normalizeVersionToken(appVersion)}:e`
 const DefaultTemplatesRootDir = "./views"
+const SkipRuntimeAssetSync = process.env.ANEARAPP_SKIP_RUNTIME_ASSET_SYNC === 'true'
 
 // Process-wide signal handling.
 // We install exactly once per process to avoid duplicate handlers in reconnect/restart scenarios.
@@ -152,9 +153,21 @@ const AnearCoreServiceMachineConfig = appId => ({
             actions: ({ context }) => logger.warn(`[ACSM] Realtime connected, but shutdown already requested for app ${context.appId}; not subscribing to CREATE/LOAD commands`)
           }
         ],
-        ATTACHED: 'uploadNewImageAssets'
+        ATTACHED: 'syncAssetsOrSkip'
       }
     },
+    syncAssetsOrSkip: {
+      always: [
+        {
+          guard: 'runtimeAssetSyncDisabled',
+          actions: () => logger.info('[ACSM] Runtime asset sync disabled; assuming CI has already published assets'),
+          target: 'loadAndCompilePugTemplates'
+        },
+        {
+          target: 'uploadNewImageAssets'
+        }
+      ]
+    },
     uploadNewImageAssets: {
       invoke: {
         src: 'uploadNewImageAssets',
@@ -298,7 +311,13 @@ const AnearCoreServiceMachineFunctions = {
     createEventsCreationChannel: assign(
       {
         newEventCreationChannel: ({ context, self }) => {
-          const channelName = CreateEventChannelNameTemplate(context.appId)
+          const attrs = context.appData?.data?.attributes || {}
+          const appVersion = attrs['latest-app-version']
+          if (!appVersion) {
+            throw new Error('[ACSM] Missing latest-app-version in app data; cannot subscribe to lifecycle channel')
+          }
+          const channelName = CreateVersionedEventChannelNameTemplate(context.appId, appVersion)
+          logger.info(`[ACSM] Subscribing to versioned lifecycle channel ${channelName}`)
           return RealtimeMessaging.getChannel(channelName, self)
         }
       }
@@ -314,7 +333,7 @@ const AnearCoreServiceMachineFunctions = {
         self,
         'LOAD_EVENT'
       )
-      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on events channel (pid=${process.pid})`)
+      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on versioned lifecycle channel (pid=${process.pid})`)
     },
     logIgnoredLifecycleCommand: ({ event, context }) => {
       logger.warn(`[ACSM] Ignoring ${event.type} because shutdown has been requested (appId=${context.appId} pid=${process.pid})`)
@@ -436,10 +455,15 @@ const AnearCoreServiceMachineFunctions = {
   },
   guards: {
     noImageAssetFilesFound: ({ event }) => event.output === null,
-    acceptLifecycleCommands: ({ context }) => !context.shutdownRequested
+    acceptLifecycleCommands: ({ context }) => !context.shutdownRequested,
+    runtimeAssetSyncDisabled: () => SkipRuntimeAssetSync
   }
 }
 
+function normalizeVersionToken(value) {
+  return String(value).replace(/[^A-Za-z0-9_.-]/g, '_')
+}
+
 const AnearCoreServiceMachine = (appEventMachineFactory, appParticipantMachineFactory = null) => {
   const appId = process.env.ANEARAPP_APP_ID
   const machineConfig = AnearCoreServiceMachineConfig(appId)

package/lib/state_machines/AnearParticipantMachine.js

@@ -654,7 +654,20 @@ const AnearParticipantMachineFunctions = {
   actors: {
     publishPrivateDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
-      const displayMessage = { content: event.content }
+      let displayMessage
+      if (event.targets != null && typeof event.targets === 'object' && !Array.isArray(event.targets)) {
+        displayMessage = { targets: event.targets }
+      } else if (event.anchor != null && event.content !== undefined) {
+        const val = (event.type === 'replace' || event.type === 'append')
+          ? { content: event.content, type: event.type }
+          : event.content
+        displayMessage = { targets: { [event.anchor]: val } }
+      } else {
+        displayMessage = { content: event.content }
+      }
+      if (event.timeout != null) {
+        displayMessage.timeout = event.timeout
+      }
       EventStats.recordPublish(context.eventStats, context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       await RealtimeMessaging.publish(context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       return { timeout: event.timeout }

package/lib/utils/AppMachineTransition.js

@@ -169,37 +169,46 @@ const AppMachineTransition = (anearEvent) => {
 
       if (meta.allParticipants) {
         viewer = 'allParticipants'
-        const { viewPath, props } = _extractViewAndProps(meta.allParticipants)
-        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, meta.allParticipants.timeout)
+        const extracted = _extractViewAndProps(meta.allParticipants)
+        const config = meta.allParticipants
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, typeof config === 'object' && !Array.isArray(config) ? config.timeout : undefined)
 
-        // Extract cancel property if present
-        if (meta.allParticipants.cancel && !cancelActionType) {
-          cancelActionType = meta.allParticipants.cancel
+        if (typeof config === 'object' && !Array.isArray(config) && config.cancel && !cancelActionType) {
+          cancelActionType = config.cancel
         }
 
-        displayEvent = RenderContextBuilder.buildDisplayEvent(
-          viewPath,
-          RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
-          viewer,
-          null,
-          null,
-          props
-        )
+        if (extracted.targets && extracted.targets.length > 0) {
+          displayEvent = RenderContextBuilder.buildDisplayEventWithTargets(
+            extracted.targets,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null
+          )
+        } else {
+          displayEvent = RenderContextBuilder.buildDisplayEvent(
+            extracted.viewPath,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null,
+            extracted.props,
+            extracted.anchor,
+            extracted.type,
+            extracted.content,
+            extracted.contentType
+          )
+        }
         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,
@@ -208,27 +217,79 @@ const AppMachineTransition = (anearEvent) => {
               null
             )
 
+            const byParticipant = new Map()
             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 || {}
+              if (!participantDisplay || !participantDisplay.participantId) return
+              const participantViewPath = participantDisplay.view || participantDisplay.viewPath || null
+              const hasDirectContent = participantDisplay.content !== undefined && participantDisplay.content !== null
+              if (!participantViewPath && !hasDirectContent) return
+              const pid = participantDisplay.participantId
+              const targetSpec = {
+                viewPath: participantViewPath,
+                view: participantViewPath,
+                anchor: participantDisplay.anchor != null ? participantDisplay.anchor : null,
+                type: (participantDisplay.type === 'replace' || participantDisplay.type === 'append') ? participantDisplay.type : null,
+                props: participantDisplay.props || {},
+                content: hasDirectContent ? participantDisplay.content : null,
+                contentType: (participantDisplay.contentType === 'html' || participantDisplay.contentType === 'text') ? participantDisplay.contentType : null
+              }
+              const existing = byParticipant.get(pid)
+              if (existing) {
+                existing.targets.push(targetSpec)
+                if (participantDisplay.timeout != null && existing.timeout == null) {
+                  existing.timeout = participantDisplay.timeout
+                }
+              } else {
+                byParticipant.set(pid, {
+                  participantId: pid,
+                  targets: [targetSpec],
+                  timeout: participantDisplay.timeout ?? null
+                })
+              }
+            })
 
+            byParticipant.forEach(({ participantId: pid, targets: targetSpecs, timeout: to }) => {
+              if (targetSpecs.length === 1 && !targetSpecs[0].anchor) {
+                displayEvent = RenderContextBuilder.buildDisplayEvent(
+                  targetSpecs[0].viewPath,
+                  baseAppRenderContext,
+                  viewer,
+                  pid,
+                  to,
+                  targetSpecs[0].props,
+                  null,
+                  null,
+                  targetSpecs[0].content,
+                  targetSpecs[0].contentType
+                )
+              } else if (targetSpecs.length === 1) {
                 displayEvent = RenderContextBuilder.buildDisplayEvent(
-                  participantDisplay.view,
-                  baseAppRenderContext, // Reuse the same base context
+                  targetSpecs[0].viewPath,
+                  baseAppRenderContext,
+                  viewer,
+                  pid,
+                  to,
+                  targetSpecs[0].props,
+                  targetSpecs[0].anchor,
+                  targetSpecs[0].type,
+                  targetSpecs[0].content,
+                  targetSpecs[0].contentType
+                )
+              } else {
+                displayEvent = RenderContextBuilder.buildDisplayEventWithTargets(
+                  targetSpecs,
+                  baseAppRenderContext,
                   viewer,
-                  participantDisplay.participantId,
-                  timeout,
-                  props
+                  pid,
+                  to
                 )
-                displayEvents.push(displayEvent)
               }
+              displayEvents.push(displayEvent)
             })
           }
         } else {
           // Legacy participant rendering - normalize to selective format
-          const { viewPath, props } = _extractViewAndProps(meta.eachParticipant)
+          const { viewPath, props, anchor, type, content, contentType } = _extractViewAndProps(meta.eachParticipant)
           const timeoutFn = RenderContextBuilder.buildTimeoutFn('participant', meta.eachParticipant.timeout)
 
           // Extract cancel property if present (for legacy eachParticipant format)
@@ -243,7 +304,11 @@ const AppMachineTransition = (anearEvent) => {
             viewer,
             'ALL_PARTICIPANTS', // Special marker for "all participants"
             null,
-            props
+            props,
+            anchor,
+            type,
+            content,
+            contentType
           )
           displayEvents.push(displayEvent)
         }
@@ -251,33 +316,63 @@ const AppMachineTransition = (anearEvent) => {
 
       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
-        )
+        const extracted = _extractViewAndProps(meta.host)
+        const config = meta.host
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, typeof config === 'object' && !Array.isArray(config) ? config.timeout : undefined)
+
+        if (extracted.targets && extracted.targets.length > 0) {
+          displayEvent = RenderContextBuilder.buildDisplayEventWithTargets(
+            extracted.targets,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null
+          )
+        } else {
+          displayEvent = RenderContextBuilder.buildDisplayEvent(
+            extracted.viewPath,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null,
+            extracted.props,
+            extracted.anchor,
+            extracted.type,
+            extracted.content,
+            extracted.contentType
+          )
+        }
         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
-        )
+        const extracted = _extractViewAndProps(meta.spectators)
+        const config = meta.spectators
+        timeoutFn = RenderContextBuilder.buildTimeoutFn(viewer, typeof config === 'object' && !Array.isArray(config) ? config.timeout : undefined)
+
+        if (extracted.targets && extracted.targets.length > 0) {
+          displayEvent = RenderContextBuilder.buildDisplayEventWithTargets(
+            extracted.targets,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null
+          )
+        } else {
+          displayEvent = RenderContextBuilder.buildDisplayEvent(
+            extracted.viewPath,
+            RenderContextBuilder.buildAppRenderContext(appContext, appStateName, event.type, viewer, timeoutFn),
+            viewer,
+            null,
+            null,
+            extracted.props,
+            extracted.anchor,
+            extracted.type,
+            extracted.content,
+            extracted.contentType
+          )
+        }
         displayEvents.push(displayEvent)
       }
     })
@@ -303,20 +398,39 @@ const AppMachineTransition = (anearEvent) => {
 }
 
 const _extractViewAndProps = (config) => {
-  if (!config) return { viewPath: null, props: {} }
+  if (!config) return { viewPath: null, props: {}, anchor: null, type: null, content: null, contentType: null, targets: null }
 
   if (typeof config === 'string') {
-    return { viewPath: config, props: {} }
+    return { viewPath: config, props: {}, anchor: null, type: null, content: null, contentType: null, targets: null }
+  }
+
+  if (Array.isArray(config)) {
+    const targets = config
+      .filter(t => t && ((t.view || t.viewPath) || (t.content !== undefined && t.content !== null)))
+      .map(t => ({
+        viewPath: t.view || t.viewPath,
+        view: t.view || t.viewPath,
+        anchor: t.anchor != null ? t.anchor : null,
+        type: (t.type === 'replace' || t.type === 'append') ? t.type : null,
+        props: t.props || {},
+        content: (t.content !== undefined && t.content !== null) ? t.content : null,
+        contentType: (t.contentType === 'html' || t.contentType === 'text') ? t.contentType : null
+      }))
+    return { viewPath: null, props: {}, anchor: null, type: null, content: null, contentType: null, targets: targets.length > 0 ? targets : null }
   }
 
   if (typeof config === 'object') {
-    const viewPath = config.view
+    const viewPath = config.view || config.viewPath || null
     const props = config.props || {}
-    return { viewPath, props }
+    const anchor = config.anchor != null ? config.anchor : null
+    const type = (config.type === 'replace' || config.type === 'append') ? config.type : null
+    const content = (config.content !== undefined && config.content !== null) ? config.content : null
+    const contentType = (config.contentType === 'html' || config.contentType === 'text') ? config.contentType : null
+    return { viewPath, props, anchor, type, content, contentType, targets: null }
   }
 
   logger.warn(`[AppMachineTransition] Unknown meta format: ${JSON.stringify(config)}`)
-  return { viewPath: null, props: {} }
+  return { viewPath: null, props: {}, anchor: null, type: null, content: null, contentType: null, targets: null }
 }
 
 const _stringifiedState = (stateValue) => {

package/lib/utils/DisplayEventProcessor.js

@@ -111,32 +111,53 @@ class DisplayEventProcessor {
   }
 
   _processSingle(displayEvent) {
-    const { viewPath, appRenderContext, viewer, participantId, timeout: displayTimeout, props } = displayEvent
+    const { viewPath, targets: targetsArray, appRenderContext, viewer, participantId, timeout: displayTimeout, props, anchor, type, content, contentType } = displayEvent
     const timeoutFn = appRenderContext.meta.timeoutFn
 
-    const normalizedPath = viewPath.endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`
-    const template = this.pugTemplates[normalizedPath]
-    let publishPromise
-    let timeout = null
-
-    if (!template) {
-      throw new Error(`Template not found: ${normalizedPath}`)
-    }
-
-    const templateRenderContext = {
+    const baseContext = {
       ...appRenderContext,
       anearEvent: this.anearEvent,
       participants: this.participantsIndex,
-      ...this.pugHelpers,
-      props
+      ...this.pugHelpers
     }
 
-    const formattedDisplayMessage = () => {
-      const displayMessage = {
-        content: template(templateRenderContext),
+    const templateRenderContext = { ...baseContext, props: props || {} }
+    const normalizedPath = viewPath ? ((viewPath || '').endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`) : null
+    const template = normalizedPath ? this.pugTemplates[normalizedPath] : null
+    let publishPromise
+    let timeout = null
+
+    const formattedDisplayMessage = (contextOverrides = {}) => {
+      const ctx = { ...templateRenderContext, ...contextOverrides }
+      if (Array.isArray(targetsArray) && targetsArray.length > 0) {
+        const targetsObj = {}
+        for (const t of targetsArray) {
+          const a = t.anchor
+          if (a == null) continue
+          targetsObj[a] = this._buildTargetValue(t, ctx)
+        }
+        return { targets: targetsObj }
       }
 
-      return displayMessage
+      if (content !== null && content !== undefined) {
+        const directContent = this._stringifyContent(content)
+        if (anchor != null) {
+          return { targets: { [anchor]: this._buildTargetValue({ content: directContent, contentType, type }, ctx) } }
+        }
+        return { content: directContent }
+      }
+
+      if (!template) throw new Error(`Template not found: ${normalizedPath || viewPath || '[unknown]'}`)
+      const html = template(ctx)
+      if (anchor != null) {
+        const val = this._buildTargetValue({ content: html, contentType: contentType || 'html', type }, ctx)
+        return { targets: { [anchor]: val } }
+      }
+      return { content: html }
+    }
+
+    if (!Array.isArray(targetsArray) && content == null && !template) {
+      throw new Error(`Template not found: ${normalizedPath || viewPath || '[unknown]'}`)
     }
 
     // The viewer determines who sees the view. It can be set directly on the
@@ -146,7 +167,7 @@ class DisplayEventProcessor {
     let displaySent = false
     switch (displayViewer) {
       case 'allParticipants':
-        const templateName = normalizedPath.replace(C.PugSuffix, '')
+        const templateName = normalizedPath ? normalizedPath.replace(C.PugSuffix, '') : '[inline-content]'
         logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateName} viewer=allParticipants`)
 
         // Use display timeout if available, otherwise fall back to timeoutFn
@@ -183,7 +204,7 @@ class DisplayEventProcessor {
         break
 
       case 'spectators':
-        const templateNameSpectators = normalizedPath.replace(C.PugSuffix, '')
+        const templateNameSpectators = normalizedPath ? normalizedPath.replace(C.PugSuffix, '') : '[inline-content]'
         logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameSpectators} viewer=spectators`)
 
         // If this event/app does not support spectators, the spectatorsDisplayChannel
@@ -229,20 +250,17 @@ class DisplayEventProcessor {
         break
 
       case 'eachParticipant': {
-        const templateNameEach = normalizedPath.replace(C.PugSuffix, '')
+        const templateNameEach = (targetsArray?.[0]?.viewPath || targetsArray?.[0]?.view || normalizedPath || '[inline-content]').replace(C.PugSuffix, '')
         if (participantId === 'ALL_PARTICIPANTS') {
-          // Legacy behavior - send to all participants (uses timeoutFn)
           logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameEach} viewer=eachParticipant participantId=ALL_PARTICIPANTS`)
-          publishPromise = this._processPrivateParticipantDisplays(template, templateRenderContext, timeoutFn)
-          displaySent = true // We attempt to send to all in index; at least one may receive
+          publishPromise = this._processPrivateParticipantDisplays(template, templateRenderContext, timeoutFn, anchor, type, targetsArray, content, contentType)
+          displaySent = true
         } else if (participantId) {
-          // Selective participant rendering - send to specific participant only (uses displayTimeout)
           logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameEach} viewer=eachParticipant participantId=${participantId}`)
-          const result = this._processSelectiveParticipantDisplayWithSent(template, templateRenderContext, null, participantId, displayTimeout)
+          const result = this._processSelectiveParticipantDisplayWithSent(template, templateRenderContext, null, participantId, displayTimeout, anchor, type, targetsArray, content, contentType)
           publishPromise = result.promise
           displaySent = result.displaySent
         } else {
-          // Fallback - should not happen with unified approach
           logger.warn(`[DisplayEventProcessor] Unexpected participant display event without participantId`)
           publishPromise = Promise.resolve()
         }
@@ -250,7 +268,7 @@ class DisplayEventProcessor {
       }
 
       case 'host':
-        const templateNameHost = normalizedPath.replace(C.PugSuffix, '')
+        const templateNameHost = normalizedPath ? normalizedPath.replace(C.PugSuffix, '') : '[inline-content]'
         logger.info(`[DisplayEventProcessor] RENDER_DISPLAY template=${templateNameHost} viewer=host`)
         // Host may optionally have a real timeout (if configured). Otherwise, host
         // mirrors the allParticipants visual timer without starting a host timeout.
@@ -285,7 +303,12 @@ class DisplayEventProcessor {
         publishPromise = this._processHostDisplay(
           template,
           templateRenderContext,
-          hostOwnMsecs !== null ? (() => hostOwnMsecs) : null
+          hostOwnMsecs !== null ? (() => hostOwnMsecs) : null,
+          anchor,
+          type,
+          targetsArray,
+          content,
+          contentType
         )
         displaySent = true
         break
@@ -296,7 +319,7 @@ class DisplayEventProcessor {
     return { publishPromise, timeout, displaySent }
   }
 
-  _processHostDisplay(template, templateRenderContext, timeoutFn) {
+  _processHostDisplay(template, templateRenderContext, timeoutFn, anchor = null, type = null, targetsArray = null, content = null, contentType = null) {
     const hostEntry = Object.entries(this.participants).find(
       ([id, participantInfo]) => participantInfo.isHost
     );
@@ -311,29 +334,23 @@ class DisplayEventProcessor {
     if (!hostMachine) {
       throw new Error(`[DisplayEventProcessor] Host participant machine not found for hostId: ${hostId}`)
     }
-    this._sendPrivateDisplay(hostMachine, hostId, template, templateRenderContext, timeoutFn)
+    this._sendPrivateDisplay(hostMachine, hostId, template, templateRenderContext, timeoutFn, anchor, type, targetsArray, content, contentType)
     return Promise.resolve()
   }
 
-  _processPrivateParticipantDisplays(template, templateRenderContext, timeoutFn) {
+  _processPrivateParticipantDisplays(template, templateRenderContext, timeoutFn, anchor = null, type = null, targetsArray = null, content = null, contentType = null) {
     Object.values(this.participantsIndex.all).forEach(
       participantStruct => {
-        // Exclude the host from receiving displays targeted at all participants.
-        // Host-specific displays should use the `meta: { host: '...' }` syntax.
         if (participantStruct.info.isHost) return;
-
-        // Skip inactive participants (idle in open house events)
-        // Note: _buildParticipantsIndex already filters these out, but adding check for safety
         if (participantStruct.info.active === false) return;
 
         const participantId = participantStruct.info.id
         const participantMachine = this.participantMachines[participantId]
-        // Skip if no machine (shouldn't happen since we filter active participants, but safety check)
         if (!participantMachine) {
           logger.warn(`[DisplayEventProcessor] Participant machine not found for ${participantId}, skipping display`)
           return
         }
-        this._sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, timeoutFn)
+        this._sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, timeoutFn, anchor, type, targetsArray, content, contentType)
       }
     )
 
@@ -345,7 +362,7 @@ class DisplayEventProcessor {
    * When participant is not found (exited), we treat as delivered (displaySent: false) so the
    * render cycle can complete and we avoid infinite RENDER_DISPLAY/RENDERED loops.
    */
-  _processSelectiveParticipantDisplayWithSent(template, templateRenderContext, timeoutFn, participantId, displayTimeout = null) {
+  _processSelectiveParticipantDisplayWithSent(template, templateRenderContext, timeoutFn, participantId, displayTimeout = null, anchor = null, type = null, targetsArray = null, content = null, contentType = null) {
     const participantStruct = this.participantsIndex.get(participantId)
 
     if (!participantStruct) {
@@ -353,13 +370,11 @@ class DisplayEventProcessor {
       return { promise: Promise.resolve(), displaySent: false }
     }
 
-    // Exclude the host from receiving displays targeted at participants
     if (participantStruct.info.isHost) {
       logger.warn(`[DisplayEventProcessor] Cannot send participant display to host ${participantId}`)
       return { promise: Promise.resolve(), displaySent: false }
     }
 
-    // Skip inactive participants (idle in open house events)
     if (participantStruct.info.active === false) {
       logger.debug(`[DisplayEventProcessor] Skipping display for inactive participant ${participantId}`)
       return { promise: Promise.resolve(), displaySent: false }
@@ -371,29 +386,26 @@ class DisplayEventProcessor {
       return { promise: Promise.resolve(), displaySent: false }
     }
 
-    // Use displayTimeout if available, otherwise fall back to timeoutFn
     const effectiveTimeoutFn = displayTimeout !== null ?
       () => displayTimeout :
       timeoutFn
 
-    this._sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, effectiveTimeoutFn)
+    this._sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, effectiveTimeoutFn, anchor, type, targetsArray, content, contentType)
     return { promise: Promise.resolve(), displaySent: true }
   }
 
-  _processSelectiveParticipantDisplay(template, templateRenderContext, timeoutFn, participantId, displayTimeout = null) {
-    const { promise } = this._processSelectiveParticipantDisplayWithSent(template, templateRenderContext, timeoutFn, participantId, displayTimeout)
+  _processSelectiveParticipantDisplay(template, templateRenderContext, timeoutFn, participantId, displayTimeout = null, anchor = null, type = null, targetsArray = null, content = null, contentType = null) {
+    const { promise } = this._processSelectiveParticipantDisplayWithSent(template, templateRenderContext, timeoutFn, participantId, displayTimeout, anchor, type, targetsArray, content, contentType)
     return promise
   }
 
-  _sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, timeoutFn) {
+  _sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, timeoutFn, anchor = null, type = null, targetsArray = null, content = null, contentType = null) {
     let timeout = null
 
     const participantStruct = this.participantsIndex.get(participantId)
     const appCtx = templateRenderContext.app || {}
 
     if (timeoutFn) {
-      // For participant displays, any non-null / positive timeout value should
-      // start a real per-participant timer on that participant's APM.
       if (!participantStruct) {
         logger.warn(`[DisplayEventProcessor] Participant struct not found for ${participantId}, skipping timeout calculation`)
       } else {
@@ -402,7 +414,6 @@ class DisplayEventProcessor {
           if (typeof msecs === 'number' && msecs > 0) {
             timeout = msecs
           } else {
-            // Log when timeout function returns null/undefined to help diagnose issues
             logger.debug(`[DisplayEventProcessor] Timeout function returned ${msecs === null ? 'null' : msecs === undefined ? 'undefined' : `non-numeric value: ${msecs}`} for ${participantId}`)
           }
         } catch (error) {
@@ -415,16 +426,8 @@ class DisplayEventProcessor {
       participant: participantStruct
     }
 
-    // Build visual timeout (meta.timeout) used by the countdown bar.
-    // For participant displays we support two patterns:
-    //   1) Global participants timeout (allParticipants flow) – mirror the
-    //      shared participantsActionTimeout so EVERYONE sees the same bar,
-    //      regardless of whether their own APM is timed.
-    //   2) Per-participant timeout (eachParticipant flow) – no global timeout;
-    //      only the timed participant gets a bar, derived from their own APM.
     let visualTimeout = null
     try {
-      // First, prefer a shared participants timeout if one exists (e.g., move timer).
       const pat = this.precomputedParticipantsTimeout || this.participantsActionTimeout
       if (pat && typeof pat.msecs === 'number') {
         const now = Date.now()
@@ -432,10 +435,6 @@ class DisplayEventProcessor {
         const remainingMsecs = Math.max(0, pat.msecs - (now - start))
         visualTimeout = { msecs: pat.msecs, remainingMsecs }
       } else {
-        // Fallback: no global timeout.
-        // If this participant currently has an active APM timer, show a bar based on that.
-        // This enables "visual-only" re-renders (timeout=null) during an active wait without
-        // attempting to restart/reset the timer.
         const state = participantMachine?.state
         const ctx = state?.context
         if (ctx && ctx.actionTimeoutStart && ctx.actionTimeoutMsecs != null && ctx.actionTimeoutMsecs > 0) {
@@ -448,13 +447,11 @@ class DisplayEventProcessor {
             remainingMsecs
           }
         } else if (timeout !== null) {
-          // Backward compatibility: if we have an explicit timeout, mirror it.
           visualTimeout = { msecs: timeout, remainingMsecs: timeout }
         }
       }
     } catch (_e) {
-      // If anything goes wrong computing visualTimeout, we simply omit it and
-      // let the templates fall back to their default behavior.
+      // ignore
     }
 
     if (visualTimeout) {
@@ -464,16 +461,86 @@ class DisplayEventProcessor {
       }
     }
 
-    const privateHtml = template(privateRenderContext)
-
-    const renderMessage = { content: privateHtml }
+    let renderMessage
+    if (Array.isArray(targetsArray) && targetsArray.length > 0) {
+      const targetsObj = {}
+      for (const t of targetsArray) {
+        const a = t.anchor
+        if (a == null) continue
+        targetsObj[a] = this._buildTargetValue(t, privateRenderContext)
+      }
+      renderMessage = { targets: targetsObj }
+    } else if (content !== null && content !== undefined) {
+      const directContent = this._stringifyContent(content)
+      if (anchor != null) {
+        renderMessage = { targets: { [anchor]: this._buildTargetValue({ content: directContent, contentType, type }, privateRenderContext) } }
+      } else {
+        renderMessage = { content: directContent }
+      }
+    } else {
+      if (!template) {
+        throw new Error(`[DisplayEventProcessor] Template not found for participant ${participantId}`)
+      }
+      const privateHtml = template(privateRenderContext)
+      if (anchor != null) {
+        const val = this._buildTargetValue({ content: privateHtml, contentType: contentType || 'html', type }, privateRenderContext)
+        renderMessage = { targets: { [anchor]: val } }
+      } else {
+        renderMessage = { content: privateHtml }
+      }
+    }
     if (timeout !== null) {
       renderMessage.timeout = timeout
     }
 
-    // v5: send events as objects
     participantMachine.send({ type: 'RENDER_DISPLAY', ...renderMessage })
   }
+
+  _normalizeAnchorUpdateType(type) {
+    return (type === 'replace' || type === 'append') ? type : null
+  }
+
+  _normalizeContentType(contentType) {
+    return (contentType === 'html' || contentType === 'text') ? contentType : null
+  }
+
+  _stringifyContent(content) {
+    if (typeof content === 'string') return content
+    return String(content)
+  }
+
+  _buildTargetValue(targetSpec, baseContext) {
+    const ty = this._normalizeAnchorUpdateType(targetSpec?.type)
+    const ct = this._normalizeContentType(targetSpec?.contentType)
+
+    if (targetSpec && targetSpec.content !== null && targetSpec.content !== undefined) {
+      const directContent = this._stringifyContent(targetSpec.content)
+      if (ty || ct) {
+        const payload = { content: directContent }
+        if (ty) payload.type = ty
+        if (ct) payload.contentType = ct
+        return payload
+      }
+      return directContent
+    }
+
+    const pathSource = targetSpec?.viewPath || targetSpec?.view
+    if (!pathSource) {
+      throw new Error('[DisplayEventProcessor] Target spec requires either content or view/viewPath')
+    }
+    const path = pathSource.endsWith(C.PugSuffix) ? pathSource : `${pathSource}${C.PugSuffix}`
+    const tmpl = this.pugTemplates[path]
+    if (!tmpl) throw new Error(`Template not found: ${path}`)
+    const tCtx = { ...baseContext, props: targetSpec?.props || {} }
+    const html = tmpl(tCtx)
+    if (ty || ct) {
+      const payload = { content: html }
+      if (ty) payload.type = ty
+      if (ct) payload.contentType = ct
+      return payload
+    }
+    return html
+  }
 }
 
 module.exports = DisplayEventProcessor

package/lib/utils/RenderContextBuilder.js

@@ -57,15 +57,19 @@ class RenderContextBuilder {
 
   /**
    * Build display event object
-   * @param {string} viewPath - Template/view path
+   * @param {string|null} viewPath - Template/view path
    * @param {Object} appRenderContext - Context object
    * @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
+   * @param {string} anchor - Optional anchor name for single-anchor inject
+   * @param {string} type - Optional 'replace' | 'append' for anchor updates; default 'replace'
+   * @param {string|number|null} content - Optional direct content payload for full/anchor updates
+   * @param {string|null} contentType - Optional content kind: 'html' | 'text'
    * @returns {Object} Display event object
    */
-  static buildDisplayEvent(viewPath, appRenderContext, viewer = null, participantId = null, timeout = null, props = {}) {
+  static buildDisplayEvent(viewPath, appRenderContext, viewer = null, participantId = null, timeout = null, props = {}, anchor = null, type = null, content = null, contentType = null) {
     const displayEvent = {
       viewPath,
       appRenderContext,
@@ -84,6 +88,42 @@ class RenderContextBuilder {
       displayEvent.timeout = timeout
     }
 
+    if (anchor != null) {
+      displayEvent.anchor = anchor
+    }
+
+    if (type != null && (type === 'replace' || type === 'append')) {
+      displayEvent.type = type
+    }
+
+    if (content !== null && content !== undefined) {
+      displayEvent.content = content
+    }
+
+    if (contentType != null && (contentType === 'html' || contentType === 'text')) {
+      displayEvent.contentType = contentType
+    }
+
+    return displayEvent
+  }
+
+  /**
+   * Build display event object with multiple targets
+   * @param {Array} targets - Array of { viewPath?, anchor?, type?, props?, content?, contentType? }
+   * @param {Object} appRenderContext - Context object
+   * @param {string} viewer - Viewer type
+   * @param {string} participantId - Optional participant ID for selective rendering
+   * @param {number} timeout - Optional timeout in milliseconds
+   * @returns {Object} Display event object with targets array
+   */
+  static buildDisplayEventWithTargets(targets, appRenderContext, viewer = null, participantId = null, timeout = null) {
+    const displayEvent = {
+      targets: targets,
+      appRenderContext
+    }
+    if (viewer) displayEvent.viewer = viewer
+    if (participantId) displayEvent.participantId = participantId
+    if (timeout !== null) displayEvent.timeout = timeout
     return displayEvent
   }
 }

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "anear-js-api",
-  "version": "1.6.6",
+  "version": "2.0.1",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "audit:prod": "npm audit --omit=dev",
+    "audit:prod:fix": "npm audit fix --omit=dev",
+    "audit:full": "npm audit",
+    "audit:full:fix": "npm audit fix"
   },
   "repository": {
     "type": "git",

package/tests/AppMachineTransition.test.js

@@ -0,0 +1,57 @@
+const AppMachineTransition = require('../lib/utils/AppMachineTransition')
+
+describe('AppMachineTransition eachParticipant content targets', () => {
+  test('accepts direct content without a view in function-based eachParticipant meta', () => {
+    const anearEvent = { send: jest.fn() }
+    const onTransition = AppMachineTransition(anearEvent)
+
+    const state = {
+      context: { scoreByParticipant: { p1: 98, p2: 77 } },
+      value: 'play',
+      getMeta: () => ({
+        play: {
+          eachParticipant: (appContext) => ([
+            {
+              participantId: 'p1',
+              anchor: 'seat_p1_score',
+              content: String(appContext.scoreByParticipant.p1),
+              contentType: 'text',
+              type: 'replace'
+            },
+            {
+              participantId: 'p2',
+              anchor: 'seat_p2_score',
+              content: String(appContext.scoreByParticipant.p2),
+              contentType: 'text',
+              type: 'replace'
+            }
+          ])
+        }
+      })
+    }
+
+    onTransition(state, { type: 'TURN_COMPLETE' }, { source: 'test' })
+
+    expect(anearEvent.send).toHaveBeenCalledTimes(1)
+    const payload = anearEvent.send.mock.calls[0][0]
+    expect(payload.type).toBe('RENDER_DISPLAY')
+    expect(payload.displayEvents).toHaveLength(2)
+    expect(payload.displayEvents[0]).toMatchObject({
+      viewer: 'eachParticipant',
+      participantId: 'p1',
+      anchor: 'seat_p1_score',
+      content: '98',
+      contentType: 'text',
+      type: 'replace'
+    })
+    expect(payload.displayEvents[1]).toMatchObject({
+      viewer: 'eachParticipant',
+      participantId: 'p2',
+      anchor: 'seat_p2_score',
+      content: '77',
+      contentType: 'text',
+      type: 'replace'
+    })
+  })
+})
+

package/tests/DisplayEventProcessor.test.js

@@ -0,0 +1,87 @@
+const DisplayEventProcessor = require('../lib/utils/DisplayEventProcessor')
+
+const makeProcessor = (overrides = {}) => {
+  const participantMachine = { send: jest.fn(), state: { context: {} } }
+  const baseContext = {
+    anearEvent: {},
+    participantsActionTimeout: null,
+    pugTemplates: {},
+    pugHelpers: {},
+    participantMachines: { p1: participantMachine },
+    participantsDisplayChannel: 'participants-channel',
+    spectatorsDisplayChannel: null,
+    participants: {
+      p1: { id: 'p1', isHost: false, active: true }
+    },
+    eventStats: null,
+    ...overrides
+  }
+
+  return {
+    processor: new DisplayEventProcessor(baseContext),
+    participantMachine
+  }
+}
+
+describe('DisplayEventProcessor anchor updates', () => {
+  test('sends direct text content to an anchor for eachParticipant', () => {
+    const { processor, participantMachine } = makeProcessor()
+
+    processor._processSingle({
+      appRenderContext: { app: { score: 98 }, meta: { viewer: 'eachParticipant', timeoutFn: null } },
+      viewer: 'eachParticipant',
+      participantId: 'p1',
+      anchor: 'seat_p1_score',
+      content: 98,
+      contentType: 'text',
+      type: 'replace',
+      props: {}
+    })
+
+    expect(participantMachine.send).toHaveBeenCalledWith({
+      type: 'RENDER_DISPLAY',
+      targets: {
+        seat_p1_score: {
+          content: '98',
+          contentType: 'text',
+          type: 'replace'
+        }
+      }
+    })
+  })
+
+  test('supports multi-target participant updates mixing text and html', () => {
+    const { processor, participantMachine } = makeProcessor({
+      pugTemplates: {
+        'seat_label.pug': () => '<span>Seat A</span>'
+      }
+    })
+
+    processor._processSingle({
+      appRenderContext: { app: {}, meta: { viewer: 'eachParticipant', timeoutFn: null } },
+      viewer: 'eachParticipant',
+      participantId: 'p1',
+      targets: [
+        { anchor: 'seat_p1_score', content: 12, contentType: 'text', type: 'replace' },
+        { anchor: 'seat_p1_label', viewPath: 'seat_label', type: 'replace' }
+      ],
+      props: {}
+    })
+
+    expect(participantMachine.send).toHaveBeenCalledWith({
+      type: 'RENDER_DISPLAY',
+      targets: {
+        seat_p1_score: {
+          content: '12',
+          contentType: 'text',
+          type: 'replace'
+        },
+        seat_p1_label: {
+          content: '<span>Seat A</span>',
+          type: 'replace'
+        }
+      }
+    })
+  })
+})
+