@companion-surface/base 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.1](https://github.com/bitfocus/companion-surface-api/compare/companion-surface-base-v0.6.0...companion-surface-base-v0.6.1) (2025-11-24)
+
+
+### Bug Fixes
+
+* make serialnumber always defined, and add helper for generating unique serials ([2cfc41e](https://github.com/bitfocus/companion-surface-api/commit/2cfc41ed58487a5d0bab7b6c6aa110774b1bf907))
+
 ## [0.6.0](https://github.com/bitfocus/companion-surface-api/compare/companion-surface-base-v0.5.0...companion-surface-base-v0.6.0) (2025-11-23)
 
 

package/dist/__tests__/util.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=util.test.d.ts.map

package/dist/__tests__/util.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/util.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/util.test.js

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'vitest';
+import { StableDeviceIdGenerator } from '../util.js';
+describe('StableDeviceIdGenerator', () => {
+    test('generates different IDs for different uniqueness keys', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator.generateId('1234:9999', '/dev/hidraw1');
+        expect(id1).not.toBe(id2);
+        expect(id1).toHaveLength(40); // SHA1 hex digest length
+        expect(id2).toHaveLength(40);
+    });
+    test('generates different IDs for same uniqueness key with different paths', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator.generateId('1234:5678', '/dev/hidraw1');
+        expect(id1).not.toBe(id2);
+    });
+    test('returns same ID for same device path on repeated calls', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator.generateId('1234:5678', '/dev/hidraw0');
+        expect(id1).toBe(id2);
+    });
+    test('handles missing device path parameter', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678');
+        const id2 = generator.generateId('1234:5678');
+        // Without path, each call should generate a new ID
+        expect(id1).not.toBe(id2);
+        expect(id1).toHaveLength(40);
+        expect(id2).toHaveLength(40);
+    });
+    test('generates stable IDs with counter increment', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator.generateId('1234:5678', '/dev/hidraw1');
+        const id3 = generator.generateId('1234:5678', '/dev/hidraw2');
+        // All should be unique
+        expect(new Set([id1, id2, id3]).size).toBe(3);
+    });
+    test('separate instances have independent state', () => {
+        const generator1 = new StableDeviceIdGenerator();
+        const generator2 = new StableDeviceIdGenerator();
+        const id1 = generator1.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator2.generateId('1234:5678', '/dev/hidraw1');
+        // Same inputs in different instances should produce same ID
+        expect(id1).toBe(id2);
+    });
+    test('handles multiple devices with same uniqueness key in batch', () => {
+        const generator = new StableDeviceIdGenerator();
+        // Simulate 3 identical devices (same vendor/product) with different paths
+        const ids = [
+            generator.generateId('1234:5678', '/dev/hidraw0'),
+            generator.generateId('1234:5678', '/dev/hidraw1'),
+            generator.generateId('1234:5678', '/dev/hidraw2'),
+        ];
+        // All should be unique
+        expect(new Set(ids).size).toBe(3);
+        // Requesting same path again should return cached ID
+        expect(generator.generateId('1234:5678', '/dev/hidraw1')).toBe(ids[1]);
+    });
+    test('handles mixed scenarios with and without device paths', () => {
+        const generator = new StableDeviceIdGenerator();
+        const withPath1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const withoutPath1 = generator.generateId('1234:5678');
+        const withPath2 = generator.generateId('1234:5678', '/dev/hidraw1');
+        const withoutPath2 = generator.generateId('1234:5678');
+        // All should be unique
+        expect(new Set([withPath1, withoutPath1, withPath2, withoutPath2]).size).toBe(4);
+        // Cached path should return same ID
+        expect(generator.generateId('1234:5678', '/dev/hidraw0')).toBe(withPath1);
+    });
+    test('handles undefined device path (same as omitted)', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('1234:5678', undefined);
+        const id2 = generator.generateId('1234:5678', undefined);
+        // Should generate different IDs when path is undefined
+        expect(id1).not.toBe(id2);
+    });
+    test('generates valid hex SHA1 hashes', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id = generator.generateId('1234:5678', '/dev/hidraw0');
+        // Should be 40 character hex string
+        expect(id).toMatch(/^[0-9a-f]{40}$/);
+    });
+    test('deduplicates multiple endpoints of same device', () => {
+        const generator = new StableDeviceIdGenerator();
+        // Simulate same device with multiple HID endpoints (same path)
+        const id1 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id2 = generator.generateId('1234:5678', '/dev/hidraw0');
+        const id3 = generator.generateId('1234:5678', '/dev/hidraw0');
+        expect(id1).toBe(id2);
+        expect(id2).toBe(id3);
+    });
+    test('handles empty uniqueness key', () => {
+        const generator = new StableDeviceIdGenerator();
+        const id1 = generator.generateId('', '/dev/hidraw0');
+        const id2 = generator.generateId('', '/dev/hidraw1');
+        expect(id1).not.toBe(id2);
+        expect(id1).toHaveLength(40);
+    });
+    test('real-world scenario: 2 identical Stream Decks', () => {
+        const generator = new StableDeviceIdGenerator();
+        // Same vendor:product, different USB paths
+        const deck1 = generator.generateId('4057:96', '/dev/hidraw0');
+        const deck2 = generator.generateId('4057:96', '/dev/hidraw1');
+        expect(deck1).not.toBe(deck2);
+        expect(deck1).toHaveLength(40);
+        expect(deck2).toHaveLength(40);
+        // Re-enumerating same devices should return same IDs
+        expect(generator.generateId('4057:96', '/dev/hidraw0')).toBe(deck1);
+        expect(generator.generateId('4057:96', '/dev/hidraw1')).toBe(deck2);
+    });
+});
+//# sourceMappingURL=util.test.js.map

