node-red-contrib-room-tools 1.8.2 → 1.8.3

package/CONTROL_PANEL_AI_GUIDE.md

@@ -1,239 +1,74 @@
-# ControlPanel AI 开发契约
+# ControlPanel 前端页面编写规范
 
-适用节点：`ui-control-panel` 1.8.2。
+本文适用于当前 `ui-control-panel` 的可视化绑定版本。给 AI 编写页面前先阅读本文：页面作者只负责普通 Dashboard 2 / Vue 页面和控件状态，不编写设备协议、驱动路径、绑定表或 ControlPanel 专用 API。
 
-把本文件作为 AI 开发或修改 ControlPanel Template 前的强制上下文。目标是让
-不同页面使用同一套控制语义，避免滑杆积压、重复队列、反馈回环和跨房间误发。
+## 页面交付与绑定流程
 
-## 1. 保持节点边界
+1. 在 `ui-control-panel` 的 Template 中粘贴 Vue 单文件组件式页面（`<template>`、可选的 `<script>` 和 `<style>`）。节点选择 Dashboard 页面，填写 `Room ID`、普通页面账号及独立的编辑账号，保存并 Deploy。
+2. 重新打开该节点，点击 `Open page binding editor`。用编辑账号登录；编辑页默认启用 Select，可点击或右键点选可绑定控件，再选择在线设备、读写点位与编号方式。控件的绑定会先保存为草稿。
+3. 在编辑页点 Apply，节点校验并保存隐藏映射、备份 Flow、重新生成该面板的 native bridge 并部署。Apply 后仍留在编辑页；点 Exit 才返回普通页面的登录页。
+4. 普通用户用普通账号登录后才能操作已绑定控件。修改 Template 可能使旧控件定位失效；重新 Deploy 后进入编辑页检查并重新 Apply。普通 Deploy 本身不会替代编辑页的 Apply。
 
-- 保留节点类型 `ui-control-panel`，不要改回普通 `ui-template`。
-- 页面布局、Vue 状态和交互写在 Template；鉴权和路由交给 `room-gateway`；
-  设备协议、TCP 和 ACK 交给 Script-as-Device 驱动。
-- 禁止在 Template 中重新实现 debounce、throttle、latest-wins `Map`、
-  `Promise` 发送队列或设备 TCP 逻辑。
-- 推荐使用普通 `<script>export default {}</script>`。`defineComponent(...)` 和
-  `<script setup>` 可以编译，但 Options API 最适合直接调用注入的生命周期方法。
+绑定时设备必须在线，且 Automator 目录能返回该设备的参数。已有绑定会保存在 Flow 中；Automator 启动时不靠设备在线才能显示已保存的页面。可绑定点位按目录中的参数类型、枚举、量程和读写权限筛选；不是任意设备命令都可绑定。
 
-## 2. 公共 API
+## 页面代码的基本约定
 
-节点运行时自动注入以下方法，Template 不得重定义这些名字：
+- 使用普通 HTML、CSS 和 Vue 编写布局、导航、场景展示和页面内部交互。需要设备绑定的控件只维护普通的控件值；发送、反馈、登录、范围换算由节点处理。
+- Vue 绑定字段使用 `data()` 中的顶层简单字段，例如 `volume`、`muted`、`source`。不要用 `state.volume`、数组下标、计算属性或表达式作为待绑定模型。
+- 给控件稳定且唯一的标准 `id` 或 `name`，尤其是重复出现或外观相同的控件。不要把待绑定控件放在 `v-for` 内；绑定时控件应实际显示在页面上。
+- 不要手写 `data-cp-*` 标签、设备路径、HTTP/WebSocket 调用、驱动命令或反馈回写。`data-cp-*` 会被拒绝。不要给待绑定控件叠加 `@click`、`@input`、`@change`、`@update:model-value` 等自行处理设备状态的事件，也不要额外绑定 `:value`、`:checked` 或 `:model-value`（下述只读进度条例外）。
+- Vuetify 标签一律成对闭合，包括只用于装饰的组件：写 `<v-icon></v-icon>`，不要写 `<v-icon/>`。Dashboard 模板会把自闭合自定义标签后的控件错误地吞进去；节点现会直接报错。
+- 普通页面可以使用其他 Vuetify 组件作布局或纯页面交互，但只有下表列出的组件具备自动设备绑定适配器。
 
