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

package/CONTROL_PANEL_AI_GUIDE.md

@@ -1,6 +1,6 @@
 # ControlPanel AI 开发契约
 
-适用节点：`ui-control-panel` 1.7.1。
+适用节点：`ui-control-panel` 1.8.0。
 
 把本文件作为 AI 开发或修改 ControlPanel Template 前的强制上下文。目标是让
 不同页面使用同一套控制语义，避免滑杆积压、重复队列、反馈回环和跨房间误发。
@@ -56,10 +56,21 @@ onControlFeedbackStatus(connected) // 自定义连接状态展示
 this.setControlSession(session)
 ```
 
-该调用会自动连接当前房间的被动反馈流。Template 不得主动查询设备状态，也不得再创建自己的状态轮询器、
+该调用会自动连接当前房间的被动反馈流。`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
@@ -173,7 +184,8 @@ Power、Source 和 Preset 使用相同原则：事件处理函数只计算并发
 ## 5. 反馈与显示规则
 
 - `room-gateway` 的公开状态只来自设备反馈；接受控制命令不会提前改变公开状态。
-- 登录后的实时反馈由公共 API 自动接收并写入 `deviceState`。
+- 驱动连接设备后负责查询一次真实状态；实时反馈由 Gateway 缓存并由公共 API 自动接收、写入
+  `deviceState`。Dashboard 离线时收到的状态会在下次登录后的反馈首帧恢复。
 - Power、Source、Preset、Mute、温度步进按钮等非滑杆控件必须显示
   `deviceState` 中的实际值，不得乐观切换本地状态。
 - Level、Dimmer、Position 滑杆直接发送目标值且不主动查询。拖动和松手后都保持
@@ -210,6 +222,8 @@ AI 完成页面后必须逐项确认：
 11. 未收到反馈的字段显示未知/禁用，不用默认值冒充实际状态。
 12. 桌面和移动尺寸下文字、滑杆、按钮不重叠。
 13. 页面卸载时清理 Template 自己创建的 timer 和 listener。
+14. 设备连接后的首次查询由 Script-as-Device 驱动负责；Gateway 没有查询输出，Template
+    没有自行调用 `queryStatus` 或任何查询接口。
 
 给 AI 的推荐提示语：
 

package/README.md

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

package/control-panel.html

@@ -12,7 +12,7 @@
         const template = []
 
         template.push('<!--')
-        template.push('AI / DEVELOPER CONTRACT - ui-control-panel 1.7.1')
+        template.push('AI / DEVELOPER CONTRACT - ui-control-panel 1.8.0')
         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.')
@@ -26,6 +26,7 @@
         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.')
         template.push('12. Read CONTROL_PANEL_AI_GUIDE.md in node-red-contrib-room-tools before generating a production panel.')
+        template.push('13. Device state is retained by room-gateway and delivered in the feedback stream first snapshot; never query device state from this Template.')
         template.push('-->')
         template.push('<template>')
         template.push('    <div>')
@@ -390,7 +391,7 @@
         <li>Use <code>isControlPending(key)</code> to show that a command is waiting for matching device feedback.</li>
         <li>Sliders directly send and hold their latest target through <code>controlDisplayValue()</code>; unmatched older feedback must not move them.</li>
     </ul>
-    <p>After login call <code>setControlSession(session)</code>; it opens the authenticated passive room feedback stream. On logout call <code>clearControlSession()</code>. Feedback is available through <code>deviceState</code>, <code>hasDeviceState()</code>, <code>deviceValue()</code>, <code>deviceFeedbackConnected</code> and the optional <code>onDeviceFeedback(feedback, state)</code> hook. Use <code>controlDisplayValue()</code> for continuous controls. Do not add active state queries, and never echo feedback back as a command.</p>
+    <p>After login call <code>setControlSession(session)</code>; it opens the authenticated passive room feedback stream. The room-gateway retains device feedback received while the page is offline and sends the complete snapshot as the stream's first event. On logout call <code>clearControlSession()</code>. Feedback is available through <code>deviceState</code>, <code>hasDeviceState()</code>, <code>deviceValue()</code>, <code>deviceFeedbackConnected</code> and the optional <code>onDeviceFeedback(feedback, state)</code> hook. Use <code>controlDisplayValue()</code> for continuous controls. Do not add active state queries in the Template, and never echo feedback back as a command.</p>
     <p>See <code>CONTROL_PANEL_AI_GUIDE.md</code> in the node package for the complete AI authoring contract and examples.</p>
 </script>
 

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',
@@ -399,17 +402,337 @@ 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) {
+        if (feedback.controlKey && feedback.controlKey !== key) continue
+        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 && (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 +740,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.7.1",
+  "version": "1.8.1",
   "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": {

package/room-gateway.html

@@ -16,5 +16,6 @@ RED.nodes.registerType('room-gateway',{
 <script type="text/html" data-help-name="room-gateway">
 <p>Template 通过同源 /room-panel-api/regions/&lt;区域 ID&gt; 登录和发送控制请求；ui-control-panel 登录后自动订阅该区域的实时设备反馈。Template 输出不再用于控制设备。</p>
 <p>本节点输出已授权消息，连接原来的 Switch。设备反馈必须含 room、kind: state、topic 和 payload，接入本节点输入，不接 Template。</p>
+<p>网关会保存每个已关联控件最后收到的真实设备状态。页面在线时通过实时反馈流立即推送；页面未登录时继续缓存，登录后在反馈流首帧发送完整状态快照。</p>
 <p>公开状态只包含设备反馈，不会把刚接受的控制目标冒充实际状态。Node-RED 编辑器属于管理员入口，部署时应独立保护。生产 iPad 访问请配置 HTTPS 并启用 HTTPS Cookie。</p>
 </script>