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

package/control-policy.js

@@ -1,5 +1,6 @@
 const acorn = require('acorn')
 const escodegen = require('escodegen')
+const { initializeVisualBinding, disposeVisualBinding } = require('./panel-binding-editor')
 
 const CONTROL_POLICY_MARKER = '/* ui-control-panel-control-api-v1 */'
 const FEEDBACK_TOPIC_FIELDS = Object.freeze({
@@ -57,7 +58,7 @@ function createControlPanelPolicy ({
   if (!Number.isFinite(intervalMs) || intervalMs < 0) throw new Error('ControlPanel interval must be a non-negative number')
 
   const continuousTypes = new Set(['level', 'dimmer', 'position'])
-  const discreteTypes = new Set(['power', 'source', 'preset', 'mute'])
+  const discreteTypes = new Set(['power', 'source', 'preset', 'mute', 'text'])
   const continuousControls = new Map()
   let discreteQueue = Promise.resolve()
   let disposed = false
@@ -274,7 +275,6 @@ const __controlPanelPolicyMixin = {
     },
     __acknowledgeControlFeedback (feedback) {
       for (const [key, request] of this.__controlPanelRequests) {
-        if (feedback.controlKey && feedback.controlKey !== key) continue
         let matched = request.topic === 'room/reset'
         let value
         if (!matched && feedback.topic === request.topic) {
@@ -287,7 +287,15 @@ const __controlPanelPolicyMixin = {
             value = feedback.state[field]
           }
         }
-        if (matched && (request.topic === 'room/reset' || Object.is(value, request.value))) {
+        if (!matched) continue
+
+        const sameTopicRequests = [...this.__controlPanelRequests.values()]
+          .filter(candidate => candidate.topic === request.topic).length
+        const correlated = !feedback.controlKey || feedback.controlKey === key || sameTopicRequests === 1
+        if (!correlated) continue
+
+        const continuous = ['level', 'dimmer', 'position'].includes(request.type)
+        if (!continuous || request.topic === 'room/reset' || Object.is(value, request.value)) {
           this.__clearControlPending(key)
         }
       }
@@ -406,11 +414,27 @@ const __controlPanelPolicyMixin = {
 // as component options when the script contains one `export default { ... }`
 // statement. Keep every helper inside data, methods, or lifecycle hooks so the
 // generated script remains inside that supported subset.
-function buildDashboardPolicyOptionsSource () {
+function buildDashboardPolicyOptionsSource (controls = [], boundPanel = null) {
+  const boundControls = controls.map(({ id, type, mode }) => ({ id, type, mode }))
+  const visualMethods = boundPanel?.visual
+    ? `__initializeVisualBinding: ${initializeVisualBinding.toString()},
+    __disposeVisualBinding: ${disposeVisualBinding.toString()},`
+    : ''
+  const visualMounted = boundPanel?.visual
+    ? 'this.$nextTick(() => this.__initializeVisualBinding())'
+    : ''
+  const visualUnmounted = boundPanel?.visual ? 'this.__disposeVisualBinding()' : ''
   return `
 export default {
   data () {
     return {
+      boundState: {},
+      boundPending: {},
+      boundTargets: {},
+      boundUnconfirmed: {},
+      boundFeedbackRevision: 0,
+      boundFeedbackConnected: false,
+      boundAuthenticated: false,
       deviceState: {},
       deviceFeedbackRevision: 0,
       deviceFeedbackConnected: false,
@@ -419,6 +443,117 @@ export default {
     }
   },
   methods: {
+    ${visualMethods}
+    __boundPanelConfig () {
+      return ${JSON.stringify(boundPanel)}
+    },
+    __boundControls () {
+      return ${JSON.stringify(boundControls)}
+    },
+    __boundControl (id) {
+      return this.__boundControls().find(control => control.id === id)
+    },
+    applyBoundFeedback (message) {
+      if (['bound-snapshot', 'bound-feedback'].includes(message?.kind)) {
+        if (message.room !== this.__boundPanelConfig()?.room || !Array.isArray(message.items) ||
+          !Number.isInteger(message.revision) || message.revision < this.boundFeedbackRevision) return false
+        if (message.kind === 'bound-snapshot') this.boundState = {}
+        this.boundFeedbackRevision = message.revision
+        return message.items.map(item => this.applyBoundFeedback({
+          __boundRevision: message.revision,
+          _controlPanel: { kind: 'state', id: item.id, value: item.value }
+        }))
+      }
+      const state = message?._controlPanel
+      if (state?.kind === 'states' && Array.isArray(state.items)) {
+        return state.items.map(item => this.applyBoundFeedback({ _controlPanel: { kind: 'state', ...item } }))
+      }
+      if (state?.kind !== 'state' || !this.__boundControl(state.id) ||
+        !Object.prototype.hasOwnProperty.call(state, 'value')) return false
+      this.boundState = { ...this.boundState, [state.id]: state.value }
+      const control = this.__boundControl(state.id)
+      if (!['level', 'dimmer', 'position'].includes(control.type) ||
+        Object.is(this.boundTargets[state.id], state.value)) {
+        this.__clearBoundPending(state.id)
+      } else {
+        const settlement = this.__boundSettlements.get(state.id)
+        if (settlement && (message.__boundRevision === undefined ||
+          message.__boundRevision > settlement.finalRevision)) {
+          settlement.newFeedback = true
+          if (settlement.expired) this.__clearBoundPending(state.id)
+        }
+      }
+      return true
+    },
+    __clearBoundPending (id) {
+      const settlement = this.__boundSettlements.get(id)
+      if (settlement?.timer) clearTimeout(settlement.timer)
+      this.__boundSettlements.delete(id)
+      const pending = { ...this.boundPending }
+      const targets = { ...this.boundTargets }
+      const unconfirmed = { ...this.boundUnconfirmed }
+      delete pending[id]
+      delete targets[id]
+      delete unconfirmed[id]
+      this.boundPending = pending
+      this.boundTargets = targets
+      this.boundUnconfirmed = unconfirmed
+    },
+    __clearAllBoundSettlements () {
+      for (const settlement of this.__boundSettlements.values()) {
+        if (settlement.timer) clearTimeout(settlement.timer)
+      }
+      this.__boundSettlements.clear()
+      this.boundPending = {}
+      this.boundTargets = {}
+      this.boundUnconfirmed = {}
+    },
+    __boundSettleDelayMs () { return 700 },
+    controlValue (id, fallback = null) {
+      return Object.prototype.hasOwnProperty.call(this.boundState, id) ? this.boundState[id] : fallback
+    },
+    boundDisplayValue (id, fallback = null) {
+      return this.boundPending[id] === true && Object.prototype.hasOwnProperty.call(this.boundTargets, id)
+        ? this.boundTargets[id] : this.controlValue(id, fallback)
+    },
+    sendBoundControl (command) {
+      const id = command?.id
+      const control = this.__boundControl(id)
+      if (!control) throw new Error('Unknown control ID: ' + id)
+      if (control.mode === 'read') throw new Error('Read-only control: ' + id)
+      if (!Object.prototype.hasOwnProperty.call(command, 'value')) throw new Error('Bound control needs a value')
+      if (!this.__boundPanelSession?.csrf) throw new Error('Bound panel login required')
+      const previous = this.__boundSettlements.get(id)
+      if (previous?.timer) clearTimeout(previous.timer)
+      this.__boundSettlements.delete(id)
+      const unconfirmed = { ...this.boundUnconfirmed }
+      delete unconfirmed[id]
+      this.boundUnconfirmed = unconfirmed
+      this.boundPending = { ...this.boundPending, [id]: true }
+      const continuous = ['level', 'dimmer', 'position'].includes(control.type)
+      this.boundTargets = { ...this.boundTargets, [id]: command.value }
+      try {
+        const sent = this.__controlPanelPolicy.send({
+          type: control.type, topic: '__bound', key: id,
+          value: command.value, final: command.final === true
+        })
+        if (continuous && command.final === true) {
+          const settlement = { finalRevision: this.boundFeedbackRevision, newFeedback: false, expired: false, timer: null }
+          settlement.timer = setTimeout(() => {
+            if (this.__boundSettlements.get(id) !== settlement) return
+            settlement.timer = null
+            settlement.expired = true
+            if (settlement.newFeedback) this.__clearBoundPending(id)
+            else this.boundUnconfirmed = { ...this.boundUnconfirmed, [id]: true }
+          }, this.__boundSettleDelayMs())
+          this.__boundSettlements.set(id, settlement)
+        }
+        return sent
+      } catch (error) {
+        this.__clearBoundPending(id)
+        throw error
+      }
+    },
     __controlPanelCreatePolicy: ${createControlPanelPolicy.toString()},
     __controlPanelNormalizeFeedback: ${normalizeControlFeedback.toString()},
     __controlPanelFeedbackFields () {
@@ -428,16 +563,28 @@ export default {
       this.__controlPanelSession = null
       this.__controlPanelFeedbackSource = null
       this.__controlPanelRequests = new Map()
+      this.__boundPanelSession = null
+      this.__boundPanelSource = null
+      this.__boundAuthGeneration = 0
+      this.__boundSettlements = new Map()
       this.__resetControlPolicy()
+      if (typeof this.$watch === 'function') {
+        this.__boundUnwatch = this.$watch('msg', message => this.applyBoundFeedback(message), { immediate: true })
+      }
     },
     __disposeControlPanelPolicy () {
+      this.__boundUnwatch?.()
+      this.__boundUnwatch = null
+      this.__clearAllBoundSettlements()
       this.__closeControlFeedback()
+      this.__closeBoundFeedback()
       this.__controlPanelPolicy?.dispose()
       this.__controlPanelPolicy = null
       this.__controlPanelRequests?.clear()
       this.controlPending = {}
       this.controlTargets = {}
       this.__controlPanelSession = null
+      this.__boundPanelSession = null
     },
     __resetControlPolicy () {
       this.__controlPanelPolicy?.dispose()
@@ -445,6 +592,9 @@ export default {
         intervalMs: 40,
         dispatch: (command) => this.__dispatchControl(command),
         onError: (error, command) => {
+          if (command?.topic === '__bound' && command.controlKey) {
+            this.__clearBoundPending(command.controlKey)
+          }
           if (command?.controlKey) this.__clearControlPending(command.controlKey)
           if (typeof this.onControlError === 'function') this.onControlError(error, command)
           else console.error('ControlPanel command failed', error)
@@ -503,7 +653,6 @@ export default {
     __acknowledgeControlFeedback (feedback) {
       const feedbackFields = this.__controlPanelFeedbackFields()
       for (const [key, request] of this.__controlPanelRequests) {
-        if (feedback.controlKey && feedback.controlKey !== key) continue
         let matched = request.topic === 'room/reset'
         let value
         if (!matched && feedback.topic === request.topic) {
@@ -516,7 +665,15 @@ export default {
             value = feedback.state[field]
           }
         }
-        if (matched && (request.topic === 'room/reset' || Object.is(value, request.value))) {
+        if (!matched) continue
+
+        const sameTopicRequests = [...this.__controlPanelRequests.values()]
+          .filter(candidate => candidate.topic === request.topic).length
+        const correlated = !feedback.controlKey || feedback.controlKey === key || sameTopicRequests === 1
+        if (!correlated) continue
+
+        const continuous = ['level', 'dimmer', 'position'].includes(request.type)
+        if (!continuous || request.topic === 'room/reset' || Object.is(value, request.value)) {
           this.__clearControlPending(key)
         }
       }
@@ -548,7 +705,103 @@ export default {
       this.deviceState = {}
       this.deviceFeedbackRevision = 0
     },
+    __closeBoundFeedback () {
+      this.__boundPanelSource?.close()
+      this.__boundPanelSource = null
+      this.boundFeedbackConnected = false
+    },
+    __connectBoundFeedback () {
+      this.__closeBoundFeedback()
+      const config = this.__boundPanelConfig()
+      if (!config || !this.__boundPanelSession || typeof EventSource === 'undefined') return
+      const source = new EventSource(config.endpoint + '/events')
+      this.__boundPanelSource = source
+      source.onopen = () => {
+        if (this.__boundPanelSource === source) this.boundFeedbackConnected = true
+      }
+      source.onmessage = event => {
+        if (this.__boundPanelSource !== source) return
+        try { this.applyBoundFeedback(JSON.parse(event.data)) } catch (error) {
+          if (typeof this.onControlError === 'function') this.onControlError(error)
+          else console.error('Bound feedback failed', error)
+        }
+      }
+      source.onerror = () => {
+        if (this.__boundPanelSource === source) this.boundFeedbackConnected = false
+      }
+    },
+    setBoundPanelSession (session) {
+      const config = this.__boundPanelConfig()
+      if (!config || session?.room !== config.room || !session.csrf) {
+        throw new Error('Invalid bound panel session')
+      }
+      if (this.__boundPanelSession?.csrf !== session.csrf) {
+        this.__resetControlPolicy()
+        this.__clearAllBoundSettlements()
+        this.boundState = {}
+        this.boundFeedbackRevision = 0
+      }
+      this.__boundPanelSession = { room: session.room, csrf: session.csrf }
+      this.boundAuthenticated = true
+      this.__connectBoundFeedback()
+    },
+    clearBoundPanelSession () {
+      this.__boundAuthGeneration++
+      this.__closeBoundFeedback()
+      this.__boundPanelSession = null
+      this.boundAuthenticated = false
+      this.__resetControlPolicy()
+      this.__clearAllBoundSettlements()
+      this.boundState = {}
+      this.boundFeedbackRevision = 0
+    },
+    async loginBoundPanel (username, password) {
+      const config = this.__boundPanelConfig()
+      if (!config) throw new Error('This panel has no bound login endpoint')
+      this.clearBoundPanelSession()
+      const generation = this.__boundAuthGeneration
+      const response = await fetch(config.endpoint + '/login', {
+        method: 'POST', credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ username, password })
+      })
+      if (!response.ok) throw new Error('Panel login failed (' + response.status + ')')
+      const session = await response.json()
+      if (generation !== this.__boundAuthGeneration) return null
+      this.setBoundPanelSession(session)
+      return session
+    },
+    async restoreBoundPanelSession () {
+      const config = this.__boundPanelConfig()
+      if (!config) return null
+      const generation = this.__boundAuthGeneration
+      const response = await fetch(config.endpoint + '/session', { credentials: 'same-origin' })
+      if (generation !== this.__boundAuthGeneration) return this.__boundPanelSession
+      if (!response.ok) {
+        this.clearBoundPanelSession()
+        return null
+      }
+      const session = await response.json()
+      if (generation !== this.__boundAuthGeneration) return this.__boundPanelSession
+      this.setBoundPanelSession(session)
+      return session
+    },
+    async logoutBoundPanel () {
+      const config = this.__boundPanelConfig()
+      const session = this.__boundPanelSession
+      this.clearBoundPanelSession()
+      if (!config || !session) return
+      const response = await fetch(config.endpoint + '/logout', {
+        method: 'POST', credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', 'X-Room-CSRF': session.csrf },
+        body: '{}'
+      })
+      if (!response.ok) throw new Error('Panel logout failed (' + response.status + ')')
+    },
     sendControl (command) {
+      if (command && Object.prototype.hasOwnProperty.call(command, 'id')) {
+        return this.sendBoundControl(command)
+      }
       const key = String(command?.key ?? command?.controlKey ?? '')
       const type = String(command?.type ?? command?.controlType ?? '').toLowerCase()
       const value = Object.prototype.hasOwnProperty.call(command || {}, 'value') ? command.value : command?.payload
@@ -602,6 +855,24 @@ export default {
       return this.deviceValue(field, fallback)
     },
     async __dispatchControl (command) {
+      if (command.topic === '__bound') {
+        const config = this.__boundPanelConfig()
+        const session = this.__boundPanelSession
+        if (!config || !session) throw new Error('Bound panel login required')
+        const response = await fetch(config.endpoint + '/bound-command', {
+          method: 'POST', credentials: 'same-origin',
+          headers: { 'Content-Type': 'application/json', 'X-Room-CSRF': session.csrf },
+          body: JSON.stringify({ room: session.room, _controlPanel: {
+            kind: 'command', id: command.controlKey, value: command.payload, final: command.final
+          } }),
+          signal: AbortSignal.timeout(8000)
+        })
+        if (!response.ok) {
+          if (response.status === 401) this.clearBoundPanelSession()
+          throw new Error('Bound command failed (' + response.status + ')')
+        }
+        return response
+      }
       if (typeof this.controlTransport === 'function') return this.controlTransport(command)
 
       const session = this.__controlPanelSession
@@ -624,8 +895,11 @@ export default {
   },
   mounted () {
     this.__initializeControlPanelPolicy()
+    if (this.__boundPanelConfig()) this.restoreBoundPanelSession().catch(() => undefined)
+    ${visualMounted}
   },
   unmounted () {
+    ${visualUnmounted}
     this.__disposeControlPanelPolicy()
   }
 }
@@ -659,11 +933,11 @@ function functionSource (property) {
   return property ? escodegen.generate(property.value) : null
 }
 
-function mergeDashboardOptions (userSource) {
+function mergeDashboardOptions (userSource, controls = [], boundPanel = null) {
   const user = parseOptionsObject(userSource)
   if (!user) return null
 
-  const policy = parseOptionsObject(buildDashboardPolicyOptionsSource())
+  const policy = parseOptionsObject(buildDashboardPolicyOptionsSource(controls, boundPanel))
   const policyData = findProperty(policy, 'data')
   const policyMethods = findProperty(policy, 'methods')
   const policyMounted = findProperty(policy, 'mounted')
@@ -724,7 +998,7 @@ function mergeDashboardOptions (userSource) {
   })
 }
 
-function injectControlPolicy (format) {
+function injectControlPolicy (format, controls = [], boundPanel = null) {
   if (typeof format !== 'string' || format.includes(CONTROL_POLICY_MARKER)) return format
 
   const scriptMatch = /<script(?!\s+setup\b)(?:\s[^>]*)?>/i.exec(format)
@@ -732,7 +1006,7 @@ function injectControlPolicy (format) {
     const setupMatch = /<script\s+setup\b([^>]*)>/i.exec(format)
     if (setupMatch || !/<template(?:\s|>)/i.test(format)) return format
     return format + '\n<script>\n' + CONTROL_POLICY_MARKER + '\n' +
-      buildDashboardPolicyOptionsSource().trim() + '\n</script>\n'
+      buildDashboardPolicyOptionsSource(controls, boundPanel).trim() + '\n</script>\n'
   }
 
   const scriptStart = scriptMatch.index + scriptMatch[0].length
@@ -742,7 +1016,7 @@ function injectControlPolicy (format) {
   const source = format.slice(scriptStart, scriptEnd)
   let wrapped
   try {
-    wrapped = mergeDashboardOptions(source)
+    wrapped = mergeDashboardOptions(source, controls, boundPanel)
   } catch (_) {
     return format
   }

package/control-type-contract.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "types": {
+    "slider": { "family": "number", "delivery": "continuous" },
+    "level": { "family": "number", "delivery": "continuous" },
+    "volume": { "family": "number", "delivery": "continuous" },
+    "dimmer": { "family": "number", "delivery": "continuous" },
+    "position": { "family": "number", "delivery": "continuous" },
+    "toggle": { "family": "boolean", "delivery": "discrete" },
+    "mute": { "family": "boolean", "delivery": "discrete" },
+    "power": { "family": "boolean", "delivery": "discrete" },
+    "text": { "family": "text", "delivery": "discrete" },
+    "string": { "family": "text", "delivery": "discrete" },
+    "source": { "family": "enum", "delivery": "discrete" },
+    "preset": { "family": "enum", "delivery": "discrete" }
+  }
+}

package/control-type-model.js

@@ -0,0 +1,63 @@
+const contract = require('./control-type-contract.json')
+
+const ADAPTER_FAMILIES = Object.freeze({
+  range: ['number'],
+  switch: ['boolean'],
+  meter: ['number'],
+  'text-display': ['text', 'number', 'enum', 'boolean'],
+  'text-input': ['text'],
+  select: ['enum']
+})
+
+const READ_ONLY = new Set(['meter', 'text-display'])
+
+function targetFamily (target) {
+  if (target.controlSchemaVersion !== contract.schemaVersion) return null
+  const definition = contract.types[String(target.controlType || '').toLowerCase()]
+  if (!definition) return null
+  const type = target.type
+  if (definition.family === 'number' && !['integer', 'float'].includes(type)) return null
+  if (definition.family === 'boolean' && type !== 'boolean' &&
+    !(type === 'integer' && target.booleanEncoding === 'integer01' &&
+      target.min === 0 && target.max === 1)) return null
+  if (definition.family === 'text' && !['string', 'dstring'].includes(type)) return null
+  if (definition.family === 'enum' && !['enum', 'integer', 'string'].includes(type)) return null
+  return definition.family
+}
+
+function compatibleTarget (adapter, target, direction, candidate = {}) {
+  const family = targetFamily(target)
+  if (!family || target.kind !== 'param' || !ADAPTER_FAMILIES[adapter]?.includes(family)) return false
+  if (direction === 'write' && READ_ONLY.has(adapter)) return false
+  if (direction === 'write' && !['wo', 'rw'].includes(target.access)) return false
+  if (direction === 'read' && !['ro', 'rw'].includes(target.access)) return false
+  if (candidate.unit && candidate.unit !== target.unit) return false
+  return true
+}
+
+function controlTypeForAdapter (adapter, target) {
+  if (!compatibleTarget(adapter, target, 'read') && !compatibleTarget(adapter, target, 'write')) {
+    throw new Error('Target is incompatible with this control')
+  }
+  const family = targetFamily(target)
+  if (family === 'number') return 'level'
+  if (family === 'boolean') return 'mute'
+  if (family === 'text') return 'text'
+  if (family === 'enum') return 'source'
+  throw new Error('Unsupported control family')
+}
+
+function targetMeta (target, onebased) {
+  if (typeof target.onebased !== 'boolean' && typeof onebased !== 'boolean') {
+    throw new Error('Select target numbering mode')
+  }
+  return {
+    kind: target.kind, type: target.type, access: target.access,
+    onebased: typeof target.onebased === 'boolean' ? target.onebased : onebased,
+    min: target.min, max: target.max, enums: target.enums,
+    ...(target.booleanEncoding ? { booleanEncoding: target.booleanEncoding } : {}),
+    controlType: target.controlType, controlSchemaVersion: target.controlSchemaVersion
+  }
+}
+
+module.exports = { contract, compatibleTarget, controlTypeForAdapter, targetFamily, targetMeta }

package/gateway.cjs

@@ -119,18 +119,35 @@ function createGateway ({
   password,
   room = 'room-01',
   onCommand = () => {},
+  onBoundCommand,
+  onBoundLogin,
+  boundOnly = false,
   secureCookie = false,
   prefix,
-  continuousIntervalMs = CONTINUOUS_INTERVAL_MS
+  continuousIntervalMs = CONTINUOUS_INTERVAL_MS,
+  sessionTtlMs = 8 * 3600000,
+  restoredSessions
 }) {
   const routePrefix = prefix || PREFIX + '/regions/' + encodeURIComponent(room)
   if (!username || typeof password !== 'string' || password.length < 12) {
     throw Error('Set a username and password of at least 12 characters')
   }
+  if (!Number.isSafeInteger(sessionTtlMs) || sessionTtlMs < 1) {
+    throw Error('Invalid session lifetime')
+  }
 
   const salt = crypto.randomBytes(16)
   const hash = crypto.scryptSync(password, salt, 32)
   const sessions = new Map()
+  if (restoredSessions instanceof Map) {
+    for (const [token, session] of restoredSessions) {
+      if (sessions.size >= 100) break
+      if (typeof token === 'string' && typeof session?.csrf === 'string' &&
+        Number.isFinite(session.expiry) && session.expiry > Date.now()) {
+        sessions.set(token, { csrf: session.csrf, expiry: session.expiry })
+      }
+    }
+  }
   const attempts = new Map()
   const continuousDispatcher = createLatestWinsDispatcher({
     onDispatch: onCommand,
@@ -139,6 +156,8 @@ function createGateway ({
   const subscribers = new Set()
   let desiredState = defaults()
   let reportedState = {}
+  const boundState = new Map()
+  let boundRevision = 0
   let revision = 0
   let commandRevision = 0
   let closed = false
@@ -201,6 +220,7 @@ function createGateway ({
   }
 
   function feedback (msg) {
+    if (boundOnly) throw Error('Use boundFeedback for a bound panel')
     if (msg.room !== room || msg.kind !== 'state') {
       throw Error('Feedback requires matching room and kind=state')
     }
@@ -223,6 +243,27 @@ function createGateway ({
     return message
   }
 
+  function boundFeedback (items) {
+    if (!boundOnly || !Array.isArray(items) || !items.length ||
+      items.some(item => !item || typeof item.id !== 'string' || !item.id ||
+        !Object.hasOwn(item, 'value'))) {
+      throw Error('Invalid bound feedback')
+    }
+    for (const { id, value } of items) boundState.set(id, value)
+    boundRevision++
+    const message = { room, kind: 'bound-feedback', items, revision: boundRevision }
+    broadcastFeedback(message)
+    return message
+  }
+
+  function boundSnapshot () {
+    return {
+      room, kind: 'bound-snapshot',
+      items: [...boundState].map(([id, value]) => ({ id, value })),
+      revision: boundRevision
+    }
+  }
+
   function reply (res, status, data, headers = {}) {
     res.writeHead(status, {
       'Content-Type': 'application/json; charset=utf-8',
@@ -310,8 +351,13 @@ function createGateway ({
         attempts.delete(ip)
         const token = crypto.randomBytes(32).toString('hex')
         const csrf = crypto.randomBytes(24).toString('hex')
-        sessions.set(token, { csrf, expiry: now + 8 * 3600000 })
-        reply(res, 200, { room, username, csrf }, { 'Set-Cookie': cookie(token, 28800) })
+        sessions.set(token, { csrf, expiry: now + sessionTtlMs })
+        reply(res, 200, { room, username, csrf }, {
+          'Set-Cookie': cookie(token, Math.ceil(sessionTtlMs / 1000))
+        })
+        if (boundOnly && typeof onBoundLogin === 'function') {
+          queueMicrotask(() => { if (!closed) onBoundLogin({ room, user: username }) })
+        }
         return true
       }
 
@@ -344,7 +390,7 @@ function createGateway ({
         const subscriber = { res, token }
         subscribers.add(subscriber)
         res.on('close', () => closeSubscriber(subscriber))
-        sendFeedbackEvent(subscriber, feedbackMessage())
+        sendFeedbackEvent(subscriber, boundOnly ? boundSnapshot() : feedbackMessage())
         ensureHeartbeat()
         return true
       }
@@ -353,7 +399,7 @@ function createGateway ({
           reply(res, 403, { error: 'Region denied' })
           return true
         }
-        reply(res, 200, feedbackMessage())
+        reply(res, 200, boundOnly ? boundSnapshot() : feedbackMessage())
         return true
       }
       if (path === routePrefix + '/logout' && req.method === 'POST') {
@@ -362,7 +408,28 @@ function createGateway ({
         reply(res, 200, { ok: true }, { 'Set-Cookie': cookie('', 0) })
         return true
       }
+      if (path === routePrefix + '/bound-command' && req.method === 'POST') {
+        if (typeof onBoundCommand !== 'function') {
+          reply(res, 404, { error: 'Not found' })
+          return true
+        }
+        const data = await body(req)
+        if (data.room !== room) {
+          reply(res, 403, { error: 'Region denied' })
+          return true
+        }
+        if (await onBoundCommand(data, { room, user: username }) === false) {
+          reply(res, 409, { error: 'Managed bridge is out of sync' })
+          return true
+        }
+        reply(res, 200, { ok: true })
+        return true
+      }
       if (path === routePrefix + '/command' && req.method === 'POST') {
+        if (boundOnly) {
+          reply(res, 404, { error: 'Not found' })
+          return true
+        }
         const data = await body(req)
         if (data.room !== room) {
           reply(res, 403, { error: 'Region denied' })
@@ -427,6 +494,11 @@ function createGateway ({
   return {
     handler,
     feedback,
+    boundFeedback,
+    sessionSnapshot () {
+      return new Map([...sessions].filter(([, session]) => session.expiry > Date.now())
+        .map(([token, session]) => [token, { ...session }]))
+    },
     close () {
       closed = true
       continuousDispatcher.close()