-```js
-setControlSession(session)
-clearControlSession()
-sendControl({ type, topic, key, value, final })
-flushControl(key)
-applyControlFeedback(message)
-hasDeviceState(field)
-deviceValue(field, fallback)
-isControlPending(key)
-controlDisplayValue(key, field, fallback)
-```
-
-节点还注入以下响应式状态，Template 不得用自己的 `data()` 覆盖同名字段：
-
-```js
-deviceState               // 只保存设备反馈确认的状态
-deviceFeedbackRevision    // 最近一次设备反馈版本号
-deviceFeedbackConnected   // 实时反馈流是否连接
-controlPending            // 等待匹配设备反馈的 controlKey 集合
-controlTargets            // 连续控件尚待设备确认的最后目标值
-```
-
-还保留两个可选扩展点：
-
-```js
-controlTransport(command) // 自定义传输时实现
-onControlError(error, command) // 自定义错误展示时实现
-onDeviceFeedback(feedback, state) // 把反馈同步到滑杆草稿等页面状态
-onControlFeedbackStatus(connected) // 自定义连接状态展示
-```
-
-成功登录 `room-gateway` 后必须执行：
-
-```js
-this.setControlSession(session)
-```
+## 可绑定写法
 
-该调用会自动连接当前房间的被动反馈流。`room-gateway` 会缓存 Dashboard 离线期间收到的
-真实设备状态，并在反馈流建立后的首帧发送完整快照。Template 不得主动查询设备状态，也不得再创建自己的状态轮询器、
-`EventSource` 或 WebSocket。若使用完全自定义的 `controlTransport()`，可由外部代码把
-标准 `kind: 'state'` 消息交给 `applyControlFeedback(message)`。
-
-Automator 的状态连线规则：`room-gateway` 输出只接控制命令流程；设备参数反馈接 Gateway 输入。
-以当前 room-01 Rane 映射为例，`//processors/1/channels/1/mute` 参数反馈通过
-`room-message(audio/mute, useInput=true)` 返回 Gateway 输入，
-`//processors/1/channels/2/level` 参数反馈通过
-`room-message(audio/volume, useInput=true)` 返回 Gateway 输入。Template 不负责这些连线。
-由于 Automator Event 只报告参数变化，如果 Automator 可能晚于驱动启动，还需要使用
-`Inject once -> Status stateReady -> Switch true -> Status mute/level -> room-message -> Gateway`
-在流程启动时读取 MUSE 虚拟设备已保存的当前值；同时用 `Event stateReady=true` 触发同一组
-Status 节点，覆盖设备晚于 Automator 上线的情况。Mute/Level Event 节点继续负责后续实时变化。
-
-退出、锁屏或会话失效时必须执行：
-
-```js
-this.clearControlSession()
-```
-
-这会同时清除该会话尚未发送的连续值和离散队列。
-
-## 3. 命令格式
-
-每条设备控制命令只声明以下字段：
-
-```js
-this.sendControl({
-  type: 'level',
-  topic: 'audio/volume',
-  key: 'rane/1/level/2',
-  value: 65,
-  final: false
-})
-```
+| 用途 | 原生 HTML | Vuetify | 模型与限制 |
+| --- | --- | --- | --- |
+| 连续数值控制 | `<input type="range">`、`<input type="number">` | `v-slider` | 数字；滑杆用简单 `v-model`，允许 `.number`。`min`、`max`、`step` 只写数字常量（包括 `:max="100"`），不要绑定动态字段。 |
+| 布尔控制 | `<input type="checkbox">`、`<button aria-pressed="false">`、`<button role="switch" aria-checked="false">` | `v-switch`、`v-checkbox` | Vuetify 使用布尔 `v-model`；不支持自定义 `true-value` / `false-value`、`multiple` 或值数组。语义按钮由节点更新状态并处理点击。 |
+| 单选枚举 | `<select>` | `v-select`、`v-radio-group` | Vuetify 使用字符串或数字的简单 `v-model`，选项值与驱动枚举值一致；可用 `.number`。不支持多选、`return-object`、`clearable`；单选项不要自带发送事件。 |
+| 文本控制 | `<input type="text">`、`<textarea>` | `v-text-field`、`v-textarea` | Vuetify 使用字符串 `v-model`；在 change 或失焦时提交，`v-text-field` 也支持 Enter。不支持数字型 `v-text-field` 或 `.number`。 |
+| 只读数值反馈 | `<meter>`、`<progress>` | `v-progress-linear`、`v-progress-circular` | 只能绑定读点位。Vuetify 用数字 `:model-value="progress"` 或 `v-model="progress"`；linear 可用固定正数 `max`，circular 固定 0–100；不支持 indeterminate/clickable。 |
+| 只读文本反馈 | `<span>`、`<strong>`、`<b>`、`<output>`、`<h1>`、`<h2>`、`<h3>` | 暂无自动适配组件 | 元素内使用单个顶层字段插值，如 `{{ status }}`；也可用纯文本。只可绑定读点位，不支持拼接或格式化表达式。 |
 
