npm - node-red-contrib-room-tools - Versions diffs - 1.8.16 → 1.9.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/CONTROL_PANEL_AI_GUIDE.md +250 -109
package/README.md +3 -1
package/control-catalog.js +5 -2
package/control-panel.js +24 -4
package/control-policy.js +8 -0
package/control-type-contract.json +1 -0
package/control-type-model.js +8 -3
package/managed-native-bridge.js +2 -1
package/native-binding-plan.js +61 -7
package/npm-shrinkwrap.json +2 -2
package/package.json +8 -2
package/panel-binding-editor.js +193 -34
package/panel-meter.js +2 -1
package/panel-template-instrumentation.js +144 -33
package/panel-visual-bindings.js +33 -9
package/panel-xy-series-client.js +84 -0
package/panel-xy-series.js +186 -0
package/xy-series-frame.js +98 -0
package/xy-series-route.js +11 -0

package/CONTROL_PANEL_AI_GUIDE.md CHANGED Viewed

@@ -1,125 +1,201 @@
 # ControlPanel 前端页面编写指南
-适用基线：`node-red-contrib-room-tools@1.8.9` 的 `ui-control-panel`，当前本地修订为 `node-red-contrib-room-tools@1.8.15`，Dashboard 2，Vue Options API。本文按当前代码审核，不表示支持任意 Vue、Vuetify 或第三方组件。
+适用基线：当前统一工程中的 `node-red-contrib-room-tools@1.9.1`、Dashboard 2 和 Vue Options API。
-给 AI 编写页面前阅读本文。目标是：页面作者只写普通前端页面；部署人员在网页编辑模式选择设备与点位；ControlPanel 保存映射并负责设备命令、反馈和网页侧量程换算。
+本文件是给页面编写 AI 的实现契约，不是完整的 Vue 或 Vuetify 手册。目标是：页面作者只写普通 HTML、CSS 和 Vue 页面；设备、驱动、映射表、反馈订阅和通信细节全部由 `ControlPanel` 节点处理。
-## 1. 职责边界
+## 1. 最重要的规则
-页面作者使用普通 HTML、CSS 和 Vue 编写布局、样式、导航、控件及其本地状态。无需知道驱动协议、点位路径、内部 Control ID 或绑定表结构。标准 HTML `id`、Vue `v-model` 和 ARIA 属性不是 ControlPanel 专用标签。
+页面作者只需要：
-节点负责登录界面、普通与编辑权限、控件识别、映射保存、桥接生成、命令发送和反馈更新。页面不调用这些内部服务，不实现第二套设备通信。即使一个页面同时显示几十或上百个实时 Meter，页面也只声明普通控件和普通 Vue 数据字段，并用 `volume` 与 `meter1` 等不同字段表达不同语义。
+- 按普通 H5/Vue 方式写布局、样式、导航、控件和页面本地状态。
+- 为需要绑定的控件准备简单、可写、类型正确的 Vue 数据字段。
+- 使用稳定的普通 HTML `id` 或 `name`，并为重复列表使用稳定的 `:key`。
+- 用 `volume`、`muted`、`source`、`meter` 等字段表达页面语义。字段名只是页面模型名，不需要使用任何内部 Control ID。
-不得从旧页面复制以下内容：
+页面作者不需要知道：
-- 手写 `data-cp-*` 属性。这些属性会被拒绝；运行时自动添加的内部标记不属于页面交付代码。
-- `sendControl`、`postControl`、`setControlSession`、`deviceValue` 等旧页面接口。
-- 写死设备路径、驱动命令、绑定表，或调用 ControlPanel 的 HTTP、WebSocket、SSE 接口。
-- 声明 stream ID、订阅主题、帧格式、Socket.IO 事件或批量反馈协议。
-- 为修复反馈而添加设备轮询、强制回写滑杆、重复发送监听器或设备状态定时器。
+- 驱动协议、设备路径、编号方式或 `program.json`。
+- ControlPanel 的映射 JSON、桥接节点、stream、socket、SSE、帧格式或订阅主题。
+- 内部 `data-cp-*` 标记、ControlPanel HTTP API 或设备发送接口。
+- 量程换算、连续值节流、latest-wins、命令队列和反馈重连。
-这些限制针对设备绑定，不禁止正常的页面导航、CSS 动画、图片明暗变化等纯前端功能。未绑定控件不会自动控制设备。待绑定控件的模型应独立；不要让两个不同设备控件共用一个 `v-model` 字段。
+不要在页面里实现第二套设备通信。不要写设备轮询、定时回写滑杆、反馈回写命令、重复发送监听器或自定义发送函数。未绑定的控件不会自动控制设备。
-## 2. 页面格式
+页面里的 `volume` 和 `meter` 是两个不同语义：
-交付可直接粘贴到节点 Template 的组件片段：一个 `<template>`，可选的 `<script>`、`<style>`。不要交付带 `<html>`、`<head>`、`<body>` 的完整文档，也不要交付需要外部构建才能运行的项目。
+- `volume` 等普通数值字段用于音量/增益等可写连续控制，并可接收普通真实值反馈。
+- `meter` 等字段用于只读实时信号电平，只能接收驱动声明了 Meter 元数据的点位。
+- `series`、`spectrum` 等数组字段用于只读实时二维点列，只能接收驱动声明了 XY-series 元数据的点位。
-脚本使用 `export default { data() { ... }, computed: { ... }, methods: { ... } }`。待绑定字段必须是 `data()` 中的顶层、可写、简单字段，例如 `volume`、`muted`、`source`、`status`。不支持将 `state.volume`、数组下标、计算属性、函数调用或表达式作为绑定模型；不使用 `<script setup>`、组件导入或自行创建 Vue 应用。
+不要把同一个模型字段同时用于不同设备点位，尤其不要让 Meter 和 Volume 共用一个模型。
-为待绑定控件设置稳定、唯一的普通 `id`，尤其是重复控件。也可使用标准 `name`，但优先使用 `id`。不要根据运行时随机值生成 ID。改动 ID、标签类型或绑定写法后，原映射可能失效，需要重新检查。
+## 2. 页面格式与 Vue 约束
-所有 Vuetify 标签都成对闭合，包括装饰组件：`<v-icon></v-icon>`，不要写 `<v-icon/>`。Dashboard 的 HTML 渲染可能错误地吞入后续元素，节点会拒绝这种自闭合写法。原生 HTML 的 void 元素，如 `<input>`、`<img>`，不受此限制。
+交付可以直接粘贴到节点 Template 的组件片段：一个外层 `<template>`，可选的 `<script>` 和 `<style>`。不要交付带 `<html>`、`<head>`、`<body>` 的完整文档，也不要交付需要外部构建才能运行的项目。
-## 3. 可绑定控件
+脚本使用 Vue Options API：
-以下表格是当前自动绑定适配器的范围，不是整个 Vuetify 的组件清单。
+```js
+export default {
+  data () {
+    return { volume: 0, muted: false, status: '待机' }
+  },
+  computed: {},
+  methods: {}
+}
+```
-| 用途 | 原生 HTML | Vuetify | 数据与提交方式 |
-| --- | --- | --- | --- |
-| 连续数值 | `input[type=range]`、`input[type=number]` | `v-slider` | 数字；原生 input/change 发送，Vuetify 模型变化发送并在变化停止后提交最终值。 |
-| 布尔开关 | `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。 |
-| 普通只读数值 | `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 }}`，或由节点替换的纯文本；只绑定读点位。 |
+不要使用 `<script setup>`、组件导入、自行创建 Vue 应用或外部运行时依赖。普通绑定模型应是 `data()` 中的顶层字段，或本指南 3.2 节规定的列表模型。计算属性、函数调用、取反、条件表达式和动态索引不能作为绑定模型。
-原生输入可以不写 Vue 模型，也支持简单顶层 `v-model`。Vuetify 交互控件必须写简单 `v-model`；进度组件可以使用简单 `:model-value="progress"`。初始化数值为数字、开关为布尔值、文本为字符串，不用数组、对象或空值占位。
+不要手写任何 `data-cp-*` 属性。节点会在渲染副本中自动加入内部标记，页面源码不应依赖这些标记；手写此类属性会被拒绝。
-### 3.1 通用限制
+不要给绑定控件添加 `@click`、`@input`、`@change`、`@update:model-value` 等事件指令，也不要额外绑定 `:value`、`:checked` 或 `:model-value`。节点需要独占这些事件和模型更新。页面导航、标签切换、纯视觉交互等事件可以放在不绑定设备的独立控件上。
-- 待绑定控件自身不能有 `@click`、`@input`、`@change`、`@update:model-value` 等任何事件指令。即使事件只做本地操作，也会被当前识别器判为已有逻辑。页面导航等事件可放在独立、不绑定设备的控件上。
-- 交互输入控件不额外叠加 `: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` 等正常布局可以保留。编辑该控件时先让它显示出来，并确保同一定位只出现一个元素。绑定提示会随元素重建恢复。
-- 普通 Vuetify 布局组件可使用，但 `v-btn`、`v-range-slider`、`v-autocomplete`、`v-combobox`、原生 radio 等不在自动设备绑定清单中。不要假定外观相似就支持。
+以下是两个例外：
-### 3.2 各类控件限制
+- 只读原生 `<meter>`/`<progress>` 可以使用 `:value`。
+- 只读 `v-progress-linear`/`v-progress-circular` 可以使用简单 `v-model` 或 `:model-value`。
+- 语义开关按钮可以使用简单的 `:aria-pressed` 或 `:aria-checked`。
-- 数值：`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()`、拼接表达式或多个插值。复杂展示可用另外的纯前端元素，不把它作为设备反馈绑定目标。
+所有 Vuetify 组件标签都成对闭合，例如 `<v-icon></v-icon>`。Dashboard 的模板渲染可能吞掉自闭合组件后面的内容，节点会在部署前拒绝 `<v-slider />`、`<v-progress-linear />` 等写法。原生 HTML void 元素，如 `<input>` 和 `<img>`，不受此限制。
-### 3.3 Meter 实时信号与批量反馈
+## 3. 可绑定控件
-页面作者不编写订阅、socket 或批处理代码，但要用不同字段表达不同语义：音量/增益使用 `volume` 等普通可写字段；实时信号使用 `meter`、`meter1` 等只读字段。部署人员在绑定编辑页选择 Feedback point；只有驱动明确声明 Meter 元数据的点位才会进入 Meter 列表，ControlPanel 会在运行时自动采用批量反馈通道，并把同一帧的数据一次性更新到本页对应的所有表头。
+以下是当前适配器支持的范围，不代表任意 Vuetify 或第三方组件都支持。
-页面不需要也不得声明设备、驱动、stream、socket、帧序号、点位路径或 ControlPanel API。断线、过期帧、重连、同帧合并和页面量程换算都由节点处理。反馈短暂失效时节点保留最后显示值并标记无效；页面作者不添加轮询、定时器或回写逻辑。标签页、`v-if` 等使控件重新创建后，节点会重新关联控件。
+| 用途 | 原生 HTML | Vuetify | 模型与行为 |
+| --- | --- | --- | --- |
+| 连续数值控制 | `input[type=range]`、`input[type=number]` | `v-slider` | 数字；range 在拖动时发送中间值，结束时发送最终值。 |
+| 布尔控制 | `input[type=checkbox]`、带语义属性的 `button` | `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 提交。 |
+| 普通只读反馈 | `span`、`output` 等简单文本展示 | 暂无专用组件 | 只读普通反馈，不发送命令。 |
+| 实时信号电平 Meter | `meter`、`progress` | `v-progress-linear`、`v-progress-circular` | 只读数值；必须绑定驱动的 Meter 点位，不发送命令。 |
+| 实时二维点列 XY-series | `canvas` + `:data-points` 或 `:data-series`；地图容器 + `:data-coordinates` | 第三方图表暂不自动识别 | 只读 `[[x, y], ...]` 数组；不发送命令。 |
-多个表头必须使用不同的 `id` 和不同的顶层字段。不要让属于不同设备点位的表头共用同一个字段；同一个滑杆及其纯视觉旁显可以共享字段，但只能绑定其中一个控件。Meter 与 volume 是完全独立的通信类型：volume 负责音量/增益设置和普通真实值反馈，Meter 只负责某音频通道的高频实时信号电平反馈。代码或驱动中的历史 `level` 名称不自动表示 Meter；是否具备 Meter 能力由点位的 Meter 元数据决定。
+交互控件建议写简单顶层 `v-model`。原生 range/select 可以使用 `.number`；不要给布尔、文本或 Meter 加 `.number`。Vuetify 进度组件可以使用简单 `v-model`，也可以使用简单 `:model-value`。原生 Meter/Progress 可以使用简单顶层 `v-model`，节点会把它转换成只读 `:value`；在 `v-for` 列表中应直接写 `:value="item.meter"`，不要写嵌套字段的原生 `v-model`。
-### 3.4 普通按钮与开关按钮
+初始化值应匹配控件类型：数值为数字，开关为布尔值，文本和枚举为字符串。不要用数组、对象或 `null` 作为普通绑定控件的占位值。
-一个只有文字的普通 `<button>` 不会自动成为设备控件。需要布尔设备开关时使用标准语义：
+XY-series 使用数组字段初始化，例如 `spectrum: []`。推荐使用标准 Canvas：
 ```html
-<button id="room-power" type="button" :aria-pressed="powered">电源</button>
-<button id="room-mute" type="button" role="switch" :aria-checked="muted">静音</button>
+<canvas id="room-spectrum" :data-points="spectrum" aria-label="实时频谱"></canvas>
+```
+地图坐标使用普通 HTML 容器和标准地理坐标顺序 `[经度, 纬度]`：
+```html
+<div id="room-map" class="room-map"
+  :data-coordinates="locations" aria-label="实时位置"></div>
 ```
