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

package/CONTROL_PANEL_AI_GUIDE.md

@@ -1,125 +1,182 @@
 # 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.8.16`、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 元数据的点位。
 
-脚本使用 `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. 可绑定控件
-
-以下表格是当前自动绑定适配器的范围，不是整个 Vuetify 的组件清单。
-
-| 用途 | 原生 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 }}`，或由节点替换的纯文本；只绑定读点位。 |
-
-原生输入可以不写 Vue 模型，也支持简单顶层 `v-model`。Vuetify 交互控件必须写简单 `v-model`；进度组件可以使用简单 `:model-value="progress"`。初始化数值为数字、开关为布尔值、文本为字符串，不用数组、对象或空值占位。
+脚本使用 Vue Options API：
 
-### 3.1 通用限制
-
-- 待绑定控件自身不能有 `@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 等不在自动设备绑定清单中。不要假定外观相似就支持。
+```js
+export default {
+  data () {
+    return { volume: 0, muted: false, status: '待机' }
+  },
+  computed: {},
+  methods: {}
+}
+```
 
-### 3.2 各类控件限制
+不要使用 `<script setup>`、组件导入、自行创建 Vue 应用或外部运行时依赖。普通绑定模型应是 `data()` 中的顶层字段，或本指南 3.2 节规定的列表模型。计算属性、函数调用、取反、条件表达式和动态索引不能作为绑定模型。
 
-- 数值：`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()`、拼接表达式或多个插值。复杂展示可用另外的纯前端元素，不把它作为设备反馈绑定目标。
+不要手写任何 `data-cp-*` 属性。节点会在渲染副本中自动加入内部标记，页面源码不应依赖这些标记；手写此类属性会被拒绝。
 
-### 3.3 Meter 实时信号与批量反馈
+不要给绑定控件添加 `@click`、`@input`、`@change`、`@update:model-value` 等事件指令，也不要额外绑定 `:value`、`:checked` 或 `:model-value`。节点需要独占这些事件和模型更新。页面导航、标签切换、纯视觉交互等事件可以放在不绑定设备的独立控件上。
 
-页面作者不编写订阅、socket 或批处理代码，但要用不同字段表达不同语义：音量/增益使用 `volume` 等普通可写字段；实时信号使用 `meter`、`meter1` 等只读字段。部署人员在绑定编辑页选择 Feedback point；只有驱动明确声明 Meter 元数据的点位才会进入 Meter 列表，ControlPanel 会在运行时自动采用批量反馈通道，并把同一帧的数据一次性更新到本页对应的所有表头。
+以下是两个例外：
 
-页面不需要也不得声明设备、驱动、stream、socket、帧序号、点位路径或 ControlPanel API。断线、过期帧、重连、同帧合并和页面量程换算都由节点处理。反馈短暂失效时节点保留最后显示值并标记无效；页面作者不添加轮询、定时器或回写逻辑。标签页、`v-if` 等使控件重新创建后，节点会重新关联控件。
+- 只读原生 `<meter>`/`<progress>` 可以使用 `:value`。
+- 只读 `v-progress-linear`/`v-progress-circular` 可以使用简单 `v-model` 或 `:model-value`。
+- 语义开关按钮可以使用简单的 `:aria-pressed` 或 `:aria-checked`。
 
-多个表头必须使用不同的 `id` 和不同的顶层字段。不要让属于不同设备点位的表头共用同一个字段；同一个滑杆及其纯视觉旁显可以共享字段，但只能绑定其中一个控件。Meter 与 volume 是完全独立的通信类型：volume 负责音量/增益设置和普通真实值反馈，Meter 只负责某音频通道的高频实时信号电平反馈。代码或驱动中的历史 `level` 名称不自动表示 Meter；是否具备 Meter 能力由点位的 Meter 元数据决定。
+所有 Vuetify 组件标签都成对闭合，例如 `<v-icon></v-icon>`。Dashboard 的模板渲染可能吞掉自闭合组件后面的内容，节点会在部署前拒绝 `<v-slider />`、`<v-progress-linear />` 等写法。原生 HTML void 元素，如 `<input>` 和 `<img>`，不受此限制。
 
-### 3.4 普通按钮与开关按钮
+## 3. 可绑定控件
 
-一个只有文字的普通 `<button>` 不会自动成为设备控件。需要布尔设备开关时使用标准语义：
+以下是当前适配器支持的范围，不代表任意 Vuetify 或第三方组件都支持。
 
-```html
-<button id="room-power" type="button" :aria-pressed="powered">电源</button>
-<button id="room-mute" type="button" role="switch" :aria-checked="muted">静音</button>
-```
+| 用途 | 原生 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 点位，不发送命令。 |
 
-在 `data()` 中将 `powered`、`muted` 初始化为布尔值。也可使用静态 `aria-pressed="false"` 或 `role="switch" aria-checked="false"`，由节点更新按钮状态。不要叠加点击事件。`aria-pressed`/`aria-checked` 的动态表达式只写顶层字段，不写取反、条件或函数。
+交互控件建议写简单顶层 `v-model`。原生 range/select 可以使用 `.number`；不要给布尔、文本或 Meter 加 `.number`。Vuetify 进度组件可以使用简单 `v-model`，也可以使用简单 `:model-value`。原生 Meter/Progress 可以使用简单顶层 `v-model`，节点会把它转换成只读 `:value`；在 `v-for` 列表中应直接写 `:value="item.meter"`，不要写嵌套字段的原生 `v-model`。
 
-## 4. 示例
+初始化值应匹配控件类型：数值为数字，开关为布尔值，文本和枚举为字符串。不要用数组、对象或 `null` 作为普通绑定控件的占位值。
 
-### 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 +184,132 @@ 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`。普通布局组件可以使用，但布局组件本身不是绑定目标。
 