-- `type`：控制语义，决定发送策略。
-- `topic`：业务功能，由 `room-gateway` 验证和路由。
-- `key`：稳定且唯一的设备控制标识。推荐
-  `<device>/<slot>/<control>/<channel>`，例如 `rane/1/level/2`。
-- `value`：目标值。
-- `final`：仅连续控制需要；松手或 change 时设为 `true`。
+原生控件的简单顶层 `v-model` 也可用。Vuetify 交互控件必须有简单 `v-model`；其模型的初始类型要与表格一致。原生 `meter`/`progress` 默认量程为 0–1；原生 range 默认 0–100。为可读性和准确换算，数值控件尽量显式声明页面量程。
 
-不要把显示文本、Vue 组件 ID 或随机值当作 `key`。同一个物理控制始终使用相同
-`key`；不同设备或不同控制号必须使用不同 `key`。
+原生滑杆可按常规 Vue 写法使用，例如 `<input id="room-light" type="range" min="0" max="100" step="1" v-model.number="light">`，并在 `data()` 中将 `light` 初始化为数字。拖动产生的发送和设备反馈由 ControlPanel 处理；不要为了绑定再添加手写的 `input`/`change` 发送监听、定时器或强制回写滑杆值。若滑杆能拖动但设备无变化，或设备已变化而页面显示旧值，应分别检查绑定、设备收发和反馈的新鲜度，不要在页面里补第二套设备逻辑。
 
-## 4. 控件策略
-
-| `type` | 前端写法 | 公共 API 行为 |
-| --- | --- | --- |
-| `power` | 每次明确点击发送一次 | 顺序发送 |
-| `source` | 用户选择后发送一次 | 顺序发送 |
-| `preset` | 每次明确点击发送一次 | 顺序发送 |
-| `mute` | 每次明确点击发送一次 | 顺序发送 |
-| `level` | 拖动发送，松手再发最终值 | 每个 key 40 ms latest-wins |
-| `dimmer` | 拖动发送，松手再发最终值 | 每个 key 40 ms latest-wins |
-| `position` | 拖动发送，松手再发最终值 | 每个 key 40 ms latest-wins |
-
-滑杆标准写法：
+### 最小示例
 
 ```html
-<input
-  :value="controlDisplayValue('rane/1/level/2', 'volume', volume)"
-  type="range"
-  min="0"
-  max="100"
-  @input="sendVolume($event, false)"
-  @change="sendVolume($event, true)"
-/>
-```
-
-```js
-sendVolume (event, final) {
-  this.volume = Number(event.target.value)
-  return this.sendControl({
-    type: 'level',
-    topic: 'audio/volume',
-    key: 'rane/1/level/2',
-    value: this.volume,
-    final
-  })
-},
-onDeviceFeedback (feedback, state) {
-  // pending 期间保持最后目标位置，不让较旧的中间反馈拉回滑杆。
-  if (!this.isControlPending('rane/1/level/2') && Number.isFinite(state.volume)) {
-    this.volume = state.volume
+<template>
+  <section>
+    <v-slider id="room-volume" label="音量" v-model="volume" :min="0" :max="100" :step="1"></v-slider>
+    <v-switch id="room-mute" label="静音" v-model="muted"></v-switch>
+    <v-select id="room-source" label="输入源" v-model="source" :items="sources"></v-select>
+    <v-progress-linear id="room-level" :model-value="level" :max="100"></v-progress-linear>
+    <span id="room-status">{{ status }}</span>
+  </section>
+</template>
+<script>
+export default {
+  data () {
+    return {
+      volume: 0,
+      muted: false,
+      source: 'A',
+      sources: ['A', 'B'],
+      level: 0,
+      status: '待机'
+    }
   }
 }
+</script>
 ```
 