-在 `data()` 中将 `powered`、`muted` 初始化为布尔值。也可使用静态 `aria-pressed="false"` 或 `role="switch" aria-checked="false"`，由节点更新按钮状态。不要叠加点击事件。`aria-pressed`/`aria-checked` 的动态表达式只写顶层字段，不写取反、条件或函数。
+`locations` 的值也是完整快照，例如 `[[116.397, 39.908], [121.473, 31.230]]`。节点只负责把驱动的二维数组更新到这个普通 Vue 数组；地图底图、投影、标记和缩放属于页面自己的显示逻辑。当前自动识别支持 `div`、`section`、`article`、`main`、`aside`、`svg` 和 `g` 上的 `:data-coordinates`，不要求页面引入地图 SDK，也不要求页面知道驱动或订阅机制。
-## 4. 示例
+节点会把每个完整帧更新到 `spectrum` 或 `locations`，页面自己的绘图逻辑可以观察这个普通 Vue 数组。`data-points`、`data-series` 和 `data-coordinates` 都是普通 HTML `data-*` 属性，不是 ControlPanel 私有属性。Canvas 的频谱点列与地图坐标只是页面呈现语义不同，底层使用同一个只读 XY-series 通道。当前自动识别只支持顶层简单字段，不支持 `v-for` 内的二维点列模型、函数调用、表达式、多个数据源合并或第三方图表组件的专用数据格式。
-### 4.1 原生 H5 控件
+### 3.1 普通控件写法
 ```html
 <template>
   <section>
     <label for="room-volume">音量</label>
     <input id="room-volume" type="range" min="0" max="100" step="1" v-model.number="volume">
-    <label><input id="room-mute" type="checkbox" v-model="muted">静音</label>
+    <label>
+      <input id="room-mute" type="checkbox" v-model="muted">
+      静音
+    </label>
     <button id="room-power" type="button" :aria-pressed="powered">电源</button>
     <select id="room-source" v-model="source">
       <option value="A">输入 A</option>
       <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, meter: 0, muted: false, powered: false, source: 'A', status: '待机', progress: 0 }
+    return {
+      volume: 0,
+      muted: false,
+      powered: false,
+      source: 'A',
+      status: '待机',
+      meter: 0,
+      progress: 0
+    }
   }
 }
 </script>
 ```
