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

package/panel-template-instrumentation.js

@@ -8,6 +8,15 @@ 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'])
+
+function safePropertyPath (value) {
+  return SIMPLE_PROPERTY_PATH.test(value) &&
+    value.split('.').every(part => !UNSAFE_PROPERTY_NAMES.has(part))
+}
 
 function attribute (node, name) {
   const prop = (node.props || []).find(item => item.type === 6 && item.name === name)
@@ -55,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'
@@ -63,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)
@@ -78,42 +100,99 @@ function staticNumericProp (node, name) {
   return { value: numeric, dynamic: !Number.isFinite(numeric) }
 }
 
-function displayModel (node) {
+function repeatModelInfo (expression, repeat) {
+  const model = String(expression || '').trim()
+  if (SIMPLE_IDENTIFIER.test(model)) return { valid: true, repeatModel: null }
+  if (!repeat?.valid) return { valid: false, repeatModel: null }
+  const indexedPrefix = repeat.index ? `${repeat.source}[${repeat.index}].` : ''
+  if (indexedPrefix && model.startsWith(indexedPrefix)) {
+    const field = model.slice(indexedPrefix.length)
+    if (safePropertyPath(field)) {
+      return { valid: true, repeatModel: { kind: 'source-index-property', field } }
+    }
+  }
+  if (repeat.kind === 'item') {
+    const escaped = repeat.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const match = model.match(new RegExp('^' + escaped + '\\.' +
+      '(' + SIMPLE_PROPERTY_PATH.source.slice(1, -1) + ')$'))
+    return match && safePropertyPath(match[1])
+      ? { valid: true, repeatModel: { kind: 'item-property', field: match[1] } }
+      : { valid: false, repeatModel: null }
+  }
+  return model === `${repeat.source}[${repeat.index}]`
+    ? { valid: true, repeatModel: { kind: 'array-index' } }
+    : { valid: false, repeatModel: null }
+}
+
+function displayModel (node, repeat) {
   const dynamic = (node.children || []).filter(child => child.type === 5)
   if (!dynamic.length) return { model: '', valid: true }
   const expression = dynamic.length === 1 ? dynamic[0].content?.content?.trim() : ''
-  return { model: expression, valid: /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(expression) }
+  return { model: expression, ...repeatModelInfo(expression, repeat) }
 }
 
-function inputModel (node, allowNumber = false) {
+function inputModel (node, allowNumber = false, repeat) {
   const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'model')
   if (!directive) return { model: '', valid: true }
   const model = directive.exp?.content?.trim() || ''
   const modifiers = (directive.modifiers || []).map(item => typeof item === 'string' ? item : item.content)
-  return { model, valid: !directive.arg && modifiers.every(item => allowNumber && item === 'number') &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !directive.arg && modifiers.every(item => allowNumber && item === 'number') && info.valid }
 }
 
-function progressModel (node) {
+function progressModel (node, repeat) {
   const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     ['model-value', 'modelValue'].includes(prop.arg?.content))
-  if (!bound) return inputModel(node)
+  if (!bound) return inputModel(node, false, repeat)
   const model = bound.exp?.content?.trim() || ''
-  return { model, valid: !hasDirective(node, ['model']) && !bound.modifiers?.length &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !hasDirective(node, ['model']) && !bound.modifiers?.length && info.valid }
 }
 
-function nativeMeterModel (node) {
+function nativeMeterModel (node, repeat) {
   const modelDirective = (node.props || []).find(prop => prop.type === 7 && prop.name === 'model')
   if (modelDirective) {
-    return { model: modelDirective.exp?.content?.trim() || '', valid: !modelDirective.arg && !modelDirective.modifiers?.length &&
-      /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(modelDirective.exp?.content?.trim() || '') }
+    const model = modelDirective.exp?.content?.trim() || ''
+    const info = repeatModelInfo(model, repeat)
+    return { model, repeatModel: info.repeatModel,
+      valid: !modelDirective.arg && !modelDirective.modifiers?.length && info.valid }
   }
   const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     prop.arg?.content === 'value')
   if (!bound) return { model: '', valid: true }
   const model = bound.exp?.content?.trim() || ''
-  return { model, valid: !bound.modifiers?.length && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !bound.modifiers?.length && info.valid }
+}
+
+function repeatDescriptor (node) {
+  const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'for')
+  if (!directive) return null
+  const parsed = directive.forParseResult
+  const source = parsed?.source?.content?.trim() || ''
+  const value = parsed?.value?.content?.trim() || ''
+  const index = parsed?.key?.content?.trim() || ''
+  const keyProp = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
+    prop.arg?.content === 'key' && !prop.modifiers?.length)
+  const key = keyProp?.exp?.content?.trim() || ''
+  const locator = `repeat:${hash(`${node.tag}:${node.loc.start.offset}:${directive.exp?.content || ''}`)}`
+  let kind = ''
+  let reason = ''
+  if (!SIMPLE_IDENTIFIER.test(source)) reason = 'v-for source must be one top-level array field'
+  else if (!SIMPLE_IDENTIFIER.test(value)) reason = 'v-for item alias must be a simple identifier'
+  else if (index && !SIMPLE_IDENTIFIER.test(index)) reason = 'v-for index alias must be a simple identifier'
+  else if (!key) reason = 'Repeated controls need a stable :key'
+  else if (key === `${value}.id`) kind = 'item'
+  else if (index && key === index) kind = 'array'
+  else reason = index
+    ? 'Object lists need :key="item.id" or array lists need :key="index"'
+    : 'Item v-for bindings require :key="item.id"'
+  return { locator, source, value, ...(index ? { index } : {}), key, kind,
+    markerOnControl: node.tag.toLowerCase() === 'template',
+    valid: !reason, ...(reason ? { reason } : {}) }
 }
 
 function normalizeMeterVModels (format) {
@@ -146,13 +225,14 @@ function normalizeMeterVModels (format) {
   return normalized
 }
 
-function pressedModel (node) {
+function pressedModel (node, repeat) {
   const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     ['aria-pressed', 'aria-checked'].includes(prop.arg?.content))
   if (!directive) return { model: '', valid: true }
   const model = directive.exp?.content?.trim() || ''
+  const info = repeatModelInfo(model, repeat)
   return { model, valid: !directive.modifiers?.length &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+    info.valid, repeatModel: info.repeatModel }
 }
 
 function openingTagEnd (source, start) {
@@ -188,13 +268,22 @@ function inspectTemplate (format) {
   }
   const candidates = []
   const counts = new Map()
+  const repeatMarkers = []
 
-  function visit (node, repeated = false) {
+  function visit (node, repeatContext = null) {
     if (node.type === 1) {
       if (node.tag.toLowerCase().startsWith('v-') && node.isSelfClosing) {
         throw new Error(`Vuetify component <${node.tag}> needs an explicit closing tag in Dashboard templates`)
       }
-      const insideRepeat = repeated || hasDirective(node, ['for'])
+      const ownRepeat = repeatDescriptor(node)
+      const activeRepeat = ownRepeat
+        ? repeatContext ? { ...ownRepeat, valid: false, reason: 'Nested v-for bindings are not supported' } : ownRepeat
+        : repeatContext
+      const insideRepeat = Boolean(activeRepeat)
+      if (ownRepeat?.valid && !repeatContext && !ownRepeat.markerOnControl) {
+        repeatMarkers.push({ offset: openingTagEnd(format, node.loc.start.offset),
+          locator: ownRepeat.locator, key: ownRepeat.key })
+      }
       const adapter = candidateAdapter(node)
       const customAttribute = (node.props || []).some(prop =>
         (prop.type === 6 && prop.name.startsWith('data-cp-')) ||
@@ -203,12 +292,13 @@ function inspectTemplate (format) {
       if (adapter) {
         const component = COMPONENT_ADAPTERS[node.tag.toLowerCase()] ? node.tag.toLowerCase() : ''
         const display = adapter === 'text-display'
-          ? displayModel(node)
-          : ['v-progress-linear', 'v-progress-circular'].includes(component) ? progressModel(node)
-          : adapter === 'meter' && !component ? nativeMeterModel(node)
+          ? 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'
-            ? pressedModel(node)
-            : inputModel(node, adapter === 'range' || adapter === 'select')
+            ? pressedModel(node, activeRepeat)
+            : inputModel(node, adapter === 'range' || adapter === 'select', activeRepeat)
         const source = format.slice(node.loc.start.offset, openingTagEnd(format, node.loc.start.offset) + 1)
         const stableName = attribute(node, 'id') || attribute(node, 'name')
         const locator = stableName
@@ -252,6 +342,7 @@ function inspectTemplate (format) {
         const candidate = {
           locator, adapter,
           ...(component ? { component } : {}),
+          ...(activeRepeat ? { repeat: activeRepeat } : {}),
           label: attribute(node, 'aria-label') || attribute(node, 'label') || attribute(node, 'title') ||
             stableName || display.model || (adapter === 'text-display' ? node.children[0]?.content?.trim() : '') || node.tag,
           ...(display.model ? { model: display.model } : {}),
@@ -267,12 +358,12 @@ function inspectTemplate (format) {
           } : {}),
           ...(attribute(node, 'data-unit') ? { unit: attribute(node, 'data-unit') } : {}),
           line: node.loc.start.line,
-          supported: !insideRepeat && !explicitLogic && display.valid && !dynamicBounds &&
+          supported: (!insideRepeat || Boolean(activeRepeat.valid && display.valid)) && !explicitLogic && display.valid && !dynamicBounds &&
             !invalidSliderBounds &&
             !customSwitchValues && !unsupportedSelect && !unsupportedRadio &&
             !unsupportedTextType && !unsupportedProgress && !unsupportedCircular &&
             (!component || Boolean(display.model)),
-          reason: insideRepeat ? 'Repeated controls need a stable item identity' :
+          reason: insideRepeat && !activeRepeat.valid ? activeRepeat.reason :
             explicitLogic ? 'Controls with existing handlers or reactive value bindings need a dedicated adapter' :
               !display.valid ? (adapter === 'text-display' ? 'Dynamic text needs one writable data field' :
                 'Only a simple Vue v-model field is supported') :
@@ -284,16 +375,20 @@ 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)
       }
-      for (const child of node.children || []) visit(child, insideRepeat)
+      for (const child of node.children || []) visit(child, activeRepeat)
       return
     }
-    for (const child of node.children || []) visit(child, repeated)
-    for (const branch of node.branches || []) visit(branch, repeated)
+    for (const child of node.children || []) visit(child, repeatContext)
+    for (const branch of node.branches || []) visit(branch, repeatContext)
   }
 
   if (descriptor.template?.ast) visit(descriptor.template.ast)
@@ -303,17 +398,33 @@ function inspectTemplate (format) {
       candidate.reason = 'This element is ambiguous; give it a unique HTML id or name'
     }
   }
-  return { candidates, templateHash: hash(format) }
+  return { candidates, repeatMarkers, templateHash: hash(format) }
 }
 
 function instrumentTemplate (format) {
   const inspected = inspectTemplate(format)
   let rendered = format
-  for (const candidate of [...inspected.candidates].reverse()) {
-    const before = rendered.slice(0, candidate.offset)
+  const insertions = new Map()
+  const addInsertion = (offset, value) => {
+    const list = insertions.get(offset) || []
+    list.push(value)
+    insertions.set(offset, list)
+  }
+  for (const candidate of inspected.candidates) {
+    addInsertion(candidate.offset, `data-cp-auto="${candidate.locator}"`)
+    if (candidate.repeat?.markerOnControl) {
+      addInsertion(candidate.offset,
+        `data-cp-repeat="${candidate.repeat.locator}" :data-cp-repeat-key="String(${candidate.repeat.key})"`)
+    }
+  }
+  for (const marker of inspected.repeatMarkers) {
+    addInsertion(marker.offset, `data-cp-repeat="${marker.locator}" :data-cp-repeat-key="String(${marker.key})"`)
+  }
+  for (const [offset, attributes] of [...insertions.entries()].sort((a, b) => b[0] - a[0])) {
+    const before = rendered.slice(0, offset)
     const selfClosing = /\/\s*$/.test(before)
-    const insertAt = selfClosing ? before.lastIndexOf('/') : candidate.offset
-    rendered = rendered.slice(0, insertAt) + ` data-cp-auto="${candidate.locator}"` + rendered.slice(insertAt)
+    const insertAt = selfClosing ? before.lastIndexOf('/') : offset
+    rendered = rendered.slice(0, insertAt) + ' ' + attributes.join(' ') + rendered.slice(insertAt)
   }
   return {
     format: normalizeMeterVModels(rendered),

package/panel-visual-bindings.js

@@ -1,10 +1,23 @@
 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}$/
 const MODES = new Set(['read', 'write', 'both'])
 
+function targetKey (candidate, entry) {
+  if (!candidate.repeat) return candidate.locator
+  if (typeof entry.instanceKey !== 'string' || !INSTANCE_KEY.test(entry.instanceKey)) {
+    throw new Error('Repeated visual controls need a stable instance key')
+  }
+  if (candidate.repeat.kind === 'array' && !/^(0|[1-9][0-9]*)$/.test(entry.instanceKey)) {
+    throw new Error('Array repeated controls need a non-negative integer instance key')
+  }
+  return `${candidate.locator}#${entry.instanceKey}`
+}
+
 function parseVisualBindings (config) {
   let raw = config.visualBindings || '{}'
   if (typeof raw === 'string') raw = JSON.parse(raw)
@@ -26,10 +39,11 @@ function visualRoutes (config) {
     if (!candidate || candidate.adapter !== entry.adapter) {
       throw new Error(`Visual control moved or became ambiguous: ${id}`)
     }
-    if (usedLocators.has(entry.locator)) throw new Error(`Duplicate visual control locator: ${id}`)
-    usedLocators.add(entry.locator)
+    const bindingKey = targetKey(candidate, entry)
+    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) {
@@ -39,9 +53,16 @@ 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 },
+        adapter: entry.adapter, locator: entry.locator,
+        ...(candidate.repeat ? { instanceKey: entry.instanceKey } : {}) },
       binding: entry
     })
   }
@@ -62,9 +83,10 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     used.add(raw.id)
     const candidate = candidates.get(raw.locator)
     if (!candidate || candidate.adapter !== raw.adapter) throw new Error(`Control changed: ${raw.id}`)
-    if (usedLocators.has(raw.locator)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
-    usedLocators.add(raw.locator)
-    if (!MODES.has(raw.mode) || (['meter', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
+    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', '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) {
@@ -91,15 +113,17 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     }
     if (candidate.model) {
       const identity = JSON.stringify([raw.device, read?.path, write?.path])
-      const previous = models.get(candidate.model)
+      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`)
       }
-      models.set(candidate.model, { identity, meter: Boolean(read?.meter) })
+      models.set(modelKey, { identity, meter: Boolean(read?.meter) })
     }
     result[raw.id] = {
       locator: raw.locator, adapter: raw.adapter, type, label: raw.label.trim(), mode: raw.mode,
       ...(candidate.model ? { model: candidate.model } : {}),
+      ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: raw.instanceKey } : {}),
       ...(candidate.component ? { component: candidate.component } : {}),
       ...(['range', 'meter'].includes(raw.adapter)
         ? { uiRange: { min: candidate.min, max: candidate.max, step: candidate.step } } : {}),

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 }