-Vuetify 滑杆可把相同逻辑分别放在 `@update:model-value` 和 `@end`。
-连续控件直接发送目标值，不主动查询当前值。匹配目标的被动反馈会自动清除 pending；
-未匹配的较旧反馈只更新 `deviceState`，`controlDisplayValue()` 仍返回最后目标。
-
-离散控件的下一条同 topic 真实反馈会解除 pending，并直接以该反馈值显示实际状态，
-即使 Automator 反馈携带的是 MUSE provider path、与 Template 的 UI `key` 不同。若同一房间内
-有多个相同 topic 的控件，反馈必须提供与 Template 一致的 `controlKey`，避免误确认其他控件。
-连续控件仍只有在反馈值匹配最后目标时才解除 pending。
-
-离散按钮必须显示设备反馈值，不能先改本地状态。标准写法：
-
-```html
-<v-btn
-  :class="{ active: deviceValue('muted', false) }"
-  :loading="isControlPending('rane/1/mute/1')"
-  :disabled="!hasDeviceState('muted')"
-  @click="requestMute"
->
-  Mute
-</v-btn>
-```
-
-```js
-requestMute () {
-  const next = !this.deviceValue('muted', false)
-  return this.sendControl({
-    type: 'mute',
-    topic: 'audio/mute',
-    key: 'rane/1/mute/1',
-    value: next
-  })
-}
-```
-
-Power、Source 和 Preset 使用相同原则：事件处理函数只计算并发送目标值，不修改
-代表设备状态的本地变量。按钮的 active、selected、pressed、switch model-value 和
-下拉框 value 必须来自 `deviceState`/`deviceValue()`。`isControlPending(key)` 只用于
-显示“等待设备确认”，不能当作成功状态。
-
-## 5. 反馈与显示规则
-
-- `room-gateway` 的公开状态只来自设备反馈；接受控制命令不会提前改变公开状态。
-- 驱动连接设备后负责查询一次真实状态；实时反馈由 Gateway 缓存并由公共 API 自动接收、写入
-  `deviceState`。Dashboard 离线时收到的状态会在下次登录后的反馈首帧恢复。
-- Power、Source、Preset、Mute、温度步进按钮等非滑杆控件必须显示
-  `deviceState` 中的实际值，不得乐观切换本地状态。
-- Level、Dimmer、Position 滑杆直接发送目标值且不主动查询。拖动和松手后都保持
-  最后目标位置；匹配最终目标的被动反馈只负责确认，不改变滑杆位置。
-- 连续控制 pending 期间收到的旧中间反馈可以更新 `deviceState`，但不能覆盖
-  `controlTargets` 或拉回滑杆。只有发送失败，或没有 pending 时发生外部调节，
-  才把滑杆同步到实际反馈值。
-- 反馈没有包含某个字段时，使用 `hasDeviceState(field)` 显示未知或禁用状态，不能
-  用假定默认值冒充设备实际状态。
-- 禁止使用会把反馈值自动发送回设备的 `watch`。
-- 控制发送只能来自明确的用户事件或业务动作。
-- 需要把反馈复制到滑杆草稿或其他页面状态时，实现 `onDeviceFeedback(feedback,
-  state)`；先用 `isControlPending(key)` 阻止旧反馈覆盖目标。该方法只赋值，不调用
-  `sendControl()`。
-- Template 只清理自己创建的动画和纯 UI timer；公共 API 的发送队列、反馈连接和
-  pending 状态由节点在页面卸载时自动清理。
-
-## 6. AI 交付前检查
-
-AI 完成页面后必须逐项确认：
-
-1. 所有设备控制都调用 `sendControl()`，没有 `this.send()`、命令 `fetch()` 或 TCP。
-2. 每条命令都有正确的 `type`、`topic`、稳定 `key` 和 `value`。
-3. 连续控件在松手/change 时发送相同目标值并带 `final: true`。
-4. Template 内没有自建限速器、latest-wins Map 或发送队列。
-5. 登录成功调用 `setControlSession()`，退出或会话失效调用
-   `clearControlSession()`。
-6. 非滑杆控件的 active、selected、pressed、value 等显示只来自设备反馈。
-7. 非滑杆事件处理函数没有在发送前修改设备状态变量。
-8. 滑杆使用 `controlDisplayValue()`，松手后保持最后目标，不被旧中间反馈拉回。
-9. 连续控件直接发送目标值；Template 没有主动状态查询、自建轮询、`EventSource`
-   或 WebSocket。
-10. 设备反馈和 `onDeviceFeedback()` 不会触发控制命令回发。
-11. 未收到反馈的字段显示未知/禁用，不用默认值冒充实际状态。
-12. 桌面和移动尺寸下文字、滑杆、按钮不重叠。
-13. 页面卸载时清理 Template 自己创建的 timer 和 listener。
-14. 设备连接后的首次查询由 Script-as-Device 驱动负责；Gateway 没有查询输出，Template
-    没有自行调用 `queryStatus` 或任何查询接口。
+其中 `sources` 的值仅是示例，实际枚举值要与所选驱动点位一致。控件可以先写好页面，设备与点位留到可视化绑定编辑页选择。
 