-图片明暗、数值旁显等效果可以正常依赖 `volume` 或 `light` 做 Vue/CSS 展示。这些展示元素不发送设备命令，也不要反过来用 watch、mounted 或定时器重置正在绑定的字段。
+以下写法当前不支持：
 
-## 5. 部署与绑定
+- `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 工作。
 
-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，回到普通页面登录页，再输入普通账号密码。普通账号不能进入编辑模式；不登录不能操作设备。进程重启或凭据变化可能要求重新登录。
+下拉选项可以是标量数组或普通 `{ title, value }` 选项，但模型必须是单个标量，且值必须与设备枚举值一致。示例中的 A/B 只是页面占位数据，节点不会自动生成或修改下拉选项。
 
-Bindings 列表可 Edit 或 Remove；这些操作先改草稿，最后统一 Apply。从列表进入 Edit，保存或取消后返回列表。刷新、离开或重启前先 Apply，避免草稿丢失。
+## 4. Meter 与普通数值反馈
 
-普通 Deploy 不能替代网页 Apply。Template 改动可能使已保存控件失效；重新 Deploy 后检查绑定。Apply 的原有模板、目录、Flow 版本和输入校验保持不变；Flow 页面刷新不自动合并画布改动，也不自动 Deploy。
+Meter 是驱动端的特殊只读数据类型，不是“另一个滑杆”。页面作者只声明普通进度/电平控件；编辑人员把它绑定到带 Meter 元数据的 Feedback point 后，ControlPanel 自动完成批量订阅、同帧投影、页面侧量程换算、过期判断和重连。
 
-设备必须在线且当前运行环境的 AMX 目录可返回参数，才能查询或重新 Apply 相关绑定。已保存映射在 Flow 中，启动和显示页面不要求驱动在线；但断线时不能保证设备控制或新反馈。Mac 安装模块不等于 MUSE 已安装，Push 也不等于复制本地 node_modules。部署模块属于运行环境操作，不属于前端开发职责。
+- 一个 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。应按页面显示范围声明固定量程。
 
-## 6. 匹配、编号与范围
+量程适配发生在网页侧：页面量程与驱动量程之间做线性换算，反馈按相反方向换算，不修改驱动或协议。两端都必须是有限且 max > min 的数字；否则按原值传递，不能猜测量程。整数驱动值会取整，反馈会按页面 step 对齐。
+
+普通只读反馈使用文本展示即可：
+
+```html
+<span id="room-status">{{ status }}</span>
+<output id="room-value">{{ outputValue }}</output>
+```
 
-点位筛选基于参数描述，而不是页面文字或驱动显式 `controlType`：
+文本展示只使用一个简单字段插值，例如 `{{ status }}` 或 `{{ outputValue }}`。不要使用 `toFixed()`、拼接表达式或多个插值作为绑定模型。
+
+## 5. 语义开关按钮
+
+普通文字 `<button>` 不会自动成为设备控件。需要布尔设备控制时使用标准语义，不添加事件：
+
+```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。实际绑定由使用者在编辑页面完成：
+
+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 才回到普通页面登录页。
+
+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 进度组件；只能读。 |
+| 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 分开。 |
+| 页面一直 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。
+- 页面量程明确、数值常量有效；枚举选项与实际设备值对应。
+- 没有手写 `data-cp-*`、设备通信、轮询、反馈回写、绑定控件事件或第二套发送逻辑。
+- 实时表头仍是普通 HTML/Vue/Vuetify 控件；没有 stream、socket、订阅、帧协议或驱动代码。
+- Vuetify 标签成对闭合；不使用本指南明确列出的不支持组件和属性。
+- 保留正常的视觉和纯前端交互；不要为了绑定修改驱动或猜测设备量程。
+- 不声称任意普通页面都能无条件自动绑定；遇到不支持的组件或表达式，应改写为支持的普通写法。

package/README.md

@@ -10,7 +10,7 @@ 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.
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.8.16",
+  "version": "1.9.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "node-red-contrib-room-tools",
-      "version": "1.8.16",
+      "version": "1.9.0",
       "license": "UNLICENSED",
       "dependencies": {
         "@vue/compiler-sfc": "3.5.42",

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.8.16",
+  "version": "1.9.0",
   "description": "Authenticated visual control panel binding for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
-  "engines": { "node": ">=18.16.0" },
+  "engines": {
+    "node": ">=18.16.0"
+  },
   "keywords": [
     "node-red"
   ],

package/panel-binding-editor.js

@@ -107,25 +107,106 @@ function initializeVisualBinding () {
     }
     return String(node.value)
   }