-### 4.2 Vuetify 控件
+### 3.2 `v-for` 列表绑定
+当前支持一层、来源为 `data()` 顶层数组字段的列表。对象列表使用稳定对象 ID：
+```html
+<div v-for="item in items" :key="item.id">
+  <span>{{ item.name }}</span>
+  <input :id="'volume-' + item.id" type="range"
+    min="0" max="100" step="1" v-model.number="item.volume">
+</div>
+```
+也支持带索引别名的对象列表：
+```html
+<div v-for="(item, index) in items" :key="item.id">
+  <input id="row-volume" type="range" v-model.number="items[index].volume">
+</div>
+```
+数组列表使用索引作为 key：
+```html
+<input v-for="(value, index) in values" :key="index"
+  :id="'value-' + index" type="range" v-model.number="values[index]">
+```
+对象项可以使用静态嵌套字段，例如 `item.audio.volume` 或 `items[index].audio.volume`。数组项可以使用 `values[index]`。模型路径必须是标识符和静态点路径，不能调用函数、做计算或使用动态属性。
+一个列表项需要多个并列控件时，可使用内层 `<template v-for>`，但它必须是外层节点 Template 的子节点：
+```html
+<template>
+  <template v-for="item in items" :key="item.id">
+    <input id="row-volume" type="range" v-model.number="item.volume">
+    <input id="row-balance" type="range" v-model.number="item.balance">
+  </template>
+</template>
+```
+列表规则：
+- 对象列表必须使用精确的 `:key="item.id"`；数组列表必须使用精确的 `:key="index"`。
+- `item.id` 必须稳定且在当前列表中唯一。重复 key/ID 的实例不会被安全绑定；Vue 重渲染期间短暂出现的重复 DOM 会被节点暂时忽略，key 恢复唯一后自动重新关联，但页面不应依赖这种容错。
+- 列表外的每个绑定控件都应有唯一的普通 `id` 或 `name`。列表内的重复实例可以使用同一个静态 `id`，节点通过列表 key 区分实例；不要为每一项拼接依赖运行时随机值的 ID。
+- 列表控件在编辑页面中按实际渲染出的实例逐项选择。列表增加或删除后，应重新进入编辑器、补齐或移除对应映射，再 Apply。
+- `v-for` 可以写在实际容器上，也可以写在内层 `<template>` 上。不要把 `v-for` 直接写在唯一的外层节点 Template 上。
+- 不支持嵌套 `v-for`、动态列表来源、过滤或计算表达式、复杂 key、slot scope、自定义列表项事件和任意动态索引。
+`v-if`、标签页切换、普通 DOM 重建和过渡造成的重新渲染可以使用。节点会在元素重新出现后恢复绑定；不要通过 `mounted`、`watch` 或定时器手动补绑或回写模型。
+### 3.3 Vuetify 控件
 ```html
 <template>
   <section>
-    <v-slider id="room-volume" label="音量" v-model="volume" :min="0" :max="100" :step="1"></v-slider>
+    <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-radio-group id="room-mode" label="模式" v-model="mode">
@@ -127,82 +203,147 @@ 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-meter" :model-value="meter" :max="100"></v-progress-linear>
+    <v-progress-linear id="room-meter" v-model="meter" :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'],
-      mode: 'A', title: '', meter: 0, status: '待机'
+      volume: 0,
+      muted: false,
+      sources: ['A', 'B'],
+      source: 'A',
+      mode: 'A',
+      title: '',
+      meter: 0,
+      status: '待机'
     }
   }
 }
 </script>
 ```
