node-red-contrib-room-tools 1.8.2 → 1.8.3-visual-binding.17

package/control-catalog.js

@@ -0,0 +1,97 @@
+const { schemaVersion } = require('./control-type-contract.json')
+
+function catalogBase () {
+  const localAutomator = process.platform === 'darwin' &&
+    process.execPath.includes('/MUSE Automator.app/Contents/MacOS/MUSE Automator')
+  const raw = process.env.CONTROL_PANEL_POC_CATALOG_BASE_URL ||
+    (localAutomator ? 'http://127.0.0.1:48080/red/' : '')
+  if (!raw) return null
+  const url = new URL(raw)
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname) || url.username || url.password) {
+    throw new Error('PoC catalog URL must be an unauthenticated localhost HTTP URL')
+  }
+  return url.href.endsWith('/') ? url.href : `${url.href}/`
+}
+
+async function catalogRequest (base, path, device, fetcher = fetch) {
+  const options = { signal: AbortSignal.timeout(5000) }
+  if (device !== undefined) {
+    options.method = 'POST'
+    options.headers = { 'content-type': 'application/json' }
+    options.body = JSON.stringify([device])
+  }
+  const response = await fetcher(new URL(path, base), options)
+  if (!response.ok) throw new Error(`Automator catalog HTTP ${response.status}`)
+  const data = await response.json()
+  if (data.code !== 0 || !Array.isArray(data.value)) throw new Error(data.reason || 'Invalid Automator catalog response')
+  return data.value
+}
+
+async function listCatalogDevices (base, fetcher = fetch) {
+  const values = await catalogRequest(base, 'amx-com/devices', undefined, fetcher)
+  return values.filter(item => typeof item.instanceId === 'string').map(item => ({
+    id: item.instanceId,
+    driver: item.driver?.driver || '',
+    online: item.online === true
+  }))
+}
+
+function catalogBound (value) {
+  return typeof value === 'number' && Number.isFinite(value) &&
+    Math.abs(value) < Number.MAX_SAFE_INTEGER ? value : undefined
+}
+
+function inferredControl (path, properties, type, min, max, enums) {
+  if (properties['.kind'] !== 'param' || path.startsWith('//module/')) return { controlType: '' }
+  if (type === 'boolean') return { controlType: 'toggle' }
+  if (type === 'integer' && min === 0 && max === 1 && !enums?.length) {
+    return { controlType: 'toggle', booleanEncoding: 'integer01' }
+  }
+  if (type === 'enum' || (enums?.length && ['integer', 'string'].includes(type))) {
+    return { controlType: 'source' }
+  }
+  if (type === 'integer' && /\/(preset|source)$/.test(path.toLowerCase())) {
+    return { controlType: 'source' }
+  }
+  if (['integer', 'float'].includes(type)) return { controlType: 'slider' }
+  if (['string', 'dstring'].includes(type)) return { controlType: 'text' }
+  return { controlType: '' }
+}
+
+async function listCatalogTargets (base, device, fetcher = fetch) {
+  if (typeof device !== 'string' || !device || device.length > 128) throw new Error('Invalid device name')
+  const [parameters, commands] = await Promise.all([
+    catalogRequest(base, 'amx-com/device/status', device, fetcher),
+    catalogRequest(base, 'amx-com/device/commands', device, fetcher)
+  ])
+  const targets = [...parameters, ...commands].filter(item => typeof item.path === 'string').map(item => {
+    const properties = item.properties || {}
+    const type = properties['.type'] || item.schema?.type || ''
+    const min = catalogBound(properties['.min'])
+    const max = catalogBound(properties['.max'])
+    const enums = properties['.enums']
+    return {
+      path: item.path,
+      kind: properties['.kind'] || '',
+      type,
+      access: properties['.access'],
+      onebased: typeof properties['.onebased'] === 'boolean' ? properties['.onebased']
+        : typeof item.onebased === 'boolean' ? item.onebased : undefined,
+      min, max, enums,
+      ...inferredControl(item.path, properties, type, min, max, enums),
+      controlSchemaVersion: schemaVersion,
+      unit: properties['.metadata']?.unit || ''
+    }
+  })
+  const unique = new Map()
+  for (const target of targets) {
+    const previous = unique.get(target.path)
+    if (previous && JSON.stringify(previous) !== JSON.stringify(target)) {
+      throw new Error(`Conflicting catalog descriptors for ${target.path}`)
+    }
+    unique.set(target.path, target)
+  }
+  return [...unique.values()]
+}
+
+module.exports = { catalogBase, listCatalogDevices, listCatalogTargets }