+  function repeatMarkerFor (node, repeat) {
+    let current = node
+    while (current && current !== root) {
+      if (current.getAttribute?.('data-cp-repeat') === repeat?.locator) {
+        const key = current.getAttribute('data-cp-repeat-key')
+        return key == null ? null : String(key)
+      }
+      current = current.parentElement
+    }
+    return null
+  }
+  function bindingMatchesNode (node, binding) {
+    if (node.getAttribute('data-cp-auto') !== binding.locator) return false
+    if (!binding.repeat) return true
+    return repeatMarkerFor(node, binding.repeat) === String(binding.instanceKey)
+  }
+  function nodesForBinding (binding) {
+    return [...root.querySelectorAll('[data-cp-auto]')].filter(node => bindingMatchesNode(node, binding))
+  }
+  function nodeForBinding (binding) {
+    const matches = nodesForBinding(binding)
+    return matches.length === 1 ? matches[0] : null
+  }
+  function repeatItem (binding) {
+    const repeat = binding.repeat
+    const source = component[repeat.source]
+    if (!Array.isArray(source)) return undefined
+    if (repeat.kind === 'array') return source[Number(binding.instanceKey)]
+    const keyField = repeat.key.slice(repeat.value.length + 1)
+    return source.find(value => value && String(value[keyField]) === String(binding.instanceKey))
+  }
+  function readRepeatField (item, field) {
+    return field.split('.').reduce((value, name) => value == null ? undefined : value[name], item)
+  }
+  function writeRepeatField (item, field, value) {
+    const names = field.split('.')
+    const last = names.pop()
+    let target = item
+    for (const name of names) {
+      if (!target || typeof target !== 'object') return false
+      target = target[name]
+    }
+    if (!target || typeof target !== 'object') return false
+    if (!Object.is(target[last], value)) target[last] = value
+    return true
+  }
+  function repeatModelValue (binding) {
+    if (!binding.repeat || !binding.model) return binding.model ? component[binding.model] : undefined
+    const repeat = binding.repeat
+    const source = component[repeat.source]
+    if (!Array.isArray(source)) return undefined
+    const item = repeatItem(binding)
+    if (repeat.kind === 'array' && binding.model === `${repeat.source}[${repeat.index}]`) return item
+    const prefix = repeat.value + '.'
+    const indexedPrefix = repeat.index ? `${repeat.source}[${repeat.index}].` : ''
+    const field = binding.model.startsWith(prefix) ? binding.model.slice(prefix.length)
+      : indexedPrefix && binding.model.startsWith(indexedPrefix)
+        ? binding.model.slice(indexedPrefix.length) : ''
+    return item && field ? readRepeatField(item, field) : undefined
+  }
+  function setRepeatModel (binding, value) {
+    if (!binding.repeat || !binding.model) return false
+    const repeat = binding.repeat
+    const source = component[repeat.source]
+    if (!Array.isArray(source)) return false
+    const item = repeatItem(binding)
+    const prefix = repeat.value + '.'
+    const indexedPrefix = repeat.index ? `${repeat.source}[${repeat.index}].` : ''
+    const field = binding.model.startsWith(prefix) ? binding.model.slice(prefix.length)
+      : indexedPrefix && binding.model.startsWith(indexedPrefix)
+        ? binding.model.slice(indexedPrefix.length) : ''
+    if (field) {
+      return writeRepeatField(item, field, value)
+    }
+    if (repeat.kind !== 'array' || binding.model !== `${repeat.source}[${repeat.index}]`) return false
+    const index = Number(binding.instanceKey)
+    if (!Number.isInteger(index) || index < 0 || index >= source.length) return false
+    if (!Object.is(source[index], value)) source[index] = value
+    return true
+  }
   function showFeedback () {
     for (const [id, binding] of saved) {
       if (binding.mode === 'write' || binding.readMeta?.meter) continue
-      const matches = root.querySelectorAll('[data-cp-auto="' + binding.locator + '"]')
-      if (matches.length !== 1) continue
+      const node = nodeForBinding(binding)
+      if (!node) continue
       if (!Object.prototype.hasOwnProperty.call(component.boundState, id)) continue
       const value = component.boundDisplayValue(id, component.boundState[id])
-      const node = matches[0]
       const displayValue = ['range', 'meter'].includes(binding.adapter)
         ? mappedValue(Number(value), binding.readMeta || binding.writeMeta,
           numericRange(binding, node)) : value
       if (binding.model) {
         if (binding.component && binding.adapter === 'text-input' &&
           (pendingText.has(id) || node.contains?.(document.activeElement))) continue
-        if (binding.model in component && !component.$options?.computed?.[binding.model]) {
-          if (!Object.is(component[binding.model], displayValue)) {
+        const current = repeatModelValue(binding)
+        if (binding.repeat || (binding.model in component && !component.$options?.computed?.[binding.model])) {
+          if (!Object.is(current, displayValue)) {
             pendingText.delete(id)
             if (binding.component) feedbackModels.set(id, displayValue)
-            component[binding.model] = displayValue
+            if (binding.repeat) setRepeatModel(binding, displayValue)
+            else component[binding.model] = displayValue
             if (binding.component && component.$nextTick) {
               void component.$nextTick(() => {
                 if (Object.is(feedbackModels.get(id), displayValue)) feedbackModels.delete(id)
@@ -151,11 +232,12 @@ function initializeVisualBinding () {
   function attachControls () {
     for (const node of root.querySelectorAll('[data-cp-auto]')) {
       if (attached.has(node)) continue
-      attached.add(node)
       const locator = node.getAttribute('data-cp-auto')
-      const matched = [...saved].find(([, entry]) => entry.locator === locator)
+      const matched = [...saved].find(([, entry]) => bindingMatchesNode(node, entry))
       if (!matched) continue
       const [id, binding] = matched
+      if (nodeForBinding(binding) !== node) continue
+      attached.add(node)
       if (binding.mode === 'read') continue
       if (binding.component) {
         if (binding.adapter === 'text-input') {
@@ -198,14 +280,9 @@ function initializeVisualBinding () {
       } else node.addEventListener('change', () => send(true))
     }
     if (meterEntries.length) {
-      const locators = new Map()
-      for (const node of root.querySelectorAll('[data-cp-auto]')) {
-        const locator = node.getAttribute('data-cp-auto')
-        locators.set(locator, locators.has(locator) ? null : node)
-      }
       meterTargets.clear()
       for (const [id, binding] of meterEntries) {
-        const node = locators.get(binding.locator)
+        const node = nodeForBinding(binding)
         if (node) meterTargets.set(id, { node, binding })
       }
       if (lastMeterFrame) applyMeterFrame(lastMeterFrame.frame, lastMeterFrame.ids)
@@ -224,7 +301,8 @@ function initializeVisualBinding () {
       if (!frame.valid[index]) continue
       const value = mappedValue(frame.values[index], binding.readMeta, numericRange(binding, node))
       if (binding.model) {
-        if (binding.model in component && !component.$options?.computed?.[binding.model]) component[binding.model] = value
+        if (binding.repeat) setRepeatModel(binding, value)
+        else if (binding.model in component && !component.$options?.computed?.[binding.model]) component[binding.model] = value
       } else node.value = value
     }
   }
@@ -271,7 +349,9 @@ function initializeVisualBinding () {
           console.error('ControlPanel binding command failed', error)
         }
       }
-      const unwatch = component.$watch(binding.model, value => {
+      const unwatch = component.$watch(
+        binding.repeat ? () => repeatModelValue(binding) : binding.model,
+        value => {
         if (feedbackModels.has(id)) {
           const feedbackValue = feedbackModels.get(id)
           feedbackModels.delete(id)
@@ -287,21 +367,25 @@ function initializeVisualBinding () {
           clearTimeout(finishTimer)
           finishTimer = setTimeout(() => send(value, true), 160)
         } else send(value, true)
-      })
+        })
       cleanup.push(() => { clearTimeout(finishTimer); unwatch() })
     }
   }
   function closeOverlay () { overlay?.remove(); overlay = null }
+  function sameBindingTarget (entry, candidate) {
+    return entry.locator === candidate.locator &&
+      (!candidate.repeat || String(entry.instanceKey) === String(candidate.instanceKey))
+  }
   function updateBindingMarkers () {
     for (const node of root.querySelectorAll('[data-cpv-bound="true"]')) {
       node.removeAttribute('data-cpv-bound')
       node.removeAttribute('data-cpv-binding-id')
     }
     if (!editing || !editSession) return
-    const bindings = new Map(draft.map(entry => [entry.locator, entry]))
     for (const node of root.querySelectorAll('[data-cp-auto]')) {
-      const entry = bindings.get(node.getAttribute('data-cp-auto'))
+      const entry = draft.find(item => bindingMatchesNode(node, item))
       if (!entry) continue
+      if (nodeForBinding(entry) !== node) continue
       node.setAttribute('data-cpv-bound', 'true')
       node.setAttribute('data-cpv-binding-id', entry.id)
     }
@@ -310,10 +394,10 @@ function initializeVisualBinding () {
     closeOverlay()
     overlay = element('div', null, 'cpv-menu')
     overlay.setAttribute('role', 'menu')
-    const existing = draft.find(entry => entry.locator === candidate.locator)
+    const existing = draft.find(entry => sameBindingTarget(entry, candidate))
     overlay.append(button(existing ? 'Edit binding' : 'Bind control', () => bindingDialog(candidate)))
     if (existing) overlay.append(button('Remove binding', () => {
-      draft = draft.filter(entry => entry.locator !== candidate.locator)
+      draft = draft.filter(entry => !sameBindingTarget(entry, candidate))
       updateBindingMarkers()
       closeOverlay()
       inform('Binding removed from draft')
@@ -457,14 +541,17 @@ function initializeVisualBinding () {
   }
   async function bindingDialog (candidate, options = {}) {
     const returnToBindings = options.returnToBindings === true
-    const existing = draft.find(entry => entry.locator === candidate.locator)
+    const existing = draft.find(entry => sameBindingTarget(entry, candidate))
     const dialog = showDialog(existing ? 'Edit binding' : 'Bind control')
     const form = element('form')
     const name = field(form, 'Name', element('input'))
-    name.value = existing?.label || candidate.label
+    name.value = existing?.label || (candidate.repeat ? `${candidate.label} [${candidate.instanceKey}]` : candidate.label)
     name.maxLength = 80
     const id = field(form, 'Control ID', element('input'))
-    id.value = existing?.id || 'control.' + candidate.locator.slice(-12)
+    const instanceSuffix = candidate.repeat
+      ? '.' + String(candidate.instanceKey).replace(/[^A-Za-z0-9._/-]/g, '-').slice(0, 48)
+      : ''
+    id.value = existing?.id || 'control.' + candidate.locator.slice(-12) + instanceSuffix
     const modeOptions = ['meter', 'text-display'].includes(candidate.adapter)
       ? ['read'] : ['both', 'write', 'read']
     const mode = field(form, 'Mode', choose('Mode', modeOptions.map(value => ({ value, text: value })), existing?.mode || modeOptions[0]))
@@ -532,7 +619,7 @@ function initializeVisualBinding () {
     const actions = element('div', null, 'cpv-actions')
     actions.append(button('Cancel', () => finishBindingEdit(returnToBindings)))
     if (existing) actions.append(button('Remove', () => {
-      draft = draft.filter(entry => entry.locator !== candidate.locator)
+      draft = draft.filter(entry => !sameBindingTarget(entry, candidate))
       finishBindingEdit(returnToBindings)
       inform('Binding removed from draft')
     }))
@@ -543,7 +630,7 @@ function initializeVisualBinding () {
     form.addEventListener('submit', event => {
       event.preventDefault()
       if (!/^[A-Za-z][A-Za-z0-9._/-]{0,127}$/.test(id.value) ||
-        draft.some(entry => entry.id === id.value && entry.locator !== candidate.locator)) {
+        draft.some(entry => entry.id === id.value && !sameBindingTarget(entry, candidate))) {
         message.textContent = 'Control ID must be unique and valid'; return
       }
       if (!name.value.trim() || !device.value || (mode.value !== 'read' && !write.value) ||
@@ -553,12 +640,13 @@ function initializeVisualBinding () {
       const entry = {
         id: id.value, locator: candidate.locator, adapter: candidate.adapter,
         ...(candidate.model ? { model: candidate.model } : {}),
+        ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: String(candidate.instanceKey) } : {}),
         label: name.value.trim(), mode: mode.value, device: device.value,
         writePath: mode.value === 'read' ? '' : write.value,
         readPath: mode.value === 'write' ? '' : read.value,
         onebased: numbering.value === 'true'
       }
-      draft = draft.filter(item => item.locator !== candidate.locator)
+      draft = draft.filter(item => !sameBindingTarget(item, candidate))
       draft.push(entry)
       updateBindingMarkers()
       finishBindingEdit(returnToBindings)
@@ -612,6 +700,8 @@ function initializeVisualBinding () {
       const position = (order.get(a.locator) ?? Number.MAX_SAFE_INTEGER) -
         (order.get(b.locator) ?? Number.MAX_SAFE_INTEGER)
       if (position) return position
+      const instancePosition = String(a.instanceKey || '').localeCompare(String(b.instanceKey || ''))
+      if (instancePosition) return instancePosition
       return String(a.id).localeCompare(String(b.id))
     })
   }
@@ -626,10 +716,11 @@ function initializeVisualBinding () {
         details.append(element('span', path, 'cpv-binding-path'))
         row.append(details)
         const actions = element('div', null, 'cpv-binding-actions')
-        const candidate = snapshot.candidates.find(item => item.locator === entry.locator && item.supported)
+        const baseCandidate = snapshot.candidates.find(item => item.locator === entry.locator && item.supported)
+        const candidate = baseCandidate?.repeat ? { ...baseCandidate, instanceKey: entry.instanceKey } : baseCandidate
         const edit = button('Edit', () => bindingDialog(candidate, { returnToBindings: true }))
-        edit.disabled = !candidate
-        if (!candidate) edit.title = 'This control is no longer available on the page'
+        edit.disabled = !candidate || !nodeForBinding(entry)
+        if (edit.disabled) edit.title = 'This control is no longer available on the page'
         actions.append(edit)
         actions.append(button('Remove', () => {
           draft = draft.filter(item => item.id !== entry.id)
@@ -650,9 +741,17 @@ function initializeVisualBinding () {
   function candidateFromEvent (event) {
     const node = event.target?.closest?.('[data-cp-auto]')
     if (!node || !root.contains(node) || !snapshot) return null
-    const candidate = snapshot.candidates.find(item => item.locator === node.getAttribute('data-cp-auto'))
-    if (!candidate?.component || !candidate.model) return candidate
-    const value = component[candidate.model]
+    const baseCandidate = snapshot.candidates.find(item => item.locator === node.getAttribute('data-cp-auto'))
+    if (!baseCandidate) return null
+    const instanceKey = baseCandidate.repeat ? repeatMarkerFor(node, baseCandidate.repeat) : undefined
+    const candidate = baseCandidate.repeat
+      ? { ...baseCandidate, ...(instanceKey == null ? {} : { instanceKey }) }
+      : baseCandidate
+    if (candidate.repeat && instanceKey == null) {
+      return { ...candidate, supported: false, reason: 'Repeated control instance key is unavailable' }
+    }
+    if (!candidate.component || !candidate.model) return candidate
+    const value = candidate.repeat ? repeatModelValue(candidate) : component[candidate.model]
     if (value == null) return candidate
     if (candidate.adapter === 'switch' && typeof value !== 'boolean') {
       return { ...candidate, supported: false, reason: 'This Vuetify switch needs a boolean v-model field' }

package/panel-meter.js

@@ -188,7 +188,8 @@ function createPanelMeter ({ panelId, room, bindings, hub, onSubscribe = () => {
         subscribers.set(socket.id, { socket, active: entry.active, disconnect })
         socket.on('disconnect', disconnect)
         socket.emit('control-panel:meter-ready', layout)
-        emitFrame(socket, hub.snapshot(panelId))
+        const initial = hub.snapshot(panelId)
+        emitFrame(socket, initial)
         onSubscribe()
       },
       'control-panel:meter-unsubscribe': (socket, id) => { if (id === panelId) remove(socket.id) }

package/panel-template-instrumentation.js

@@ -8,6 +8,14 @@ const COMPONENT_ADAPTERS = Object.freeze({
   'v-text-field': 'text-input', 'v-textarea': 'text-input',
   'v-progress-linear': 'meter', 'v-progress-circular': 'meter'
 })
+const SIMPLE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const SIMPLE_PROPERTY_PATH = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/
+const UNSAFE_PROPERTY_NAMES = new Set(['__proto__', 'prototype', 'constructor'])
+
+function safePropertyPath (value) {
+  return SIMPLE_PROPERTY_PATH.test(value) &&
+    value.split('.').every(part => !UNSAFE_PROPERTY_NAMES.has(part))
+}
 
 function attribute (node, name) {
   const prop = (node.props || []).find(item => item.type === 6 && item.name === name)
@@ -78,42 +86,99 @@ function staticNumericProp (node, name) {
   return { value: numeric, dynamic: !Number.isFinite(numeric) }
 }
 
-function displayModel (node) {
+function repeatModelInfo (expression, repeat) {
+  const model = String(expression || '').trim()
+  if (SIMPLE_IDENTIFIER.test(model)) return { valid: true, repeatModel: null }
+  if (!repeat?.valid) return { valid: false, repeatModel: null }
+  const indexedPrefix = repeat.index ? `${repeat.source}[${repeat.index}].` : ''
+  if (indexedPrefix && model.startsWith(indexedPrefix)) {
+    const field = model.slice(indexedPrefix.length)
+    if (safePropertyPath(field)) {
+      return { valid: true, repeatModel: { kind: 'source-index-property', field } }
+    }
+  }
+  if (repeat.kind === 'item') {
+    const escaped = repeat.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const match = model.match(new RegExp('^' + escaped + '\\.' +
+      '(' + SIMPLE_PROPERTY_PATH.source.slice(1, -1) + ')$'))
+    return match && safePropertyPath(match[1])
+      ? { valid: true, repeatModel: { kind: 'item-property', field: match[1] } }
+      : { valid: false, repeatModel: null }
+  }
+  return model === `${repeat.source}[${repeat.index}]`
+    ? { valid: true, repeatModel: { kind: 'array-index' } }
+    : { valid: false, repeatModel: null }
+}
+
+function displayModel (node, repeat) {
   const dynamic = (node.children || []).filter(child => child.type === 5)
   if (!dynamic.length) return { model: '', valid: true }
   const expression = dynamic.length === 1 ? dynamic[0].content?.content?.trim() : ''
-  return { model: expression, valid: /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(expression) }
+  return { model: expression, ...repeatModelInfo(expression, repeat) }
 }
 
-function inputModel (node, allowNumber = false) {
+function inputModel (node, allowNumber = false, repeat) {
   const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'model')
   if (!directive) return { model: '', valid: true }
   const model = directive.exp?.content?.trim() || ''
   const modifiers = (directive.modifiers || []).map(item => typeof item === 'string' ? item : item.content)
-  return { model, valid: !directive.arg && modifiers.every(item => allowNumber && item === 'number') &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !directive.arg && modifiers.every(item => allowNumber && item === 'number') && info.valid }
 }
 
-function progressModel (node) {
+function progressModel (node, repeat) {
   const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     ['model-value', 'modelValue'].includes(prop.arg?.content))
-  if (!bound) return inputModel(node)
+  if (!bound) return inputModel(node, false, repeat)
   const model = bound.exp?.content?.trim() || ''
-  return { model, valid: !hasDirective(node, ['model']) && !bound.modifiers?.length &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !hasDirective(node, ['model']) && !bound.modifiers?.length && info.valid }
 }
 
-function nativeMeterModel (node) {
+function nativeMeterModel (node, repeat) {
   const modelDirective = (node.props || []).find(prop => prop.type === 7 && prop.name === 'model')
   if (modelDirective) {
-    return { model: modelDirective.exp?.content?.trim() || '', valid: !modelDirective.arg && !modelDirective.modifiers?.length &&
-      /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(modelDirective.exp?.content?.trim() || '') }
+    const model = modelDirective.exp?.content?.trim() || ''
+    const info = repeatModelInfo(model, repeat)
+    return { model, repeatModel: info.repeatModel,
+      valid: !modelDirective.arg && !modelDirective.modifiers?.length && info.valid }
   }
   const bound = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     prop.arg?.content === 'value')
   if (!bound) return { model: '', valid: true }
   const model = bound.exp?.content?.trim() || ''
-  return { model, valid: !bound.modifiers?.length && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+  const info = repeatModelInfo(model, repeat)
+  return { model, repeatModel: info.repeatModel,
+    valid: !bound.modifiers?.length && info.valid }
+}
+
+function repeatDescriptor (node) {
+  const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'for')
+  if (!directive) return null
+  const parsed = directive.forParseResult
+  const source = parsed?.source?.content?.trim() || ''
+  const value = parsed?.value?.content?.trim() || ''
+  const index = parsed?.key?.content?.trim() || ''
+  const keyProp = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
+    prop.arg?.content === 'key' && !prop.modifiers?.length)
+  const key = keyProp?.exp?.content?.trim() || ''
+  const locator = `repeat:${hash(`${node.tag}:${node.loc.start.offset}:${directive.exp?.content || ''}`)}`
+  let kind = ''
+  let reason = ''
+  if (!SIMPLE_IDENTIFIER.test(source)) reason = 'v-for source must be one top-level array field'
+  else if (!SIMPLE_IDENTIFIER.test(value)) reason = 'v-for item alias must be a simple identifier'
+  else if (index && !SIMPLE_IDENTIFIER.test(index)) reason = 'v-for index alias must be a simple identifier'
+  else if (!key) reason = 'Repeated controls need a stable :key'
+  else if (key === `${value}.id`) kind = 'item'
+  else if (index && key === index) kind = 'array'
+  else reason = index
+    ? 'Object lists need :key="item.id" or array lists need :key="index"'
+    : 'Item v-for bindings require :key="item.id"'
+  return { locator, source, value, ...(index ? { index } : {}), key, kind,
+    markerOnControl: node.tag.toLowerCase() === 'template',
+    valid: !reason, ...(reason ? { reason } : {}) }
 }
 
 function normalizeMeterVModels (format) {
@@ -146,13 +211,14 @@ function normalizeMeterVModels (format) {
   return normalized
 }
 
-function pressedModel (node) {
+function pressedModel (node, repeat) {
   const directive = (node.props || []).find(prop => prop.type === 7 && prop.name === 'bind' &&
     ['aria-pressed', 'aria-checked'].includes(prop.arg?.content))
   if (!directive) return { model: '', valid: true }
   const model = directive.exp?.content?.trim() || ''
+  const info = repeatModelInfo(model, repeat)
   return { model, valid: !directive.modifiers?.length &&
-    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(model) }
+    info.valid, repeatModel: info.repeatModel }
 }
 
 function openingTagEnd (source, start) {
@@ -188,13 +254,22 @@ function inspectTemplate (format) {
   }
   const candidates = []
   const counts = new Map()
+  const repeatMarkers = []
 
-  function visit (node, repeated = false) {
+  function visit (node, repeatContext = null) {
     if (node.type === 1) {
       if (node.tag.toLowerCase().startsWith('v-') && node.isSelfClosing) {
         throw new Error(`Vuetify component <${node.tag}> needs an explicit closing tag in Dashboard templates`)
       }
-      const insideRepeat = repeated || hasDirective(node, ['for'])
+      const ownRepeat = repeatDescriptor(node)
+      const activeRepeat = ownRepeat
+        ? repeatContext ? { ...ownRepeat, valid: false, reason: 'Nested v-for bindings are not supported' } : ownRepeat
+        : repeatContext
+      const insideRepeat = Boolean(activeRepeat)
+      if (ownRepeat?.valid && !repeatContext && !ownRepeat.markerOnControl) {
+        repeatMarkers.push({ offset: openingTagEnd(format, node.loc.start.offset),
+          locator: ownRepeat.locator, key: ownRepeat.key })
+      }
       const adapter = candidateAdapter(node)
       const customAttribute = (node.props || []).some(prop =>
         (prop.type === 6 && prop.name.startsWith('data-cp-')) ||
@@ -203,12 +278,12 @@ function inspectTemplate (format) {
       if (adapter) {
         const component = COMPONENT_ADAPTERS[node.tag.toLowerCase()] ? node.tag.toLowerCase() : ''
         const display = adapter === 'text-display'
-          ? displayModel(node)
-          : ['v-progress-linear', 'v-progress-circular'].includes(component) ? progressModel(node)
-          : adapter === 'meter' && !component ? nativeMeterModel(node)
+          ? displayModel(node, activeRepeat)
+          : ['v-progress-linear', 'v-progress-circular'].includes(component) ? progressModel(node, activeRepeat)
+          : adapter === 'meter' && !component ? nativeMeterModel(node, activeRepeat)
           : adapter === 'switch' && node.tag.toLowerCase() === 'button'
-            ? pressedModel(node)
-            : inputModel(node, adapter === 'range' || adapter === 'select')
+            ? pressedModel(node, activeRepeat)
+            : inputModel(node, adapter === 'range' || adapter === 'select', activeRepeat)
         const source = format.slice(node.loc.start.offset, openingTagEnd(format, node.loc.start.offset) + 1)
         const stableName = attribute(node, 'id') || attribute(node, 'name')
         const locator = stableName
@@ -252,6 +327,7 @@ function inspectTemplate (format) {
         const candidate = {
           locator, adapter,
           ...(component ? { component } : {}),
+          ...(activeRepeat ? { repeat: activeRepeat } : {}),
           label: attribute(node, 'aria-label') || attribute(node, 'label') || attribute(node, 'title') ||
             stableName || display.model || (adapter === 'text-display' ? node.children[0]?.content?.trim() : '') || node.tag,
           ...(display.model ? { model: display.model } : {}),
@@ -267,12 +343,12 @@ function inspectTemplate (format) {
           } : {}),
           ...(attribute(node, 'data-unit') ? { unit: attribute(node, 'data-unit') } : {}),
           line: node.loc.start.line,
-          supported: !insideRepeat && !explicitLogic && display.valid && !dynamicBounds &&
+          supported: (!insideRepeat || Boolean(activeRepeat.valid && display.valid)) && !explicitLogic && display.valid && !dynamicBounds &&
             !invalidSliderBounds &&
             !customSwitchValues && !unsupportedSelect && !unsupportedRadio &&
             !unsupportedTextType && !unsupportedProgress && !unsupportedCircular &&
             (!component || Boolean(display.model)),
-          reason: insideRepeat ? 'Repeated controls need a stable item identity' :
+          reason: insideRepeat && !activeRepeat.valid ? activeRepeat.reason :
             explicitLogic ? 'Controls with existing handlers or reactive value bindings need a dedicated adapter' :
               !display.valid ? (adapter === 'text-display' ? 'Dynamic text needs one writable data field' :
                 'Only a simple Vue v-model field is supported') :
@@ -289,11 +365,11 @@ function inspectTemplate (format) {
         candidates.push({ ...candidate, offset: openingTagEnd(format, node.loc.start.offset) })
         counts.set(locator, (counts.get(locator) || 0) + 1)
       }
-      for (const child of node.children || []) visit(child, insideRepeat)
+      for (const child of node.children || []) visit(child, activeRepeat)
       return
     }
-    for (const child of node.children || []) visit(child, repeated)
-    for (const branch of node.branches || []) visit(branch, repeated)
+    for (const child of node.children || []) visit(child, repeatContext)
+    for (const branch of node.branches || []) visit(branch, repeatContext)
   }
 
   if (descriptor.template?.ast) visit(descriptor.template.ast)
@@ -303,17 +379,33 @@ function inspectTemplate (format) {
       candidate.reason = 'This element is ambiguous; give it a unique HTML id or name'
     }
   }
-  return { candidates, templateHash: hash(format) }
+  return { candidates, repeatMarkers, templateHash: hash(format) }
 }
 
 function instrumentTemplate (format) {
   const inspected = inspectTemplate(format)
   let rendered = format
-  for (const candidate of [...inspected.candidates].reverse()) {
-    const before = rendered.slice(0, candidate.offset)
+  const insertions = new Map()
+  const addInsertion = (offset, value) => {
+    const list = insertions.get(offset) || []
+    list.push(value)
+    insertions.set(offset, list)
+  }
+  for (const candidate of inspected.candidates) {
+    addInsertion(candidate.offset, `data-cp-auto="${candidate.locator}"`)
+    if (candidate.repeat?.markerOnControl) {
+      addInsertion(candidate.offset,
+        `data-cp-repeat="${candidate.repeat.locator}" :data-cp-repeat-key="String(${candidate.repeat.key})"`)
+    }
+  }
+  for (const marker of inspected.repeatMarkers) {
+    addInsertion(marker.offset, `data-cp-repeat="${marker.locator}" :data-cp-repeat-key="String(${marker.key})"`)
+  }
+  for (const [offset, attributes] of [...insertions.entries()].sort((a, b) => b[0] - a[0])) {
+    const before = rendered.slice(0, offset)
     const selfClosing = /\/\s*$/.test(before)
-    const insertAt = selfClosing ? before.lastIndexOf('/') : candidate.offset
-    rendered = rendered.slice(0, insertAt) + ` data-cp-auto="${candidate.locator}"` + rendered.slice(insertAt)
+    const insertAt = selfClosing ? before.lastIndexOf('/') : offset
+    rendered = rendered.slice(0, insertAt) + ' ' + attributes.join(' ') + rendered.slice(insertAt)
   }
   return {
     format: normalizeMeterVModels(rendered),

package/panel-visual-bindings.js

@@ -3,8 +3,20 @@ const { compatibleTarget, controlTypeForAdapter, targetMeta } = require('./contr
 const { meterRoute } = require('./meter-route')
 
 const ID = /^[A-Za-z][A-Za-z0-9._/-]{0,127}$/
+const INSTANCE_KEY = /^[A-Za-z0-9._:/-]{1,160}$/
 const MODES = new Set(['read', 'write', 'both'])
 
+function targetKey (candidate, entry) {
+  if (!candidate.repeat) return candidate.locator
+  if (typeof entry.instanceKey !== 'string' || !INSTANCE_KEY.test(entry.instanceKey)) {
+    throw new Error('Repeated visual controls need a stable instance key')
+  }
+  if (candidate.repeat.kind === 'array' && !/^(0|[1-9][0-9]*)$/.test(entry.instanceKey)) {
+    throw new Error('Array repeated controls need a non-negative integer instance key')
+  }
+  return `${candidate.locator}#${entry.instanceKey}`
+}
+
 function parseVisualBindings (config) {
   let raw = config.visualBindings || '{}'
   if (typeof raw === 'string') raw = JSON.parse(raw)
@@ -26,8 +38,9 @@ function visualRoutes (config) {
     if (!candidate || candidate.adapter !== entry.adapter) {
       throw new Error(`Visual control moved or became ambiguous: ${id}`)
     }
-    if (usedLocators.has(entry.locator)) throw new Error(`Duplicate visual control locator: ${id}`)
-    usedLocators.add(entry.locator)
+    const bindingKey = targetKey(candidate, entry)
+    if (usedLocators.has(bindingKey)) throw new Error(`Duplicate visual control locator: ${id}`)
+    usedLocators.add(bindingKey)
     if (!MODES.has(entry.mode) || !entry.type || !entry.label ||
       (['meter', 'text-display'].includes(entry.adapter) && entry.mode !== 'read')) {
       throw new Error(`Invalid visual binding settings: ${id}`)
@@ -41,7 +54,8 @@ function visualRoutes (config) {
     }
     routes.set(id, {
       control: { id, type: entry.type, mode: entry.mode, label: entry.label,
-        adapter: entry.adapter, locator: entry.locator },
+        adapter: entry.adapter, locator: entry.locator,
+        ...(candidate.repeat ? { instanceKey: entry.instanceKey } : {}) },
       binding: entry
     })
   }
@@ -62,8 +76,9 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     used.add(raw.id)
     const candidate = candidates.get(raw.locator)
     if (!candidate || candidate.adapter !== raw.adapter) throw new Error(`Control changed: ${raw.id}`)
-    if (usedLocators.has(raw.locator)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
-    usedLocators.add(raw.locator)
+    const bindingKey = targetKey(candidate, raw)
+    if (usedLocators.has(bindingKey)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
+    usedLocators.add(bindingKey)
     if (!MODES.has(raw.mode) || (['meter', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
       throw new Error(`Invalid binding mode: ${raw.id}`)
     }
@@ -91,15 +106,17 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     }
     if (candidate.model) {
       const identity = JSON.stringify([raw.device, read?.path, write?.path])
-      const previous = models.get(candidate.model)
+      const modelKey = candidate.repeat ? `${candidate.model}#${raw.instanceKey}` : candidate.model
+      const previous = models.get(modelKey)
       if (previous && (read?.meter || previous.meter) && previous.identity !== identity) {
         throw Error(`Meter model "${candidate.model}" is already used by another binding; use a separate Vue model for the meter. Meter and volume controls must not share a model`)
       }
-      models.set(candidate.model, { identity, meter: Boolean(read?.meter) })
+      models.set(modelKey, { identity, meter: Boolean(read?.meter) })
     }
     result[raw.id] = {
       locator: raw.locator, adapter: raw.adapter, type, label: raw.label.trim(), mode: raw.mode,
       ...(candidate.model ? { model: candidate.model } : {}),
+      ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: raw.instanceKey } : {}),
       ...(candidate.component ? { component: candidate.component } : {}),
       ...(['range', 'meter'].includes(raw.adapter)
         ? { uiRange: { min: candidate.min, max: candidate.max, step: candidate.step } } : {}),