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

package/CONTROL_PANEL_AI_GUIDE.md

@@ -8,13 +8,14 @@
 
 页面作者使用普通 HTML、CSS 和 Vue 编写布局、样式、导航、控件及其本地状态。无需知道驱动协议、点位路径、内部 Control ID 或绑定表结构。标准 HTML `id`、Vue `v-model` 和 ARIA 属性不是 ControlPanel 专用标签。
 
-节点负责登录界面、普通与编辑权限、控件识别、映射保存、桥接生成、命令发送和反馈更新。页面不调用这些内部服务，不实现第二套设备通信。
+节点负责登录界面、普通与编辑权限、控件识别、映射保存、桥接生成、命令发送和反馈更新。页面不调用这些内部服务，不实现第二套设备通信。即使一个页面同时显示几十或上百个实时 Meter，页面也只声明普通控件和普通 Vue 数据字段，并用 `volume` 与 `meter1` 等不同字段表达不同语义。
 
 不得从旧页面复制以下内容：
 
 - 手写 `data-cp-*` 属性。这些属性会被拒绝；运行时自动添加的内部标记不属于页面交付代码。
 - `sendControl`、`postControl`、`setControlSession`、`deviceValue` 等旧页面接口。
 - 写死设备路径、驱动命令、绑定表，或调用 ControlPanel 的 HTTP、WebSocket、SSE 接口。
+- 声明 stream ID、订阅主题、帧格式、Socket.IO 事件或批量反馈协议。
 - 为修复反馈而添加设备轮询、强制回写滑杆、重复发送监听器或设备状态定时器。
 
 这些限制针对设备绑定，不禁止正常的页面导航、CSS 动画、图片明暗变化等纯前端功能。未绑定控件不会自动控制设备。待绑定控件的模型应独立；不要让两个不同设备控件共用一个 `v-model` 字段。
@@ -39,7 +40,8 @@
 | 布尔开关 | `input[type=checkbox]`、语义开关按钮 | `v-switch`、`v-checkbox` | 布尔值；切换发送。语义按钮写法见下节。 |
 | 单选枚举 | `select` | `v-select`、`v-radio-group` | 字符串或数字的单个值，必须与设备枚举值对应。 |
 | 文本输入 | `input[type=text]`、`textarea` | `v-text-field`、`v-textarea` | 字符串；原生 change 提交，Vuetify 在 change 或失焦时提交，`v-text-field` 还支持 Enter。 |
-| 只读数值 | `meter`、`progress` | `v-progress-linear`、`v-progress-circular` | 只绑定 Feedback point，不发送命令。 |
+| 普通只读数值 | `output`、文本展示 | 暂无 | 只绑定普通 Feedback point，不发送命令。使用简单顶层字段；不要把普通数值反馈写成 Meter。 |
+| 实时信号电平 Meter | `meter`、`progress` | `v-progress-linear`、`v-progress-circular` | 只绑定驱动明确声明 Meter 元数据的 Feedback point，不发送命令。使用独立的 `meter`/`meter1` 字段；原生 `meter`/`progress` 可使用简单 `v-model` 作为只读别名。 |
 | 只读文本 | `span`、`strong`、`b`、`output`、`h1`、`h2`、`h3` | 暂无 | 使用简单字段插值，如 `{{ status }}`，或由节点替换的纯文本；只绑定读点位。 |
 
 原生输入可以不写 Vue 模型，也支持简单顶层 `v-model`。Vuetify 交互控件必须写简单 `v-model`；进度组件可以使用简单 `:model-value="progress"`。初始化数值为数字、开关为布尔值、文本为字符串，不用数组、对象或空值占位。
@@ -47,7 +49,7 @@
 ### 3.1 通用限制
 
 - 待绑定控件自身不能有 `@click`、`@input`、`@change`、`@update:model-value` 等任何事件指令。即使事件只做本地操作，也会被当前识别器判为已有逻辑。页面导航等事件可放在独立、不绑定设备的控件上。