package/dist/__tests__/util.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.test.js","sourceRoot":"","sources":["../../src/__tests__/util.test.ts"],"names":[],"mappings":"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"}

package/dist/surface-api/types.d.ts

@@ -10,7 +10,11 @@ export interface HIDDevice {
     vendorId: number;
     productId: number;
     path: string;
-    serialNumber: string | undefined;
+    /**
+     * The serial number of the device.
+     * This is either the serial number provided by the device, or something generated by Companion to give this device a unique ID
+     */
+    serialNumber: string;
     manufacturer: string | undefined;
     product: string | undefined;
     release: number;

package/dist/surface-api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/surface-api/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAA;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAExE;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAC9B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AACD,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,aAAa,EAAE,6BAA6B,CAAA;IAC5C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,oBAAoB,GAAG,qBAAqB,CAAC,CAAA;IACvE;;;OAGG;IACH,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAEpC;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvB;;OAEG;IACH,YAAY,EAAE,uBAAuB,EAAE,GAAG,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,aAAa,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,2BAA2B;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,aAAa,CAAA;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/surface-api/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAA;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAExE;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAC9B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AACD,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,aAAa,EAAE,6BAA6B,CAAA;IAC5C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,oBAAoB,GAAG,qBAAqB,CAAC,CAAA;IACvE;;;OAGG;IACH,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAEpC;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvB;;OAEG;IACH,YAAY,EAAE,uBAAuB,EAAE,GAAG,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,aAAa,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,2BAA2B;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,aAAa,CAAA;CACrB"}

package/dist/util.d.ts

@@ -5,4 +5,27 @@ export interface RgbColor {
     b: number;
 }
 export declare function parseColor(color: string | undefined): RgbColor;
+/**
+ * Helper class to generate stable, unique device IDs for devices that lack serial numbers.
+ * Each instance is scoped to a single batch of devices, ensuring uniqueness within that batch.
+ *
+ * @example
+ * ```typescript
+ * const generator = new StableDeviceIdGenerator()
+ * const serial1 = generator.generateId('1234:5678', '/dev/hidraw0')
+ * const serial2 = generator.generateId('1234:5678', '/dev/hidraw1')
+ * // serial1 and serial2 will be unique even for the same uniquenessKey
+ * ```
+ */
+export declare class StableDeviceIdGenerator {
+    #private;
+    /**
+     * Generate a stable unique ID for a device within the current batch.
+     *
+     * @param uniquenessKey - A string containing device identifiers (e.g., "vendorId:productId")
+     * @param devicePath - A unique identifier for the device. Typically the device path. This is to ensure that multiple endpoints of the same hid device get the same id.
+     * @returns A stable unique identifier for the device
+     */
+    generateId(uniquenessKey: string, devicePath?: string): string;
+}
 //# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE3C;AAED,MAAM,WAAW,QAAQ;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACT;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAM9D"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAEA,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE3C;AAED,MAAM,WAAW,QAAQ;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACT;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAM9D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAuB;;IAInC;;;;;;OAMG;IACH,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAsB9D"}

package/dist/util.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 export function assertNever(_v) {
     // Nothing to do
 }
@@ -7,4 +8,47 @@ export function parseColor(color) {
     const b = color ? parseInt(color.substr(5, 2), 16) : 0;
     return { r, g, b };
 }
+/**
+ * Helper class to generate stable, unique device IDs for devices that lack serial numbers.
+ * Each instance is scoped to a single batch of devices, ensuring uniqueness within that batch.
+ *
+ * @example
+ * ```typescript
+ * const generator = new StableDeviceIdGenerator()
+ * const serial1 = generator.generateId('1234:5678', '/dev/hidraw0')
+ * const serial2 = generator.generateId('1234:5678', '/dev/hidraw1')
+ * // serial1 and serial2 will be unique even for the same uniquenessKey
+ * ```
+ */
+export class StableDeviceIdGenerator {
+    #previousForDevicePath = new Map();
+    #returnedIds = new Map();
+    /**
+     * Generate a stable unique ID for a device within the current batch.
+     *
+     * @param uniquenessKey - A string containing device identifiers (e.g., "vendorId:productId")
+     * @param devicePath - A unique identifier for the device. Typically the device path. This is to ensure that multiple endpoints of the same hid device get the same id.
+     * @returns A stable unique identifier for the device
+     */
+    generateId(uniquenessKey, devicePath) {
+        // Generate a complete key
+        // If there is something cached against the devicePath, use that
+        const pathCacheKey = `${uniquenessKey}||${devicePath}`;
+        if (devicePath) {
+            const cached = this.#previousForDevicePath.get(pathCacheKey);
+            if (cached)
+                return cached;
+        }
+        // Loop until we find a non-colliding ID
+        for (let i = 0;; i++) {
+            const id = `${uniquenessKey}||${i}`;
+            if (!this.#returnedIds.has(id)) {
+                const fakeSerial = createHash('sha1').update(id).digest('hex');
+                this.#returnedIds.set(id, fakeSerial);
+                this.#previousForDevicePath.set(pathCacheKey, fakeSerial);
+                return fakeSerial;
+            }
+        }
+    }
+}
 //# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,EAAS;IACpC,gBAAgB;AACjB,CAAC;AAQD,MAAM,UAAU,UAAU,CAAC,KAAyB;IACnD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;AACnB,CAAC"}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,UAAU,WAAW,CAAC,EAAS;IACpC,gBAAgB;AACjB,CAAC;AAQD,MAAM,UAAU,UAAU,CAAC,KAAyB;IACnD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,uBAAuB;IAC1B,sBAAsB,GAAG,IAAI,GAAG,EAAkB,CAAA;IAClD,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAA;IAEjD;;;;;;OAMG;IACH,UAAU,CAAC,aAAqB,EAAE,UAAmB;QACpD,0BAA0B;QAE1B,gEAAgE;QAChE,MAAM,YAAY,GAAG,GAAG,aAAa,KAAK,UAAU,EAAE,CAAA;QACtD,IAAI,UAAU,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YAC5D,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAA;QAC1B,CAAC;QAED,wCAAwC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;YACvB,MAAM,EAAE,GAAG,GAAG,aAAa,KAAK,CAAC,EAAE,CAAA;YACnC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAE9D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;gBACrC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;gBACzD,OAAO,UAAU,CAAA;YAClB,CAAC;QACF,CAAC;IACF,CAAC;CACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-surface/base",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "license": "MIT",
   "repository": "https://github.com/bitfocus/companion-surface-api",