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

package/panel-momentary-client.js

@@ -0,0 +1,91 @@
+// Serialized into the Dashboard component; only standard browser APIs belong here.
+function attachMomentaryButton ({ node, id, endpoint, getSession, canStart, request, onError, state = { seq: 0 } }) {
+  if (!state.client) state.client = Array.from(crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, '0')).join('')
+  let generation = 0, active = null, timer = null
+  const listeners = []
+  function listen (target, name, callback) {
+    target.addEventListener(name, callback)
+    listeners.push(() => target.removeEventListener(name, callback))
+  }
+  function transmit (action, session) {
+    return request(endpoint + '/bound-command', {
+      method: 'POST', credentials: 'same-origin', keepalive: action === 'release',
+      headers: { 'Content-Type': 'application/json', 'X-Room-CSRF': session.csrf },
+      body: JSON.stringify({ room: session.room, _controlPanel: { kind: 'command', id,
+        value: action !== 'release', final: true,
+        hold: { client: state.client, seq: ++state.seq, action, epoch: session.holdEpoch } } })
+    }, 1800, async response => {
+      if (!response.ok) throw Error('Momentary command failed (' + response.status + ')')
+      if (typeof response.json === 'function') {
+        const result = await response.json()
+        if (action !== 'release' && result.held !== true) throw Error('Momentary hold expired; press again')
+      }
+    })
+  }
+  function release () {
+    if (!active) return
+    const previous = active
+    active = null
+    generation++
+    clearTimeout(timer)
+    timer = null
+    void transmit('release', previous.session).catch(onError)
+    if (previous.pointer !== undefined && node.hasPointerCapture?.(previous.pointer)) {
+      try { node.releasePointerCapture(previous.pointer) } catch (_) {}
+    }
+  }
+  function renew (version) {
+    if (!active || version !== generation) return
+    if (!node.isConnected || !canStart()) { release(); return }
+    void transmit('renew', active.session).then(() => {
+      if (active && version === generation) timer = setTimeout(() => renew(version), 750)
+    }).catch(error => {
+      if (active && version === generation) release()
+      onError(error)
+    })
+  }
+  function start (source) {
+    if (active || node.disabled || !canStart()) return
+    const session = getSession()
+    if (!session?.csrf) return
+    active = { ...source, session: { ...session } }
+    const version = ++generation
+    void transmit('start', active.session).then(() => {
+      if (active && version === generation) timer = setTimeout(() => renew(version), 750)
+    }).catch(error => {
+      if (active && version === generation) release()
+      onError(error)
+    })
+  }
+  listen(node, 'pointerdown', event => {
+    if (event.button !== 0 || active) return
+    event.preventDefault()
+    node.focus()
+    start({ pointer: event.pointerId })
+    if (active) { try { node.setPointerCapture(event.pointerId) } catch (_) {} }
+  })
+  const pointerEnd = event => { if (active?.pointer === event.pointerId) release() }
+  listen(window, 'pointerup', pointerEnd)
+  listen(window, 'pointercancel', pointerEnd)
+  listen(node, 'lostpointercapture', pointerEnd)
+  listen(node, 'keydown', event => {
+    if (![' ', 'Enter'].includes(event.key)) return
+    event.preventDefault()
+    if (!event.repeat) start({ key: event.key })
+  })
+  listen(window, 'keyup', event => {
+    if (active?.key === event.key) { event.preventDefault(); release() }
+  })
+  listen(node, 'click', event => event.preventDefault())
+  listen(node, 'blur', release)
+  listen(window, 'blur', release)
+  listen(window, 'pagehide', release)
+  listen(document, 'visibilitychange', () => { if (document.hidden) release() })
+  return {
+    release,
+    check () { if (!node.isConnected || node.disabled || !canStart()) release() },
+    dispose () { release(); for (const remove of listeners) remove() }
+  }
+}
+
+module.exports = { attachMomentaryButton }

package/panel-momentary.js