-给 AI 的推荐提示语：
+## 映射规则与检查
 
-> 先完整阅读 `CONTROL_PANEL_AI_GUIDE.md`、当前 ControlPanel Template 和
-> `control-policy.js`，再修改页面。严格使用注入的 `sendControl()` API，禁止在
-> Template 中重写发送队列、限速、latest-wins 或反馈连接。所有非滑杆控件必须
-> 显示设备反馈确认的状态，不能乐观修改本地状态；滑杆直接发送并保持最后目标，
-> 不主动查询，也不能被旧中间反馈拉回。完成后按照指南第 6 节逐项检查。
+- 数值滑杆和进度条由网页侧在页面量程与驱动量程之间换算；不会修改驱动。只有两侧量程元数据有效时才能换算；否则不要假定会自动缩放。整数目标会取整。
+- Write point 改动时，Feedback point 默认跟随；之后可单独指定反馈点位。新绑定默认 Zero-based；必须按实际设备协议确认。只读控件没有 Write point。
+- 编辑页只展示当前控件类型、值类型和读写权限兼容的参数。设备列表为空时，先检查设备在线和 Automator 参数目录，不能靠前端 HTML 使离线设备的点位出现。
+- 一个页面元素只能绑定一个映射。`v-for`、无法唯一定位的重复元素、复杂模型、动态量程、既有发送处理器及不在上表中的组件不会被自动接管。
+- Apply 成功才算映射及桥接部署完成。桥接版本与保存的映射不一致时命令会被拒绝。先验证登录、绑定、页面反馈，再检查实际设备收发；本地模拟测试不等于真实设备闭环。

package/README.md

@@ -1,159 +1,21 @@
 # Room Tools
 
-One package containing three nodes:
+This package provides `ui-control-panel` for Node-RED and MUSE Automator.
 
-- room-gateway: authenticated region control and feedback gateway.
-- room-message: typed panel feedback message generator.
-- ui-control-panel: Dashboard 2 template widget without message ports.
+## ControlPanel
 
-When asking an AI to create or modify a panel, have it read
-`CONTROL_PANEL_AI_GUIDE.md` before editing the Template. New ControlPanel nodes
-also include a shortened copy of that contract as a non-rendered HTML comment.
+The page author writes ordinary HTML/CSS/Vue and pastes it into the `ui-control-panel` Template. After configuring a Dashboard page, room ID, control login, and separate editor login, save and Deploy. Reopen the node and select **Open page binding editor**. Sign in with the editor account, right-click a supported control, choose its device points, and Apply.
 
