node-red-contrib-room-tools 1.8.0 → 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

@@ -1,3 +1,6 @@
+const acorn = require('acorn')
+const escodegen = require('escodegen')
+
 const CONTROL_POLICY_MARKER = '/* ui-control-panel-control-api-v1 */'
 const FEEDBACK_TOPIC_FIELDS = Object.freeze({
   'display/power': 'display',
@@ -271,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) {
@@ -284,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)
         }
       }
@@ -399,17 +409,344 @@ const __controlPanelPolicyMixin = {
 `
 }
 
+// Dashboard 2.0 1.31 parses ui-template scripts itself. It only treats a script
+// as component options when the script contains one `export default { ... }`
+// statement. Keep every helper inside data, methods, or lifecycle hooks so the
+// generated script remains inside that supported subset.
+function buildDashboardPolicyOptionsSource () {
+  return `
+export default {
+  data () {
+    return {
+      deviceState: {},
+      deviceFeedbackRevision: 0,
+      deviceFeedbackConnected: false,
+      controlPending: {},
+      controlTargets: {}
+    }
+  },
+  methods: {
+    __controlPanelCreatePolicy: ${createControlPanelPolicy.toString()},
+    __controlPanelNormalizeFeedback: ${normalizeControlFeedback.toString()},
+    __controlPanelFeedbackFields () {
+      return ${JSON.stringify(FEEDBACK_TOPIC_FIELDS)}
+    },
+    __initializeControlPanelPolicy () {
+      this.__controlPanelSession = null
+      this.__controlPanelFeedbackSource = null
+      this.__controlPanelRequests = new Map()
+      this.__resetControlPolicy()
+    },
+    __disposeControlPanelPolicy () {
+      this.__closeControlFeedback()
+      this.__controlPanelPolicy?.dispose()
+      this.__controlPanelPolicy = null
+      this.__controlPanelRequests?.clear()
+      this.controlPending = {}
+      this.controlTargets = {}
+      this.__controlPanelSession = null
+    },
+    __resetControlPolicy () {
+      this.__controlPanelPolicy?.dispose()
+      this.__controlPanelPolicy = this.__controlPanelCreatePolicy({
+        intervalMs: 40,
+        dispatch: (command) => this.__dispatchControl(command),
+        onError: (error, command) => {
+          if (command?.controlKey) this.__clearControlPending(command.controlKey)
+          if (typeof this.onControlError === 'function') this.onControlError(error, command)
+          else console.error('ControlPanel command failed', error)
+        }
+      })
+    },
+    __setControlPending (key, pending) {
+      const next = { ...this.controlPending }
+      if (pending) next[key] = true
+      else delete next[key]
+      this.controlPending = next
+    },
+    __setControlTarget (key, value) {
+      this.controlTargets = { ...this.controlTargets, [key]: value }
+    },
+    __clearControlPending (key) {
+      this.__controlPanelRequests.delete(String(key))
+      this.__setControlPending(String(key), false)
+      const targets = { ...this.controlTargets }
+      delete targets[String(key)]
+      this.controlTargets = targets
+    },
+    __setFeedbackConnected (connected) {
+      const next = connected === true
+      if (this.deviceFeedbackConnected === next) return
+      this.deviceFeedbackConnected = next
+      if (typeof this.onControlFeedbackStatus === 'function') this.onControlFeedbackStatus(next)
+    },
+    __closeControlFeedback () {
+      this.__controlPanelFeedbackSource?.close()
+      this.__controlPanelFeedbackSource = null
+      this.__setFeedbackConnected(false)
+    },
+    __connectControlFeedback () {
+      this.__closeControlFeedback()
+      const session = this.__controlPanelSession
+      if (!session || typeof EventSource === 'undefined') return
+      const source = new EventSource('/room-panel-api/regions/' + encodeURIComponent(session.room) + '/events')
+      this.__controlPanelFeedbackSource = source
+      source.onopen = () => {
+        if (this.__controlPanelFeedbackSource === source) this.__setFeedbackConnected(true)
+      }
+      source.onmessage = (event) => {
+        if (this.__controlPanelFeedbackSource !== source) return
+        try {
+          this.applyControlFeedback(JSON.parse(event.data))
+        } catch (error) {
+          if (typeof this.onControlError === 'function') this.onControlError(error)
+          else console.error('ControlPanel feedback failed', error)
+        }
+      }
+      source.onerror = () => {
+        if (this.__controlPanelFeedbackSource === source) this.__setFeedbackConnected(false)
+      }
+    },
+    __acknowledgeControlFeedback (feedback) {
+      const feedbackFields = this.__controlPanelFeedbackFields()
+      for (const [key, request] of this.__controlPanelRequests) {
+        let matched = request.topic === 'room/reset'
+        let value
+        if (!matched && feedback.topic === request.topic) {
+          matched = true
+          value = feedback.payload
+        } else if (!matched && feedback.topic === 'room/state') {
+          const field = feedbackFields[request.topic]
+          if (field && Object.prototype.hasOwnProperty.call(feedback.state, field)) {
+            matched = true
+            value = feedback.state[field]
+          }
+        }
+        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)
+        }
+      }
+    },
+    setControlSession (session) {
+      if (!session || typeof session !== 'object' || !session.room || !session.csrf) {
+        throw new Error('ControlPanel session needs room and csrf')
+      }
+      const next = { room: String(session.room), csrf: String(session.csrf) }
+      if (this.__controlPanelSession &&
+        (this.__controlPanelSession.room !== next.room || this.__controlPanelSession.csrf !== next.csrf)) {
+        this.__resetControlPolicy()
+        this.__controlPanelRequests.clear()
+        this.controlPending = {}
+        this.controlTargets = {}
+        this.deviceState = {}
+        this.deviceFeedbackRevision = 0
+      }
+      this.__controlPanelSession = next
+      this.__connectControlFeedback()
+    },
+    clearControlSession () {
+      this.__closeControlFeedback()
+      this.__controlPanelSession = null
+      this.__resetControlPolicy()
+      this.__controlPanelRequests.clear()
+      this.controlPending = {}
+      this.controlTargets = {}
+      this.deviceState = {}
+      this.deviceFeedbackRevision = 0
+    },
+    sendControl (command) {
+      const key = String(command?.key ?? command?.controlKey ?? '')
+      const type = String(command?.type ?? command?.controlType ?? '').toLowerCase()
+      const value = Object.prototype.hasOwnProperty.call(command || {}, 'value') ? command.value : command?.payload
+      if (key) {
+        this.__controlPanelRequests.set(key, {
+          topic: String(command.topic ?? ''),
+          type,
+          value
+        })
+        this.__setControlPending(key, true)
+        if (['level', 'dimmer', 'position'].includes(type)) this.__setControlTarget(key, value)
+      }
+      try {
+        return this.__controlPanelPolicy.send(command)
+      } catch (error) {
+        if (key) this.__clearControlPending(key)
+        throw error
+      }
+    },
+    flushControl (key) {
+      return this.__controlPanelPolicy.flush(key)
+    },
+    applyControlFeedback (message) {
+      const room = this.__controlPanelSession?.room || this.authorizedRoom
+      const feedback = this.__controlPanelNormalizeFeedback(
+        message,
+        room,
+        this.__controlPanelFeedbackFields()
+      )
+      this.deviceState = { ...this.deviceState, ...feedback.state }
+      if (feedback.revision !== null) this.deviceFeedbackRevision = feedback.revision
+      this.__acknowledgeControlFeedback(feedback)
+      if (typeof this.onDeviceFeedback === 'function') this.onDeviceFeedback(feedback, this.deviceState)
+      return feedback
+    },
+    hasDeviceState (field) {
+      return Object.prototype.hasOwnProperty.call(this.deviceState, String(field))
+    },
+    deviceValue (field, fallback = null) {
+      return this.hasDeviceState(field) ? this.deviceState[String(field)] : fallback
+    },
+    isControlPending (key) {
+      return this.controlPending[String(key)] === true
+    },
+    controlDisplayValue (key, field, fallback = null) {
+      const controlKey = String(key)
+      if (this.isControlPending(controlKey) &&
+        Object.prototype.hasOwnProperty.call(this.controlTargets, controlKey)) {
+        return this.controlTargets[controlKey]
+      }
+      return this.deviceValue(field, fallback)
+    },
+    async __dispatchControl (command) {
+      if (typeof this.controlTransport === 'function') return this.controlTransport(command)
+
+      const session = this.__controlPanelSession
+      const room = session?.room || this.authorizedRoom
+      if (typeof this.postControl === 'function') {
+        return this.postControl(room ? { ...command, room } : command, this.sessionGeneration)
+      }
+      if (!session) throw new Error('Call setControlSession() after login, or define controlTransport(command)')
+
+      const response = await fetch('/room-panel-api/regions/' + encodeURIComponent(session.room) + '/command', {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', 'X-Room-CSRF': session.csrf },
+        body: JSON.stringify({ room: session.room, ...command }),
+        signal: AbortSignal.timeout(8000)
+      })
+      if (!response.ok) throw new Error('Control command failed (' + response.status + ')')
+      return response
+    }
+  },
+  mounted () {
+    this.__initializeControlPanelPolicy()
+  },
+  unmounted () {
+    this.__disposeControlPanelPolicy()
+  }
+}
+`
+}
+
+function parseOptionsObject (source) {
+  const tree = acorn.parse(source, { ecmaVersion: 'latest', sourceType: 'module' })
+  if (tree.body.length !== 1 || tree.body[0].type !== 'ExportDefaultDeclaration' ||
+    tree.body[0].declaration.type !== 'ObjectExpression') return null
+  return tree.body[0].declaration
+}
+
+function propertyName (property) {
+  if (!property || property.type !== 'Property') return null
+  if (!property.computed && property.key.type === 'Identifier') return property.key.name
+  if (property.key.type === 'Literal') return String(property.key.value)
+  return null
+}
+
+function findProperty (object, name) {
+  return object.properties.find(property => propertyName(property) === name)
+}
+
+function parseProperty (source) {
+  const object = acorn.parse('({' + source + '})', { ecmaVersion: 'latest' }).body[0].expression
+  return object.properties[0]
+}
+
+function functionSource (property) {
+  return property ? escodegen.generate(property.value) : null
+}
+
+function mergeDashboardOptions (userSource) {
+  const user = parseOptionsObject(userSource)
+  if (!user) return null
+
+  const policy = parseOptionsObject(buildDashboardPolicyOptionsSource())
+  const policyData = findProperty(policy, 'data')
+  const policyMethods = findProperty(policy, 'methods')
+  const policyMounted = findProperty(policy, 'mounted')
+  const policyUnmounted = findProperty(policy, 'unmounted')
+  const userData = findProperty(user, 'data')
+  const userMethods = findProperty(user, 'methods')
+  const userMounted = findProperty(user, 'mounted')
+  const userUnmounted = findProperty(user, 'unmounted')
+
+  if (userMethods && userMethods.value.type !== 'ObjectExpression') return null
+
+  const data = userData
+    ? parseProperty(`data () {
+        const userState = (${functionSource(userData)}).call(this) || {}
+        const policyState = (${functionSource(policyData)}).call(this) || {}
+        return { ...userState, ...policyState }
+      }`)
+    : policyData
+
+  const policyMethodNames = new Set(policyMethods.value.properties.map(propertyName))
+  const methods = parseProperty('methods: {}')
+  methods.value.properties = [
+    ...(userMethods ? userMethods.value.properties.filter(property => !policyMethodNames.has(propertyName(property))) : []),
+    ...policyMethods.value.properties
+  ]
+
+  const mounted = userMounted
+    ? parseProperty(`mounted () {
+        (${functionSource(policyMounted)}).call(this)
+        return (${functionSource(userMounted)}).call(this)
+      }`)
+    : policyMounted
+
+  const unmounted = userUnmounted
+    ? parseProperty(`unmounted () {
+        try {
+          return (${functionSource(userUnmounted)}).call(this)
+        } finally {
+          (${functionSource(policyUnmounted)}).call(this)
+        }
+      }`)
+    : policyUnmounted
+
+  const replaced = new Set(['data', 'methods', 'mounted', 'unmounted'])
+  const merged = {
+    ...user,
+    properties: [
+      ...user.properties.filter(property => !replaced.has(propertyName(property))),
+      data,
+      methods,
+      mounted,
+      unmounted
+    ]
+  }
+
+  return CONTROL_POLICY_MARKER + '\nexport default ' + escodegen.generate(merged, {
+    format: { indent: { style: '  ' } }
+  })
+}
+
 function injectControlPolicy (format) {
   if (typeof format !== 'string' || format.includes(CONTROL_POLICY_MARKER)) return format
 
   const scriptMatch = /<script(?!\s+setup\b)(?:\s[^>]*)?>/i.exec(format)
   if (!scriptMatch) {
     const setupMatch = /<script\s+setup\b([^>]*)>/i.exec(format)
-    if (!setupMatch && !/<template(?:\s|>)/i.test(format)) return format
-    const langMatch = setupMatch?.[1]?.match(/\blang\s*=\s*(["'])([^"']+)\1/i)
-    const scriptOpen = langMatch ? '<script lang="' + langMatch[2] + '">' : '<script>'
-    return format + '\n' + scriptOpen + '\n' + buildControlPolicyMixinSource() +
-      '\nexport default { mixins: [__controlPanelPolicyMixin] }\n</script>\n'
+    if (setupMatch || !/<template(?:\s|>)/i.test(format)) return format
+    return format + '\n<script>\n' + CONTROL_POLICY_MARKER + '\n' +
+      buildDashboardPolicyOptionsSource().trim() + '\n</script>\n'
   }
 
   const scriptStart = scriptMatch.index + scriptMatch[0].length
@@ -417,33 +754,23 @@ function injectControlPolicy (format) {
   if (scriptEnd === -1) return format
 
   const source = format.slice(scriptStart, scriptEnd)
-  const exportMatch = /(^|\n)([ \t]*)export\s+default\b/.exec(source)
-  if (!exportMatch) {
-    const wrapped = source + '\n' + buildControlPolicyMixinSource() +
-      '\nexport default { mixins: [__controlPanelPolicyMixin] }\n'
-    return format.slice(0, scriptStart) + wrapped + format.slice(scriptEnd)
+  let wrapped
+  try {
+    wrapped = mergeDashboardOptions(source)
+  } catch (_) {
+    return format
   }
-
-  const exportStart = exportMatch.index + exportMatch[1].length + exportMatch[2].length
-  const exportEnd = exportMatch.index + exportMatch[0].length
-  const userOptions = source.slice(0, exportStart) +
-    'const __controlPanelUserOptions =' +
-    source.slice(exportEnd)
-  const wrapped = userOptions + '\n' + buildControlPolicyMixinSource() + `
-export default {
-  ...__controlPanelUserOptions,
-  mixins: [...(__controlPanelUserOptions.mixins || []), __controlPanelPolicyMixin]
-}
-`
-
-  return format.slice(0, scriptStart) + wrapped + format.slice(scriptEnd)
+  if (!wrapped) return format
+  return format.slice(0, scriptStart) + '\n' + wrapped + '\n' + format.slice(scriptEnd)
 }
 
 module.exports = {
   CONTROL_POLICY_MARKER,
   FEEDBACK_TOPIC_FIELDS,
   buildControlPolicyMixinSource,
+  buildDashboardPolicyOptionsSource,
   createControlPanelPolicy,
   injectControlPolicy,
+  mergeDashboardOptions,
   normalizeControlFeedback
 }

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Room panel message generator and authenticated region gateway for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
   "keywords": ["node-red"],
+  "dependencies": {
+    "acorn": "^8.15.0",
+    "escodegen": "^2.1.0"
+  },
   "files": ["gateway.cjs", "room-gateway.js", "room-gateway.html", "room-message.js", "room-message.html", "control-panel.js", "control-panel.html", "control-policy.js", "CONTROL_PANEL_AI_GUIDE.md", "README.md"],
   "node-red": {
     "nodes": {