-- 不额外叠加 `:value`、`:checked`、`:model-value`。只读进度组件的 `:model-value` 是例外；语义开关按钮的简单 ARIA 布尔绑定也是例外。
+- 交互输入控件不额外叠加 `:value`、`:checked`、`:model-value`。只读原生 meter/progress 的 `:value`、Vuetify 进度组件的 `:model-value` 和语义开关按钮的简单 ARIA 布尔绑定是例外。
 - 只允许 range/select 的 `v-model.number`；不要用 `.lazy`、`.trim`、带参数的 `v-model` 或其他修饰符。
 - 待绑定元素不能位于 `v-for` 中，即使写了 `:key`。相同模板会生成多个元素，当前不能按列表项分别绑定。
 - 标签页、`v-if` 等正常布局可以保留。编辑该控件时先让它显示出来，并确保同一定位只出现一个元素。绑定提示会随元素重建恢复。
@@ -57,13 +59,22 @@
 
 - 数值：`min`、`max`、`step` 用固定数字，也可用 `:min="0"`、`:max="100"`、`:step="1"`。不能绑定到动态字段或表达式。`v-slider` 要求 min < max、step > 0，不支持 `step="any"`。
 - 原生 range 默认 0–100；原生 meter/progress 默认 0–1。原生 number 没有缺省完整量程；需要自动缩放时明确写 min/max。不要把原生缺省量程误当成设备量程。
+- 原生 `meter`/`progress` 可使用标准 `:value="meter1"`，也可使用简单 `v-model="meter1"` 作为只读别名；节点会在编译前将后者转换为 `:value`。不支持 `v-model.number`、动态表达式或同时写 `:value`。只有驱动点位带有 Meter 元数据时，`meter`/`progress` 才能建立绑定；它由独立的 Meter 批量帧通道更新，不能接收网页设置。音量滑杆的 `volume` 与 Meter 的 `meter` 必须是两个不同字段，不能把同一个字段绑定到两个不同设备点位。普通 volume/level 反馈不能选择为 Meter。Vuetify `progress` 组件仍使用简单 `:model-value`；未绑定的进度条可以作为普通前端视觉元素。
 - Vuetify switch/checkbox 不支持 `value`、自定义 `true-value`/`false-value`、`multiple` 或数组模型。
 - Vuetify select 不支持多选、`return-object`、`clearable` 或对象模型；选项可用标量数组，或普通 `{ title, value }` 选项但模型必须是标量。`v-radio-group` 使用标量模型，子项也不能自带事件处理器。
 - Vuetify 文本控件只用字符串模型。`v-text-field` 使用文本类型，不用数字、密码等类型；不支持 `.number`。`v-textarea` 的 Enter 是换行，不是提交。
 - `v-progress-linear` 从 0 到固定正数 max，默认 max=100；不支持 min、step、indeterminate、clickable。`v-progress-circular` 固定 0–100，不声明 min/max/step，也不使用 indeterminate。
 - 文本展示推荐只放一个简单插值，如 `<span>{{ status }}</span>`，不使用 `status.toFixed()`、拼接表达式或多个插值。复杂展示可用另外的纯前端元素，不把它作为设备反馈绑定目标。
 
-### 3.3 普通按钮与开关按钮
+### 3.3 Meter 实时信号与批量反馈
+
+页面作者不编写订阅、socket 或批处理代码，但要用不同字段表达不同语义：音量/增益使用 `volume` 等普通可写字段；实时信号使用 `meter`、`meter1` 等只读字段。部署人员在绑定编辑页选择 Feedback point；只有驱动明确声明 Meter 元数据的点位才会进入 Meter 列表，ControlPanel 会在运行时自动采用批量反馈通道，并把同一帧的数据一次性更新到本页对应的所有表头。
+
+页面不需要也不得声明设备、驱动、stream、socket、帧序号、点位路径或 ControlPanel API。断线、过期帧、重连、同帧合并和页面量程换算都由节点处理。反馈短暂失效时节点保留最后显示值并标记无效；页面作者不添加轮询、定时器或回写逻辑。标签页、`v-if` 等使控件重新创建后，节点会重新关联控件。
+
+多个表头必须使用不同的 `id` 和不同的顶层字段。不要让属于不同设备点位的表头共用同一个字段；同一个滑杆及其纯视觉旁显可以共享字段，但只能绑定其中一个控件。Meter 与 volume 是完全独立的通信类型：volume 负责音量/增益设置和普通真实值反馈，Meter 只负责某音频通道的高频实时信号电平反馈。代码或驱动中的历史 `level` 名称不自动表示 Meter；是否具备 Meter 能力由点位的 Meter 元数据决定。
+
+### 3.4 普通按钮与开关按钮
 
 一个只有文字的普通 `<button>` 不会自动成为设备控件。需要布尔设备开关时使用标准语义：
 