package/control-panel.html

@@ -9,79 +9,12 @@
             return Object.prototype.hasOwnProperty.call(obj, prop)
         }
 
-        const template = []
-
-        template.push('<!--')
-        template.push('AI / DEVELOPER CONTRACT - ui-control-panel 1.8.2')
-        template.push('AI START HERE: 先完整阅读 CONTROL_PANEL_AI_GUIDE.md、当前 ControlPanel Template 和 control-policy.js，再开发或修改页面。严格使用注入的 sendControl() 和设备反馈 API，禁止在 Template 中重写发送队列、限速、debounce、latest-wins、主动状态查询或反馈连接。所有非滑杆控件必须显示设备反馈确认的实际状态；滑杆必须直接发送并保持最后目标，不能被旧中间反馈拉回；设备反馈不能触发命令回发。完成后按照指南第 6 节逐项检查。')
-        template.push('1. Use the injected sendControl({ type, topic, key, value, final }) API for device commands.')
-        template.push('2. Never add debounce, throttle, latest-wins maps, Promise queues, or raw device TCP code here.')
-        template.push('3. Continuous types: level, dimmer, position. Send final:true on release/change.')
-        template.push('4. Discrete types: power, source, preset, mute. Send once per deliberate user action.')
-        template.push('5. key must be stable and unique per device control, for example rane/1/level/2.')
-        template.push('6. After room-gateway login call setControlSession(session); on logout call clearControlSession().')
-        template.push('7. Bind discrete control visuals to deviceState/deviceValue(), not to an optimistic local value.')
-        template.push('8. Use isControlPending(key) only for a waiting indicator; discrete pending clears on authoritative topic feedback, while continuous pending waits for its target value.')
-        template.push('9. Sliders directly send and hold the latest target; use controlDisplayValue() so stale feedback cannot pull them back.')
-        template.push('10. Feedback may update UI state, but must never trigger a watcher that sends the value back.')
-        template.push('11. Do not redefine any injected ControlPanel API or its feedback state fields.')
-        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>')
-        template.push('        <h2>Counter</h2>')
-        template.push('        <!-- Conditional Styling using Attribute Binding (":") -->')
-        template.push('        <!-- and rendering content inside <tags></tags> with {{ }} -->')
-        template.push('        <p :style="{\'color\' : (count > 5 ? \'red\' : \'green\' )}">Current Count: {{ count }}</p>')
-        template.push('        <!-- Computed Rendering using Vue Computed Variables -->')
-        template.push('        <p class="my-class">Formatted Count: {{ formattedCount }}</p>')
-        template.push('        <!-- Conditional Rendering with "v-if" -->')
-        template.push('        <b v-if="count > 5">Too many!</b>')
-        template.push('        <v-btn @click="increase()">Increment</v-btn>')
-        template.push('    </div>')
-        template.push('</template>')
-        template.push('')
-        template.push('<script>')
-        template.push('    export default {')
-        template.push('        data() {')
-        template.push('            // define variables available component-wide')
-        template.push('            // (in <template> and component functions)')
-        template.push('            return {')
-        template.push('                count: 0')
-        template.push('            }')
-        template.push('        },')
-        template.push('        computed: {')
-        template.push('            // automatically compute this variable')
-        template.push('            // whenever VueJS deems appropriate')
-        template.push('            formattedCount: function () {')
-        template.push('                return this.count + \' Apples\'')
-        template.push('            }')
-        template.push('        },')
-        template.push('        methods: {')
-        template.push('            // UI-only method. Device commands must use this.sendControl({...}).')
-        template.push('            increase: function () {')
-        template.push('                this.count++')
-        template.push('            }')
-        template.push('        },')
-        template.push('        mounted() {')
-        template.push('            // After a successful login: this.setControlSession(session)')
-        template.push('        },')
-        template.push('        unmounted() {')
-        template.push('            // The injected policy cleans its queues and timers automatically.')
-        template.push('            // Clean only timers/listeners created by this Template.')
-        template.push('        }')
-        template.push('    }')
-        // eslint complaingin about unterminated string literal - need to do this oddity to get around it
-        template.push('</' + 'script>')
-        template.push('<style>')
-        template.push('    /* define any styles here - supports raw CSS */')
-        template.push('    .my-class {')
-        template.push('        color: red;')
-        template.push('    }')
-        template.push('</style>')
-
-        const defaultTemplate = template.join('\n')
+        const defaultTemplate = [
+            '<!-- Read CONTROL_PANEL_AI_GUIDE.md before adding device controls. -->',
+            '<template>',
+            '    <div></div>',
+            '</template>'
+        ].join('\n')
 
         RED.nodes.registerType('ui-control-panel', {
             category: RED._('@flowfuse/node-red-dashboard/ui-base:ui-base.label.category'),
@@ -158,14 +91,25 @@
                 height: { value: 0 },
                 head: { value: '' },
                 format: { value: defaultTemplate },
+                visualBindings: { value: '{}' },
+                boundRoom: { value: '' },
+                nativeBridge: { value: false },
+                bridgeRevisionApplied: { value: '' },
+                secureCookie: { value: false },
                 storeOutMessages: { value: true },
                 passthru: { value: true },
                 resendOnRefresh: { value: true },
                 templateScope: { value: 'local' },
                 className: { value: '' }
             },
-            inputs: 0,
-            outputs: 0,
+            credentials: {
+                username: { type: 'text' },
+                password: { type: 'password' },
+                editorUsername: { type: 'text' },
+                editorPassword: { type: 'password' }
+            },
+            inputs: 1,
+            outputs: 1,
             icon: 'font-awesome/fa-code',
             paletteLabel: 'ControlPanel',
             label: function () {
@@ -284,6 +228,20 @@
                     value: $('#node-input-format').val()
                 })
 
