From b9c740f3981b2f946d7448b07659cf3f5d4fbc4f Mon Sep 17 00:00:00 2001 From: Chris Busillo Date: Fri, 18 Sep 2026 17:06:32 -0400 Subject: [PATCH 1/3] feat: add optional one-shot surface haptic feedback Let a surface declare that it can give haptic feedback and implement triggerHapticFeedback(). The host reports the capability only when the registration flag is true and the method exists, so existing modules are unaffected and need no changes. Requests are accepted only once the surface is ready, and failures in the surface's implementation are caught and logged. Each successful open gets a connection ID that a request must match, so a delayed request cannot reach a surface that was closed and reopened under the same surface ID. --- packages/base/src/surface-api/instance.ts | 8 ++ packages/base/src/surface-api/types.ts | 7 + .../__tests__/plugin.hapticFeedback.spec.ts | 136 ++++++++++++++++++ packages/host/src/plugin.ts | 33 ++++- packages/host/src/surfaceProxy.ts | 38 ++++- packages/host/src/types.ts | 9 ++ 6 files changed, 228 insertions(+), 3 deletions(-) create mode 100644 packages/host/src/__tests__/plugin.hapticFeedback.spec.ts diff --git a/packages/base/src/surface-api/instance.ts b/packages/base/src/surface-api/instance.ts index e35f3ad..53f7c61 100644 --- a/packages/base/src/surface-api/instance.ts +++ b/packages/base/src/surface-api/instance.ts @@ -36,6 +36,14 @@ export interface SurfaceInstance { */ ready(): Promise + /** + * Request the surface's short, implementation-defined haptic feedback effect. + * + * This is a best-effort submission only. Resolving does not confirm that the + * effect was felt, and implementations must not rely on a host timeout or ACK. + */ + triggerHapticFeedback?(): Promise + // updateCapabilities(capabilities: ClientCapabilities): void /** diff --git a/packages/base/src/surface-api/types.ts b/packages/base/src/surface-api/types.ts index a9a3dec..496fdb3 100644 --- a/packages/base/src/surface-api/types.ts +++ b/packages/base/src/surface-api/types.ts @@ -54,6 +54,13 @@ export interface SurfaceRegisterProps { * Whether the surface supports setting brightness */ brightness: boolean + /** + * Whether this opened surface supports short, implementation-defined haptic feedback. + * + * Omit this for unsupported surfaces. When set, the SurfaceInstance must also + * implement triggerHapticFeedback. + */ + hapticFeedback?: boolean /** * The definition of the controls on the surface and the properties needed for drawing */ diff --git a/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts b/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts new file mode 100644 index 0000000..0ed4b4c --- /dev/null +++ b/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts @@ -0,0 +1,136 @@ +import { describe, expect, it, vi } from 'vitest' +import { mock } from 'vitest-mock-extended' +import { PluginWrapper } from '../plugin.js' +import type { SurfaceHostContext } from '../context.js' +import type { + HIDDevice, + SurfaceInstance, + SurfacePlugin, + SurfaceRegisterProps, + SurfaceSchemaLayoutDefinition, +} from '@companion-surface/base' + +function validLayout(): SurfaceSchemaLayoutDefinition { + return { + stylePresets: { default: { bitmap: { w: 72, h: 72 } } }, + controls: { '0/0': { row: 0, column: 0 } }, + } +} + +function makeSurface(triggerHapticFeedback?: () => Promise): SurfaceInstance { + const surface = mock() + surface.init.mockResolvedValue(undefined) + surface.close.mockResolvedValue(undefined) + surface.ready.mockResolvedValue(undefined) + surface.triggerHapticFeedback = triggerHapticFeedback + return surface +} + +function registerProps(hapticFeedback?: boolean): SurfaceRegisterProps { + return { + brightness: false, + ...(hapticFeedback === undefined ? {} : { hapticFeedback }), + surfaceLayout: validLayout(), + pincodeMap: null, + location: null, + configFields: null, + } +} + +function makeWrapper(surface: SurfaceInstance, props: SurfaceRegisterProps) { + const plugin = mock>() + plugin.detection = undefined + plugin.checkSupportsHidDevice.mockReturnValue({ + surfaceId: 'test-surface', + description: 'Test Surface', + pluginInfo: {}, + }) + plugin.openSurface.mockResolvedValue({ surface, registerProps: props }) + + return new PluginWrapper(mock(), plugin) +} + +async function open(wrapper: PluginWrapper) { + const result = await wrapper.openHidDevice(mock(), 'test-surface') + expect(result).not.toBeNull() + return result! +} + +describe('PluginWrapper haptic feedback', () => { + it('keeps legacy and capability-method-mismatched surfaces unsupported', async () => { + const legacy = makeSurface() + const legacyResult = await open(makeWrapper(legacy, registerProps())) + expect(legacyResult.hapticFeedback).toBeUndefined() + + const methodOnlyTrigger = vi.fn().mockResolvedValue(undefined) + const methodOnlyResult = await open(makeWrapper(makeSurface(methodOnlyTrigger), registerProps())) + expect(methodOnlyResult.hapticFeedback).toBeUndefined() + expect(methodOnlyTrigger).not.toHaveBeenCalled() + + const capabilityOnlyResult = await open(makeWrapper(makeSurface(), registerProps(true))) + expect(capabilityOnlyResult.hapticFeedback).toBeUndefined() + }) + + it('submits one request only for a ready capable surface', async () => { + const trigger = vi.fn().mockResolvedValue(undefined) + const surface = makeSurface(trigger) + const wrapper = makeWrapper(surface, registerProps(true)) + const result = await open(wrapper) + const connectionId = result.hapticFeedback?.connectionId + expect(connectionId).toEqual(expect.any(String)) + + await wrapper.triggerHapticFeedback('test-surface', connectionId!) + expect(trigger).not.toHaveBeenCalled() + + await wrapper.readySurface('test-surface', {}) + await wrapper.triggerHapticFeedback('test-surface', connectionId!) + expect(trigger).toHaveBeenCalledTimes(1) + }) + + it('drops closed requests and contains rejected submissions', async () => { + const trigger = vi.fn().mockRejectedValue(new Error('device unavailable')) + const surface = makeSurface(trigger) + const wrapper = makeWrapper(surface, registerProps(true)) + const result = await open(wrapper) + const connectionId = result.hapticFeedback!.connectionId + await wrapper.readySurface('test-surface', {}) + + await expect(wrapper.triggerHapticFeedback('test-surface', connectionId)).resolves.toBeUndefined() + expect(trigger).toHaveBeenCalledTimes(1) + + await wrapper.closeDevice('test-surface') + await wrapper.triggerHapticFeedback('test-surface', connectionId) + expect(trigger).toHaveBeenCalledTimes(1) + }) + + it('drops an old generation after reopening the same surface id', async () => { + const oldTrigger = vi.fn().mockResolvedValue(undefined) + const newTrigger = vi.fn().mockResolvedValue(undefined) + const oldSurface = makeSurface(oldTrigger) + const newSurface = makeSurface(newTrigger) + const plugin = mock>() + plugin.detection = undefined + plugin.checkSupportsHidDevice.mockReturnValue({ + surfaceId: 'test-surface', + description: 'Test Surface', + pluginInfo: {}, + }) + plugin.openSurface.mockResolvedValueOnce({ surface: oldSurface, registerProps: registerProps(true) }) + plugin.openSurface.mockResolvedValueOnce({ surface: newSurface, registerProps: registerProps(true) }) + const wrapper = new PluginWrapper(mock(), plugin) + + const oldResult = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + await wrapper.closeDevice('test-surface') + const newResult = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + + expect(newResult.hapticFeedback!.connectionId).not.toBe(oldResult.hapticFeedback!.connectionId) + await wrapper.triggerHapticFeedback('test-surface', oldResult.hapticFeedback!.connectionId) + expect(oldTrigger).not.toHaveBeenCalled() + expect(newTrigger).not.toHaveBeenCalled() + + await wrapper.triggerHapticFeedback('test-surface', newResult.hapticFeedback!.connectionId) + expect(newTrigger).toHaveBeenCalledTimes(1) + }) +}) diff --git a/packages/host/src/plugin.ts b/packages/host/src/plugin.ts index 594900e..dc08ad5 100644 --- a/packages/host/src/plugin.ts +++ b/packages/host/src/plugin.ts @@ -1,4 +1,5 @@ import { SurfaceProxy, SurfaceProxyContext } from './surfaceProxy.js' +import { randomUUID } from 'node:crypto' import { createModuleLogger, type RemoteSurfaceConnectionInfo, @@ -249,8 +250,22 @@ export class PluginWrapper { throw e } - // Wrap the surface - const wrapped = new SurfaceProxy(this.#host, surfaceContext, surface.surface, surface.registerProps) + const hapticFeedbackSupported = + surface.registerProps.hapticFeedback === true && typeof surface.surface.triggerHapticFeedback === 'function' + if (surface.registerProps.hapticFeedback === true && !hapticFeedbackSupported) { + this.#logger.warn(`Surface ${resolvedSurfaceId} registered haptic feedback without an implementation`) + } + + // The connection generation is deliberately per open, so a delayed request + // cannot target a later instance with the same surface id. + const hapticFeedbackConnectionId = hapticFeedbackSupported ? randomUUID() : undefined + const wrapped = new SurfaceProxy( + this.#host, + surfaceContext, + surface.surface, + surface.registerProps, + hapticFeedbackConnectionId, + ) this.#openSurfaces.set(resolvedSurfaceId, wrapped) // Trigger a firmware update check @@ -261,6 +276,7 @@ export class PluginWrapper { surfaceId: resolvedSurfaceId, description: description, supportsBrightness: surface.registerProps.brightness, + hapticFeedback: hapticFeedbackConnectionId ? { connectionId: hapticFeedbackConnectionId } : undefined, surfaceLayout: surface.registerProps.surfaceLayout, transferVariables: surface.registerProps.transferVariables ?? null, location: surface.registerProps.location ?? null, @@ -340,6 +356,19 @@ export class PluginWrapper { this.#cleanupSurfaceById(surfaceId) } + /** + * Submit one best-effort haptic request to the matching ready surface. + * + * A stale, closed, unsupported, or not-ready connection is intentionally a + * no-op. Promise resolution never acknowledges physical feedback. + */ + async triggerHapticFeedback(surfaceId: string, connectionId: string): Promise { + const surface = this.#openSurfaces.get(surfaceId) + if (!surface || surface.hapticFeedbackConnectionId !== connectionId) return + + await surface.triggerHapticFeedback(connectionId) + } + async setBrightness(surfaceId: string, brightness: number): Promise { const surface = this.#openSurfaces.get(surfaceId) if (!surface) throw new Error(`Surface with id ${surfaceId} is not opened`) diff --git a/packages/host/src/surfaceProxy.ts b/packages/host/src/surfaceProxy.ts index 77ae28b..9062cfb 100644 --- a/packages/host/src/surfaceProxy.ts +++ b/packages/host/src/surfaceProxy.ts @@ -34,6 +34,8 @@ export class SurfaceProxy { readonly #registerProps: SurfaceRegisterProps readonly #drawQueue: DrawingState + #hapticFeedbackConnectionId: string | undefined + #isReady = false #pincodeCharacterCount = 0 #pincodeRotation: SurfaceRotation = 0 @@ -48,18 +50,23 @@ export class SurfaceProxy { get registerProps(): SurfaceRegisterProps { return this.#registerProps } + get hapticFeedbackConnectionId(): string | undefined { + return this.#hapticFeedbackConnectionId + } constructor( host: SurfaceHostContext, context: SurfaceProxyContext, surface: SurfaceInstance, registerProps: SurfaceRegisterProps, + hapticFeedbackConnectionId?: string, ) { this.#logger = createModuleLogger(`SurfaceProxy/${surface.surfaceId}`) this.#host = host this.#context = context this.#surface = surface this.#registerProps = registerProps + this.#hapticFeedbackConnectionId = hapticFeedbackConnectionId this.#drawQueue = new DrawingState(this.surfaceId, 'preinit') @@ -68,6 +75,8 @@ export class SurfaceProxy { } async close(): Promise { + this.#hapticFeedbackConnectionId = undefined + this.#isReady = false this.#drawQueue.abortQueued('closed') return this.#surface.close() @@ -93,13 +102,40 @@ export class SurfaceProxy { } async readySurface(config: Record): Promise { + this.#isReady = false this.#drawQueue.abortQueued('reinit') if (this.#surface.updateConfig) { await this.#surface.updateConfig(config) } - return this.#surface.ready() + await this.#surface.ready() + this.#isReady = true + } + + /** + * Submit a one-shot haptic request for the matching open connection. + * + * This intentionally does not use the draw queue. It resolves after the + * request has been submitted or dropped; it is not a physical-delivery ACK. + * Requests during initialization/reinitialization are dropped, including when + * configuration or readiness failed. They are never saved for later playback. + */ + async triggerHapticFeedback(connectionId: string): Promise { + if ( + this.#hapticFeedbackConnectionId !== connectionId || + !this.#isReady || + this.#registerProps.hapticFeedback !== true || + !this.#surface.triggerHapticFeedback + ) { + return + } + + try { + await this.#surface.triggerHapticFeedback() + } catch (e) { + this.#logger.warn(`Haptic feedback failed: ${e}`) + } } async setBrightness(percent: number): Promise { diff --git a/packages/host/src/types.ts b/packages/host/src/types.ts index 313eb5d..d22d2c2 100644 --- a/packages/host/src/types.ts +++ b/packages/host/src/types.ts @@ -38,6 +38,15 @@ export interface OpenDeviceResult { * Whether the surface supports setting brightness */ supportsBrightness: boolean + /** + * A per-open connection generation for best-effort haptic feedback. + * + * When absent, haptic feedback is unsupported. Pass connectionId back to + * PluginWrapper.triggerHapticFeedback; it is invalidated when this surface closes. + */ + hapticFeedback?: { + connectionId: string + } /** * The definition of the controls on the surface and the properties needed for drawing */ From cf9168e11d6bdb541161b105bc729abd18ec0b17 Mon Sep 17 00:00:00 2001 From: Chris Busillo Date: Sun, 18 Oct 2026 13:25:47 -0400 Subject: [PATCH 2/3] feat: replace haptic feedback with optional per-control events Surfaces can now register controlEvents and implement controlEvent(controlId, event) instead of a haptics-only call. The two events are press (a press ran an action group, on down or release) and hold (a run-while-held group fired). A surface decides how to show them, for example a haptic click or a flash of the key, and may ignore the control id. The host keeps the per-open connection id, drops events before ready, while locked, after close and for unknown controls, and contains errors from the surface. --- packages/base/src/surface-api/instance.ts | 13 +- packages/base/src/surface-api/types.ts | 16 +- .../src/__tests__/plugin.controlEvent.spec.ts | 161 ++++++++++++++++++ .../__tests__/plugin.hapticFeedback.spec.ts | 136 --------------- packages/host/src/main.ts | 1 + packages/host/src/plugin.ts | 37 ++-- packages/host/src/surfaceProxy.ts | 40 +++-- packages/host/src/types.ts | 8 +- 8 files changed, 231 insertions(+), 181 deletions(-) create mode 100644 packages/host/src/__tests__/plugin.controlEvent.spec.ts delete mode 100644 packages/host/src/__tests__/plugin.hapticFeedback.spec.ts diff --git a/packages/base/src/surface-api/instance.ts b/packages/base/src/surface-api/instance.ts index 53f7c61..ba5c26d 100644 --- a/packages/base/src/surface-api/instance.ts +++ b/packages/base/src/surface-api/instance.ts @@ -1,6 +1,6 @@ import type { CardGenerator } from './cards.js' import type { SurfaceFirmwareUpdateCache, SurfaceFirmwareUpdateInfo } from './firmware.js' -import type { SurfaceDrawProps, SurfaceId } from './types.js' +import type { ControlId, SurfaceControlEvent, SurfaceDrawProps, SurfaceId } from './types.js' export interface SurfaceInstance { /** @@ -37,12 +37,15 @@ export interface SurfaceInstance { ready(): Promise /** - * Request the surface's short, implementation-defined haptic feedback effect. + * Show that Companion acted on physical input to a control, for example with a haptic click or a flash of the key. + * Only called when the surface registered `controlEvents: true`. * - * This is a best-effort submission only. Resolving does not confirm that the - * effect was felt, and implementations must not rely on a host timeout or ACK. + * How to show it is up to the surface, and a surface that can only signal for the whole device may ignore the controlId. + * This is best-effort: the host does not wait for or retry it, and resolving does not confirm the user noticed. + * @param controlId The control the input came from + * @param event What happened. Ignore any event that isn't recognised, as more may be added later */ - triggerHapticFeedback?(): Promise + controlEvent?(controlId: ControlId, event: SurfaceControlEvent): Promise // updateCapabilities(capabilities: ClientCapabilities): void diff --git a/packages/base/src/surface-api/types.ts b/packages/base/src/surface-api/types.ts index 496fdb3..1ea2e4b 100644 --- a/packages/base/src/surface-api/types.ts +++ b/packages/base/src/surface-api/types.ts @@ -27,6 +27,15 @@ export interface HIDDevice { export type SurfaceId = string export type ControlId = string +/** + * Something Companion did in response to physical input on a control, which a surface may choose to show. + * - `press`: a press of the control ran an action group, either on press or on release + * - `hold`: an action group set to run while the control is held has fired, while it is still held + * + * More events may be added in future, so surfaces should ignore any they don't recognise. + */ +export type SurfaceControlEvent = 'press' | 'hold' + /** * Definition of a varaible produced by a surface */ @@ -55,12 +64,11 @@ export interface SurfaceRegisterProps { */ brightness: boolean /** - * Whether this opened surface supports short, implementation-defined haptic feedback. + * Whether this opened surface wants to be told about control events, such as a press running actions. * - * Omit this for unsupported surfaces. When set, the SurfaceInstance must also - * implement triggerHapticFeedback. + * Omit this if the surface can't show them. When set, the SurfaceInstance must also implement controlEvent. */ - hapticFeedback?: boolean + controlEvents?: boolean /** * The definition of the controls on the surface and the properties needed for drawing */ diff --git a/packages/host/src/__tests__/plugin.controlEvent.spec.ts b/packages/host/src/__tests__/plugin.controlEvent.spec.ts new file mode 100644 index 0000000..afa46d6 --- /dev/null +++ b/packages/host/src/__tests__/plugin.controlEvent.spec.ts @@ -0,0 +1,161 @@ +import { describe, expect, it, vi } from 'vitest' +import { mock } from 'vitest-mock-extended' +import { PluginWrapper } from '../plugin.js' +import type { SurfaceHostContext } from '../context.js' +import type { + HIDDevice, + SurfaceControlEvent, + SurfaceInstance, + SurfacePlugin, + SurfaceRegisterProps, + SurfaceSchemaLayoutDefinition, +} from '@companion-surface/base' + +type ControlEventFn = (controlId: string, event: SurfaceControlEvent) => Promise + +function validLayout(): SurfaceSchemaLayoutDefinition { + return { + stylePresets: { default: { bitmap: { w: 72, h: 72 } } }, + controls: { + '0/0': { row: 0, column: 0 }, + '0/1': { row: 0, column: 1 }, + }, + } +} + +function makeSurface(controlEvent?: ControlEventFn): SurfaceInstance { + const surface = mock() + surface.init.mockResolvedValue(undefined) + surface.close.mockResolvedValue(undefined) + surface.ready.mockResolvedValue(undefined) + surface.controlEvent = controlEvent + return surface +} + +function registerProps(controlEvents?: boolean): SurfaceRegisterProps { + return { + brightness: false, + ...(controlEvents === undefined ? {} : { controlEvents }), + surfaceLayout: validLayout(), + pincodeMap: { type: 'custom' }, + location: null, + configFields: null, + } +} + +function makePlugin(...opens: Array<{ surface: SurfaceInstance; props: SurfaceRegisterProps }>) { + const plugin = mock>() + plugin.detection = undefined + plugin.checkSupportsHidDevice.mockReturnValue({ + surfaceId: 'test-surface', + description: 'Test Surface', + pluginInfo: {}, + }) + for (const { surface, props } of opens) { + plugin.openSurface.mockResolvedValueOnce({ surface, registerProps: props }) + } + return new PluginWrapper(mock(), plugin) +} + +async function open(wrapper: PluginWrapper) { + const result = await wrapper.openHidDevice(mock(), 'test-surface') + expect(result).not.toBeNull() + return result! +} + +async function openReady(controlEvent: ControlEventFn) { + const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(true) }) + const result = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + return { wrapper, connectionId: result.controlEvents!.connectionId } +} + +describe('PluginWrapper control events', () => { + it('keeps legacy and capability-method-mismatched surfaces unsupported', async () => { + const legacyResult = await open(makePlugin({ surface: makeSurface(), props: registerProps() })) + expect(legacyResult.controlEvents).toBeUndefined() + + const methodOnly = vi.fn().mockResolvedValue(undefined) + const methodOnlyResult = await open(makePlugin({ surface: makeSurface(methodOnly), props: registerProps() })) + expect(methodOnlyResult.controlEvents).toBeUndefined() + + const capabilityOnlyResult = await open(makePlugin({ surface: makeSurface(), props: registerProps(true) })) + expect(capabilityOnlyResult.controlEvents).toBeUndefined() + }) + + it('passes the control and event to a ready surface, and drops them before ready', async () => { + const controlEvent = vi.fn().mockResolvedValue(undefined) + const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(true) }) + const result = await open(wrapper) + const connectionId = result.controlEvents?.connectionId + expect(connectionId).toEqual(expect.any(String)) + + await wrapper.controlEvent('test-surface', connectionId!, '0/1', 'press') + expect(controlEvent).not.toHaveBeenCalled() + + await wrapper.readySurface('test-surface', {}) + await wrapper.controlEvent('test-surface', connectionId!, '0/1', 'press') + await wrapper.controlEvent('test-surface', connectionId!, '0/0', 'hold') + expect(controlEvent.mock.calls).toEqual([ + ['0/1', 'press'], + ['0/0', 'hold'], + ]) + }) + + it('drops events for controls the surface does not have', async () => { + const controlEvent = vi.fn().mockResolvedValue(undefined) + const { wrapper, connectionId } = await openReady(controlEvent) + + await wrapper.controlEvent('test-surface', connectionId, '9/9', 'press') + await wrapper.controlEvent('test-surface', connectionId, '__proto__', 'press') + expect(controlEvent).not.toHaveBeenCalled() + }) + + it('drops events while the surface is locked', async () => { + const controlEvent = vi.fn().mockResolvedValue(undefined) + const { wrapper, connectionId } = await openReady(controlEvent) + + await wrapper.showLockedStatus('test-surface', true, 0, 0) + await wrapper.controlEvent('test-surface', connectionId, '0/0', 'press') + expect(controlEvent).not.toHaveBeenCalled() + + await wrapper.showLockedStatus('test-surface', false, 0, 0) + await wrapper.controlEvent('test-surface', connectionId, '0/0', 'press') + expect(controlEvent).toHaveBeenCalledTimes(1) + }) + + it('contains a rejecting surface and drops events after close', async () => { + const controlEvent = vi.fn().mockRejectedValue(new Error('device unavailable')) + const { wrapper, connectionId } = await openReady(controlEvent) + + await expect(wrapper.controlEvent('test-surface', connectionId, '0/0', 'press')).resolves.toBeUndefined() + expect(controlEvent).toHaveBeenCalledTimes(1) + + await wrapper.closeDevice('test-surface') + await wrapper.controlEvent('test-surface', connectionId, '0/0', 'press') + expect(controlEvent).toHaveBeenCalledTimes(1) + }) + + it('drops an old connection id after reopening the same surface id', async () => { + const oldEvent = vi.fn().mockResolvedValue(undefined) + const newEvent = vi.fn().mockResolvedValue(undefined) + const wrapper = makePlugin( + { surface: makeSurface(oldEvent), props: registerProps(true) }, + { surface: makeSurface(newEvent), props: registerProps(true) }, + ) + + const oldResult = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + await wrapper.closeDevice('test-surface') + const newResult = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + + expect(newResult.controlEvents!.connectionId).not.toBe(oldResult.controlEvents!.connectionId) + await wrapper.controlEvent('test-surface', oldResult.controlEvents!.connectionId, '0/0', 'press') + expect(oldEvent).not.toHaveBeenCalled() + expect(newEvent).not.toHaveBeenCalled() + + await wrapper.controlEvent('test-surface', newResult.controlEvents!.connectionId, '0/0', 'press') + expect(newEvent).toHaveBeenCalledTimes(1) + }) +}) diff --git a/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts b/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts deleted file mode 100644 index 0ed4b4c..0000000 --- a/packages/host/src/__tests__/plugin.hapticFeedback.spec.ts +++ /dev/null @@ -1,136 +0,0 @@ -import { describe, expect, it, vi } from 'vitest' -import { mock } from 'vitest-mock-extended' -import { PluginWrapper } from '../plugin.js' -import type { SurfaceHostContext } from '../context.js' -import type { - HIDDevice, - SurfaceInstance, - SurfacePlugin, - SurfaceRegisterProps, - SurfaceSchemaLayoutDefinition, -} from '@companion-surface/base' - -function validLayout(): SurfaceSchemaLayoutDefinition { - return { - stylePresets: { default: { bitmap: { w: 72, h: 72 } } }, - controls: { '0/0': { row: 0, column: 0 } }, - } -} - -function makeSurface(triggerHapticFeedback?: () => Promise): SurfaceInstance { - const surface = mock() - surface.init.mockResolvedValue(undefined) - surface.close.mockResolvedValue(undefined) - surface.ready.mockResolvedValue(undefined) - surface.triggerHapticFeedback = triggerHapticFeedback - return surface -} - -function registerProps(hapticFeedback?: boolean): SurfaceRegisterProps { - return { - brightness: false, - ...(hapticFeedback === undefined ? {} : { hapticFeedback }), - surfaceLayout: validLayout(), - pincodeMap: null, - location: null, - configFields: null, - } -} - -function makeWrapper(surface: SurfaceInstance, props: SurfaceRegisterProps) { - const plugin = mock>() - plugin.detection = undefined - plugin.checkSupportsHidDevice.mockReturnValue({ - surfaceId: 'test-surface', - description: 'Test Surface', - pluginInfo: {}, - }) - plugin.openSurface.mockResolvedValue({ surface, registerProps: props }) - - return new PluginWrapper(mock(), plugin) -} - -async function open(wrapper: PluginWrapper) { - const result = await wrapper.openHidDevice(mock(), 'test-surface') - expect(result).not.toBeNull() - return result! -} - -describe('PluginWrapper haptic feedback', () => { - it('keeps legacy and capability-method-mismatched surfaces unsupported', async () => { - const legacy = makeSurface() - const legacyResult = await open(makeWrapper(legacy, registerProps())) - expect(legacyResult.hapticFeedback).toBeUndefined() - - const methodOnlyTrigger = vi.fn().mockResolvedValue(undefined) - const methodOnlyResult = await open(makeWrapper(makeSurface(methodOnlyTrigger), registerProps())) - expect(methodOnlyResult.hapticFeedback).toBeUndefined() - expect(methodOnlyTrigger).not.toHaveBeenCalled() - - const capabilityOnlyResult = await open(makeWrapper(makeSurface(), registerProps(true))) - expect(capabilityOnlyResult.hapticFeedback).toBeUndefined() - }) - - it('submits one request only for a ready capable surface', async () => { - const trigger = vi.fn().mockResolvedValue(undefined) - const surface = makeSurface(trigger) - const wrapper = makeWrapper(surface, registerProps(true)) - const result = await open(wrapper) - const connectionId = result.hapticFeedback?.connectionId - expect(connectionId).toEqual(expect.any(String)) - - await wrapper.triggerHapticFeedback('test-surface', connectionId!) - expect(trigger).not.toHaveBeenCalled() - - await wrapper.readySurface('test-surface', {}) - await wrapper.triggerHapticFeedback('test-surface', connectionId!) - expect(trigger).toHaveBeenCalledTimes(1) - }) - - it('drops closed requests and contains rejected submissions', async () => { - const trigger = vi.fn().mockRejectedValue(new Error('device unavailable')) - const surface = makeSurface(trigger) - const wrapper = makeWrapper(surface, registerProps(true)) - const result = await open(wrapper) - const connectionId = result.hapticFeedback!.connectionId - await wrapper.readySurface('test-surface', {}) - - await expect(wrapper.triggerHapticFeedback('test-surface', connectionId)).resolves.toBeUndefined() - expect(trigger).toHaveBeenCalledTimes(1) - - await wrapper.closeDevice('test-surface') - await wrapper.triggerHapticFeedback('test-surface', connectionId) - expect(trigger).toHaveBeenCalledTimes(1) - }) - - it('drops an old generation after reopening the same surface id', async () => { - const oldTrigger = vi.fn().mockResolvedValue(undefined) - const newTrigger = vi.fn().mockResolvedValue(undefined) - const oldSurface = makeSurface(oldTrigger) - const newSurface = makeSurface(newTrigger) - const plugin = mock>() - plugin.detection = undefined - plugin.checkSupportsHidDevice.mockReturnValue({ - surfaceId: 'test-surface', - description: 'Test Surface', - pluginInfo: {}, - }) - plugin.openSurface.mockResolvedValueOnce({ surface: oldSurface, registerProps: registerProps(true) }) - plugin.openSurface.mockResolvedValueOnce({ surface: newSurface, registerProps: registerProps(true) }) - const wrapper = new PluginWrapper(mock(), plugin) - - const oldResult = await open(wrapper) - await wrapper.readySurface('test-surface', {}) - await wrapper.closeDevice('test-surface') - const newResult = await open(wrapper) - await wrapper.readySurface('test-surface', {}) - - expect(newResult.hapticFeedback!.connectionId).not.toBe(oldResult.hapticFeedback!.connectionId) - await wrapper.triggerHapticFeedback('test-surface', oldResult.hapticFeedback!.connectionId) - expect(oldTrigger).not.toHaveBeenCalled() - expect(newTrigger).not.toHaveBeenCalled() - - await wrapper.triggerHapticFeedback('test-surface', newResult.hapticFeedback!.connectionId) - expect(newTrigger).toHaveBeenCalledTimes(1) - }) -}) diff --git a/packages/host/src/main.ts b/packages/host/src/main.ts index 91e1c5b..8380f24 100644 --- a/packages/host/src/main.ts +++ b/packages/host/src/main.ts @@ -20,6 +20,7 @@ export { SurfaceFirmwareUpdateInfo, HIDDevice, SurfaceDrawProps, + SurfaceControlEvent, HostCapabilities, GridSize, SurfaceInputVariable, diff --git a/packages/host/src/plugin.ts b/packages/host/src/plugin.ts index dc08ad5..9513de1 100644 --- a/packages/host/src/plugin.ts +++ b/packages/host/src/plugin.ts @@ -5,6 +5,8 @@ import { type RemoteSurfaceConnectionInfo, type HIDDevice, type OpenSurfaceResult, + type ControlId, + type SurfaceControlEvent, type SurfaceDrawProps, type SurfacePlugin, DetectionSurfaceInfo, @@ -250,21 +252,21 @@ export class PluginWrapper { throw e } - const hapticFeedbackSupported = - surface.registerProps.hapticFeedback === true && typeof surface.surface.triggerHapticFeedback === 'function' - if (surface.registerProps.hapticFeedback === true && !hapticFeedbackSupported) { - this.#logger.warn(`Surface ${resolvedSurfaceId} registered haptic feedback without an implementation`) + const controlEventsSupported = + surface.registerProps.controlEvents === true && typeof surface.surface.controlEvent === 'function' + if (surface.registerProps.controlEvents === true && !controlEventsSupported) { + this.#logger.warn(`Surface ${resolvedSurfaceId} registered control events without implementing controlEvent`) } - // The connection generation is deliberately per open, so a delayed request - // cannot target a later instance with the same surface id. - const hapticFeedbackConnectionId = hapticFeedbackSupported ? randomUUID() : undefined + // The connection id is deliberately per open, so a delayed event + // cannot reach a later instance with the same surface id. + const controlEventsConnectionId = controlEventsSupported ? randomUUID() : undefined const wrapped = new SurfaceProxy( this.#host, surfaceContext, surface.surface, surface.registerProps, - hapticFeedbackConnectionId, + controlEventsConnectionId, ) this.#openSurfaces.set(resolvedSurfaceId, wrapped) @@ -276,7 +278,7 @@ export class PluginWrapper { surfaceId: resolvedSurfaceId, description: description, supportsBrightness: surface.registerProps.brightness, - hapticFeedback: hapticFeedbackConnectionId ? { connectionId: hapticFeedbackConnectionId } : undefined, + controlEvents: controlEventsConnectionId ? { connectionId: controlEventsConnectionId } : undefined, surfaceLayout: surface.registerProps.surfaceLayout, transferVariables: surface.registerProps.transferVariables ?? null, location: surface.registerProps.location ?? null, @@ -357,16 +359,21 @@ export class PluginWrapper { } /** - * Submit one best-effort haptic request to the matching ready surface. + * Tell a ready surface about an event on one of its controls. * - * A stale, closed, unsupported, or not-ready connection is intentionally a - * no-op. Promise resolution never acknowledges physical feedback. + * A stale, closed, unsupported or not-ready connection, or an unknown control, is a no-op. + * Resolving does not mean the surface showed anything. */ - async triggerHapticFeedback(surfaceId: string, connectionId: string): Promise { + async controlEvent( + surfaceId: string, + connectionId: string, + controlId: ControlId, + event: SurfaceControlEvent, + ): Promise { const surface = this.#openSurfaces.get(surfaceId) - if (!surface || surface.hapticFeedbackConnectionId !== connectionId) return + if (!surface || surface.controlEventsConnectionId !== connectionId) return - await surface.triggerHapticFeedback(connectionId) + await surface.controlEvent(connectionId, controlId, event) } async setBrightness(surfaceId: string, brightness: number): Promise { diff --git a/packages/host/src/surfaceProxy.ts b/packages/host/src/surfaceProxy.ts index 9062cfb..de6461c 100644 --- a/packages/host/src/surfaceProxy.ts +++ b/packages/host/src/surfaceProxy.ts @@ -2,6 +2,7 @@ import { type HostCapabilities, type ControlId, type SurfaceContext, + type SurfaceControlEvent, type SurfaceDrawProps, type SurfaceId, type SurfaceInstance, @@ -34,7 +35,7 @@ export class SurfaceProxy { readonly #registerProps: SurfaceRegisterProps readonly #drawQueue: DrawingState - #hapticFeedbackConnectionId: string | undefined + #controlEventsConnectionId: string | undefined #isReady = false #pincodeCharacterCount = 0 @@ -50,8 +51,8 @@ export class SurfaceProxy { get registerProps(): SurfaceRegisterProps { return this.#registerProps } - get hapticFeedbackConnectionId(): string | undefined { - return this.#hapticFeedbackConnectionId + get controlEventsConnectionId(): string | undefined { + return this.#controlEventsConnectionId } constructor( @@ -59,14 +60,14 @@ export class SurfaceProxy { context: SurfaceProxyContext, surface: SurfaceInstance, registerProps: SurfaceRegisterProps, - hapticFeedbackConnectionId?: string, + controlEventsConnectionId?: string, ) { this.#logger = createModuleLogger(`SurfaceProxy/${surface.surfaceId}`) this.#host = host this.#context = context this.#surface = surface this.#registerProps = registerProps - this.#hapticFeedbackConnectionId = hapticFeedbackConnectionId + this.#controlEventsConnectionId = controlEventsConnectionId this.#drawQueue = new DrawingState(this.surfaceId, 'preinit') @@ -75,7 +76,7 @@ export class SurfaceProxy { } async close(): Promise { - this.#hapticFeedbackConnectionId = undefined + this.#controlEventsConnectionId = undefined this.#isReady = false this.#drawQueue.abortQueued('closed') @@ -114,27 +115,32 @@ export class SurfaceProxy { } /** - * Submit a one-shot haptic request for the matching open connection. + * Pass an event for one control to the surface, for the matching open connection. * - * This intentionally does not use the draw queue. It resolves after the - * request has been submitted or dropped; it is not a physical-delivery ACK. - * Requests during initialization/reinitialization are dropped, including when - * configuration or readiness failed. They are never saved for later playback. + * This deliberately bypasses the draw queue, and resolves once the surface has taken + * the event or it was dropped. Events while the surface is initialising, reinitialising + * or locked, and events for unknown controls, are dropped and never replayed. */ - async triggerHapticFeedback(connectionId: string): Promise { + async controlEvent(connectionId: string, controlId: ControlId, event: SurfaceControlEvent): Promise { if ( - this.#hapticFeedbackConnectionId !== connectionId || + this.#controlEventsConnectionId !== connectionId || !this.#isReady || - this.#registerProps.hapticFeedback !== true || - !this.#surface.triggerHapticFeedback + this.#context.isLocked || + this.#registerProps.controlEvents !== true || + !this.#surface.controlEvent ) { return } + if (BANNED_PROPS.has(controlId) || !this.#registerProps.surfaceLayout.controls[controlId]) { + this.#logger.warn(`Dropping control event for unknown controlId: ${controlId}`) + return + } + try { - await this.#surface.triggerHapticFeedback() + await this.#surface.controlEvent(controlId, event) } catch (e) { - this.#logger.warn(`Haptic feedback failed: ${e}`) + this.#logger.warn(`Control event failed: ${e}`) } } diff --git a/packages/host/src/types.ts b/packages/host/src/types.ts index d22d2c2..656a8ab 100644 --- a/packages/host/src/types.ts +++ b/packages/host/src/types.ts @@ -39,12 +39,12 @@ export interface OpenDeviceResult { */ supportsBrightness: boolean /** - * A per-open connection generation for best-effort haptic feedback. + * Present when the surface wants control events. When absent, don't send any. * - * When absent, haptic feedback is unsupported. Pass connectionId back to - * PluginWrapper.triggerHapticFeedback; it is invalidated when this surface closes. + * Pass connectionId back to PluginWrapper.controlEvent. It is new on every open and + * invalidated on close, so a delayed event can't reach a later surface with the same id. */ - hapticFeedback?: { + controlEvents?: { connectionId: string } /** From 4d97b93b19143c9752abd3924261b2a8c9a8136d Mon Sep 17 00:00:00 2001 From: Chris Busillo Date: Sat, 14 Nov 2026 19:40:17 -0500 Subject: [PATCH 3/3] fix: list supported control events and require the connection id argument --- packages/base/src/surface-api/instance.ts | 2 +- packages/base/src/surface-api/types.ts | 7 +++-- .../src/__tests__/plugin.controlEvent.spec.ts | 28 +++++++++++++++---- .../src/__tests__/surfaceProxy.leds.spec.ts | 2 +- .../src/__tests__/surfaceProxy.rotate.spec.ts | 2 +- packages/host/src/plugin.ts | 6 ++-- packages/host/src/surfaceProxy.ts | 4 +-- 7 files changed, 34 insertions(+), 17 deletions(-) diff --git a/packages/base/src/surface-api/instance.ts b/packages/base/src/surface-api/instance.ts index ed43cd5..4793604 100644 --- a/packages/base/src/surface-api/instance.ts +++ b/packages/base/src/surface-api/instance.ts @@ -39,7 +39,7 @@ export interface SurfaceInstance { /** * Show that Companion acted on physical input to a control, for example with a haptic click or a flash of the key. - * Only called when the surface registered `controlEvents: true`. + * Only called for events listed in the `controlEvents` the surface registered. * * How to show it is up to the surface, and a surface that can only signal for the whole device may ignore the controlId. * This is best-effort: the host does not wait for or retry it, and resolving does not confirm the user noticed. diff --git a/packages/base/src/surface-api/types.ts b/packages/base/src/surface-api/types.ts index 4265d00..9b0287e 100644 --- a/packages/base/src/surface-api/types.ts +++ b/packages/base/src/surface-api/types.ts @@ -65,11 +65,12 @@ export interface SurfaceRegisterProps { */ brightness: boolean /** - * Whether this opened surface wants to be told about control events, such as a press running actions. + * The control events this opened surface can show, such as a press running actions. + * Only events in this list are sent to the surface. * - * Omit this if the surface can't show them. When set, the SurfaceInstance must also implement controlEvent. + * Omitted or empty means none. When non-empty, the SurfaceInstance must also implement controlEvent. */ - controlEvents?: boolean + controlEvents?: SurfaceControlEvent[] /** * The definition of the controls on the surface and the properties needed for drawing */ diff --git a/packages/host/src/__tests__/plugin.controlEvent.spec.ts b/packages/host/src/__tests__/plugin.controlEvent.spec.ts index afa46d6..4485951 100644 --- a/packages/host/src/__tests__/plugin.controlEvent.spec.ts +++ b/packages/host/src/__tests__/plugin.controlEvent.spec.ts @@ -32,7 +32,7 @@ function makeSurface(controlEvent?: ControlEventFn): SurfaceInstance { return surface } -function registerProps(controlEvents?: boolean): SurfaceRegisterProps { +function registerProps(controlEvents?: SurfaceControlEvent[]): SurfaceRegisterProps { return { brightness: false, ...(controlEvents === undefined ? {} : { controlEvents }), @@ -64,7 +64,7 @@ async function open(wrapper: PluginWrapper) { } async function openReady(controlEvent: ControlEventFn) { - const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(true) }) + const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(['press', 'hold']) }) const result = await open(wrapper) await wrapper.readySurface('test-surface', {}) return { wrapper, connectionId: result.controlEvents!.connectionId } @@ -79,13 +79,18 @@ describe('PluginWrapper control events', () => { const methodOnlyResult = await open(makePlugin({ surface: makeSurface(methodOnly), props: registerProps() })) expect(methodOnlyResult.controlEvents).toBeUndefined() - const capabilityOnlyResult = await open(makePlugin({ surface: makeSurface(), props: registerProps(true) })) + const capabilityOnlyResult = await open( + makePlugin({ surface: makeSurface(), props: registerProps(['press', 'hold']) }), + ) expect(capabilityOnlyResult.controlEvents).toBeUndefined() + + const emptyListResult = await open(makePlugin({ surface: makeSurface(methodOnly), props: registerProps([]) })) + expect(emptyListResult.controlEvents).toBeUndefined() }) it('passes the control and event to a ready surface, and drops them before ready', async () => { const controlEvent = vi.fn().mockResolvedValue(undefined) - const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(true) }) + const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(['press', 'hold']) }) const result = await open(wrapper) const connectionId = result.controlEvents?.connectionId expect(connectionId).toEqual(expect.any(String)) @@ -102,6 +107,17 @@ describe('PluginWrapper control events', () => { ]) }) + it('only passes events the surface listed', async () => { + const controlEvent = vi.fn().mockResolvedValue(undefined) + const wrapper = makePlugin({ surface: makeSurface(controlEvent), props: registerProps(['press']) }) + const result = await open(wrapper) + await wrapper.readySurface('test-surface', {}) + + await wrapper.controlEvent('test-surface', result.controlEvents!.connectionId, '0/0', 'hold') + await wrapper.controlEvent('test-surface', result.controlEvents!.connectionId, '0/0', 'press') + expect(controlEvent.mock.calls).toEqual([['0/0', 'press']]) + }) + it('drops events for controls the surface does not have', async () => { const controlEvent = vi.fn().mockResolvedValue(undefined) const { wrapper, connectionId } = await openReady(controlEvent) @@ -140,8 +156,8 @@ describe('PluginWrapper control events', () => { const oldEvent = vi.fn().mockResolvedValue(undefined) const newEvent = vi.fn().mockResolvedValue(undefined) const wrapper = makePlugin( - { surface: makeSurface(oldEvent), props: registerProps(true) }, - { surface: makeSurface(newEvent), props: registerProps(true) }, + { surface: makeSurface(oldEvent), props: registerProps(['press', 'hold']) }, + { surface: makeSurface(newEvent), props: registerProps(['press', 'hold']) }, ) const oldResult = await open(wrapper) diff --git a/packages/host/src/__tests__/surfaceProxy.leds.spec.ts b/packages/host/src/__tests__/surfaceProxy.leds.spec.ts index 58cc65f..5c66dc3 100644 --- a/packages/host/src/__tests__/surfaceProxy.leds.spec.ts +++ b/packages/host/src/__tests__/surfaceProxy.leds.spec.ts @@ -40,7 +40,7 @@ function makeProxy() { configFields: null, } - const proxy = new SurfaceProxy(host, context, surface, registerProps) + const proxy = new SurfaceProxy(host, context, surface, registerProps, undefined) return { proxy, surface } } diff --git a/packages/host/src/__tests__/surfaceProxy.rotate.spec.ts b/packages/host/src/__tests__/surfaceProxy.rotate.spec.ts index 787459e..261ef78 100644 --- a/packages/host/src/__tests__/surfaceProxy.rotate.spec.ts +++ b/packages/host/src/__tests__/surfaceProxy.rotate.spec.ts @@ -33,7 +33,7 @@ function makeContext() { const context = new SurfaceProxyContext(host, 'surf1', vi.fn()) // The SurfaceProxy constructor registers itself with the context via storeSurface - new SurfaceProxy(host, context, surface, registerProps) + new SurfaceProxy(host, context, surface, registerProps, undefined) return { context, inputRotate } } diff --git a/packages/host/src/plugin.ts b/packages/host/src/plugin.ts index e37ef93..99d7810 100644 --- a/packages/host/src/plugin.ts +++ b/packages/host/src/plugin.ts @@ -356,9 +356,9 @@ export class PluginWrapper { modelId = null } - const controlEventsSupported = - surface.registerProps.controlEvents === true && typeof surface.surface.controlEvent === 'function' - if (surface.registerProps.controlEvents === true && !controlEventsSupported) { + const wantsControlEvents = (surface.registerProps.controlEvents?.length ?? 0) > 0 + const controlEventsSupported = wantsControlEvents && typeof surface.surface.controlEvent === 'function' + if (wantsControlEvents && !controlEventsSupported) { this.#logger.warn(`Surface ${resolvedSurfaceId} registered control events without implementing controlEvent`) } diff --git a/packages/host/src/surfaceProxy.ts b/packages/host/src/surfaceProxy.ts index e4c9612..476ffb8 100644 --- a/packages/host/src/surfaceProxy.ts +++ b/packages/host/src/surfaceProxy.ts @@ -62,7 +62,7 @@ export class SurfaceProxy { context: SurfaceProxyContext, surface: SurfaceInstance, registerProps: SurfaceRegisterProps, - controlEventsConnectionId?: string, + controlEventsConnectionId: string | undefined, ) { this.#logger = createModuleLogger(`SurfaceProxy/${surface.surfaceId}`) this.#host = host @@ -128,7 +128,7 @@ export class SurfaceProxy { this.#controlEventsConnectionId !== connectionId || !this.#isReady || this.#context.isLocked || - this.#registerProps.controlEvents !== true || + !this.#registerProps.controlEvents?.includes(event) || !this.#surface.controlEvent ) { return