-Every room gateway uses `/room-panel-api/regions/<room-id>` so additional
-regions follow the same URL structure.
+Bindings are stored in `visualBindings` on the node. The runtime reads that mapping to authenticate commands, route feedback, and generate a native bridge. The page author does not put device paths, `data-cp-*` attributes, or device-send code in the Template. Author-provided `data-cp-*` attributes are rejected.
 
-## Control traffic policy
+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.
 
-Version 1.8.2 uses the same control semantics at the panel, gateway and device
-driver boundaries:
+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.
 
-- `power`, `source`, `preset` and `mute` are discrete controls. The panel sends
-  them in order and the gateway never coalesces them.
-- `level`, `dimmer` and `position` are continuous controls. The panel sends at
-  most 25 updates per second, overwrites an unsent value for the same
-  `controlKey`, and sends the final value again on `change`/release.
-- The gateway independently enforces the same 40 ms latest-wins window. A
-  custom panel that produces too many slider events therefore cannot create an
-  unbounded downstream queue.
-- Every command emitted by the gateway includes validated `controlType`,
-  `controlKey` and `final` fields. Authentication, CSRF checks, room isolation
-  and value validation still happen before a command is accepted.
+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.
 
-Every `ui-control-panel` Template using Vue's Options API now receives the
-following methods automatically: `sendControl`, `flushControl`,
-`setControlSession`, `clearControlSession`, `applyControlFeedback`,
-`hasDeviceState`, `deviceValue`, `isControlPending` and `controlDisplayValue`.
-The scheduler and passive live
-feedback connection are owned by the node, so new templates do not copy queues,
-timers, polling loops or `EventSource` code.
+After clicking Apply in the page binding editor, the package validates the mapping, backs up the active Flow, generates the native bridge for that panel, and deploys the updated Flow in one operation. The bridge revision must match the saved mapping before a command can reach a device. A Node-RED simulation verifies software behavior, while live device operation requires a separate check.
 
-After a successful room-gateway login, pass the returned session to the API:
+## Installation
 