-示例选项 A/B 只是占位数据，不保证与实际设备相符。部署人员应确认驱动的枚举值，再决定前端选项。节点不会自动生成或改写下拉菜单选项。
+当前 Vuetify 适配器包括 `v-slider`、`v-switch`、`v-checkbox`、`v-select`、`v-radio-group`、`v-text-field`、`v-textarea`、`v-progress-linear` 和 `v-progress-circular`。普通布局组件可以使用，但布局组件本身不是绑定目标。
+以下写法当前不支持：
+- `v-btn` 作为自动设备按钮；需要布尔设备控制时使用语义按钮写法。
+- `v-range-slider`、多选、`return-object`、对象模型、数组模型、自定义 `true-value`/`false-value`。
+- `v-autocomplete`、`v-combobox`、原生 radio 和带独立事件处理器的子控件。
+- 动态量程；range 的 `min`、`max`、`step` 必须是数字字面量或数字字面量绑定。`v-slider` 必须满足 min < max、step > 0。
+- `v-progress-linear` 的 `min`/`step`、`indeterminate`、`clickable`；`v-progress-circular` 的 `min`/`max`/`step`、`indeterminate`。前者按 0 到 max 工作，后者固定按 0 到 100 工作。
+下拉选项可以是标量数组或普通 `{ title, value }` 选项，但模型必须是单个标量，且值必须与设备枚举值一致。示例中的 A/B 只是页面占位数据，节点不会自动生成或修改下拉选项。
+## 4. Meter 与普通数值反馈
+Meter 是驱动端的特殊只读数据类型，不是“另一个滑杆”。页面作者只声明普通进度/电平控件；编辑人员把它绑定到带 Meter 元数据的 Feedback point 后，ControlPanel 自动完成批量订阅、同帧投影、页面侧量程换算、过期判断和重连。
+- 一个 Meter 绑定只能使用 `read` 模式，不能配置 Write point。
+- 只有驱动点位带有有效 `.metadata.meter`，并且是只读整数/浮点参数时，才会出现在 Meter 可选目标中。
+- 普通 numeric `level`、`volume` 或其他连续参数不会因为名字像电平就自动变成 Meter。
+- 一个面板最多支持 256 个 Meter 绑定。多个 Meter 会按流聚合，前端每帧一次性更新本页所有对应表头；页面不编写任何批处理或 socket 代码。
+- Meter 需要独立字段，例如 `meter1`、`meter2`。不要与音量滑杆的 `volume` 共用字段，也不要让不同点位共用一个 Meter 模型。
+- 断线、无效帧和过期帧由节点处理；页面看到的是最后值并带无效状态，页面作者不添加轮询或回写逻辑。
+- 原生 `<meter>`/`<progress>` 默认页面范围是 0 到 1；Vuetify 进度组件分别使用固定的 0 到 max 或 0 到 100。应按页面显示范围声明固定量程。
+量程适配发生在网页侧：页面量程与驱动量程之间做线性换算，反馈按相反方向换算，不修改驱动或协议。两端都必须是有限且 max > min 的数字；否则按原值传递，不能猜测量程。整数驱动值会取整，反馈会按页面 step 对齐。
+普通只读反馈使用文本展示即可：
+```html
+<span id="room-status">{{ status }}</span>
+<output id="room-value">{{ outputValue }}</output>
+```
+## 4.1 XY-series 与普通实时数组反馈
-图片明暗、数值旁显等效果可以正常依赖 `volume` 或 `light` 做 Vue/CSS 展示。这些展示元素不发送设备命令，也不要反过来用 watch、mounted 或定时器重置正在绑定的字段。
+XY-series 是 Meter 的独立数组版本，不是多个 Meter 的替代写法：
-## 5. 部署与绑定
+- 每个驱动帧是一个完整的 `[[x, y], ...]` 快照，第一层长度可以变化，也可以是空数组。
+- 每个点必须恰好有两个有限数字；节点保留点的顺序，不自动排序、不自动缩放、不自动丢弃旧点。
+- 数据只读，绑定只能使用 `read` 模式，没有 Write point；它与 Volume、Level 和 Meter 不能共用同一个模型字段。
+- 多个页面绑定相同 stream 时只建立一个源订阅，页面帧使用 latest-wins；网络拥塞时允许丢弃旧帧，不补发历史帧。
+- 当前每个 stream 默认最多 8192 个点，每个面板最多 256 个 XY-series 绑定；真实 MUSE 测试前仍需按点数和帧大小验证吞吐。
+- 页面作者不写 socket、订阅、帧解析或重连代码，只维护普通数组。频谱坐标轴、Canvas 绘制、坐标变换和图表样式属于页面显示逻辑。
-1. 将页面粘贴到 `ui-control-panel` Template，选择 Dashboard 页面，设置 Room ID、普通账号及独立的编辑账号。普通账号密码至少 12 个字符；账号密码由节点配置，不能写入 H5。保存并 Deploy。
-2. 重新打开节点，点击 `Open binding editor`，用编辑账号登录。Select 默认激活，可以点击、右键或触屏长按可绑定控件。`Open page` 打开普通控制页面，使用普通用户账号登录。
-3. 选择在线设备、模式、Write point、Feedback point、编号方式，保存草稿。草稿和亮紫色边框不表示已部署；边框只在编辑模式显示。
-4. 点 Apply。节点检查当前模板、目录参数和 Flow 版本，备份后替换该面板此前生成的桥接并保存。Apply 不替用户 Deploy；当 Automator 报告外部 Flow 变化时，编辑器只刷新一次 Flow 页面，之后由用户检查并手动 Deploy。不会无限追加旧桥接，也不会清除其他面板的绑定。Apply 成功后仍在编辑页，无需再次登录。
-5. 点 Exit，回到普通页面登录页，再输入普通账号密码。普通账号不能进入编辑模式；不登录不能操作设备。进程重启或凭据变化可能要求重新登录。
+文本展示只使用一个简单字段插值，例如 `{{ status }}` 或 `{{ outputValue }}`。不要使用 `toFixed()`、拼接表达式或多个插值作为绑定模型。
-Bindings 列表可 Edit 或 Remove；这些操作先改草稿，最后统一 Apply。从列表进入 Edit，保存或取消后返回列表。刷新、离开或重启前先 Apply，避免草稿丢失。
+## 5. 语义开关按钮
-普通 Deploy 不能替代网页 Apply。Template 改动可能使已保存控件失效；重新 Deploy 后检查绑定。Apply 的原有模板、目录、Flow 版本和输入校验保持不变；Flow 页面刷新不自动合并画布改动，也不自动 Deploy。
+普通文字 `<button>` 不会自动成为设备控件。需要布尔设备控制时使用标准语义，不添加事件：
-设备必须在线且当前运行环境的 AMX 目录可返回参数，才能查询或重新 Apply 相关绑定。已保存映射在 Flow 中，启动和显示页面不要求驱动在线；但断线时不能保证设备控制或新反馈。Mac 安装模块不等于 MUSE 已安装，Push 也不等于复制本地 node_modules。部署模块属于运行环境操作，不属于前端开发职责。
+```html
+<button id="room-power" type="button" :aria-pressed="powered">电源</button>
+<button id="room-mute" type="button" role="switch" :aria-checked="muted">静音</button>
+```
+在 `data()` 中把 `powered` 和 `muted` 初始化为布尔值。也可以使用静态 `aria-pressed="false"` 或 `aria-checked="false"`，由节点更新状态。动态 ARIA 表达式只能是顶层字段，不能写取反、条件或函数。
+## 6. 绑定与编辑流程
+页面作者只需交付 Template。实际绑定由使用者在编辑页面完成：
-## 6. 匹配、编号与范围
+1. 将 Template 保存到 `ui-control-panel`，配置 Dashboard 页面、Room ID、普通登录账号和独立编辑账号，然后保存并 Deploy。
+2. 重新打开节点，点击 `Open binding editor`。编辑页登录使用编辑账号；进入后 Select 默认激活。`Open page` 打开普通控制页面，普通页面必须使用普通账号登录。
+3. 在 Select 模式选择控件，选择设备、模式、Write point、Feedback point 和编号方式。已绑定控件在编辑模式显示亮紫色边框；这只是编辑提示。
+4. 点 Apply。节点验证当前模板、设备目录和映射，备份当前 Flow，并通过运行时 Flow API 更新当前面板的映射和受管理桥接。它不会导入、清除或追加其他面板的 Flow。
+5. Apply 成功后仍停留在编辑页；Bindings 列表可以 Edit 或 Remove，取消/保存后回到列表。Apply 后不应要求再次登录；点 Exit 才回到普通页面登录页。
-点位筛选基于参数描述，而不是页面文字或驱动显式 `controlType`：
+Automator 的同步脚本只监听更新后的运行时 Flow 版本，并最多刷新一次 Flow 编辑器页面；它不读取、导入、合并、清除或再次提交 Flow。当前实现不判断画布是否有未 Deploy 改动，也不会合并画布草稿；在 Apply 前应先处理好 Automator 中未保存的画布改动。
+Template 修改可能使已有映射失效。重新 Deploy 后，应重新打开绑定编辑器检查候选控件；列表增删、控件 ID/标签类型/模型写法改变后，也应重新检查并 Apply。普通页面登录账号不能进入编辑模式，未登录不能操作设备。
+## 7. 点位匹配与量程
+编辑器根据 AMX 参数描述推导可匹配类型，不根据页面文字，也不把驱动作者写入的旧式显式 `controlType` 当作页面契约。主要依据是 `.kind`、`.type`、`.access`、`.min`、`.max`、`.enums` 和 `.metadata`。Meter 的 `.metadata.meter` 是实时通道所需的特殊元数据，不能省略。
 | 参数描述 | 可匹配控件 |
 | --- | --- |
