node-red-contrib-room-tools 1.9.3 → 1.9.5

package/panel-meter.js

@@ -2,6 +2,7 @@ const crypto = require('node:crypto')
 const { createMeterReceiver } = require('./meter-frame')
 const { readJsonBody, replyJson } = require('./panel-http')
 const { meterRoute } = require('./meter-route')
+const { emitTelemetryFrame } = require('./panel-telemetry-send')
 
 function createMeterRoom ({ room, now = Date.now, staleMs = 1000 }) {
   const sources = new Map(), panels = new Map()
@@ -26,7 +27,6 @@ function createMeterRoom ({ room, now = Date.now, staleMs = 1000 }) {
       const meter = meterRoute(binding.readMeta.meter)
       const key = JSON.stringify([binding.device, meter.streamId])
       let source = sources.get(key)
-      if (source && JSON.stringify(source.route) !== JSON.stringify(meter)) throw Error('Conflicting meter stream')
       if (!source) {
         source = { device: binding.device, route: meter, receiver: null, receivedAt: null,
           revision: 0, refs: new Set(), indices: new Map() }
@@ -37,7 +37,7 @@ function createMeterRoom ({ room, now = Date.now, staleMs = 1000 }) {
     })
     const layout = { kind: 'room-meter-layout', panelId, room, epoch: crypto.randomBytes(16).toString('hex'),
       ids: points.map(([id]) => id) }
-    const panel = { projections, layout, sequence: 0 }
+    const panel = { projections, streams: [...new Set(projections.map(point => point.source))], layout, sequence: 0 }
     panels.set(panelId, panel)
     return layout
   }
@@ -100,7 +100,7 @@ function createMeterRoom ({ room, now = Date.now, staleMs = 1000 }) {
     const panel = panels.get(panelId)
     if (!panel) return ''
     const time = now()
-    return panel.projections.map(({ source }) => `${source.revision}:${source.receivedAt !== null &&
+    return panel.streams.map(source => `${source.revision}:${source.receivedAt !== null &&
       time - source.receivedAt <= staleMs}`).join(',')
   }
 
@@ -151,7 +151,7 @@ function createPanelMeter ({ panelId, room, bindings, hub, onSubscribe = () => {
     if (revision === lastRevision) return
     lastRevision = revision
     const frame = hub.snapshot(panelId)
-    for (const { socket } of subscribers.values()) emitFrame(socket, frame)
+    emitTelemetryFrame('control-panel:meter-frame', frame, subscribers)
   })
 
   return {

package/panel-momentary.js

@@ -53,7 +53,7 @@ function createMomentaryControls ({ routes, send, onError = () => {}, leaseMs =
     let record = records.get(key)
     if (!record) {
       if (records.size >= 1024) throw Error('Momentary client limit reached')
-      record = { seq: 0, active: false, target: destination(command), identity,
+      record = { seq: 0, active: false, controlId: request.id, target: destination(command), identity,
         off: resolveBoundCommand(routes, { _controlPanel: { kind: 'command', id: request.id, value: false, final: true } }) }
       records.set(key, record)
     }
@@ -62,6 +62,8 @@ function createMomentaryControls ({ routes, send, onError = () => {}, leaseMs =
     record.seq = hold.seq
     if (hold.action === 'release') release(record)
     else if (hold.action === 'start') {
+      if ([...records.values()].some(other => other.active && other.target === record.target &&
+        !Object.is(other.off.payload, record.off.payload))) throw Error('Conflicting momentary state mapping')
       const alreadyHeld = occupied(record.target)
       if (!alreadyHeld) send(command, identity)
       record.active = true
@@ -74,6 +76,10 @@ function createMomentaryControls ({ routes, send, onError = () => {}, leaseMs =
     epoch,
     handle,
     isHeld (command) { sweep(); return occupied(destination(command)) },
+    releaseControl (id) {
+      for (const record of records.values()) if (record.controlId === id) release(record)
+      schedule()
+    },
     releaseSession (token) {
       for (const [key, record] of records) {
         if (record.identity.token === token) { release(record); records.delete(key) }

package/panel-telemetry-send.js

@@ -0,0 +1,13 @@
+function emitTelemetryFrame (event, frame, subscribers) {
+  const sockets = [...subscribers.values()].map(entry => entry.socket)
+  if (!sockets.length) return
+  const namespace = sockets[0].nsp
+  // A namespace broadcast encodes once, but targets only authenticated socket IDs.
+  if (typeof namespace?.to === 'function' && sockets.every(socket => socket.nsp === namespace)) {
+    namespace.to(sockets.map(socket => socket.id)).volatile.emit(event, frame)
+  } else {
+    for (const socket of sockets) socket.volatile.emit(event, frame)
+  }
+}
+
+module.exports = { emitTelemetryFrame }

package/panel-template-instrumentation.js

@@ -66,6 +66,7 @@ function candidateAdapter (node) {
   if (tag === 'meter' || tag === 'progress') return 'meter'
   if (tag === 'canvas' && hasBoundAttribute(node, ['data-points', 'data-series'])) return 'xy-series'
   if (XY_SERIES_CONTAINER_TAGS.has(tag) && hasBoundAttribute(node, ['data-coordinates'])) return 'xy-series'
+  if (attribute(node, 'data-display-only').toLowerCase() === 'true') return null
   if (['span', 'strong', 'b', 'output', 'h1', 'h2', 'h3'].includes(tag) &&
     node.children?.length === 1 && node.children[0].type === 2 &&
     node.children[0].content.trim()) return 'text-display'

package/panel-visual-apply.js

@@ -6,6 +6,27 @@ const { configuredRoutes } = require('./control-bound-protocol')
 const { provisionManagedBridges } = require('./managed-native-bridge')
 const { backupFlow, flowLocation, runtimeDirectory } = require('./managed-bridge-admin')
 
+const snapshotCache = new Map()
+
+function snapshotCacheKey (localPort, adminRoot) {
+  return `${localPort}:${adminRoot}`
+}
+
+async function waitForEditorRoute (localPort, panelId, cookie, fetcher = fetch) {
+  if (!cookie || !Number.isInteger(localPort) || !panelId) return
+  const url = `http://127.0.0.1:${localPort}/control-panel-edit/panels/${panelId}/session`
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    try {
+      const response = await fetcher(url, {
+        headers: { Cookie: cookie },
+        signal: AbortSignal.timeout(1000)
+      })
+      if (response.ok) return
+    } catch (_) {}
+    if (attempt < 19) await new Promise(resolve => setTimeout(resolve, 150))
+  }
+}
+
 function conflict (message) {
   const error = new Error(message)
   error.status = 409
@@ -24,17 +45,38 @@ function adminUrl (localPort, adminRoot = '/red') {
   return url.href
 }
 
-async function getSnapshot (localPort, fetcher = fetch, adminRoot = '/red') {
-  const response = await fetcher(adminUrl(localPort, adminRoot), {
-    headers: { 'Node-RED-API-Version': 'v2' },
-    signal: AbortSignal.timeout(10000)
-  })
-  if (!response.ok) throw new Error(`Automator Flow read failed (${response.status})`)
-  const snapshot = await response.json()
-  if (typeof snapshot.rev !== 'string' || !Array.isArray(snapshot.flows)) {
-    throw new Error('Automator did not return a versioned Flow')
+async function getSnapshot (localPort, fetcher = fetch, adminRoot = '/red', options = {}) {
+  const key = snapshotCacheKey(localPort, adminRoot)
+  const cached = snapshotCache.get(key)
+  const now = Date.now()
+  if (cached && typeof options.expectedRev === 'string' && cached.snapshot.rev === options.expectedRev) {
+    return cached.snapshot
+  }
+  if (cached && Number.isFinite(options.maxAgeMs) && now - cached.time <= options.maxAgeMs) {
+    return cached.snapshot
+  }
+  try {
+    const response = await fetcher(adminUrl(localPort, adminRoot), {
+      headers: { 'Node-RED-API-Version': 'v2' },
+      signal: AbortSignal.timeout(10000)
+    })
+    if (!response.ok) throw new Error(`Automator Flow read failed (${response.status})`)
+    const snapshot = await response.json()
+    if (typeof snapshot.rev !== 'string' || !Array.isArray(snapshot.flows)) {
+      throw new Error('Automator did not return a versioned Flow')
+    }
+    snapshotCache.set(key, { snapshot, time: Date.now() })
+    return snapshot
+  } catch (error) {
+    const isTimeout = error?.name === 'TimeoutError' || error?.code === 'ABORT_ERR' ||
+      /aborted.*timeout/i.test(String(error?.message || ''))
+    if (isTimeout && cached && Number.isFinite(options.allowStaleMs) &&
+      Date.now() - cached.time <= options.allowStaleMs) {
+      return cached.snapshot
+    }
+    if (isTimeout) throw new Error('Automator Flow is still restarting; retry in a moment')
+    throw error
   }
-  return snapshot
 }
 
 function findPanel (snapshot, panelId) {
@@ -65,12 +107,15 @@ function editorConfig (snapshot, panelId) {
 
 async function applyVisualBindings ({
   panelId, rev, templateHash, entries, userDir, localPort, adminRoot = '/red',
-  catalogBase, fetcher = fetch
+  catalogBase, editorCookie, fetcher = fetch
 }) {
   // The editor authenticates the browser; Flow access stays on the runtime's loopback interface.
   const directory = runtimeDirectory(userDir)
   if (!catalogBase) throw conflict('Device catalog is unavailable')
-  const snapshot = await getSnapshot(localPort, fetcher, adminRoot)
+  if (!Array.isArray(entries) || entries.length > 256) throw conflict('Invalid binding draft')
+  const [snapshot, devices] = await Promise.all([
+    getSnapshot(localPort, fetcher, adminRoot, { expectedRev: rev }), listCatalogDevices(catalogBase, fetcher)
+  ])
   if (snapshot.rev !== rev) throw conflict('Flow changed; refresh the visual editor')
   const panel = findPanel(snapshot, panelId)
   if (inspectTemplate(panel.format).templateHash !== templateHash) {
@@ -81,8 +126,6 @@ async function applyVisualBindings ({
     throw conflict('Deployed Flow differs from the active project file')
   }
 
-  const devices = await listCatalogDevices(catalogBase, fetcher)
-  if (!Array.isArray(entries) || entries.length > 256) throw conflict('Invalid binding draft')
   const deviceIds = [...new Set(entries.map(entry => entry?.device))]
   for (const id of deviceIds) {
     if (!devices.some(device => device.id === id && device.online)) {
@@ -98,11 +141,23 @@ async function applyVisualBindings ({
   nextPanel.nativeBridge = configuredRoutes(nextPanel).size > 0
   const provisioned = provisionManagedBridges(next, { panelId })
 
-  const latest = await getSnapshot(localPort, fetcher, adminRoot)
-  if (latest.rev !== snapshot.rev) throw conflict('Flow changed during validation; refresh and retry')
   if (JSON.stringify(JSON.parse(fs.readFileSync(location.flowFile, 'utf8'))) !== JSON.stringify(snapshot.flows)) {
     throw conflict('Active project changed during validation')
   }
+  // Node order is not a Flow change. An unchanged draft must not restart the
+  // panel and its bridge just because provisioning moved generated nodes.
+  const currentNodes = new Map(snapshot.flows.map(node => [node.id, node]))
+  if (currentNodes.size === snapshot.flows.length && provisioned.flows.length === snapshot.flows.length &&
+    provisioned.flows.every(node => JSON.stringify(node) === JSON.stringify(currentNodes.get(node.id)))) {
+    return {
+      ok: true,
+      rev: snapshot.rev,
+      updated: [],
+      unchanged: true,
+      editorConfig: editorConfig(snapshot, panelId),
+      devices
+    }
+  }
   const backupDir = backupFlow(location, snapshot.rev, snapshot.flows)
   const response = await fetcher(adminUrl(localPort, adminRoot), {
     method: 'POST',
@@ -116,18 +171,22 @@ async function applyVisualBindings ({
   })
   if (!response.ok) throw conflict(`Automator rejected the binding update (${response.status})`)
   const applied = await response.json().catch(() => ({}))
-  let confirmed
-  for (let attempt = 0; attempt < 5; attempt++) {
-    confirmed = await getSnapshot(localPort, fetcher, adminRoot)
-    const confirmedPanel = confirmed.flows.find(node => node.id === panelId)
-    if (confirmedPanel?.visualBindings === nextPanel.visualBindings &&
-      confirmedPanel.bridgeRevisionApplied === provisioned.flows.find(node => node.id === panelId)?.bridgeRevisionApplied) {
-      return { ok: true, rev: confirmed.rev, backupDir, updated: provisioned.updated }
-    }
-    if (confirmed.rev !== snapshot.rev && confirmed.rev !== applied.rev) break
-    if (attempt < 4) await new Promise(resolve => setTimeout(resolve, 200))
+  // The v2 Flow POST is the runtime acknowledgement. Avoid rereading the
+  // complete Flow repeatedly while modified nodes are still restarting.
+  const appliedRev = typeof applied.rev === 'string' ? applied.rev : snapshot.rev
+  snapshotCache.set(snapshotCacheKey(localPort, adminRoot), {
+    snapshot: { rev: appliedRev, flows: provisioned.flows },
+    time: Date.now()
+  })
+  await waitForEditorRoute(localPort, panelId, editorCookie, fetcher)
+  return {
+    ok: true,
+    rev: appliedRev,
+    backupDir,
+    updated: provisioned.updated,
+    editorConfig: editorConfig({ rev: appliedRev, flows: provisioned.flows }, panelId),
+    devices
   }
-  throw conflict('Automator did not confirm the binding update; refresh before retrying')
 }
 
 module.exports = { adminUrl, applyVisualBindings, editorConfig, getSnapshot }

package/panel-visual-bindings.js

@@ -1,11 +1,10 @@
 const { inspectTemplate } = require('./panel-template-instrumentation')
-const { compatibleTarget, controlTypeForAdapter, targetMeta } = require('./control-type-model')
+const { compatibleTarget, controlTypeForAdapter, targetMeta, bindingModes, switchMapping, stateReverse, isMeterTarget } = require('./control-type-model')
 const { meterRoute } = require('./meter-route')
 const { xySeriesRoute } = require('./xy-series-route')
 
 const ID = /^[A-Za-z][A-Za-z0-9._/-]{0,127}$/
 const INSTANCE_KEY = /^[A-Za-z0-9._:/-]{1,160}$/
-const MODES = new Set(['read', 'write', 'both'])
 
 function buttonBehavior (entry, candidate) {
   const behavior = entry.buttonBehavior ?? 'toggle'
@@ -56,10 +55,19 @@ function visualRoutes (config) {
     }
     if (usedLocators.has(bindingKey)) throw new Error(`Duplicate visual control locator: ${id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(entry.mode) || !entry.type || !entry.label ||
-      (['meter', 'xy-series', 'text-display'].includes(entry.adapter) && entry.mode !== 'read')) {
+    if (!bindingModes(entry.adapter).includes(entry.mode) || !entry.type || !entry.label) {
       throw new Error(`Invalid visual binding settings: ${id}`)
     }
+    if (entry.adapter === 'meter' && (entry.type !== 'meter' || entry.mode !== 'read' ||
+      !entry.readPath || entry.writePath || entry.writeMeta || !entry.readMeta || !isMeterTarget(entry.readMeta))) {
+      throw Error(`Invalid readonly meter binding: ${id}`)
+    }
+    if (entry.adapter === 'range' && [entry.writeMeta, entry.readMeta].some(meta => meta && isMeterTarget(meta))) {
+      throw Error(`Numeric controls cannot bind to readonly meter targets: ${id}`)
+    }
+    for (const meta of [entry.readMeta, entry.writeMeta]) {
+      if (meta?.availability) require('./device-availability').availabilityRoute(meta.availability)
+    }
     if (entry.readMeta?.meter) {
       meterRoute(entry.readMeta.meter)
       if (entry.adapter !== 'meter' || entry.mode !== 'read' || entry.readMeta.access !== 'ro' ||
@@ -93,6 +101,7 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
   const used = new Set()
   const usedLocators = new Set()
   const models = new Map()
+  const targetIndexes = new Map()
   for (const raw of entries) {
     if (!raw || !ID.test(raw.id) || used.has(raw.id)) throw new Error('Control IDs must be unique and valid')
     used.add(raw.id)
@@ -102,7 +111,7 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     const behavior = buttonBehavior(raw, candidate)
     if (usedLocators.has(bindingKey)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(raw.mode) || (['meter', 'xy-series', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
+    if (!bindingModes(raw.adapter).includes(raw.mode)) {
       throw new Error(`Invalid binding mode: ${raw.id}`)
     }
     if (typeof raw.label !== 'string' || !raw.label.trim() || raw.label.length > 80) {
@@ -111,7 +120,8 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     if (!knownDevices.has(raw.device)) throw new Error(`Unknown device: ${raw.id}`)
     const targets = targetsByDevice.get(raw.device)
     if (!targets) throw new Error(`Device catalog unavailable: ${raw.device}`)
-    const byPath = new Map(targets.map(target => [target.path, target]))
+    if (!targetIndexes.has(raw.device)) targetIndexes.set(raw.device, new Map(targets.map(target => [target.path, target])))
+    const byPath = targetIndexes.get(raw.device)
     const write = raw.mode === 'read' ? null : byPath.get(raw.writePath)
     const read = raw.mode === 'write' ? null : byPath.get(raw.readPath)
     if ((raw.mode !== 'read' && !write) || (raw.mode !== 'write' && !read)) {
@@ -124,6 +134,7 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     }
     const target = write || read
     const type = controlTypeForAdapter(raw.adapter, target)
+    const reverse = raw.adapter === 'switch' ? stateReverse(raw, write, read) : undefined
     if (read?.meter && (!Number.isFinite(read.min) || !Number.isFinite(read.max) || read.min >= read.max)) {
       throw Error(`Meter needs a finite device range: ${raw.id}`)
     }
@@ -131,14 +142,16 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
       const identity = JSON.stringify([raw.device, read?.path, write?.path])
       const modelKey = candidate.repeat ? `${candidate.model}#${raw.instanceKey}` : candidate.model
       const previous = models.get(modelKey)
-      if (previous && (read?.meter || previous.meter) && previous.identity !== identity) {
-        throw Error(`Meter model "${candidate.model}" is already used by another binding; use a separate Vue model for the meter. Meter and volume controls must not share a model`)
+      const realtime = raw.adapter === 'meter' || raw.adapter === 'xy-series'
+      if (previous && (realtime || previous.realtime) && previous.identity !== identity) {
+        throw Error(`Realtime model "${candidate.model}" is already used by another binding; use a separate Vue model for each independent telemetry target`)
       }
-      models.set(modelKey, { identity, meter: Boolean(read?.meter) })
+      models.set(modelKey, { identity, realtime })
     }
     result[raw.id] = {
       locator: raw.locator, adapter: raw.adapter, type, label: raw.label.trim(), mode: raw.mode,
       ...(candidate.button ? { buttonBehavior: behavior } : {}),
+      ...(raw.adapter === 'switch' ? { stateReverse: reverse } : {}),
       ...(candidate.model ? { model: candidate.model } : {}),
       ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: raw.instanceKey } : {}),
       ...(candidate.component ? { component: candidate.component } : {}),
@@ -146,8 +159,10 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
         ? { uiRange: { min: candidate.min, max: candidate.max, step: candidate.step } } : {}),
       device: raw.device,
       writePath: write?.path || '', readPath: read?.path || '',
-      ...(write ? { writeMeta: targetMeta(write, raw.onebased) } : {}),
-      ...(read ? { readMeta: targetMeta(read, raw.onebased) } : {})
+      ...(write ? { writeMeta: targetMeta(write, raw.onebased,
+        raw.adapter === 'switch' ? switchMapping(write, undefined, reverse) : undefined) } : {}),
+      ...(read ? { readMeta: targetMeta(read, raw.onebased,
+        raw.adapter === 'switch' ? switchMapping(read, undefined, reverse) : undefined) } : {})
     }
   }
   return result

package/panel-xy-series.js

@@ -2,6 +2,7 @@ const crypto = require('node:crypto')
 const { createXYSeriesReceiver } = require('./xy-series-frame')
 const { readJsonBody, replyJson } = require('./panel-http')
 const { xySeriesRoute } = require('./xy-series-route')
+const { emitTelemetryFrame } = require('./panel-telemetry-send')
 
 function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
   const sources = new Map(), panels = new Map(), ticks = new Set()
@@ -12,13 +13,21 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     const entries = Object.entries(bindings).filter(([, entry]) => entry.readMeta?.xySeries)
       .sort(([a], [b]) => a.localeCompare(b))
     if (!entries.length || entries.length > 256) throw Error('Invalid xy-series panel size')
-    const projections = entries.map(([id, binding]) => {
+    // Validate the whole registration before changing shared sources or references.
+    const proposed = new Map()
+    for (const [, binding] of entries) {
       const series = xySeriesRoute(binding.readMeta.xySeries)
       const key = JSON.stringify([binding.device, series.streamId])
-      let source = sources.get(key)
-      if (source && JSON.stringify(source.route) !== JSON.stringify(series)) {
+      const previous = sources.get(key)?.route || proposed.get(key)
+      if (previous && JSON.stringify(previous) !== JSON.stringify(series)) {
         throw Error(`Conflicting xy-series stream: ${series.streamId}`)
       }
+      proposed.set(key, series)
+    }
+    const projections = entries.map(([id, binding]) => {
+      const series = xySeriesRoute(binding.readMeta.xySeries)
+      const key = JSON.stringify([binding.device, series.streamId])
+      let source = sources.get(key)
       if (!source) {
         source = { device: binding.device, route: series, receiver: null,
           receivedAt: null, revision: 0, refs: new Set() }
@@ -29,7 +38,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     })
     const layout = { kind: 'room-xy-series-layout', panelId, room,
       epoch: crypto.randomBytes(16).toString('hex'), ids: entries.map(([id]) => id) }
-    panels.set(panelId, { projections, layout, sequence: 0 })
+    panels.set(panelId, { projections, streams: [...new Set(projections.map(point => point.source))], layout, sequence: 0 })
     return layout
   }
 
@@ -69,7 +78,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
       const frame = source.receiver?.snapshot()
       const age = source.receivedAt === null ? null : Math.max(0, time - source.receivedAt)
       const ok = Boolean(frame && age !== null && age <= staleMs)
-      values.push(ok ? frame.points.map(point => point.slice()) : [])
+      values.push(ok ? frame.points.map(point => [point[0], point[1]]) : [])
       valid.push(ok)
       sourcesByStream.set(key, { device: source.device, streamId: source.route.streamId,
         epoch: source.receiver?.manifest.epoch || '', seq: frame?.seq || 0,
@@ -83,7 +92,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     const panel = panels.get(panelId)
     if (!panel) return ''
     const time = now()
-    return panel.projections.map(({ source }) => `${source.revision}:${source.receivedAt !== null &&
+    return panel.streams.map(source => `${source.revision}:${source.receivedAt !== null &&
       time - source.receivedAt <= staleMs}`).join(',')
   }
 
@@ -133,7 +142,7 @@ function createPanelXYSeries ({ panelId, room, bindings, hub, onSubscribe = () =
     if (revision === lastRevision) return
     lastRevision = revision
     const frame = hub.snapshot(panelId)
-    for (const { socket } of subscribers.values()) emitFrame(socket, frame)
+    emitTelemetryFrame('control-panel:xy-series-frame', frame, subscribers)
   })
   return {
     async ticket (req, res, identity, active) {

package/xy-series-frame.js

@@ -85,8 +85,14 @@ function createRoomXYSeriesReceiver (layout) {
           (valid && points.some(point => !Array.isArray(point) || point.length !== 2 ||
             !finite(point[0]) || !finite(point[1])))) return false
       }
-      latest = { values: frame.values.map(points => points.map(point => point.slice())),
-        valid: frame.valid.slice(), seq: frame.seq }
+      if (frame.sources !== undefined && (!Array.isArray(frame.sources) || frame.sources.length > 256 ||
+        frame.sources.some(source => typeof source?.device !== 'string' || source.device.length > 128 ||
+          typeof source.streamId !== 'string' || source.streamId.length > 128 ||
+          typeof source.epoch !== 'string' || source.epoch.length > 128 ||
+          !Number.isSafeInteger(source.seq) || source.seq < 0))) return false
+      latest = { values: frame.values.map(points => points.map(point => [point[0], point[1]])),
+        valid: frame.valid.slice(), seq: frame.seq,
+        ...(frame.sources ? { sources: frame.sources.map(({ device, streamId, epoch, seq }) => ({ device, streamId, epoch, seq })) } : {}) }
       pending = true
       return true
     },