node-red-contrib-room-tools 1.9.0 → 1.9.1

package/CONTROL_PANEL_AI_GUIDE.md

@@ -1,6 +1,6 @@
 # ControlPanel 前端页面编写指南
 
-适用基线：当前统一工程中的 `node-red-contrib-room-tools@1.8.16`、Dashboard 2 和 Vue Options API。
+适用基线：当前统一工程中的 `node-red-contrib-room-tools@1.9.1`、Dashboard 2 和 Vue Options API。
 
 本文件是给页面编写 AI 的实现契约，不是完整的 Vue 或 Vuetify 手册。目标是：页面作者只写普通 HTML、CSS 和 Vue 页面；设备、驱动、映射表、反馈订阅和通信细节全部由 `ControlPanel` 节点处理。
 
@@ -26,6 +26,7 @@
 
 - `volume` 等普通数值字段用于音量/增益等可写连续控制，并可接收普通真实值反馈。
 - `meter` 等字段用于只读实时信号电平，只能接收驱动声明了 Meter 元数据的点位。
+- `series`、`spectrum` 等数组字段用于只读实时二维点列，只能接收驱动声明了 XY-series 元数据的点位。
 
 不要把同一个模型字段同时用于不同设备点位，尤其不要让 Meter 和 Volume 共用一个模型。
 