-| boolean，或无枚举且范围恰为 0–1 的 integer | 布尔开关；整数 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 | 文本输入。 |
-| 上述类型的可读参数 | 简单文本展示也可绑定。 |
-只有 `kind=param` 且具备相应 ro/wo/rw 权限的点位才参与绑定。范围未知不会通过“读取一个当前值”猜出量程；普通命令、数组或未知描述不保证适配。页面无需自己判断这些类型。
+| boolean，或没有枚举且范围恰为 0 到 1 的 integer | 布尔开关；整数 0/1 会转换为前端布尔值。 |
+| 可写 integer/float | range 或 `v-slider`；用于音量/增益等普通连续控制。 |
+| 只读 integer/float，没有 Meter 元数据 | 文本展示等普通只读反馈，不能选择为 Meter。 |
+| 只读 integer/float，带有效 `.metadata.meter` | Meter、原生 `meter`/`progress` 或 Vuetify 进度组件；只能读。 |
+| 只读参数，带有效 `.metadata.xySeries` | XY-series；使用标准 Canvas 的 `:data-points`/`:data-series`，或地图容器的 `:data-coordinates` 数组字段；只能读。 |
+| enum，或带枚举描述的 integer/string | 单选枚举。 |
+| 没有枚举但路径以 `/source` 或 `/preset` 结尾的 integer | 选择类参数，仍需确认合法选项。 |
+| string/dstring | 文本输入或文本展示。 |
-Write point 改动时 Feedback point 跟随；单独改 Feedback point 不反向改 Write point。只读模式没有 Write point。编号选择默认 Zero-based；实际保存优先采用目录里的 `.onebased`，目录未提供时才采用用户选择。它不是对网页音量值加减 1，也不是驱动 `protocolChannel` 的编号。
+只有 `kind=param` 且具备相应读/写权限的点位参与绑定。普通命令、数组和未知描述不保证可绑定。
-量程适配只发生在网页侧：有效的页面 [uiMin, uiMax] 与驱动 [driverMin, driverMax] 之间线性换算，反馈反向换算，不改驱动代码或协议。两边都必须是有限数字且 max > min；缺少有效量程时原值传递，不能假定自动缩放。整数设备目标会取整；回到网页时按页面 step 对齐。Write/Feedback 使用不同量程时分别换算，部署人员应确认二者属于同一逻辑控制量。
+Write point 改动时 Feedback point 会跟随；单独改 Feedback point 不会反向改 Write point。Meter 没有 Write point。编号方式默认 Zero-based；如果目录点位带有 `.onebased`，保存时以目录描述为准，否则使用编辑页选择。编号方式只影响驱动点位编号，不会给网页值加减 1。
-## 7. 排查顺序
+## 8. 常见排查
 | 现象 | 先检查 |
 | --- | --- |
