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

package/CONTROL_PANEL_AI_GUIDE.md

@@ -1,6 +1,6 @@
 # ControlPanel AI 开发契约
 
-适用节点：`ui-control-panel` 1.8.0。
+适用节点：`ui-control-panel` 1.8.2。
 
 把本文件作为 AI 开发或修改 ControlPanel Template 前的强制上下文。目标是让
 不同页面使用同一套控制语义，避免滑杆积压、重复队列、反馈回环和跨房间误发。
@@ -151,6 +151,11 @@ Vuetify 滑杆可把相同逻辑分别放在 `@update:model-value` 和 `@end`。
 连续控件直接发送目标值，不主动查询当前值。匹配目标的被动反馈会自动清除 pending；
 未匹配的较旧反馈只更新 `deviceState`，`controlDisplayValue()` 仍返回最后目标。
 
+离散控件的下一条同 topic 真实反馈会解除 pending，并直接以该反馈值显示实际状态，
+即使 Automator 反馈携带的是 MUSE provider path、与 Template 的 UI `key` 不同。若同一房间内
+有多个相同 topic 的控件，反馈必须提供与 Template 一致的 `controlKey`，避免误确认其他控件。
+连续控件仍只有在反馈值匹配最后目标时才解除 pending。
+
 离散按钮必须显示设备反馈值，不能先改本地状态。标准写法：
 
 ```html

package/README.md

@@ -15,7 +15,7 @@ regions follow the same URL structure.
 
 ## Control traffic policy
 
-Version 1.8.0 uses the same control semantics at the panel, gateway and device
+Version 1.8.2 uses the same control semantics at the panel, gateway and device
 driver boundaries:
 
 - `power`, `source`, `preset` and `mute` are discrete controls. The panel sends
@@ -58,7 +58,10 @@ 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.
+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

package/control-panel.html

@@ -12,7 +12,7 @@
         const template = []
 
         template.push('<!--')
-        template.push('AI / DEVELOPER CONTRACT - ui-control-panel 1.8.0')
+        template.push('AI / DEVELOPER CONTRACT - ui-control-panel 1.8.2')
         template.push('AI START HERE: 先完整阅读 CONTROL_PANEL_AI_GUIDE.md、当前 ControlPanel Template 和 control-policy.js，再开发或修改页面。严格使用注入的 sendControl() 和设备反馈 API，禁止在 Template 中重写发送队列、限速、debounce、latest-wins、主动状态查询或反馈连接。所有非滑杆控件必须显示设备反馈确认的实际状态；滑杆必须直接发送并保持最后目标，不能被旧中间反馈拉回；设备反馈不能触发命令回发。完成后按照指南第 6 节逐项检查。')
         template.push('1. Use the injected sendControl({ type, topic, key, value, final }) API for device commands.')
         template.push('2. Never add debounce, throttle, latest-wins maps, Promise queues, or raw device TCP code here.')
@@ -21,7 +21,7 @@
         template.push('5. key must be stable and unique per device control, for example rane/1/level/2.')
         template.push('6. After room-gateway login call setControlSession(session); on logout call clearControlSession().')
         template.push('7. Bind discrete control visuals to deviceState/deviceValue(), not to an optimistic local value.')
-        template.push('8. Use isControlPending(key) only for a waiting indicator; applyControlFeedback() never sends commands.')
+        template.push('8. Use isControlPending(key) only for a waiting indicator; discrete pending clears on authoritative topic feedback, while continuous pending waits for its target value.')
         template.push('9. Sliders directly send and hold the latest target; use controlDisplayValue() so stale feedback cannot pull them back.')
         template.push('10. Feedback may update UI state, but must never trigger a watcher that sends the value back.')
         template.push('11. Do not redefine any injected ControlPanel API or its feedback state fields.')

package/control-policy.js

@@ -274,7 +274,6 @@ const __controlPanelPolicyMixin = {
     },
     __acknowledgeControlFeedback (feedback) {
       for (const [key, request] of this.__controlPanelRequests) {
-        if (feedback.controlKey && feedback.controlKey !== key) continue
         let matched = request.topic === 'room/reset'
         let value
         if (!matched && feedback.topic === request.topic) {
@@ -287,7 +286,15 @@ const __controlPanelPolicyMixin = {
             value = feedback.state[field]
           }
         }
-        if (matched && (request.topic === 'room/reset' || Object.is(value, request.value))) {
+        if (!matched) continue
+
+        const sameTopicRequests = [...this.__controlPanelRequests.values()]
+          .filter(candidate => candidate.topic === request.topic).length
+        const correlated = !feedback.controlKey || feedback.controlKey === key || sameTopicRequests === 1
+        if (!correlated) continue
+
+        const continuous = ['level', 'dimmer', 'position'].includes(request.type)
+        if (!continuous || request.topic === 'room/reset' || Object.is(value, request.value)) {
           this.__clearControlPending(key)
         }
       }
@@ -503,7 +510,6 @@ export default {
     __acknowledgeControlFeedback (feedback) {
       const feedbackFields = this.__controlPanelFeedbackFields()
       for (const [key, request] of this.__controlPanelRequests) {
-        if (feedback.controlKey && feedback.controlKey !== key) continue
         let matched = request.topic === 'room/reset'
         let value
         if (!matched && feedback.topic === request.topic) {
@@ -516,7 +522,15 @@ export default {
             value = feedback.state[field]
           }
         }
-        if (matched && (request.topic === 'room/reset' || Object.is(value, request.value))) {
+        if (!matched) continue
+
+        const sameTopicRequests = [...this.__controlPanelRequests.values()]
+          .filter(candidate => candidate.topic === request.topic).length
+        const correlated = !feedback.controlKey || feedback.controlKey === key || sameTopicRequests === 1
+        if (!correlated) continue
+
+        const continuous = ['level', 'dimmer', 'position'].includes(request.type)
+        if (!continuous || request.topic === 'room/reset' || Object.is(value, request.value)) {
           this.__clearControlPending(key)
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Room panel message generator and authenticated region gateway for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
   "keywords": ["node-red"],