@@ -71,11 +72,29 @@ export default {
 | 文本控制 | `input[type=text]`、`textarea` | `v-text-field`、`v-textarea` | 字符串；原生控件在 change 时提交，Vuetify 文本框在 change、失焦时提交，`v-text-field` 也支持 Enter 提交。 |
 | 普通只读反馈 | `span`、`output` 等简单文本展示 | 暂无专用组件 | 只读普通反馈，不发送命令。 |
 | 实时信号电平 Meter | `meter`、`progress` | `v-progress-linear`、`v-progress-circular` | 只读数值；必须绑定驱动的 Meter 点位，不发送命令。 |
+| 实时二维点列 XY-series | `canvas` + `:data-points` 或 `:data-series`；地图容器 + `:data-coordinates` | 第三方图表暂不自动识别 | 只读 `[[x, y], ...]` 数组；不发送命令。 |
 
 交互控件建议写简单顶层 `v-model`。原生 range/select 可以使用 `.number`；不要给布尔、文本或 Meter 加 `.number`。Vuetify 进度组件可以使用简单 `v-model`，也可以使用简单 `:model-value`。原生 Meter/Progress 可以使用简单顶层 `v-model`，节点会把它转换成只读 `:value`；在 `v-for` 列表中应直接写 `:value="item.meter"`，不要写嵌套字段的原生 `v-model`。
 
 初始化值应匹配控件类型：数值为数字，开关为布尔值，文本和枚举为字符串。不要用数组、对象或 `null` 作为普通绑定控件的占位值。
 
+XY-series 使用数组字段初始化，例如 `spectrum: []`。推荐使用标准 Canvas：
+
+```html
+<canvas id="room-spectrum" :data-points="spectrum" aria-label="实时频谱"></canvas>
+```
+
+地图坐标使用普通 HTML 容器和标准地理坐标顺序 `[经度, 纬度]`：
+
+```html
+<div id="room-map" class="room-map"
+  :data-coordinates="locations" aria-label="实时位置"></div>
+```
+
+`locations` 的值也是完整快照，例如 `[[116.397, 39.908], [121.473, 31.230]]`。节点只负责把驱动的二维数组更新到这个普通 Vue 数组；地图底图、投影、标记和缩放属于页面自己的显示逻辑。当前自动识别支持 `div`、`section`、`article`、`main`、`aside`、`svg` 和 `g` 上的 `:data-coordinates`，不要求页面引入地图 SDK，也不要求页面知道驱动或订阅机制。
+
+节点会把每个完整帧更新到 `spectrum` 或 `locations`，页面自己的绘图逻辑可以观察这个普通 Vue 数组。`data-points`、`data-series` 和 `data-coordinates` 都是普通 HTML `data-*` 属性，不是 ControlPanel 私有属性。Canvas 的频谱点列与地图坐标只是页面呈现语义不同，底层使用同一个只读 XY-series 通道。当前自动识别只支持顶层简单字段，不支持 `v-for` 内的二维点列模型、函数调用、表达式、多个数据源合并或第三方图表组件的专用数据格式。
+
 ### 3.1 普通控件写法
 
 ```html
@@ -240,6 +259,17 @@ Meter 是驱动端的特殊只读数据类型，不是“另一个滑杆”。
 <output id="room-value">{{ outputValue }}</output>
 ```
 
+## 4.1 XY-series 与普通实时数组反馈
+
+XY-series 是 Meter 的独立数组版本，不是多个 Meter 的替代写法：
+
+- 每个驱动帧是一个完整的 `[[x, y], ...]` 快照，第一层长度可以变化，也可以是空数组。
+- 每个点必须恰好有两个有限数字；节点保留点的顺序，不自动排序、不自动缩放、不自动丢弃旧点。
+- 数据只读，绑定只能使用 `read` 模式，没有 Write point；它与 Volume、Level 和 Meter 不能共用同一个模型字段。
+- 多个页面绑定相同 stream 时只建立一个源订阅，页面帧使用 latest-wins；网络拥塞时允许丢弃旧帧，不补发历史帧。
+- 当前每个 stream 默认最多 8192 个点，每个面板最多 256 个 XY-series 绑定；真实 MUSE 测试前仍需按点数和帧大小验证吞吐。
+- 页面作者不写 socket、订阅、帧解析或重连代码，只维护普通数组。频谱坐标轴、Canvas 绘制、坐标变换和图表样式属于页面显示逻辑。
+
 文本展示只使用一个简单字段插值，例如 `{{ status }}` 或 `{{ outputValue }}`。不要使用 `toFixed()`、拼接表达式或多个插值作为绑定模型。
 
 ## 5. 语义开关按钮
@@ -277,6 +307,7 @@ Template 修改可能使已有映射失效。重新 Deploy 后，应重新打开
 | 可写 integer/float | range 或 `v-slider`；用于音量/增益等普通连续控制。 |
 | 只读 integer/float，没有 Meter 元数据 | 文本展示等普通只读反馈，不能选择为 Meter。 |
 | 只读 integer/float，带有效 `.metadata.meter` | Meter、原生 `meter`/`progress` 或 Vuetify 进度组件；只能读。 |
+| 只读参数，带有效 `.metadata.xySeries` | XY-series；使用标准 Canvas 的 `:data-points`/`:data-series`，或地图容器的 `:data-coordinates` 数组字段；只能读。 |
 | enum，或带枚举描述的 integer/string | 单选枚举。 |
 | 没有枚举但路径以 `/source` 或 `/preset` 结尾的 integer | 选择类参数，仍需确认合法选项。 |
 | string/dstring | 文本输入或文本展示。 |
@@ -293,6 +324,7 @@ Write point 改动时 Feedback point 会跟随；单独改 Feedback point 不会
 | `v-for` 实例没有出现 | 来源是否是顶层数组；key 是否严格符合对象/数组规则；列表项是否实际渲染且 key 唯一。 |
 | 设备有了但点位为空 | 设备在线状态、AMX 参数目录、`kind/type/access` 和读写权限；不是所有命令都属于可绑定参数。 |
 | Meter 可以选但无值 | 点位是否带 `.metadata.meter`；驱动是否实际发布 manifest 和 frame；页面字段是否与普通 Volume 分开。 |
+| XY-series 可以选但无值 | 点位是否带 `.metadata.xySeries`；驱动是否发布对应 manifest/frame；数组字段是否为顶层数组；检查点数、帧大小和过期状态。 |
 | 页面一直 Loading | 查看模板编译错误，重点检查原生 Meter/Progress 的 v-model 写法、自闭合 Vuetify、动态表达式和不支持的组件。设备离线不应被页面作者通过轮询“修复”。 |
 | 滑杆动不了 | 是否仍处于 Select 编辑模式；模型是否为数字；是否给绑定控件添加了自己的事件或回写逻辑。 |
 | 页面变化但设备不变 | 检查映射的 Write point、设备权限和运行日志。前端模型变化不等于设备已确认执行。 |
@@ -307,6 +339,8 @@ Write point 改动时 Feedback point 会跟随；单独改 Feedback point 不会
 - 所有待绑定控件位于支持清单，模型字段简单、独立、可写且类型正确。
 - 列表只使用本指南规定的 `v-for`、`:key` 和模型路径；对象 key 稳定唯一，数组 key 使用 index。
 - 列表内的 Meter、Volume 和其他控件使用不同模型字段；重复实例依靠稳定 key 区分，不生成随机 ID。
+- XY-series 使用独立的顶层数组字段，例如 `spectrum: []`，不要与 Meter、Volume 或普通反馈字段共用。
+- 地图坐标使用独立的顶层数组字段，例如 `locations: []`，点顺序固定为 `[经度, 纬度]`；不要与 Meter、Volume 或普通反馈字段共用。
 - 页面量程明确、数值常量有效；枚举选项与实际设备值对应。
 - 没有手写 `data-cp-*`、设备通信、轮询、反馈回写、绑定控件事件或第二套发送逻辑。
 - 实时表头仍是普通 HTML/Vue/Vuetify 控件；没有 stream、socket、订阅、帧协议或驱动代码。

package/README.md

@@ -14,6 +14,8 @@ Supported controls include native range, checkbox, semantic pressed button, sele
 
 Realtime meter delivery does not change the page-authoring contract. Authors use ordinary `meter`, `progress`, `v-progress-linear`, or `v-progress-circular` controls with stable IDs and simple top-level fields. They do not declare devices, point paths, stream IDs, sockets, subscriptions, or frame formats. A `volume` binding is a writable gain setting with ordinary feedback; a `meter` binding is read-only realtime signal telemetry and requires a target that advertises Meter metadata. A normal numeric `level` target is not automatically a Meter. When the selected feedback point advertises realtime meter delivery, ControlPanel automatically shares the device stream, projects complete frames to the bound controls, applies webpage-side range conversion, and handles stale/reconnected data.
 
+Readonly XY-series telemetry follows the same page boundary. Use a standard canvas with one simple Vue array binding, for example `<canvas id="spectrum" :data-points="spectrum"></canvas>`, or a map container with `<div id="room-map" :data-coordinates="locations"></div>`. Map coordinates use the standard `[longitude, latitude]` order. The page receives complete `[[x, y], ...]` snapshots; ControlPanel owns subscription, latest-frame replacement, stale handling, and reconnection. The page does not declare a device, stream, socket, or frame protocol. XY-series is independent from Meter and Volume: it never sends commands and does not represent a single scalar value.
+
 Vuetify adapters cover `v-slider`, `v-switch`, `v-checkbox`, `v-select`, `v-radio-group`, `v-text-field`, `v-textarea`, and read-only `v-progress-linear` and `v-progress-circular`. Interactive components use a simple top-level `v-model`; progress may also use a simple `:model-value` field. Sliders accept fixed numeric `min`, `max`, and `step` props, including numeric Vue bindings such as `:max="100"`. Text fields commit on change, blur, or Enter (`v-text-field` only). Selection values must match the device's enum values; circular progress uses a fixed 0-100 range. `v-model.number` is accepted for numeric sliders and scalar selections, but not for boolean or text controls. Dynamic bounds, array-valued switches, multi-select, object selections, custom true/false values, indeterminate progress, and controls with their own event handlers need a separate adapter.
 
 Use paired Vuetify tags in Dashboard templates, such as `<v-slider></v-slider>`; self-closing component tags can absorb the following controls during Dashboard rendering and are rejected before deployment.

package/control-catalog.js

@@ -1,6 +1,7 @@
 const { schemaVersion } = require('./control-type-contract.json')
 const { runtimeJsonRequest } = require('./panel-http')
 const { meterRoute } = require('./meter-route')
+const { xySeriesRoute } = require('./xy-series-route')
 
 function catalogBase (settings) {
   const port = Number(settings?.uiPort)
@@ -75,6 +76,7 @@ async function listCatalogTargets (base, device, fetcher = fetch) {
     const max = catalogBound(properties['.max'])
     const enums = properties['.enums']
     const meter = properties['.metadata']?.meter ? meterRoute(properties['.metadata'].meter) : null
+    const xySeries = properties['.metadata']?.xySeries ? xySeriesRoute(properties['.metadata'].xySeries) : null
     return {
       path: item.path,
       kind: properties['.kind'] || '',
@@ -83,10 +85,11 @@ async function listCatalogTargets (base, device, fetcher = fetch) {
       onebased: typeof properties['.onebased'] === 'boolean' ? properties['.onebased']
         : typeof item.onebased === 'boolean' ? item.onebased : undefined,
       min, max, enums,
-      ...(meter ? { controlType: 'meter' } : inferredControl(item.path, properties, type, min, max, enums)),
+      ...(meter ? { controlType: 'meter' } : xySeries ? { controlType: 'xy-series' } : inferredControl(item.path, properties, type, min, max, enums)),
       controlSchemaVersion: schemaVersion,
       unit: properties['.metadata']?.unit || '',
-      ...(meter ? { meter } : {})
+      ...(meter ? { meter } : {}),
+      ...(xySeries ? { xySeries } : {})
     }
   })
   const unique = new Map()

package/control-panel.js

@@ -11,6 +11,7 @@ const { applyVisualBindings, editorConfig, getSnapshot } = require('./panel-visu
 const { createGateway } = require('./gateway.cjs')
 const { managedBridgeRevision } = require('./managed-bridge-revision')
 const { createMeterRoom, createPanelMeter } = require('./panel-meter')
+const { createXYSeriesRoom, createPanelXYSeries } = require('./panel-xy-series')
 
 let statestore
 const authHandoffKey = crypto.randomBytes(32)
@@ -71,6 +72,7 @@ module.exports = function (RED) {
   const activePanels = new Map()
   const activeEditors = new Map()
   const meterRooms = new Map()
+  const xySeriesRooms = new Map()
   RED.httpAdmin.get('/ui-control-panel/editor-sync.js', RED.auth.needsPermission('nodes.read'), (_req, res) => {
     res.setHeader('Cache-Control', 'no-store')
     res.sendFile(path.join(__dirname, 'panel-flow-editor-sync.js'))
@@ -159,6 +161,16 @@ module.exports = function (RED) {
       } catch (error) { node.error(error) }
     }
 
+    let xySeries
+    if ([...routes.values()].some(route => route.binding.readMeta?.xySeries) && /^[a-zA-Z0-9_-]+$/.test(boundRoom || '')) {
+      try {
+        let hub = xySeriesRooms.get(boundRoom)
+        if (!hub) { hub = createXYSeriesRoom({ room: boundRoom }); xySeriesRooms.set(boundRoom, hub) }
+        xySeries = createPanelXYSeries({ panelId: node.id, room: boundRoom, bindings: visualBindings, hub,
+          onSubscribe: () => { if (bridgeReady) node.send({ kind: 'read-all', room: boundRoom }) } })
+      } catch (error) { node.error(error) }
+    }
+
     let gateway
     let gatewayAuthKey
     if (visualBinding && /^[a-zA-Z0-9_-]+$/.test(boundRoom || '')) {
@@ -173,7 +185,8 @@ module.exports = function (RED) {
           secureCookie: config.secureCookie === true,
           restoredSessions: takeSessions(gatewayHandoffs, node.id, gatewayAuthKey),
           onAuthenticatedRequest: (req, res, identity) => meter?.ticket(req, res, identity,
-            () => gateway?.sessionActive(identity.token)) || false,
+            () => gateway?.sessionActive(identity.token)) || xySeries?.ticket(req, res, identity,
+              () => gateway?.sessionActive(identity.token)) || false,
           onBoundCommand: (message, identity) => {
             if (!bridgeReady) return false
             node.send({ ...resolveBoundCommand(routes, message), room: identity.room, user: identity.user })
@@ -203,7 +216,8 @@ module.exports = function (RED) {
         secureCookie: config.secureCookie === true,
         restoredSessions: takeSessions(editorHandoffs, node.id, editorAuthKey),
         onAuthenticatedRequest: (req, res, identity) => meter?.ticket(req, res, identity,
-          () => editor?.sessionActive(identity.token)) || false,
+          () => editor?.sessionActive(identity.token)) || xySeries?.ticket(req, res, identity,
+            () => editor?.sessionActive(identity.token)) || false,
         getConfig: async req => editorConfig(await getSnapshot(req.socket.localPort, fetch,
           RED.settings.httpAdminRoot ?? '/'), node.id),
         getDevices: async () => {
@@ -230,7 +244,7 @@ module.exports = function (RED) {
     }
 
     const panelConfig = () => (boundMode || visualBinding) ? {
-      endpoint, room: boundRoom, meter: Boolean(meter),
+      endpoint, room: boundRoom, meter: Boolean(meter), xySeries: Boolean(xySeries),
       ...(visualBinding ? { visual: {
         panelId: node.id,
         editorEndpoint: `/control-panel-edit/panels/${node.id}`,
@@ -241,7 +255,7 @@ module.exports = function (RED) {
 
     const events = {
       onAction: !boundMode,
-      ...(meter ? { onSocket: meter.hooks } : {}),
+      ...((meter || xySeries) ? { onSocket: { ...(meter?.hooks || {}), ...(xySeries?.hooks || {}) } } : {}),
       beforeSend (msg) {
         if (msg?._controlPanel?.kind === 'command') throw new Error('Bound commands require authenticated HTTP')
         if (['device-meter-frame', 'device-meter-manifest'].includes(msg?.kind)) {
@@ -250,6 +264,10 @@ module.exports = function (RED) {
           // should be emitted. `false` is property-safe and suppresses emit.
           return false
         }
+        if (['device-xy-series-frame', 'device-xy-series-manifest'].includes(msg?.kind)) {
+          if (bridgeReady) xySeries?.accept(msg)
+          return false
+        }
         if (boundMode) {
           if (msg?.kind === 'device-feedback' && gateway) {
             gateway.boundFeedback(resolveBoundFeedback(routes, msg))
@@ -325,7 +343,9 @@ module.exports = function (RED) {
       gateway?.close()
       editor?.close()
       meter?.close()
+      xySeries?.close()
       if (meterRooms.get(boundRoom)?.stats().panels === 0) meterRooms.delete(boundRoom)
+      if (xySeriesRooms.get(boundRoom)?.stats().panels === 0) xySeriesRooms.delete(boundRoom)
       if (activePanels.get(node.id) === gateway) activePanels.delete(node.id)
       if (activeEditors.get(node.id) === editor) activeEditors.delete(node.id)
     })

package/control-policy.js

@@ -5,6 +5,8 @@ const { fetchWithTimeout } = require('./panel-http')
 const { createTargetMatcher } = require('./control-type-model')
 const { createRoomMeterReceiver, createMeterRenderer } = require('./meter-frame')
 const { createPanelMeterClient } = require('./panel-meter-client')
+const { createRoomXYSeriesReceiver, createXYSeriesRenderer } = require('./xy-series-frame')
+const { createPanelXYSeriesClient } = require('./panel-xy-series-client')
 
 const CONTROL_POLICY_MARKER = '/* ui-control-panel-control-api-v1 */'
 
@@ -164,6 +166,11 @@ function buildDashboardPolicyOptionsSource (controls = [], boundPanel = null) {
     __createMeterRenderer: ${createMeterRenderer.toString()},
     __createPanelMeterClient: ${createPanelMeterClient.toString()},`
     : ''
+  const xySeriesMethods = boundPanel?.xySeries
+    ? `__createXYSeriesReceiver: ${createRoomXYSeriesReceiver.toString()},
+    __createXYSeriesRenderer: ${createXYSeriesRenderer.toString()},
+    __createPanelXYSeriesClient: ${createPanelXYSeriesClient.toString()},`
+    : ''
   const visualMethods = boundPanel?.visual
     ? `__createTargetMatcher: ${createTargetMatcher.toString()},
     __initializeVisualBinding: ${initializeVisualBinding.toString()},
@@ -188,6 +195,7 @@ export default {
   },
   methods: {
     ${meterMethods}
+    ${xySeriesMethods}
     ${visualMethods}
     __panelFetch: ${fetchWithTimeout.toString()},
     __boundPanelConfig () {

package/control-type-contract.json

@@ -5,6 +5,7 @@
     "level": { "family": "number", "delivery": "continuous" },
     "volume": { "family": "number", "delivery": "continuous" },
     "meter": { "family": "number", "delivery": "realtime", "access": "ro" },
+    "xy-series": { "family": "xy-series", "delivery": "realtime", "access": "ro" },
     "dimmer": { "family": "number", "delivery": "continuous" },
     "position": { "family": "number", "delivery": "continuous" },
     "toggle": { "family": "boolean", "delivery": "discrete" },

package/control-type-model.js

@@ -6,10 +6,11 @@ const { meterRoute } = require('./meter-route')
 // Used by both server validation and the injected editor; keep it self-contained.
 function createTargetMatcher (typeContract) {
   const families = {
-    range: ['number'], switch: ['boolean'], meter: ['number'],
+    range: ['number'], switch: ['boolean'], meter: ['number'], 'xy-series': ['xy-series'],
     'text-display': ['text', 'number', 'enum', 'boolean'], 'text-input': ['text'], select: ['enum']
   }
   function family (target) {
+    if (target.xySeries) return 'xy-series'
     if (target.controlSchemaVersion !== typeContract.schemaVersion) return null
     const definition = typeContract.types[String(target.controlType || '').toLowerCase()]
     if (!definition) return null
@@ -24,9 +25,11 @@ function createTargetMatcher (typeContract) {
   }
   function compatible (adapter, target, direction, candidate = {}) {
     if (adapter === 'meter' && !target.meter) return false
+    if (adapter === 'xy-series' && !target.xySeries) return false
     if (target.meter && (adapter !== 'meter' || direction !== 'read' || target.access !== 'ro')) return false
+    if (target.xySeries && (adapter !== 'xy-series' || direction !== 'read' || target.access !== 'ro')) return false
     if (target.kind !== 'param' || !families[adapter]?.includes(family(target))) return false
-    if (direction === 'write' && ['meter', 'text-display'].includes(adapter)) return false
+    if (direction === 'write' && ['meter', 'xy-series', 'text-display'].includes(adapter)) return false
     if (!['read', 'write'].includes(direction)) return false
     if (!(direction === 'write' ? ['wo', 'rw'] : ['ro', 'rw']).includes(target.access)) return false
     if (candidate.unit && candidate.unit !== target.unit) return false
@@ -42,6 +45,7 @@ function controlTypeForAdapter (adapter, target) {
     throw new Error('Target is incompatible with this control')
   }
   if (adapter === 'meter' && target.meter) return 'meter'
+  if (adapter === 'xy-series' && target.xySeries) return 'xy-series'
   const family = targetFamily(target)
   if (family === 'number') return 'level'
   if (family === 'boolean') return 'mute'
@@ -60,7 +64,8 @@ function targetMeta (target, onebased) {
     min: target.min, max: target.max, enums: target.enums,
     ...(target.booleanEncoding ? { booleanEncoding: target.booleanEncoding } : {}),
     controlType: target.controlType, controlSchemaVersion: target.controlSchemaVersion,
-    ...(target.meter ? { meter: meterRoute(target.meter), unit: target.unit || '' } : {})
+    ...(target.meter ? { meter: meterRoute(target.meter), unit: target.unit || '' } : {}),
+    ...(target.xySeries ? { xySeries: require('./xy-series-route').xySeriesRoute(target.xySeries) } : {})
   }
 }
 

package/managed-native-bridge.js

@@ -25,7 +25,8 @@ function panelTargets (panel) {
         device: binding.device, path, kind: meta.kind, type: meta.type,
         access: meta.access, onebased: meta.onebased,
         ...(meta.booleanEncoding ? { booleanEncoding: meta.booleanEncoding } : {}),
-        ...(meta.meter ? { meter: meta.meter } : {})
+        ...(meta.meter ? { meter: meta.meter } : {}),
+        ...(meta.xySeries ? { xySeries: meta.xySeries } : {})
       }
       const key = JSON.stringify([target.device, target.path])
       const previous = targets.get(key)

package/native-binding-plan.js

@@ -1,5 +1,6 @@
 const { configuredRoutes } = require('./control-bound-protocol')
 const { meterRoute } = require('./meter-route')
+const { xySeriesRoute } = require('./xy-series-route')
 
 const supportedTypes = {
   boolean: { eventType: 'Boolean', eventOptions: { boolParamFilter: 'Any' } },
@@ -30,6 +31,7 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
   const readTargets = new Map()
   const writeTargets = new Map()
   const meterStreams = new Map()
+  const xySeriesStreams = new Map()
   const commandRules = []
   const commandWires = []
 
@@ -37,7 +39,7 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     const target = targetIndex.get(JSON.stringify([device, path]))
     if (!target) throw new Error(`Missing target descriptor: ${device} ${path}`)
     if (target.kind !== 'param') throw new Error(`Only parameter targets are supported: ${path}`)
-    if (!Object.hasOwn(supportedTypes, target.type)) {
+    if (!target.xySeries && !Object.hasOwn(supportedTypes, target.type)) {
       throw new Error(`Unsupported native parameter type: ${path} (${target.type})`)
     }
     if (['mute', 'power'].includes(type) && target.type !== 'boolean' &&
@@ -56,7 +58,10 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     if (type === 'meter' && (!target.meter || !['integer', 'float'].includes(target.type) || target.access !== 'ro')) {
       throw new Error(`Meter control must bind to a readonly Meter target: ${path}`)
     }
-    if (!['mute', 'power', 'level', 'dimmer', 'position', 'meter', 'text', 'source', 'preset'].includes(type)) {
+    if (type === 'xy-series' && (!target.xySeries || target.access !== 'ro')) {
+      throw new Error(`XY-series control must bind to a readonly XY-series target: ${path}`)
+    }
+    if (!['mute', 'power', 'level', 'dimmer', 'position', 'meter', 'xy-series', 'text', 'source', 'preset'].includes(type)) {
       throw new Error(`Control type requires a separate command adapter: ${type}`)
     }
     if (!['ro', 'wo', 'rw'].includes(target.access) || !target.access.includes(access)) {
@@ -134,6 +139,49 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
         }
         continue
       }
+      if (target.xySeries) {
+        const series = xySeriesRoute(target.xySeries)
+        if (control.mode !== 'read' || control.adapter !== 'xy-series') {
+          throw Error(`XY-series is read-only: ${id}`)
+        }
+        const key = JSON.stringify([target.device, series.streamId])
+        const previous = xySeriesStreams.get(key)
+        if (previous) {
+          if (JSON.stringify(previous.series) !== JSON.stringify(series) || previous.onebased !== target.onebased) {
+            throw Error(`Conflicting xy-series stream: ${series.streamId}`)
+          }
+          continue
+        }
+        const index = xySeriesStreams.size + 1
+        const statusId = `${scopeId}-xy-series-read-${index}`
+        const tagIds = []
+        xySeriesStreams.set(key, { series, onebased: target.onebased, statusId, tagIds })
+        for (const [role, path] of [['manifest', series.manifestPath], ['frame', series.eventPath]]) {
+          const eventId = `${scopeId}-xy-series-${role}-${index}`
+          const tagId = `${eventId}-tag`
+          tagIds.push(tagId)
+          const y = 540 + (index - 1) * 280 + (role === 'frame' ? 140 : 0)
+          if (role === 'manifest') nodes.push({
+            id: statusId, type: 'Status', z: subflowId, name: `Read xy-series manifest ${target.device}`,
+            x: 440, y: y - 60, mojo: { version: '1.0', device: [target.device],
+              parameter: path, onebased: target.onebased }, wires: [[tagId]]
+          })
+          nodes.push({ id: eventId, type: 'Event', z: subflowId,
+            name: `Watch xy-series ${role} ${target.device} ${series.streamId}`, x: 440, y,
+            mojo: { version: '1.0', device: [target.device], event: path,
+              eventKind: role === 'frame' ? 'Event' : 'Parameter', paramType: 'String',
+              onebased: target.onebased }, wires: [[tagId]] })
+          nodes.push({ id: tagId, type: 'change', z: subflowId,
+            name: `Identify xy-series ${role} ${target.device}`, x: 1000, y,
+            rules: [
+              { t: 'set', p: 'kind', pt: 'msg', to: 'device-xy-series-' + role, tot: 'str' },
+              { t: 'set', p: 'device', pt: 'msg', to: target.device, tot: 'str' },
+              { t: 'set', p: 'path', pt: 'msg', to: path, tot: 'str' },
+              { t: 'set', p: 'streamId', pt: 'msg', to: series.streamId, tot: 'str' }
+            ], wires: [[]] })
+        }
+        continue
+      }
       const key = JSON.stringify([target.device, target.path])
       if (readTargets.has(key)) continue
       const index = readTargets.size + 1
@@ -175,7 +223,11 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
 
   const commandSwitchId = `${scopeId}-commands`
   // Meter lanes follow ordinary feedback lanes without overlapping their labels.
-  for (const node of nodes) if (node.id.startsWith(`${scopeId}-meter-`)) node.y += readTargets.size * 170
+  for (const node of nodes) {
+    if (node.id.startsWith(`${scopeId}-meter-`) || node.id.startsWith(`${scopeId}-xy-series-`)) {
+      node.y += readTargets.size * 170
+    }
+  }
   const routerId = `${scopeId}-router`
   if (commandRules.length) {
     nodes.push({
@@ -196,17 +248,18 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     ],
     checkall: 'false', repair: false, outputs: 2,
     wires: [commandRules.length ? [commandSwitchId] : [],
-      [...readTargets.values(), ...meterStreams.values()].map(target => target.statusId)]
+      [...readTargets.values(), ...meterStreams.values(), ...xySeriesStreams.values()].map(target => target.statusId)]
   })
   const subflow = {
     id: subflowId, type: 'subflow', name: `Binding bridge ${scopeId}`,
     info: 'Generated panel binding bridge. Requires a Controller node and authenticated command source.',
     category: 'panel binding',
     in: [{ x: 170, y: 150, wires: [{ id: routerId }] }],
-    out: readTargets.size || meterStreams.size
+    out: readTargets.size || meterStreams.size || xySeriesStreams.size
       ? [{ x: meterStreams.size ? 1600 : 1290, y: Math.round((390 + (readTargets.size + meterStreams.size + 1) * 85) / 10) * 10,
         wires: [...readTargets.values()].map(target => ({ id: target.tagId, port: 0 }))
-          .concat([...meterStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 })))) }]
+          .concat([...meterStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 }))))
+          .concat([...xySeriesStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 })))) }]
       : [],
     env: [], meta: {}, color: '#96bca7'
   }
@@ -215,8 +268,9 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     manifest: {
       subflowId,
       controls: routes.size,
-      nativeReads: readTargets.size + meterStreams.size,
+      nativeReads: readTargets.size + meterStreams.size + xySeriesStreams.size,
       nativeMeterStreams: meterStreams.size,
+      nativeXYSeriesStreams: xySeriesStreams.size,
       nativeWrites: writeTargets.size,
       requiresController: true,
       initialReadMessage: { kind: 'read-all' }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "node-red-contrib-room-tools",
-      "version": "1.9.0",
+      "version": "1.9.1",
       "license": "UNLICENSED",
       "dependencies": {
         "@vue/compiler-sfc": "3.5.42",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Authenticated visual control panel binding for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
   "engines": {
@@ -27,6 +27,10 @@
     "meter-frame.js",
     "panel-meter.js",
     "panel-meter-client.js",
+    "xy-series-route.js",
+    "xy-series-frame.js",
+    "panel-xy-series.js",
+    "panel-xy-series-client.js",
     "panel-template-instrumentation.js",
     "panel-visual-bindings.js",
     "panel-visual-apply.js",

package/panel-binding-editor.js

@@ -7,8 +7,11 @@ function initializeVisualBinding () {
   const base = config.editorEndpoint
   const saved = new Map(Object.entries(config.bindings || {}))
   const meterEntries = [...saved].filter(([, entry]) => entry.readMeta?.meter)
+  const xySeriesEntries = [...saved].filter(([, entry]) => entry.readMeta?.xySeries)
   const meterTargets = new Map()
+  const xySeriesTargets = new Map()
   let meterClient = null, lastMeterFrame = null
+  let xySeriesClient = null, lastXYSeriesFrame = null
   const attached = new WeakSet()
   const feedbackModels = new Map()
   const pendingText = new Map()
@@ -189,7 +192,7 @@ function initializeVisualBinding () {
   }
   function showFeedback () {
     for (const [id, binding] of saved) {
-      if (binding.mode === 'write' || binding.readMeta?.meter) continue
+      if (binding.mode === 'write' || binding.readMeta?.meter || binding.readMeta?.xySeries) continue
       const node = nodeForBinding(binding)
       if (!node) continue
       if (!Object.prototype.hasOwnProperty.call(component.boundState, id)) continue
@@ -288,6 +291,15 @@ function initializeVisualBinding () {
       if (lastMeterFrame) applyMeterFrame(lastMeterFrame.frame, lastMeterFrame.ids)
       else invalidateMeters()
     }
+    if (xySeriesEntries.length) {
+      xySeriesTargets.clear()
+      for (const [id, binding] of xySeriesEntries) {
+        const node = nodeForBinding(binding)
+        if (node) xySeriesTargets.set(id, { node, binding })
+      }
+      if (lastXYSeriesFrame) applyXYSeriesFrame(lastXYSeriesFrame.frame, lastXYSeriesFrame.ids)
+      else invalidateXYSeries()
+    }
     showFeedback()
   }
   function applyMeterFrame (frame, ids) {
@@ -313,6 +325,32 @@ function initializeVisualBinding () {
       node.setAttribute('aria-invalid', 'true')
     }
   }
+  function applyXYSeriesFrame (frame, ids) {
+    lastXYSeriesFrame = { frame, ids }
+    for (let index = 0; index < ids.length; index++) {
+      const target = xySeriesTargets.get(ids[index])
+      if (!target) continue
+      const { node, binding } = target
+      node.setAttribute('data-cpv-xy-series-valid', String(frame.valid[index]))
+      node.setAttribute('data-cpv-xy-series-seq', String(frame.seq))
+      const points = frame.valid[index] ? frame.values[index].map(point => point.slice()) : []
+      if (binding.model) {
+        if (binding.repeat) setRepeatModel(binding, points)
+        else if (binding.model in component && !component.$options?.computed?.[binding.model]) component[binding.model] = points
+      }
+    }
+  }
+  function invalidateXYSeries () {
+    lastXYSeriesFrame = null
+    for (const { node, binding } of xySeriesTargets.values()) {
+      node.setAttribute('data-cpv-xy-series-valid', 'false')
+      node.setAttribute('aria-invalid', 'true')
+      if (binding.model) {
+        if (binding.repeat) setRepeatModel(binding, [])
+        else if (binding.model in component && !component.$options?.computed?.[binding.model]) component[binding.model] = []
+      }
+    }
+  }
   function attachModelControls () {
     for (const [id, binding] of saved) {
       if (!binding.component || !binding.model || binding.mode === 'read') continue
@@ -762,6 +800,9 @@ function initializeVisualBinding () {
     if (candidate.adapter === 'meter' && (typeof value !== 'number' || !Number.isFinite(value))) {
       return { ...candidate, supported: false, reason: 'This Vuetify progress needs a numeric model field' }
     }
+    if (candidate.adapter === 'xy-series' && !Array.isArray(value)) {
+      return { ...candidate, supported: false, reason: 'This realtime array control needs an array model field' }
+    }
     if (candidate.adapter === 'select' && typeof value !== 'string' &&
       !(typeof value === 'number' && Number.isFinite(value))) {
       return { ...candidate, supported: false, reason: 'This Vuetify selection needs one scalar model field' }
@@ -822,6 +863,25 @@ function initializeVisualBinding () {
       }))
     } catch (error) { console.error('ControlPanel meter initialization failed', error) }
   }
+  if (this.__boundPanelConfig().xySeries && xySeriesEntries.length) {
+    try {
+      const ids = xySeriesEntries.map(([id]) => id).sort((a, b) => a.localeCompare(b))
+      xySeriesClient = this.__createPanelXYSeriesClient({ socket: this.$socket,
+        panelId: config.panelId, room: this.__boundPanelConfig().room, ids,
+        request: (...args) => component.__panelFetch(...args),
+        createReceiver: this.__createXYSeriesReceiver, createRenderer: this.__createXYSeriesRenderer,
+        apply: applyXYSeriesFrame, invalidate: invalidateXYSeries,
+        onUnauthorized: () => {
+          if (editing) { editSession = null; loginView() }
+          else component.clearBoundPanelSession()
+        } })
+      cleanup.push(() => xySeriesClient.close())
+      if (!editing) cleanup.push(this.$watch('boundAuthenticated', authenticated => {
+        xySeriesClient.setAuth(authenticated ? { endpoint: component.__boundPanelConfig().endpoint,
+          csrf: component.__boundPanelSession.csrf, header: 'X-Room-CSRF' } : null)
+      }))
+    } catch (error) { console.error('ControlPanel xy-series initialization failed', error) }
+  }
   observer = new MutationObserver(() => {
     attachControls()
     updateBindingMarkers()

package/panel-template-instrumentation.js

@@ -8,6 +8,7 @@ const COMPONENT_ADAPTERS = Object.freeze({
   'v-text-field': 'text-input', 'v-textarea': 'text-input',
   'v-progress-linear': 'meter', 'v-progress-circular': 'meter'
 })
+const XY_SERIES_CONTAINER_TAGS = new Set(['div', 'section', 'article', 'main', 'aside', 'svg', 'g'])
 const SIMPLE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 const SIMPLE_PROPERTY_PATH = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/
 const UNSAFE_PROPERTY_NAMES = new Set(['__proto__', 'prototype', 'constructor'])
@@ -63,6 +64,8 @@ function candidateAdapter (node) {
   if (tag === 'button' && (attribute(node, 'aria-pressed') !== '' || attribute(node, 'role') === 'switch' ||
     hasBoundAttribute(node, ['aria-pressed', 'aria-checked']))) return 'switch'
   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 (['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'
@@ -71,6 +74,17 @@ function candidateAdapter (node) {
   return null
 }
 
+function xySeriesModel (node) {
+  const tag = node.tag.toLowerCase()
+  const names = tag === 'canvas' ? ['data-points', 'data-series'] : ['data-coordinates']
+  const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
+    names.includes(prop.arg?.content))
+  if (!bound || bound.modifiers?.length) return { model: '', valid: false, attribute: names[0] }
+  const model = bound.exp?.content?.trim() || ''
+  return { model, valid: SIMPLE_IDENTIFIER.test(model), attribute: bound.arg.content,
+    presentation: tag === 'canvas' ? 'points' : 'coordinates' }
+}
+
 function staticNumericProp (node, name) {
   const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     prop.arg?.content === name)
@@ -279,6 +293,7 @@ function inspectTemplate (format) {
         const component = COMPONENT_ADAPTERS[node.tag.toLowerCase()] ? node.tag.toLowerCase() : ''
         const display = adapter === 'text-display'
           ? displayModel(node, activeRepeat)
+          : adapter === 'xy-series' ? xySeriesModel(node)
           : ['v-progress-linear', 'v-progress-circular'].includes(component) ? progressModel(node, activeRepeat)
           : adapter === 'meter' && !component ? nativeMeterModel(node, activeRepeat)
           : adapter === 'switch' && node.tag.toLowerCase() === 'button'
@@ -360,7 +375,11 @@ function inspectTemplate (format) {
                       unsupportedTextType ? 'Only text Vuetify fields are supported' :
                         unsupportedProgress ? 'Progress needs a determinate positive range' :
                           unsupportedCircular ? 'Circular progress uses a determinate 0-100 range' :
-                    component && !display.model ? 'Vuetify controls need a simple Vue v-model field' : ''
+              adapter === 'xy-series' && !display.model
+                ? display.attribute === 'data-coordinates'
+                  ? 'Map coordinate containers need :data-coordinates="coordinates"'
+                  : 'Canvas needs :data-points="series" or :data-series="series"'
+                : component && !display.model ? 'Vuetify controls need a simple Vue v-model field' : ''
         }
         candidates.push({ ...candidate, offset: openingTagEnd(format, node.loc.start.offset) })
         counts.set(locator, (counts.get(locator) || 0) + 1)

package/panel-visual-bindings.js

@@ -1,6 +1,7 @@
 const { inspectTemplate } = require('./panel-template-instrumentation')
 const { compatibleTarget, controlTypeForAdapter, targetMeta } = 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}$/
@@ -42,7 +43,7 @@ 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', 'text-display'].includes(entry.adapter) && entry.mode !== 'read')) {
+      (['meter', 'xy-series', 'text-display'].includes(entry.adapter) && entry.mode !== 'read')) {
       throw new Error(`Invalid visual binding settings: ${id}`)
     }
     if (entry.readMeta?.meter) {
@@ -52,6 +53,12 @@ function visualRoutes (config) {
         !Number.isFinite(entry.readMeta.min) || !Number.isFinite(entry.readMeta.max) ||
         entry.readMeta.min >= entry.readMeta.max) throw Error(`Invalid meter binding: ${id}`)
     }
+    if (entry.readMeta?.xySeries) {
+      xySeriesRoute(entry.readMeta.xySeries)
+      if (entry.adapter !== 'xy-series' || entry.mode !== 'read' || entry.readMeta.access !== 'ro') {
+        throw Error(`Invalid xy-series binding: ${id}`)
+      }
+    }
     routes.set(id, {
       control: { id, type: entry.type, mode: entry.mode, label: entry.label,
         adapter: entry.adapter, locator: entry.locator,
@@ -79,7 +86,7 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     const bindingKey = targetKey(candidate, raw)
     if (usedLocators.has(bindingKey)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(raw.mode) || (['meter', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
+    if (!MODES.has(raw.mode) || (['meter', 'xy-series', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
       throw new Error(`Invalid binding mode: ${raw.id}`)
     }
     if (typeof raw.label !== 'string' || !raw.label.trim() || raw.label.length > 80) {

package/panel-xy-series-client.js

@@ -0,0 +1,84 @@
+// Self-contained client for readonly XY-series telemetry.
+function createPanelXYSeriesClient ({ socket, panelId, room, ids, request,
+  createReceiver, createRenderer, apply, invalidate, onUnauthorized }) {
+  if (!socket) throw Error('Dashboard socket is unavailable for xy-series telemetry')
+  let auth = null, renderer = null, generation = 0, disposed = false
+  let retry = null, stale = null, connecting = false, delay = 500
+  const stopRendering = () => {
+    renderer?.close(); renderer = null
+    clearTimeout(stale); stale = null
+    invalidate()
+  }
+  const pause = () => {
+    generation++
+    connecting = false
+    clearTimeout(retry); retry = null
+    if (socket.connected) socket.emit('control-panel:xy-series-unsubscribe', panelId)
+    stopRendering()
+  }
+  const connect = async () => {
+    if (disposed || !auth || document.hidden || !socket.connected || connecting) return
+    clearTimeout(retry); retry = null
+    connecting = true
+    const expected = generation
+    try {
+      const { response, result } = await request(auth.endpoint + '/xy-series-ticket', {
+        method: 'POST', credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', [auth.header]: auth.csrf },
+        body: JSON.stringify({ room, socketId: socket.id })
+      }, 5000, async response => ({ response, result: await response.json() }))
+      if (disposed || expected !== generation || document.hidden) return
+      if (response.status === 401) { pause(); auth = null; onUnauthorized(); return }
+      if (!response.ok) throw Error(result.error || 'XY-series subscription failed')
+      delay = 500
+      socket.emit('control-panel:xy-series-subscribe', panelId, result.ticket)
+    } catch (_) {
+      if (!disposed && expected === generation && auth) {
+        retry = setTimeout(connect, delay)
+        delay = Math.min(delay * 2, 5000)
+      }
+    } finally { if (expected === generation) connecting = false }
+  }
+  const ready = layout => {
+    if (disposed || !auth || document.hidden || layout?.panelId !== panelId || layout.room !== room ||
+      !Array.isArray(layout.ids) || JSON.stringify(layout.ids) !== JSON.stringify(ids)) return
+    stopRendering()
+    try {
+      renderer = createRenderer({ receiver: createReceiver(layout),
+        requestFrame: callback => requestAnimationFrame(callback), cancelFrame: cancelAnimationFrame,
+        apply: frame => apply(frame, ids) })
+    } catch (_) { stopRendering() }
+  }
+  const frame = message => {
+    if (message?.panelId !== panelId || !auth || document.hidden || !renderer?.receive(message)) return
+    clearTimeout(stale)
+    stale = setTimeout(invalidate, 1500)
+  }
+  const ended = message => {
+    if (message?.panelId !== panelId) return
+    stopRendering()
+    if (auth && !disposed && !retry) retry = setTimeout(connect, 500)
+  }
+  const disconnected = () => { generation++; connecting = false; stopRendering() }
+  const visibility = () => { if (document.hidden) pause(); else void connect() }
+  socket.on('control-panel:xy-series-ready', ready)
+  socket.on('control-panel:xy-series-frame', frame)
+  socket.on('control-panel:xy-series-ended', ended)
+  socket.on('connect', connect)
+  socket.on('disconnect', disconnected)
+  document.addEventListener('visibilitychange', visibility)
+  return {
+    setAuth (next) { pause(); auth = next; delay = 500; if (auth) void connect() },
+    close () {
+      disposed = true; pause(); auth = null
+      socket.off('control-panel:xy-series-ready', ready)
+      socket.off('control-panel:xy-series-frame', frame)
+      socket.off('control-panel:xy-series-ended', ended)
+      socket.off('connect', connect)
+      socket.off('disconnect', disconnected)
+      document.removeEventListener('visibilitychange', visibility)
+    }
+  }
+}
+
+module.exports = { createPanelXYSeriesClient }

package/panel-xy-series.js

@@ -0,0 +1,186 @@
+const crypto = require('node:crypto')
+const { createXYSeriesReceiver } = require('./xy-series-frame')
+const { readJsonBody, replyJson } = require('./panel-http')
+const { xySeriesRoute } = require('./xy-series-route')
+
+function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
+  const sources = new Map(), panels = new Map(), ticks = new Set()
+  let timer = null, generation = 0
+
+  function attach (panelId, bindings) {
+    if (panels.has(panelId)) throw Error('XY-series panel already registered')
+    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]) => {
+      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)) {
+        throw Error(`Conflicting xy-series stream: ${series.streamId}`)
+      }
+      if (!source) {
+        source = { device: binding.device, route: series, receiver: null,
+          receivedAt: null, revision: 0, refs: new Set() }
+        sources.set(key, source)
+      }
+      source.refs.add(panelId)
+      return { id, binding, source, key }
+    })
+    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 })
+    return layout
+  }
+
+  function accept (message) {
+    if (!['device-xy-series-frame', 'device-xy-series-manifest'].includes(message?.kind)) return false
+    const source = sources.get(JSON.stringify([message.device, message.streamId]))
+    if (!source || message.path !== (message.kind === 'device-xy-series-frame'
+      ? source.route.eventPath : source.route.manifestPath)) return false
+    let data = message.payload
+    if (data && typeof data === 'object' && Object.hasOwn(data, 'data')) data = data.data
+    if (typeof data === 'string') {
+      if (Buffer.byteLength(data) > 524288) return false
+      try { data = JSON.parse(data) } catch (_) { return false }
+    }
+    if (message.kind === 'device-xy-series-manifest') {
+      let receiver
+      try { receiver = createXYSeriesReceiver(data) } catch (_) { return false }
+      if (receiver.manifest.streamId !== source.route.streamId) return false
+      const previous = source.receiver?.manifest
+      if (previous && JSON.stringify(previous) === JSON.stringify(receiver.manifest)) return true
+      if (previous?.epoch === receiver.manifest.epoch &&
+        receiver.manifest.layoutVersion <= previous.layoutVersion) return false
+      source.receiver?.close(); source.receiver = receiver; source.receivedAt = null
+    } else {
+      if (!source.receiver?.accept(data)) return false
+      source.receivedAt = now()
+    }
+    source.revision = ++generation
+    return true
+  }
+
+  function snapshot (panelId) {
+    const panel = panels.get(panelId)
+    if (!panel) return null
+    const time = now(), values = [], valid = [], sourcesByStream = new Map()
+    for (const { source, key } of panel.projections) {
+      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()) : [])
+      valid.push(ok)
+      sourcesByStream.set(key, { device: source.device, streamId: source.route.streamId,
+        epoch: source.receiver?.manifest.epoch || '', seq: frame?.seq || 0,
+        sampleTime: frame?.sampleTime ?? null, ageMs: age })
+    }
+    return { kind: 'room-xy-series-frame', panelId, room, epoch: panel.layout.epoch,
+      seq: ++panel.sequence, values, valid, sources: [...sourcesByStream.values()] }
+  }
+
+  function revision (panelId) {
+    const panel = panels.get(panelId)
+    if (!panel) return ''
+    const time = now()
+    return panel.projections.map(({ source }) => `${source.revision}:${source.receivedAt !== null &&
+      time - source.receivedAt <= staleMs}`).join(',')
+  }
+
+  function detach (panelId) {
+    const panel = panels.get(panelId)
+    if (!panel) return
+    panels.delete(panelId)
+    for (const { source, key } of panel.projections) {
+      source.refs.delete(panelId)
+      if (!source.refs.size) { source.receiver?.close(); sources.delete(key) }
+    }
+  }
+
+  return { attach, accept, snapshot, revision, detach,
+    onTick (callback) {
+      ticks.add(callback)
+      if (!timer) { timer = setInterval(() => { for (const tick of ticks) tick() }, 1000 / 30); timer.unref?.() }
+      return () => {
+        ticks.delete(callback)
+        if (!ticks.size) { clearInterval(timer); timer = null }
+      }
+    },
+    stats: () => ({ panels: panels.size, sources: sources.size }) }
+}
+
+function createPanelXYSeries ({ panelId, room, bindings, hub, onSubscribe = () => {} }) {
+  const layout = hub.attach(panelId, bindings)
+  const tickets = new Map(), subscribers = new Map()
+  let closed = false, lastRevision = ''
+  const remove = socketId => {
+    const entry = subscribers.get(socketId)
+    if (entry) entry.socket.off('disconnect', entry.disconnect)
+    subscribers.delete(socketId)
+  }
+  const live = entry => entry.active() && entry.socket.connected
+  const emitFrame = (socket, frame) => socket.volatile.emit('control-panel:xy-series-frame', frame)
+  const prune = () => {
+    for (const [key, entry] of tickets) if (entry.expiry <= Date.now() || !entry.active()) tickets.delete(key)
+    for (const [key, entry] of subscribers) if (!live(entry)) {
+      entry.socket.emit('control-panel:xy-series-ended', { panelId }); remove(key)
+    }
+  }
+  const stopTick = hub.onTick(() => {
+    prune()
+    if (closed || !subscribers.size) return
+    const revision = hub.revision(panelId)
+    if (revision === lastRevision) return
+    lastRevision = revision
+    const frame = hub.snapshot(panelId)
+    for (const { socket } of subscribers.values()) emitFrame(socket, frame)
+  })
+  return {
+    async ticket (req, res, identity, active) {
+      if (!new URL(req.url, 'http://localhost').pathname.endsWith('/xy-series-ticket') || req.method !== 'POST') return false
+      if (closed) { replyJson(res, 503, { error: 'XY-series channel unavailable' }); return true }
+      prune()
+      const body = await readJsonBody(req, 4096)
+      if (body.room !== room || typeof body.socketId !== 'string' || !body.socketId || body.socketId.length > 128) {
+        replyJson(res, 403, { error: 'XY-series subscription rejected' }); return true
+      }
+      if (!req.headers.origin) { replyJson(res, 403, { error: 'XY-series subscription needs Origin' }); return true }
+      for (const [key, entry] of tickets) if (entry.token === identity.token && entry.socketId === body.socketId) tickets.delete(key)
+      if (tickets.size >= 100) { replyJson(res, 429, { error: 'XY-series ticket limit reached' }); return true }
+      const ticket = crypto.randomBytes(32).toString('hex')
+      tickets.set(ticket, { token: identity.token, socketId: body.socketId,
+        expiry: Math.min(identity.expiry, Date.now() + 10000), active })
+      replyJson(res, 200, { ticket }); return true
+    },
+    hooks: {
+      'control-panel:xy-series-subscribe': (socket, id, ticket) => {
+        if (id !== panelId || closed) return
+        prune()
+        const entry = tickets.get(ticket); tickets.delete(ticket)
+        if (!entry || !entry.active() || entry.expiry <= Date.now() || entry.socketId !== socket.id ||
+          !socket.connected || (!subscribers.has(socket.id) && subscribers.size >= 100)) {
+          socket.emit('control-panel:xy-series-ended', { panelId }); return
+        }
+        remove(socket.id)
+        const disconnect = () => remove(socket.id)
+        subscribers.set(socket.id, { socket, active: entry.active, disconnect })
+        socket.on('disconnect', disconnect)
+        socket.emit('control-panel:xy-series-ready', layout)
+        emitFrame(socket, hub.snapshot(panelId)); onSubscribe()
+      },
+      'control-panel:xy-series-unsubscribe': (socket, id) => { if (id === panelId) remove(socket.id) }
+    },
+    accept: message => !closed && hub.accept(message),
+    stats: () => ({ tickets: tickets.size, subscribers: subscribers.size, ...hub.stats() }),
+    close () {
+      closed = true; stopTick(); tickets.clear()
+      for (const entry of subscribers.values()) {
+        entry.socket.emit('control-panel:xy-series-ended', { panelId })
+        entry.socket.off('disconnect', entry.disconnect)
+      }
+      subscribers.clear(); hub.detach(panelId)
+    }
+  }
+}
+
+module.exports = { createXYSeriesRoom, createPanelXYSeries }

package/xy-series-frame.js

@@ -0,0 +1,98 @@
+function finite (value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function createXYSeriesReceiver (manifest) {
+  if (manifest?.kind !== 'xy-series-manifest' || typeof manifest.streamId !== 'string' ||
+    !manifest.streamId.trim() || manifest.streamId.length > 255 ||
+    typeof manifest.epoch !== 'string' || !manifest.epoch || manifest.epoch.length > 128 ||
+    !Number.isInteger(manifest.layoutVersion) || manifest.layoutVersion < 1 ||
+    manifest.layoutVersion > 2147483647 || manifest.clock !== 'monotonic-ms' ||
+    !finite(manifest.publishHz) || manifest.publishHz < 1 || manifest.publishHz > 60 ||
+    !Number.isSafeInteger(manifest.maxPoints) || manifest.maxPoints < 1 || manifest.maxPoints > 8192 ||
+    typeof manifest.xUnit !== 'string' || manifest.xUnit.length > 32 ||
+    typeof manifest.yUnit !== 'string' || manifest.yUnit.length > 32) {
+    throw Error('Invalid xy-series manifest')
+  }
+  const schema = Object.freeze({ ...manifest })
+  let latest = null, pending = false, closed = false
+  return {
+    manifest: schema,
+    accept (frame) {
+      if (closed || frame?.kind !== 'xy-series-frame' || frame.streamId !== schema.streamId ||
+        frame.epoch !== schema.epoch || frame.layoutVersion !== schema.layoutVersion ||
+        !Number.isSafeInteger(frame.seq) || frame.seq < 1 || (latest && frame.seq <= latest.seq) ||
+        !finite(frame.sampleTime) || frame.sampleTime < 0 || !Array.isArray(frame.points) ||
+        frame.points.length > schema.maxPoints || frame.points.some(point =>
+          !Array.isArray(point) || point.length !== 2 || !finite(point[0]) || !finite(point[1]))) return false
+      latest = Object.freeze({ kind: 'xy-series-frame', streamId: schema.streamId,
+        epoch: schema.epoch, seq: frame.seq, layoutVersion: schema.layoutVersion,
+        sampleTime: frame.sampleTime,
+        points: Object.freeze(frame.points.map(point => Object.freeze([point[0], point[1]]))) })
+      pending = true
+      return true
+    },
+    snapshot () { return latest },
+    take () { if (!pending) return null; pending = false; return latest },
+    close () { closed = true; pending = false; latest = null }
+  }
+}
+
+function createXYSeriesRenderer ({ receiver, requestFrame, cancelFrame, apply }) {
+  let handle = null, closed = false
+  return {
+    receive (frame) {
+      if (closed || !receiver.accept(frame)) return false
+      if (handle === null) {
+        handle = requestFrame(() => {
+          handle = null
+          const current = receiver.take()
+          if (!closed && current) apply(current)
+        })
+      }
+      return true
+    },
+    close () {
+      closed = true
+      if (handle !== null) cancelFrame(handle)
+      handle = null
+      receiver.close()
+    }
+  }
+}
+
+function createRoomXYSeriesReceiver (layout) {
+  const finite = value => typeof value === 'number' && Number.isFinite(value)
+  if (layout?.kind !== 'room-xy-series-layout' || typeof layout.panelId !== 'string' ||
+    typeof layout.room !== 'string' || typeof layout.epoch !== 'string' || !layout.epoch ||
+    !Array.isArray(layout.ids) || !layout.ids.length || layout.ids.length > 256 ||
+    layout.ids.some(id => typeof id !== 'string' || !id) || new Set(layout.ids).size !== layout.ids.length) {
+    throw Error('Invalid Room XY-series layout')
+  }
+  let latest = null, pending = false, closed = false
+  const count = layout.ids.length
+  return {
+    accept (frame) {
+      if (closed || frame?.kind !== 'room-xy-series-frame' || frame.panelId !== layout.panelId ||
+        frame.room !== layout.room || frame.epoch !== layout.epoch ||
+        !Number.isSafeInteger(frame.seq) || frame.seq < 1 || (latest && frame.seq <= latest.seq) ||
+        !Array.isArray(frame.values) || frame.values.length !== count ||
+        !Array.isArray(frame.valid) || frame.valid.length !== count) return false
+      for (let index = 0; index < count; index++) {
+        const points = frame.values[index], valid = frame.valid[index]
+        if (typeof valid !== 'boolean' || !Array.isArray(points) || points.length > 8192 ||
+          (!valid && points.length !== 0) ||
+          (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 }
+      pending = true
+      return true
+    },
+    take () { if (!pending) return null; pending = false; return latest },
+    close () { closed = true; latest = null; pending = false }
+  }
+}
+
+module.exports = { createXYSeriesReceiver, createXYSeriesRenderer, createRoomXYSeriesReceiver }

package/xy-series-route.js

@@ -0,0 +1,11 @@
+function xySeriesRoute (value) {
+  if (!value || typeof value !== 'object' ||
+    typeof value.streamId !== 'string' || !value.streamId.trim() || value.streamId.length > 255 ||
+    ![value.eventPath, value.manifestPath].every(path => typeof path === 'string' &&
+      /^\/\/[^/]/.test(path) && path.length <= 1026) || value.eventPath === value.manifestPath) {
+    throw Error('Invalid xy-series delivery metadata')
+  }
+  return { streamId: value.streamId, eventPath: value.eventPath, manifestPath: value.manifestPath }
+}
+
+module.exports = { xySeriesRoute }