-| 控件不能选中 | 是否在支持清单、是否有事件指令/复杂模型/v-for、自闭合 Vuetify、重复 ID；阅读编辑页给出的拒绝原因。 |
-| 有设备但点位为空 | 在线状态、参数目录、值类型与 ro/wo/rw 权限；不是所有设备命令都属于可绑定参数。 |
-| 草稿有紫框但普通页无效 | Apply 是否成功、模式和点位是否正确、桥接是否同步、MUSE 是否加载预期模块版本。 |
-| 页面一直 Loading | 先检查节点状态和运行日志中的模板编译错误，例如在原生 meter/progress 上使用带修饰符的 v-model、动态表达式或同时写 v-model 与 :value。简单顶层 v-model 会由节点转换为只读 :value；节点会显示具体模板错误。会话检查包含响应正文的超时保护，设备离线不应阻止普通页进入登录页。登录检查的时限不包含 Dashboard 资源下载和组件编译时间。 |
-| 滑杆动不了 | 是否仍在 Select 编辑模式、模型类型是否正确、是否存在手写回写逻辑；不要先改驱动。 |
-| 页面变化但设备不变 | 写映射和驱动收发日志。前端变化不证明命令到达设备。 |
-| 设备已变但页面旧值 | Feedback point、事件/读取是否有新反馈。节点不能凭写入成功制造真实设备反馈。 |
-| 原生与 Vuetify 表现不同 | 是否符合各自模型、事件和量程约束；不要给绑定控件额外增加发送监听。 |
-隔离测试只验证软件逻辑，不能证明真实设备闭环、MUSE 网络或驱动版本都正确。
-## 8. 给 AI 的交付检查
-- 输出可粘贴的 Template 组件片段，不输出 Node-RED Flow、设备路径、绑定 JSON 或账号密码。
-- 所有待绑定控件位于支持清单，使用稳定唯一 ID；数据模型简单、独立且类型正确。
-- 页面量程明确、数值常量有效；下拉菜单选项与实际设备值对应。
-- 没有手写 `data-cp-*`、旧发送接口、设备通信、绑定控件事件或复杂模型。
-- 实时表头仍是普通 HTML/Vue/Vuetify；没有 stream、socket、订阅、帧协议或驱动相关代码。
-- Vuetify 标签成对闭合；不把自动绑定目标放入 v-for。
-- 保留正常的视觉与纯前端交互；不为了绑定重写驱动或添加第二套控制逻辑。
-- 不声称任意普通页面都可无条件自动绑定；不支持的组件要明确说明，不能伪造兼容写法。
+| 控件不能选择 | 是否在支持清单；是否有事件指令、复杂模型、动态量程、重复/不唯一 key、重复 ID 或自闭合 Vuetify 标签。 |
+| `v-for` 实例没有出现 | 来源是否是顶层数组；key 是否严格符合对象/数组规则；列表项是否实际渲染且 key 唯一。 |
+| 设备有了但点位为空 | 设备在线状态、AMX 参数目录、`kind/type/access` 和读写权限；不是所有命令都属于可绑定参数。 |
+| Meter 可以选但无值 | 点位是否带 `.metadata.meter`；驱动是否实际发布 manifest 和 frame；页面字段是否与普通 Volume 分开。 |
+| XY-series 可以选但无值 | 点位是否带 `.metadata.xySeries`；驱动是否发布对应 manifest/frame；数组字段是否为顶层数组；检查点数、帧大小和过期状态。 |
+| 页面一直 Loading | 查看模板编译错误，重点检查原生 Meter/Progress 的 v-model 写法、自闭合 Vuetify、动态表达式和不支持的组件。设备离线不应被页面作者通过轮询“修复”。 |
+| 滑杆动不了 | 是否仍处于 Select 编辑模式；模型是否为数字；是否给绑定控件添加了自己的事件或回写逻辑。 |
+| 页面变化但设备不变 | 检查映射的 Write point、设备权限和运行日志。前端模型变化不等于设备已确认执行。 |
+| 设备值变了但页面旧 | 检查 Feedback point、普通反馈事件或 Meter frame 是否到达；节点不会凭写入成功伪造真实反馈。 |
+| Apply 失败并提示 Flow changed | 先处理 Automator 中的未 Deploy 改动，再刷新编辑器并重新打开绑定页；不要手工复制或追加生成桥接。 |
+隔离测试只能证明模板识别、映射和软件通信逻辑，不能证明真实设备、MUSE 网络或驱动版本已经完成闭环测试。
+## 9. 给 AI 的交付检查
+- 输出可粘贴的 Template 片段，不输出 Node-RED Flow、设备路径、绑定 JSON、账号密码或 ControlPanel API 调用。
+- 所有待绑定控件位于支持清单，模型字段简单、独立、可写且类型正确。
+- 列表只使用本指南规定的 `v-for`、`:key` 和模型路径；对象 key 稳定唯一，数组 key 使用 index。
+- 列表内的 Meter、Volume 和其他控件使用不同模型字段；重复实例依靠稳定 key 区分，不生成随机 ID。
+- XY-series 使用独立的顶层数组字段，例如 `spectrum: []`，不要与 Meter、Volume 或普通反馈字段共用。
+- 地图坐标使用独立的顶层数组字段，例如 `locations: []`，点顺序固定为 `[经度, 纬度]`；不要与 Meter、Volume 或普通反馈字段共用。
+- 页面量程明确、数值常量有效；枚举选项与实际设备值对应。
+- 没有手写 `data-cp-*`、设备通信、轮询、反馈回写、绑定控件事件或第二套发送逻辑。
+- 实时表头仍是普通 HTML/Vue/Vuetify 控件；没有 stream、socket、订阅、帧协议或驱动代码。
+- Vuetify 标签成对闭合；不使用本指南明确列出的不支持组件和属性。
+- 保留正常的视觉和纯前端交互；不要为了绑定修改驱动或猜测设备量程。
+- 不声称任意普通页面都能无条件自动绑定；遇到不支持的组件或表达式，应改写为支持的普通写法。

package/README.md CHANGED Viewed

@@ -10,10 +10,12 @@ Both logins work over HTTP on a trusted local network. HTTPS is recommended for
 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.
-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.
+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, including object-list models such as `item.volume`, `item.audio.volume`, or `items[index].volume`, primitive array models such as `values[index]`, and an inner `<template v-for>` for multiple controls per row. During Vue re-rendering, a temporary duplicate list key is ignored until the key becomes unique again, so bindings do not attach twice. 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.
+Readonly XY-series telemetry follows the same page boundary. Use a standard canvas with one simple Vue array binding, for example `<canvas id="spectrum" :data-points="spectrum"></canvas>`, or a map container with `<div id="room-map" :data-coordinates="locations"></div>`. Map coordinates use the standard `[longitude, latitude]` order. The page receives complete `[[x, y], ...]` snapshots; ControlPanel owns subscription, latest-frame replacement, stale handling, and reconnection. The page does not declare a device, stream, socket, or frame protocol. XY-series is independent from Meter and Volume: it never sends commands and does not represent a single scalar value.
 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-catalog.js CHANGED Viewed

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