+                $('#control-binding-auth').show()
+                $('#control-visual-open').on('click', function () {
+                    const group = RED.nodes.node($('#node-input-group').val() || that.group)
+                    const page = RED.nodes.node($('#node-input-page').val() || that.page || group?.page)
+                    const base = RED.nodes.node(page?.ui)
+                    if (!page?.path) {
+                        RED.notify('Choose a Dashboard page, then save and deploy this node.', { type: 'warning' })
+                        return
+                    }
+                    const url = new URL((base?.path || '/dashboard').replace(/\/$/, '') + '/' +
+                        page.path.replace(/^\//, ''), window.location.origin)
+                    url.searchParams.set('cp-edit', that.id)
+                    window.open(url.href, '_blank', 'noopener')
+                })
                 RED.library.create({
                     url: 'uitemplates', // where to get the data from
                     type: 'ui-template', // the type of object the library is for
@@ -379,20 +337,20 @@
     })()
 </script>
 
+<style>
+    .control-binding-hint { margin: 4px 0; color: var(--red-ui-secondary-text-color, #666); overflow-wrap: anywhere; }
+    .control-binding-bridge-option { display: flex; align-items: flex-start; gap: 8px; }
+    .control-binding-bridge-option > label { flex: 0 0 105px; }
+    .control-binding-bridge-option > div { flex: 1; min-width: 0; }
+    .control-binding-bridge-option small { display: block; margin-top: 3px; }
+</style>
+
 <script type="text/html" data-help-name="ui-control-panel">
     <p>This node renders a custom Vue Template and automatically injects control traffic and reported-device-state APIs.</p>
-    <p><strong>AI START HERE:</strong> 先完整阅读 <code>CONTROL_PANEL_AI_GUIDE.md</code>、当前 ControlPanel Template 和 <code>control-policy.js</code>，再开发或修改页面。严格使用注入的 <code>sendControl()</code> 和设备反馈 API，禁止在 Template 中重写发送队列、限速、debounce、latest-wins、主动状态查询或反馈连接。所有非滑杆控件必须显示设备反馈确认的实际状态；滑杆必须直接发送并保持最后目标，不能被旧中间反馈拉回；设备反馈不能触发命令回发。完成后按照指南第 6 节逐项检查。</p>
-    <p>Use <code>sendControl({ type, topic, key, value, final })</code> for device commands. Do not implement throttling, latest-wins maps, queues, or device protocol code in the Template.</p>
-    <ul>
-        <li><code>power</code>, <code>source</code>, <code>preset</code>, <code>mute</code>: ordered discrete commands.</li>
-        <li><code>level</code>, <code>dimmer</code>, <code>position</code>: 40 ms latest-wins per stable key.</li>
-        <li>Send the same continuous target with <code>final: true</code> on release/change.</li>
-        <li>Bind non-slider active/selected values to <code>deviceState</code> or <code>deviceValue()</code>; commands do not change reported state.</li>
-        <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. 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>普通 HTML/Vue 控件由页面绑定编辑器自动识别，并通过面板的 authenticated session 发送控制。开发者不需要添加标签、调用自定义节点 API，或在 Template 中实现 throttling、latest-wins、队列和设备协议。</p>
+    <p>页面只需按普通 H5/Vue 方式编写控件；编辑模式下在控件上打开绑定菜单，选择设备参数即可。登录、发送、反馈和状态同步由节点负责，Template 不应主动查询设备或把反馈回发成命令。</p>
     <p>See <code>CONTROL_PANEL_AI_GUIDE.md</code> in the node package for the complete AI authoring contract and examples.</p>
+    <p>Save and Deploy the panel, then use Open page binding editor. Apply in that page validates and saves bindings, backs up the Flow, regenerates the native bridge, and deploys it. Ordinary Deploy alone does not apply bindings. Check targets and numbering before using real hardware.</p>
 </script>
 
 <script type="text/html" data-template-name="ui-control-panel">
@@ -469,6 +427,44 @@
     <div class="form-row node-text-editor-row" style="display: block;">
         <div style="height:250px; min-height:100px" class="node-text-editor" id="node-input-format-editor" ></div>
     </div>
+    <div class="form-row">
+        <label>Page binding</label>
+        <input type="hidden" id="node-input-visualBindings">
+        <button type="button" id="control-visual-open" class="red-ui-button">Open page binding editor</button>
+        <span class="control-binding-hint">Use ordinary HTML/Vue controls. Binding is configured from the page.</span>
+    </div>
+    <div class="form-row" style="display:none">
+        <input type="hidden" id="node-input-bridgeRevisionApplied">
+    </div>
+    <div id="control-binding-auth">
+    <div class="form-row">
+        <label for="node-input-boundRoom">Room ID</label>
+        <input type="text" id="node-input-boundRoom" placeholder="room-01">
+    </div>
+    <div class="form-row">
+        <label for="node-input-username">Login user</label>
+        <input type="text" id="node-input-username" autocomplete="off">
+    </div>
+    <div class="form-row">
+        <label for="node-input-password">Password</label>
+        <input type="password" id="node-input-password" autocomplete="new-password">
+    </div>
+    <div id="control-visual-credentials">
+        <div class="form-row">
+            <label for="node-input-editorUsername">Editor user</label>
+            <input type="text" id="node-input-editorUsername" autocomplete="off">
+        </div>
+        <div class="form-row">
+            <label for="node-input-editorPassword">Editor password</label>
+            <input type="password" id="node-input-editorPassword" autocomplete="new-password">
+        </div>
+    </div>
+    <div class="form-row">
+        <label for="node-input-secureCookie">HTTPS cookie</label>
+        <input type="checkbox" id="node-input-secureCookie" style="width:auto">
+    </div>
+    <input type="hidden" id="node-input-nativeBridge">
+    </div>
     <div id="template-pass-store">
         <div class="form-row" style="margin-bottom:0px;">
             <input type="checkbox" id="node-input-passthru" style="display:inline-block; margin-left:8px; width:auto; vertical-align:top;">

package/control-panel.js

@@ -1,10 +1,55 @@
+const crypto = require('node:crypto')
+const path = require('node:path')
 const { injectControlPolicy } = require('./control-policy')
+const { configuredRoutes, resolveBoundCommand, resolveBoundFeedback } = require('./control-bound-protocol')
+const { catalogBase, listCatalogDevices, listCatalogTargets } = require('./control-catalog')
+const { contract } = require('./control-type-model')
+const { parseVisualBindings } = require('./panel-visual-bindings')
+const { instrumentTemplate } = require('./panel-template-instrumentation')
+const { createPanelEditor } = require('./panel-editor-auth')
+const { applyVisualBindings, editorConfig, getSnapshot } = require('./panel-visual-apply')
+const { createGateway } = require('./gateway.cjs')
+const { managedBridgeRevision } = require('./managed-bridge-revision')
 
 let statestore
+const authHandoffKey = crypto.randomBytes(32)
+const gatewayHandoffs = new Map()
+const editorHandoffs = new Map()
+const panelLoginImage = path.join(__dirname, 'assets', 'panel-login-bg.png')
 
-function injectWidgetPolicy (format, templateScope) {
+function authSignature (values) {
+  return crypto.createHmac('sha256', authHandoffKey).update(JSON.stringify(values)).digest('hex')
+}
+
+function holdSessions (handoffs, id, signature, sessions) {
+  const previous = handoffs.get(id)
+  if (previous) clearTimeout(previous.timer)
+  handoffs.delete(id)
+  if (!sessions?.size) return
+  const item = { signature, sessions }
+  item.timer = setTimeout(() => { if (handoffs.get(id) === item) handoffs.delete(id) }, 60000)
+  item.timer.unref?.()
+  handoffs.set(id, item)
+}
+
+function takeSessions (handoffs, id, signature) {
+  const item = handoffs.get(id)
+  if (!item) return null
+  clearTimeout(item.timer)
+  handoffs.delete(id)
+  return item.signature === signature ? item.sessions : null
+}
+
+function injectWidgetPolicy (format, templateScope, boundPanel) {
   if (templateScope === 'site:style' || templateScope === 'page:style') return format
-  return injectControlPolicy(format)
+  const rendered = instrumentTemplate(format).format
+  const controls = Object.entries(boundPanel?.visual?.bindings || {})
+    .map(([id, entry]) => ({ id, type: entry.type, mode: entry.mode }))
+  const injected = injectControlPolicy(rendered, controls, boundPanel)
+  if (!injected.includes('/* ui-control-panel-control-api-v1 */')) {
+    throw new Error('Visual binding requires a supported Vue Options API template')
+  }
+  return injected
 }
 
 function getStateStore (RED) {
@@ -21,25 +66,186 @@ function getStateStore (RED) {
 }
 
 module.exports = function (RED) {
+  const base = catalogBase()
+  const activePanels = new Map()
+  const activeEditors = new Map()
+  RED.httpNode.use((req, res, next) => {
+    const path = new URL(req.url, 'http://localhost').pathname
+    if (path === '/control-panel-assets/panel-login-bg.png') {
+      res.setHeader('Cache-Control', 'public, max-age=86400')
+      return res.sendFile(panelLoginImage)
+    }
+    const editorMatch = path.match(/^\/control-panel-edit\/panels\/([a-zA-Z0-9._-]+)\//)
+    if (editorMatch) {
+      const editor = activeEditors.get(editorMatch[1])
+      if (!editor) return res.status(404).json({ error: 'Visual editor unavailable' })
+      return editor.handler(req, res).then(handled => {
+        if (!handled) res.status(404).json({ error: 'Not found' })
+      }).catch(next)
+    }
+    const match = path
+      .match(/^\/control-panel-api\/panels\/([a-zA-Z0-9._-]+)\//)
+    if (!match) return next()
+    const gateway = activePanels.get(match[1])
+    if (!gateway) return res.status(404).json({ error: 'Panel unavailable' })
+    gateway.handler(req, res).then(handled => {
+      if (!handled) res.status(404).json({ error: 'Not found' })
+    }).catch(next)
+  })
+  RED.httpAdmin.get('/ui-control-panel/catalog/devices', RED.auth.needsPermission('nodes.read'), async (_req, res) => {
+    if (!base) return res.json({ enabled: false, devices: [] })
+    try {
+      res.json({ enabled: true, devices: await listCatalogDevices(base) })
+    } catch (error) {
+      res.status(502).json({ error: error.message })
+    }
+  })
+  RED.httpAdmin.post('/ui-control-panel/catalog/targets', RED.auth.needsPermission('nodes.read'), async (req, res) => {
+    if (!base) return res.status(404).json({ error: 'Local PoC catalog is disabled' })
+    try {
+      res.json({ targets: await listCatalogTargets(base, req.body?.device) })
+    } catch (error) {
+      res.status(502).json({ error: error.message })
+    }
+  })
   function ControlPanel (config) {
     const node = this
     RED.nodes.createNode(node, config)
 
     let parentNode
+    const styleOnly = config.templateScope === 'site:style' || config.templateScope === 'page:style'
+    const visualBinding = !styleOnly
+    let visualBindings = {}
+    if (visualBinding) {
+      try { visualBindings = parseVisualBindings(config) } catch (error) { node.error(error) }
+    }
+    const hasVisualBindings = Object.keys(visualBindings).length > 0
+    const boundMode = !styleOnly && hasVisualBindings
+    const endpoint = `/control-panel-api/panels/${node.id}`
+    const boundRoom = config.boundRoom
+    let routes
+    routes = new Map()
+    if (boundMode) {
+      try {
+        routes = configuredRoutes(config)
+      } catch (error) {
+        node.error(error)
+      }
+    }
+
+    let bridgeReady = !config.bridgeRevisionApplied
+    if (config.nativeBridge === true) {
+      try {
+        bridgeReady = config.bridgeRevisionApplied === managedBridgeRevision({ ...config, id: node.id })
+      } catch (error) {
+        bridgeReady = false
+      }
+    }
+    node.status?.(bridgeReady ? {} : { fill: 'red', shape: 'ring', text: 'bridge out of sync' })
+
+    let gateway
+    let gatewayAuthKey
+    if (visualBinding && /^[a-zA-Z0-9_-]+$/.test(boundRoom || '')) {
+      try {
+        gatewayAuthKey = authSignature([node.id, boundRoom, node.credentials?.username,
+          node.credentials?.password, config.secureCookie === true])
+        gateway = createGateway({
+          username: node.credentials?.username,
+          password: node.credentials?.password,
+          room: boundRoom,
+          prefix: endpoint,
+          boundOnly: true,
+          secureCookie: config.secureCookie === true,
+          restoredSessions: takeSessions(gatewayHandoffs, node.id, gatewayAuthKey),
+          onBoundCommand: (message, identity) => {
+            if (!bridgeReady) return false
+            node.send({ ...resolveBoundCommand(routes, message), room: identity.room, user: identity.user })
+          },
+          onBoundLogin: identity => {
+            if (!boundMode || !bridgeReady) return
+            try { node.send({ kind: 'read-all', room: identity.room, user: identity.user }) } catch (error) { node.error(error) }
+          }
+        })
+        activePanels.set(node.id, gateway)
+      } catch (error) {
+        node.error(error)
+      }
+    } else if (visualBinding) {
+      node.error('Visual panel requires a valid room')
+    }
+
+    let editor
+    let editorAuthKey
+    if (visualBinding) {
+      editorAuthKey = authSignature([node.id, node.credentials?.editorUsername,
+        node.credentials?.editorPassword, config.secureCookie === true])
+      editor = createPanelEditor({
+        panelId: node.id,
+        username: node.credentials?.editorUsername,
+        password: node.credentials?.editorPassword,
+        secureCookie: config.secureCookie === true,
+        restoredSessions: takeSessions(editorHandoffs, node.id, editorAuthKey),
+        getConfig: async req => editorConfig(await getSnapshot(req.socket.localPort), node.id),
+        getDevices: async () => {
+          if (!base) throw new Error('Device catalog unavailable')
+          return listCatalogDevices(base)
+        },
+        getTargets: async (_req, device) => {
+          if (!base) throw new Error('Device catalog unavailable')
+          return listCatalogTargets(base, device)
+        },
+        apply: async (req, body) => applyVisualBindings({
+          panelId: node.id,
+          rev: body.rev,
+          templateHash: body.templateHash,
+          entries: body.entries,
+          userDir: RED.settings.userDir,
+          remoteAddress: req.socket.remoteAddress,
+          localPort: req.socket.localPort,
+          catalogBase: base
+        })
+      })
+      if (editor) activeEditors.set(node.id, editor)
+      else node.warn?.('Visual binding editor needs an editor username and password')
+    }
+
+    const panelConfig = () => (boundMode || visualBinding) ? {
+      endpoint, room: boundRoom,
+      ...(visualBinding ? { visual: {
+        panelId: node.id,
+        editorEndpoint: `/control-panel-edit/panels/${node.id}`,
+        bindings: visualBindings,
+        contract
+      } } : {})
+    } : null
 
     const events = {
-      onAction: true,
+      onAction: !boundMode,
       beforeSend (msg) {
+        if (msg?._controlPanel?.kind === 'command') throw new Error('Bound commands require authenticated HTTP')
+        if (boundMode) {
+          if (msg?.kind === 'device-feedback' && gateway) {
+            gateway.boundFeedback(resolveBoundFeedback(routes, msg))
+          }
+          return {}
+        }
+        if (msg?.kind === 'device-feedback') {
+          return { _controlPanel: { kind: 'states', items: resolveBoundFeedback(routes, msg) } }
+        }
         if (msg && msg.ui_update && statestore) {
           const parent = parentNode
           if (parent && typeof msg.ui_update.format !== 'undefined') {
-            msg.ui_update.format = injectWidgetPolicy(msg.ui_update.format, config.templateScope)
+            msg.ui_update.format = injectWidgetPolicy(msg.ui_update.format, config.templateScope,
+              panelConfig())
             statestore.set(parent.getBase(), node, msg, 'format', msg.ui_update.format)
           }
         }
         return msg
       }
     }
+    if (boundMode) {
+      events.onSend = () => { throw new Error('Bound commands require authenticated HTTP') }
+    }
 
     let retryTimer
     let attempts = 0
@@ -58,10 +264,18 @@ module.exports = function (RED) {
       }
 
       // Keep the custom editor type in Dashboard's namespace, but use Dashboard's built-in renderer.
-      const widgetConfig = {
-        ...config,
-        type: 'ui-template',
-        format: injectWidgetPolicy(config.format, config.templateScope)
+      let widgetConfig
+      try {
+        widgetConfig = {
+          ...config,
+          type: 'ui-template',
+          format: injectWidgetPolicy(config.format, config.templateScope, panelConfig()),
+          ...(boundMode ? { passthru: false, storeOutMessages: false, resendOnRefresh: false } : {})
+        }
+      } catch (error) {
+        node.error(error)
+        node.status?.({ fill: 'red', shape: 'ring', text: 'visual template unsupported' })
+        return
       }
       parentNode = group || page || ui
       if (group) group.register(node, widgetConfig, events)
@@ -71,10 +285,23 @@ module.exports = function (RED) {
     }
 
     registerWidget()
-    node.on('close', () => clearTimeout(retryTimer))
+    node.on('close', () => {
+      clearTimeout(retryTimer)
+      if (gateway) holdSessions(gatewayHandoffs, node.id, gatewayAuthKey, gateway.sessionSnapshot())
+      if (editor) holdSessions(editorHandoffs, node.id, editorAuthKey, editor.sessionSnapshot())
+      gateway?.close()
+      editor?.close()
+      if (activePanels.get(node.id) === gateway) activePanels.delete(node.id)
+      if (activeEditors.get(node.id) === editor) activeEditors.delete(node.id)
+    })
 
   }
 
   getStateStore(RED)
-  RED.nodes.registerType('ui-control-panel', ControlPanel)
+  RED.nodes.registerType('ui-control-panel', ControlPanel, {
+    credentials: {
+      username: { type: 'text' }, password: { type: 'password' },
+      editorUsername: { type: 'text' }, editorPassword: { type: 'password' }
+    }
+  })
 }