-```js
-this.setControlSession(session)
-```
-
-`sendControl` sends directly to the matching room-gateway route. A Template
-that already implements `postControl(message, generation)` remains compatible:
-the injected API calls that method as its transport. A Template can also define
-`controlTransport(command)` for a fully custom transport.
-
-Call `clearControlSession()` on logout. It clears the room session and all
-pending controls so values from an old session cannot be emitted after a new
-login.
-
-`setControlSession` also opens an authenticated Server-Sent Events stream for
-the selected room. `deviceState` contains reported device state only. Accepted
-commands update the gateway's private desired state but do not change
-`deviceState`; matching Script-as-Device feedback is required before a Power,
-Mute, Source or Preset control appears active. `isControlPending(key)` can be
-used for a waiting indicator. A discrete control is released by the next
-authoritative feedback for its topic, even when Automator reports a provider
-path instead of the Template's UI key. Continuous controls still wait for the
-reported value to match their latest target.
-
-Non-slider controls must use `:model-value`, `:value`, `:class` or
-`:aria-pressed` from `deviceState`/`deviceValue()` and must not optimistically
-change that state in the click handler. Sliders send their target directly and
-must use `controlDisplayValue(key, field, fallback)` to hold the latest target
-until matching passive feedback arrives. Older intermediate feedback updates
-`deviceState` but does not pull the slider backward. Templates must not query
-device state actively.
-
-## Retained device state
-
-`room-gateway` keeps its original single output for authenticated control
-commands. Actual device feedback enters the gateway input as `kind: 'state'`.
-The gateway stores the latest reported value for every associated control:
-
-- If a Dashboard is online, feedback is broadcast immediately over its passive
-  Server-Sent Events connection.
-- If no Dashboard is logged in, feedback remains cached in `reportedState`.
-- When a Dashboard later opens the feedback stream, its first event is the
-  complete cached state snapshot.
-
-The Script-as-Device driver should query once when its device connection is
-established, publish the result through its virtual-device parameters, and then
-rely on device feedback. This is not periodic polling. The Template does not
-issue queries and device feedback never becomes a control command.
-
-For the current room-01 Rane mapping, use these Automator feedback connections:
-
-- Event `//processors/1/channels/1/mute` -> room-message `audio/mute` with
-  `useInput` enabled -> Gateway input.
-- Event `//processors/1/channels/2/level` -> room-message `audio/volume` with
-  `useInput` enabled -> Gateway input.
-
-Use the virtual-device name currently shown in Automator. Older deployments may
-still display `Precis Driver`; newer descriptors display `RaneProcessor`.
-
-Automator Event nodes report parameter changes but do not fetch an already
-retained value. To seed a gateway that starts after the driver, add a flow-start
-initialization branch for each associated control:
-
-```text
-Inject once -> Status //processors/1/stateReady -> Switch true
-            -> Status //processors/1/channels/1/mute  -> room-message -> Gateway
-            -> Status //processors/1/channels/2/level -> room-message -> Gateway
-
-Event //processors/1/stateReady (true) -> the same two Status nodes
-```
-
-Keep the Event nodes above in parallel for subsequent live changes. The
-`stateReady` check prevents descriptor defaults or an incomplete reconnect
-snapshot from being presented as actual state. The `stateReady=true` Event
-covers the case where the physical processor connects after Automator starts.
-
-```html
-<input
-  type="range"
-  @input="sendControl({ type: 'level', topic: 'audio/volume', key: 'rane/0/level/2', value })"
-  @change="sendControl({ type: 'level', topic: 'audio/volume', key: 'rane/0/level/2', value, final: true })"
-/>
-```
-
-```js
-sendControl({ type: 'mute', topic: 'audio/mute', key: 'rane/0/mute/1', value: true })
-```
-
-The injected API supports `power`, `source`, `preset`, `mute`, `level`,
-`dimmer` and `position`. It requires a stable `key`; this identifies one
-device control, not just a visible slider. The public names `sendControl`,
-`flushControl`, `setControlSession`, `clearControlSession`,
-`applyControlFeedback`, `hasDeviceState`, `deviceValue`, `isControlPending`,
-`controlDisplayValue`,
-`deviceState`, `deviceFeedbackRevision`, `deviceFeedbackConnected`,
-`controlPending`, `controlTargets`, `controlTransport`, `onControlError`, `onDeviceFeedback` and
-`onControlFeedbackStatus` are reserved by the ControlPanel API.
-
-The injector supports normal Options API exports, `defineComponent(...)` and
-`<script setup>`. CSS-only `site:style` and `page:style` ControlPanel nodes are
-left unchanged.
-
-The node type names and configuration fields are unchanged from the individual
-1.0.0 packages. No external dependencies or installation scripts are required.
-
-## Migrating from the individual packages
-
-Do not install this package alongside node-red-contrib-room-gateway or
-node-red-contrib-room-message: they register the same node types.
-
-Back up the project and its credentials, save changes, and stop Automator.
-In its user directory (on this Mac, ~/.node-red), uninstall the two individual
-packages with npm, then install this .tgz package before restarting Automator.
-Keep the existing flow nodes and their IDs; do not delete them from the canvas.
-After restarting, verify the gateway credentials and both nodes before use.
-
-This package does not contain accounts, passwords, or flows. Installing it on a
-Mac does not install it on a MUSE controller.
+Install this package in the Node-RED user directory or declare it in the active project `package.json`. Installing on the Mac does not install the package on a MUSE controller.

package/control-bound-protocol.js