@@ -0,0 +1,93 @@
+const { resolveBoundCommand } = require('./control-bound-protocol')
+const crypto = require('node:crypto')
+
+function createMomentaryControls ({ routes, send, onError = () => {}, leaseMs = 3000,
+  now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const records = new Map()
+  const epoch = crypto.randomBytes(16).toString('hex')
+  let timer = null
+  let closed = false
+  const destination = command => JSON.stringify([command.device, command.path])
+  const occupied = key => [...records.values()].some(record => record.active && record.target === key)
+
+  function release (record) {
+    if (!record.active) return
+    record.active = false
+    if (!occupied(record.target)) {
+      try { send(record.off, record.identity) } catch (error) { onError(error) }
+    }
+  }
+  function sweep () {
+    const time = now()
+    for (const [key, record] of records) {
+      if (record.active && record.until <= time) release(record)
+      if (record.identity.expiry <= time) { release(record); records.delete(key) }
+    }
+  }
+  function schedule () {
+    if (timer) clearTimer(timer)
+    timer = null
+    const deadlines = [...records.values()].filter(record => record.active).map(record => record.until)
+    if (closed || !deadlines.length) return
+    timer = setTimer(() => { timer = null; sweep(); schedule() }, Math.max(1, Math.min(...deadlines) - now()))
+    timer.unref?.()
+  }
+  function handle (message, identity) {
+    if (closed) throw Error('Momentary controls unavailable')
+    const request = message?._controlPanel
+    const hold = request?.hold
+    const route = routes.get(request?.id)
+    if (route?.control.buttonBehavior !== 'momentary' || route.control.mode !== 'both') {
+      throw Error('This control is not a momentary button')
+    }
+    if (!hold || hold.epoch !== epoch || !/^[A-Za-z0-9_-]{1,64}$/.test(hold.client || '') ||
+      !Number.isSafeInteger(hold.seq) || hold.seq < 1 ||
+      !['start', 'renew', 'release'].includes(hold.action) ||
+      request.value !== (hold.action !== 'release') ||
+      typeof identity?.token !== 'string' || !Number.isFinite(identity.expiry) || identity.expiry <= now()) {
+      throw Error('Invalid momentary command')
+    }
+    const command = resolveBoundCommand(routes, message)
+    sweep()
+    const key = JSON.stringify([identity.token, request.id, hold.client])
+    let record = records.get(key)
+    if (!record) {
+      if (records.size >= 1024) throw Error('Momentary client limit reached')
+      record = { seq: 0, active: false, target: destination(command), identity,
+        off: resolveBoundCommand(routes, { _controlPanel: { kind: 'command', id: request.id, value: false, final: true } }) }
+      records.set(key, record)
+    }
+    // Keep the sequence watermark after release: a delayed press must not re-enable the device.
+    if (hold.seq <= record.seq) return { held: record.active }
+    record.seq = hold.seq
+    if (hold.action === 'release') release(record)
+    else if (hold.action === 'start') {
+      const alreadyHeld = occupied(record.target)
+      if (!alreadyHeld) send(command, identity)
+      record.active = true
+      record.until = Math.min(now() + leaseMs, identity.expiry)
+    } else if (record.active) record.until = Math.min(now() + leaseMs, identity.expiry)
+    schedule()
+    return { held: record.active }
+  }
+  return {
+    epoch,
+    handle,
+    isHeld (command) { sweep(); return occupied(destination(command)) },
+    releaseSession (token) {
+      for (const [key, record] of records) {
+        if (record.identity.token === token) { release(record); records.delete(key) }
+      }
+      schedule()
+    },
+    close () {
+      closed = true
+      if (timer) clearTimer(timer)
+      timer = null
+      for (const record of records.values()) release(record)
+      records.clear()
+    }
+  }
+}
+
+module.exports = { createMomentaryControls }

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'
@@ -326,6 +341,7 @@ function inspectTemplate (format) {
           (enabledBooleanProp(node, ['indeterminate']) || hasAttribute(node, ['min', 'max', 'step']))
         const candidate = {
           locator, adapter,
+          ...(adapter === 'switch' && node.tag.toLowerCase() === 'button' ? { button: true } : {}),
           ...(component ? { component } : {}),
           ...(activeRepeat ? { repeat: activeRepeat } : {}),
           label: attribute(node, 'aria-label') || attribute(node, 'label') || attribute(node, 'title') ||
@@ -360,7 +376,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,11 +1,22 @@
 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 buttonBehavior (entry, candidate) {
+  const behavior = entry.buttonBehavior ?? 'toggle'
+  if (!['toggle', 'momentary'].includes(behavior) ||
+    (entry.buttonBehavior !== undefined && !candidate.button) ||
+    (behavior === 'momentary' && entry.mode !== 'both')) {
+    throw new Error('Button behavior requires a boolean button; momentary buttons require both mode')
+  }
+  return behavior
+}
+
 function targetKey (candidate, entry) {
   if (!candidate.repeat) return candidate.locator
   if (typeof entry.instanceKey !== 'string' || !INSTANCE_KEY.test(entry.instanceKey)) {
@@ -39,10 +50,14 @@ function visualRoutes (config) {
       throw new Error(`Visual control moved or became ambiguous: ${id}`)
     }
     const bindingKey = targetKey(candidate, entry)
+    const behavior = buttonBehavior(entry, candidate)
+    if (behavior === 'momentary' && !['mute', 'power'].includes(entry.type)) {
+      throw new Error('Momentary buttons require a boolean control type')
+    }
     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,9 +67,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,
+        ...(candidate.button ? { buttonBehavior: behavior } : {}),
         ...(candidate.repeat ? { instanceKey: entry.instanceKey } : {}) },
       binding: entry
     })
@@ -77,9 +99,10 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     const candidate = candidates.get(raw.locator)
     if (!candidate || candidate.adapter !== raw.adapter) throw new Error(`Control changed: ${raw.id}`)
     const bindingKey = targetKey(candidate, raw)
+    const behavior = buttonBehavior(raw, candidate)
     if (usedLocators.has(bindingKey)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(raw.mode) || (['meter', '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) {
@@ -115,6 +138,7 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     }
     result[raw.id] = {
       locator: raw.locator, adapter: raw.adapter, type, label: raw.label.trim(), mode: raw.mode,
+      ...(candidate.button ? { buttonBehavior: behavior } : {}),
       ...(candidate.model ? { model: candidate.model } : {}),
       ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: raw.instanceKey } : {}),
       ...(candidate.component ? { component: candidate.component } : {}),

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 }