@@ -90,12 +101,14 @@
       <option value="B">输入 B</option>
     </select>
     <span id="room-status">{{ status }}</span>
+    <meter id="room-meter" :value="meter" min="0" max="100" aria-label="实时信号电平"></meter>
+    <progress id="room-progress" :value="progress" max="100" aria-label="进度"></progress>
   </section>
 </template>
 <script>
 export default {
   data () {
-    return { volume: 0, muted: false, powered: false, source: 'A', status: '待机' }
+    return { volume: 0, meter: 0, muted: false, powered: false, source: 'A', status: '待机', progress: 0 }
   }
 }
 </script>
@@ -114,7 +127,7 @@ export default {
       <v-radio label="模式 B" value="B"></v-radio>
     </v-radio-group>
     <v-text-field id="room-title" label="名称" v-model="title"></v-text-field>
-    <v-progress-linear id="room-level" :model-value="level" :max="100"></v-progress-linear>
+    <v-progress-linear id="room-meter" :model-value="meter" :max="100"></v-progress-linear>
     <span id="room-status">{{ status }}</span>
   </section>
 </template>
@@ -123,7 +136,7 @@ export default {
   data () {
     return {
       volume: 0, muted: false, source: 'A', sources: ['A', 'B'],
-      mode: 'A', title: '', level: 0, status: '待机'
+      mode: 'A', title: '', meter: 0, status: '待机'
     }
   }
 }
@@ -155,7 +168,9 @@ Bindings 列表可 Edit 或 Remove；这些操作先改草稿，最后统一 App
 | 参数描述 | 可匹配控件 |
 | --- | --- |
 | boolean，或无枚举且范围恰为 0–1 的 integer | 布尔开关；整数 0/1 由节点转换为前端布尔值。 |
-| integer/float 数值参数 | range、数值进度；有枚举或 0/1 布尔语义时优先对应相应类别。 |
+| 可写 integer/float 数值参数 | range；这类参数用于 volume/增益等普通连续设置。 |
+| 只读 integer/float，且没有 Meter 元数据 | 只读文本展示；不能选择为 Meter。 |
+| 只读 integer/float，且带 `.metadata.meter` | Meter、原生 `meter` 或 Vuetify 进度组件；只走实时 Meter 反馈。 |
 | enum，或带枚举描述的 integer/string | 单选枚举。当前整数路径以 `/source`、`/preset` 结尾也会按选择类处理；仍需确认合法选项。 |
 | string/dstring | 文本输入。 |
 | 上述类型的可读参数 | 简单文本展示也可绑定。 |
@@ -173,6 +188,7 @@ Write point 改动时 Feedback point 跟随；单独改 Feedback point 不反向
 | 控件不能选中 | 是否在支持清单、是否有事件指令/复杂模型/v-for、自闭合 Vuetify、重复 ID；阅读编辑页给出的拒绝原因。 |
 | 有设备但点位为空 | 在线状态、参数目录、值类型与 ro/wo/rw 权限；不是所有设备命令都属于可绑定参数。 |
 | 草稿有紫框但普通页无效 | Apply 是否成功、模式和点位是否正确、桥接是否同步、MUSE 是否加载预期模块版本。 |
+| 页面一直 Loading | 先检查节点状态和运行日志中的模板编译错误，例如在原生 meter/progress 上使用带修饰符的 v-model、动态表达式或同时写 v-model 与 :value。简单顶层 v-model 会由节点转换为只读 :value；节点会显示具体模板错误。会话检查包含响应正文的超时保护，设备离线不应阻止普通页进入登录页。登录检查的时限不包含 Dashboard 资源下载和组件编译时间。 |
 | 滑杆动不了 | 是否仍在 Select 编辑模式、模型类型是否正确、是否存在手写回写逻辑；不要先改驱动。 |
 | 页面变化但设备不变 | 写映射和驱动收发日志。前端变化不证明命令到达设备。 |
 | 设备已变但页面旧值 | Feedback point、事件/读取是否有新反馈。节点不能凭写入成功制造真实设备反馈。 |
@@ -186,6 +202,7 @@ Write point 改动时 Feedback point 跟随；单独改 Feedback point 不反向
 - 所有待绑定控件位于支持清单，使用稳定唯一 ID；数据模型简单、独立且类型正确。
 - 页面量程明确、数值常量有效；下拉菜单选项与实际设备值对应。
 - 没有手写 `data-cp-*`、旧发送接口、设备通信、绑定控件事件或复杂模型。
+- 实时表头仍是普通 HTML/Vue/Vuetify；没有 stream、socket、订阅、帧协议或驱动相关代码。
 - Vuetify 标签成对闭合；不把自动绑定目标放入 v-for。
 - 保留正常的视觉与纯前端交互；不为了绑定重写驱动或添加第二套控制逻辑。
 - 不声称任意普通页面都可无条件自动绑定；不支持的组件要明确说明，不能伪造兼容写法。

package/README.md

@@ -12,6 +12,8 @@ Bindings are stored in `visualBindings` on the node. The runtime reads that mapp
 
 Supported controls include native range, checkbox, semantic pressed button, select, text input, meter, progress, and simple text display. Give repeated controls distinct standard IDs. Simple top-level Vue `v-model` works; controls with existing send handlers or ambiguous dynamic behavior are rejected until a suitable adapter exists. See `CONTROL_PANEL_AI_GUIDE.md` for examples and limits.
 
+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.
+
 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-bound-protocol.js

@@ -66,7 +66,7 @@ function resolveBoundFeedback (routes, message) {
   const matches = []
   for (const [id, route] of routes) {
     if (route.control.mode === 'write' || route.binding?.device !== message.device ||
-      route.binding.readPath !== message.path) continue
+      route.binding.readPath !== message.path || route.binding.readMeta?.meter) continue
     const type = route.control.type
     const metadata = route.binding.readMeta
     let value = message.payload

package/control-catalog.js

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

package/control-panel.js

@@ -10,6 +10,7 @@ const { createPanelEditor } = require('./panel-editor-auth')
 const { applyVisualBindings, editorConfig, getSnapshot } = require('./panel-visual-apply')
 const { createGateway } = require('./gateway.cjs')
 const { managedBridgeRevision } = require('./managed-bridge-revision')
+const { createMeterRoom, createPanelMeter } = require('./panel-meter')
 
 let statestore
 const authHandoffKey = crypto.randomBytes(32)
@@ -69,6 +70,7 @@ module.exports = function (RED) {
   const base = catalogBase(RED.settings)
   const activePanels = new Map()
   const activeEditors = new Map()
+  const meterRooms = 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'))
@@ -147,6 +149,16 @@ module.exports = function (RED) {
     }
     node.status?.(bridgeReady ? {} : { fill: 'red', shape: 'ring', text: 'bridge out of sync' })
 
+    let meter
+    if ([...routes.values()].some(route => route.binding.readMeta?.meter) && /^[a-zA-Z0-9_-]+$/.test(boundRoom || '')) {
+      try {
+        let hub = meterRooms.get(boundRoom)
+        if (!hub) { hub = createMeterRoom({ room: boundRoom }); meterRooms.set(boundRoom, hub) }
+        meter = createPanelMeter({ 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 || '')) {
@@ -160,6 +172,8 @@ module.exports = function (RED) {
           prefix: endpoint,
           secureCookie: config.secureCookie === true,
           restoredSessions: takeSessions(gatewayHandoffs, node.id, gatewayAuthKey),
+          onAuthenticatedRequest: (req, res, identity) => meter?.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 })
@@ -188,6 +202,8 @@ module.exports = function (RED) {
         password: node.credentials?.editorPassword,
         secureCookie: config.secureCookie === true,
         restoredSessions: takeSessions(editorHandoffs, node.id, editorAuthKey),
+        onAuthenticatedRequest: (req, res, identity) => meter?.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 () => {
@@ -214,7 +230,7 @@ module.exports = function (RED) {
     }
 
     const panelConfig = () => (boundMode || visualBinding) ? {
-      endpoint, room: boundRoom,
+      endpoint, room: boundRoom, meter: Boolean(meter),
       ...(visualBinding ? { visual: {
         panelId: node.id,
         editorEndpoint: `/control-panel-edit/panels/${node.id}`,
@@ -225,8 +241,15 @@ module.exports = function (RED) {
 
     const events = {
       onAction: !boundMode,
+      ...(meter ? { onSocket: meter.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)) {
+          if (bridgeReady) meter?.accept(msg)
+          // Dashboard 1.31 reads properties before checking whether a message
+          // should be emitted. `false` is property-safe and suppresses emit.
+          return false
+        }
         if (boundMode) {
           if (msg?.kind === 'device-feedback' && gateway) {
             gateway.boundFeedback(resolveBoundFeedback(routes, msg))
@@ -279,7 +302,13 @@ module.exports = function (RED) {
       } catch (error) {
         node.error(error)
         node.status?.({ fill: 'red', shape: 'ring', text: 'visual template unsupported' })
-        return
+        const message = String(error.message).replace(/[&<>]/g,
+          char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[char])
+        widgetConfig = { ...config, type: 'ui-template',
+          format: '<template><section role="alert" style="padding:24px;color:#a52a35;background:#fff">' +
+            '<h2>ControlPanel template error</h2><pre v-pre style="white-space:pre-wrap;overflow-wrap:anywhere">' +
+            message + '</pre></section></template>',
+          passthru: false, storeOutMessages: false, resendOnRefresh: false }
       }
       parentNode = group || page || ui
       if (group) group.register(node, widgetConfig, events)
@@ -295,6 +324,8 @@ module.exports = function (RED) {
       if (editor) holdSessions(editorHandoffs, node.id, editorAuthKey, editor.sessionSnapshot())
       gateway?.close()
       editor?.close()
+      meter?.close()
+      if (meterRooms.get(boundRoom)?.stats().panels === 0) meterRooms.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

@@ -3,6 +3,8 @@ const escodegen = require('escodegen')
 const { initializeVisualBinding, disposeVisualBinding } = require('./panel-binding-editor')
 const { fetchWithTimeout } = require('./panel-http')
 const { createTargetMatcher } = require('./control-type-model')
+const { createRoomMeterReceiver, createMeterRenderer } = require('./meter-frame')
+const { createPanelMeterClient } = require('./panel-meter-client')
 
 const CONTROL_POLICY_MARKER = '/* ui-control-panel-control-api-v1 */'
 
@@ -157,6 +159,11 @@ function createControlPanelPolicy ({
 // generated script remains inside that supported subset.
 function buildDashboardPolicyOptionsSource (controls = [], boundPanel = null) {
   const boundControls = controls.map(({ id, type, mode }) => ({ id, type, mode }))
+  const meterMethods = boundPanel?.meter
+    ? `__createRoomMeterReceiver: ${createRoomMeterReceiver.toString()},
+    __createMeterRenderer: ${createMeterRenderer.toString()},
+    __createPanelMeterClient: ${createPanelMeterClient.toString()},`
+    : ''
   const visualMethods = boundPanel?.visual
     ? `__createTargetMatcher: ${createTargetMatcher.toString()},
     __initializeVisualBinding: ${initializeVisualBinding.toString()},
@@ -180,6 +187,7 @@ export default {
     }
   },
   methods: {
+    ${meterMethods}
     ${visualMethods}
     __panelFetch: ${fetchWithTimeout.toString()},
     __boundPanelConfig () {
@@ -304,6 +312,7 @@ export default {
       }
     },
     __disposeControlPanelPolicy () {
+      this.__boundAuthGeneration++
       this.__boundUnwatch?.()
       this.__boundUnwatch = null
       this.__clearAllBoundSettlements()
@@ -381,28 +390,28 @@ export default {
       if (!config) throw new Error('This panel has no bound login endpoint')
       this.clearBoundPanelSession()
       const generation = this.__boundAuthGeneration
-      const response = await this.__panelFetch(config.endpoint + '/login', {
+      const { response, session } = await this.__panelFetch(config.endpoint + '/login', {
         method: 'POST', credentials: 'same-origin',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ username, password })
-      })
+      }, 12000, async response => ({ response, session: response.ok ? await response.json() : null }))
       if (!response.ok) throw new Error('Panel login failed (' + response.status + ')')
-      const session = await response.json()
       if (generation !== this.__boundAuthGeneration) return null
       this.setBoundPanelSession(session)
       return session
     },
-    async restoreBoundPanelSession () {
+    async restoreBoundPanelSession (timeoutMs = 2500) {
       const config = this.__boundPanelConfig()
       if (!config) return null
       const generation = this.__boundAuthGeneration
-      const response = await this.__panelFetch(config.endpoint + '/session', { credentials: 'same-origin' })
+      const { response, session } = await this.__panelFetch(config.endpoint + '/session', {
+        credentials: 'same-origin'
+      }, timeoutMs, async response => ({ response, session: response.ok ? await response.json() : null }))
       if (generation !== this.__boundAuthGeneration) return this.__boundPanelSession
       if (!response.ok) {
         this.clearBoundPanelSession()
         return null
       }
-      const session = await response.json()
       if (generation !== this.__boundAuthGeneration) return this.__boundPanelSession
       this.setBoundPanelSession(session)
       return session
@@ -456,7 +465,7 @@ export default {
   },
   mounted () {
     this.__initializeControlPanelPolicy()
-    if (this.__boundPanelConfig()) this.restoreBoundPanelSession().catch(() => undefined)
+    ${boundPanel?.visual ? '' : 'if (this.__boundPanelConfig()) this.restoreBoundPanelSession().catch(() => undefined)'}
     ${visualMounted}
   },
   unmounted () {

package/control-type-contract.json

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

package/control-type-model.js

@@ -1,4 +1,5 @@
 const contract = require('./control-type-contract.json')
+const { meterRoute } = require('./meter-route')
 
 
 
@@ -22,6 +23,8 @@ function createTargetMatcher (typeContract) {
     return definition.family
   }
   function compatible (adapter, target, direction, candidate = {}) {
+    if (adapter === 'meter' && !target.meter) return false
+    if (target.meter && (adapter !== 'meter' || 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 (!['read', 'write'].includes(direction)) return false
@@ -38,6 +41,7 @@ function controlTypeForAdapter (adapter, target) {
   if (!compatibleTarget(adapter, target, 'read') && !compatibleTarget(adapter, target, 'write')) {
     throw new Error('Target is incompatible with this control')
   }
+  if (adapter === 'meter' && target.meter) return 'meter'
   const family = targetFamily(target)
   if (family === 'number') return 'level'
   if (family === 'boolean') return 'mute'
@@ -55,7 +59,8 @@ function targetMeta (target, onebased) {
     onebased: typeof target.onebased === 'boolean' ? target.onebased : onebased,
     min: target.min, max: target.max, enums: target.enums,
     ...(target.booleanEncoding ? { booleanEncoding: target.booleanEncoding } : {}),
-    controlType: target.controlType, controlSchemaVersion: target.controlSchemaVersion
+    controlType: target.controlType, controlSchemaVersion: target.controlSchemaVersion,
+    ...(target.meter ? { meter: meterRoute(target.meter), unit: target.unit || '' } : {})
   }
 }
 

package/gateway.cjs

@@ -9,6 +9,7 @@ function createGateway ({
   room = 'room-01',
   onBoundCommand,
   onBoundLogin,
+  onAuthenticatedRequest,
   secureCookie = false,
   prefix,
   sessionTtlMs = 8 * 3600000,
@@ -193,6 +194,8 @@ function createGateway ({
         reply(res, 403, { error: 'CSRF rejected' })
         return true
       }
+      if (onAuthenticatedRequest && await onAuthenticatedRequest(req, res,
+        { token, expiry: session.expiry, room, user: username })) return true
       if (path === routePrefix + '/session' && req.method === 'GET') {
         reply(res, 200, { room, username, csrf: session.csrf })
         return true
@@ -255,6 +258,7 @@ function createGateway ({
   return {
     handler,
     boundFeedback,
+    sessionActive: token => !closed && (sessions.get(token)?.expiry || 0) > Date.now(),
     sessionSnapshot () {
       return new Map([...sessions].filter(([, session]) => session.expiry > Date.now())
         .map(([token, session]) => [token, { ...session }]))

package/managed-native-bridge.js

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

package/meter-frame.js

@@ -0,0 +1,111 @@
+// Shared, non-reactive receivers; usable in Node and injected Vue component methods.
+function createMeterReceiver (manifest) {
+  const number = value => typeof value === 'number' && Number.isFinite(value)
+  if (manifest?.kind !== 'meter-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' ||
+    !number(manifest.publishHz) || manifest.publishHz < 1 || manifest.publishHz > 60 ||
+    !Array.isArray(manifest.points) || !manifest.points.length || manifest.points.length > 256) {
+    throw Error('Invalid meter manifest')
+  }
+  const paths = new Set()
+  const points = Array.from(manifest.points, point => {
+    if (typeof point?.path !== 'string' || !/^\/[^/]/.test(point.path) ||
+      point.path.length > 1025 || paths.has(point.path) ||
+      !['integer', 'float'].includes(point.type) || !number(point.min) ||
+      !number(point.max) || point.min >= point.max ||
+      (point.type === 'integer' && (!Number.isSafeInteger(point.min) || !Number.isSafeInteger(point.max))) ||
+      typeof point.unit !== 'string' || point.unit.length > 32) throw Error('Invalid meter point')
+    paths.add(point.path)
+    return Object.freeze({ path: point.path, type: point.type, min: point.min, max: point.max, unit: point.unit })
+  })
+  const schema = Object.freeze({ ...manifest, points: Object.freeze(points) })
+  let latest = null, pending = false, closed = false
+  return {
+    manifest: schema,
+    accept (frame) {
+      if (closed || frame?.kind !== 'meter-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) ||
+        !number(frame.sampleTime) || frame.sampleTime < 0 ||
+        !Array.isArray(frame.values) || frame.values.length !== points.length ||
+        !Array.isArray(frame.valid) || frame.valid.length !== points.length) return false
+      const values = [], valid = []
+      for (let index = 0; index < points.length; index++) {
+        const point = points[index], value = frame.values[index], flag = frame.valid[index]
+        if (typeof flag !== 'boolean' || (flag && (!number(value) ||
+          value < point.min || value > point.max ||
+          (point.type === 'integer' && !Number.isSafeInteger(value))))) return false
+        values.push(flag ? value : null)
+        valid.push(flag)
+      }
+      latest = Object.freeze({ kind: 'meter-frame', streamId: schema.streamId,
+        epoch: schema.epoch, seq: frame.seq, layoutVersion: schema.layoutVersion,
+        sampleTime: frame.sampleTime, values: Object.freeze(values), valid: Object.freeze(valid) })
+      pending = true
+      return true
+    },
+    snapshot () { return latest },
+    take () {
+      if (!pending) return null
+      pending = false
+      return latest
+    },
+    close () { closed = true; pending = false; latest = null }
+  }
+}
+
+function createMeterRenderer ({ 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 createRoomMeterReceiver (layout) {
+  if (layout?.kind !== 'room-meter-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 meter layout')
+  }
+  let latest = null, pending = false, closed = false
+  const count = layout.ids.length
+  return {
+    accept (frame) {
+      if (closed || frame?.kind !== 'room-meter-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 ||
+        frame.valid.some((flag, index) => typeof flag !== 'boolean' || (flag
+          ? typeof frame.values[index] !== 'number' || !Number.isFinite(frame.values[index])
+          : frame.values[index] !== null))) return false
+      latest = { values: frame.values.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 = { createMeterReceiver, createMeterRenderer, createRoomMeterReceiver }

package/meter-route.js

@@ -0,0 +1,12 @@
+function meterRoute (value) {
+  if (value == null) return null
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    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 meter delivery metadata')
+  }
+  return { streamId: value.streamId, eventPath: value.eventPath, manifestPath: value.manifestPath }
+}
+
+module.exports = { meterRoute }