@@ -0,0 +1,97 @@
+const { visualRoutes } = require('./panel-visual-bindings')
+
+function configuredRoutes (config) {
+  return visualRoutes(config)
+}
+
+function resolveBoundCommand (routes, message) {
+  const request = message?._controlPanel
+  if (request?.kind !== 'command' || typeof request.id !== 'string') {
+    throw new Error('Invalid bound command')
+  }
+  const route = routes.get(request.id)
+  if (!route) throw new Error(`Unknown control ID: ${request.id}`)
+  if (route.control.mode === 'read') throw new Error(`Read-only control: ${request.id}`)
+  if (!route.binding?.device || !route.binding.writePath) {
+    throw new Error(`Incomplete command binding: ${request.id}`)
+  }
+  if (!Object.hasOwn(request, 'value')) throw new Error('Bound command needs a value')
+  const value = request.value
+  const type = route.control.type
+  if (['level', 'dimmer', 'position'].includes(type) &&
+    (typeof value !== 'number' || !Number.isFinite(value))) {
+    throw new Error(`${type} value must be a finite number`)
+  }
+  const metadata = route.binding.writeMeta
+  if (['level', 'dimmer', 'position'].includes(type) && metadata?.type === 'integer' && !Number.isInteger(value)) {
+    throw new Error(`${type} value must be an integer`)
+  }
+  if (['level', 'dimmer', 'position'].includes(type) &&
+    ((Number.isFinite(metadata?.min) && value < metadata.min) ||
+      (Number.isFinite(metadata?.max) && value > metadata.max))) {
+    throw new Error(`${type} value is outside the device range`)
+  }
+  if (['mute', 'power'].includes(type) && typeof value !== 'boolean') {
+    throw new Error(`${type} value must be a boolean`)
+  }
+  if (['source', 'preset'].includes(type) &&
+    !(typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value)))) {
+    throw new Error(`${type} value must be a string or number`)
+  }
+  if (type === 'text' && (typeof value !== 'string' || value.length > 4096)) {
+    throw new Error('Text value must be a string under 4096 characters')
+  }
+  if (Array.isArray(metadata?.enums) && metadata.enums.length &&
+    !metadata.enums.some(entry => Object.is(entry, value) || Object.is(entry?.value, value))) {
+    throw new Error('Value is not a permitted device option')
+  }
+  const payload = ['mute', 'power'].includes(type) && metadata?.booleanEncoding === 'integer01'
+    ? (value ? 1 : 0) : value
+  return {
+    kind: 'bound-command',
+    controlId: request.id,
+    controlType: type,
+    device: route.binding.device,
+    path: route.binding.writePath,
+    payload,
+    final: request.final === true
+  }
+}
+
+function resolveBoundFeedback (routes, message) {
+  if (message?.kind !== 'device-feedback' || typeof message.device !== 'string' ||
+    typeof message.path !== 'string' || !Object.hasOwn(message, 'payload')) {
+    throw new Error('Invalid device feedback')
+  }
+  const matches = []
+  for (const [id, route] of routes) {
+    if (route.control.mode === 'write' || route.binding?.device !== message.device ||
+      route.binding.readPath !== message.path) continue
+    const type = route.control.type
+    const metadata = route.binding.readMeta
+    let value = message.payload
+    if (['mute', 'power'].includes(type)) {
+      if (value === 'true' || value === 1 || value === '1') value = true
+      else if (value === 'false' || value === 0 || value === '0') value = false
+      if (typeof value !== 'boolean') throw new Error(`Invalid ${type} feedback: ${id}`)
+    } else if (['level', 'dimmer', 'position'].includes(type)) {
+      if (typeof value === 'string' && value.trim() !== '') value = Number(value)
+      if (typeof value !== 'number' || !Number.isFinite(value) ||
+        (metadata?.type === 'integer' && !Number.isInteger(value)) ||
+        (Number.isFinite(metadata?.min) && value < metadata.min) ||
+        (Number.isFinite(metadata?.max) && value > metadata.max)) {
+        throw new Error(`Invalid ${type} feedback: ${id}`)
+      }
+    } else if (['source', 'preset'].includes(type) &&
+      !(typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value)))) {
+      throw new Error(`Invalid ${type} feedback: ${id}`)
+    } else if (type === 'text' && (typeof value !== 'string' || value.length > 4096)) {
+      throw new Error(`Invalid text feedback: ${id}`)
+    }
+    matches.push({ id, value })
+  }
+  if (!matches.length) throw new Error('Unmapped device feedback')
+  return matches
+}
+
+module.exports = { configuredRoutes, resolveBoundCommand, resolveBoundFeedback }