@fcannizzaro/streamdeck-react 0.1.10 → 0.1.12

package/dist/types.d.ts

@@ -1,6 +1,18 @@
 import { ComponentType, ReactNode } from 'react';
-import { Action, Controller, Coordinates, DeviceType, DialAction, KeyAction, Size } from '@elgato/streamdeck';
 import { JsonObject, JsonValue } from '@elgato/utils';
+import { AdapterActionHandle, StreamDeckAdapter } from './adapter/types';
+/** Controller surface type. */
+export type Controller = "Keypad" | "Encoder";
+/** Grid coordinates for a key or encoder on a device. */
+export interface Coordinates {
+    column: number;
+    row: number;
+}
+/** Device grid size (number of key columns and rows). */
+export interface Size {
+    columns: number;
+    rows: number;
+}
 export interface FontConfig {
     name: string;
     data: ArrayBuffer | Buffer;
@@ -62,41 +74,80 @@ export interface TouchStripLayout {
 }
 export type EncoderLayout = string | TouchStripLayout;
 export interface PluginConfig {
+    /** Stream Deck adapter. Defaults to physicalDevice() (Elgato SDK). */
+    adapter?: StreamDeckAdapter;
     fonts: FontConfig[];
     actions: ActionDefinition[];
     wrapper?: WrapperComponent;
-    renderDebounceMs?: number;
     imageFormat?: "png" | "webp";
     caching?: boolean;
     devicePixelRatio?: number;
     onActionError?: (uuid: string, actionId: string, error: Error) => void;
     /** Enable the devtools WebSocket server. Browser devtools UI discovers it via port scanning. @default false */
     devtools?: boolean;
+    /** Enable performance diagnostics (render counters, duplicate detection, depth warnings). Defaults to `process.env.NODE_ENV !== 'production'`. */
+    debug?: boolean;
+    /** Maximum image cache size in bytes for key/dial renders. Set to 0 to disable. @default 16777216 (16 MB) */
+    imageCacheMaxBytes?: number;
+    /** Maximum TouchStrip raw buffer cache size in bytes. Set to 0 to disable. @default 8388608 (8 MB) */
+    touchStripCacheMaxBytes?: number;
+    /** Offload Takumi rendering to a worker thread. Set to false to disable. @default true */
+    useWorker?: boolean;
 }
 export interface Plugin {
     connect(): Promise<void>;
 }
+export interface ManifestActions {
+}
+/** Action UUID — a union of manifest UUIDs when available, plain `string` otherwise. */
+export type ActionUUID = [keyof ManifestActions] extends [never] ? string : Extract<keyof ManifestActions, string>;
+type HasController<UUID extends string, C extends string> = UUID extends keyof ManifestActions ? ManifestActions[UUID] extends {
+    controllers: readonly (infer Item)[];
+} ? C extends Item ? true : false : false : false;
+type KeySurface<UUID extends string> = HasController<UUID, "Keypad"> extends true ? {
+    key: ComponentType;
+} : {
+    key?: ComponentType;
+};
+type EncoderSurface<UUID extends string> = HasController<UUID, "Encoder"> extends true ? {
+    dial: ComponentType;
+    touchStrip?: ComponentType;
+} | {
+    dial?: ComponentType;
+    touchStrip: ComponentType;
+} : {
+    dial?: ComponentType;
+    touchStrip?: ComponentType;
+};
 export interface ActionConfig<S extends JsonObject = JsonObject> {
     uuid: string;
     key?: ComponentType;
     dial?: ComponentType;
-    /** Full-strip touchbar component. When set, replaces per-encoder `dial` display with a single shared React tree that spans the entire touch strip. */
-    touchBar?: ComponentType;
-    /** Target frame rate for the touchbar animation loop and render pipeline. Controls both `useTick` cadence (via `useTouchBar().fps`) and the render debounce. @default 60 */
-    touchBarFPS?: number;
+    /** Full-strip TouchStrip component. When set, replaces per-encoder `dial` display with a single shared React tree that spans the entire touch strip. */
+    touchStrip?: ComponentType;
     /** Encoder feedback layout. Defaults to a full-width `pixmap` canvas layout. Custom layouts should include a `pixmap` item keyed as `canvas`. */
     dialLayout?: EncoderLayout;
     wrapper?: WrapperComponent;
     defaultSettings?: Partial<S>;
 }
+/** Resolved action config shape. When `ManifestActions` is populated (via `streamdeck-env.d.ts`), this becomes a mapped type that iterates over every UUID in the manifest and produces a discriminated union. Each member intersects `KeySurface<UUID>` and `EncoderSurface<UUID>` to enforce controller-specific requirements. When `ManifestActions` is empty, it falls back to the permissive `ActionConfig<S>`. */
+export type ActionConfigInput<S extends JsonObject = JsonObject> = [keyof ManifestActions] extends [
+    never
+] ? ActionConfig<S> : {
+    [UUID in ActionUUID]: {
+        uuid: UUID;
+        /** Encoder feedback layout. Defaults to a full-width `pixmap` canvas layout. Custom layouts should include a `pixmap` item keyed as `canvas`. */
+        dialLayout?: EncoderLayout;
+        wrapper?: WrapperComponent;
+        defaultSettings?: Partial<S>;
+    } & KeySurface<UUID> & EncoderSurface<UUID>;
+}[ActionUUID];
 export interface ActionDefinition<S extends JsonObject = JsonObject> {
     uuid: string;
     key?: ComponentType;
     dial?: ComponentType;
-    /** Full-strip touchbar component. When set, replaces per-encoder `dial` display with a single shared React tree that spans the entire touch strip. */
-    touchBar?: ComponentType;
-    /** Target frame rate for the touchbar animation loop and render pipeline. @default 60 */
-    touchBarFPS?: number;
+    /** Full-strip TouchStrip component. When set, replaces per-encoder `dial` display with a single shared React tree that spans the entire touch strip. */
+    touchStrip?: ComponentType;
     /** Encoder feedback layout. Defaults to a full-width `pixmap` canvas layout. Custom layouts should include a `pixmap` item keyed as `canvas`. */
     dialLayout?: EncoderLayout;
     wrapper?: WrapperComponent;
@@ -104,7 +155,8 @@ export interface ActionDefinition<S extends JsonObject = JsonObject> {
 }
 export interface DeviceInfo {
     id: string;
-    type: DeviceType;
+    /** Numeric device type matching Elgato DeviceType enum values (e.g. 7 = StreamDeckPlus). */
+    type: number;
     size: Size;
     name: string;
 }
@@ -121,8 +173,8 @@ export interface CanvasInfo {
     type: "key" | "dial" | "touch";
 }
 export interface StreamDeckAccess {
-    action: Action | DialAction | KeyAction;
-    sdk: typeof import('@elgato/streamdeck').default;
+    action: AdapterActionHandle;
+    adapter: StreamDeckAdapter;
 }
 export interface KeyDownPayload {
     settings: JsonObject;
@@ -161,7 +213,7 @@ export interface DialHints {
     touch?: string;
     longTouch?: string;
 }
-export interface TouchBarInfo {
+export interface TouchStripInfo {
     /** Full render width in pixels (e.g., 800 for 4 encoders). */
     width: number;
     /** Strip height in pixels (always 100). */
@@ -170,22 +222,20 @@ export interface TouchBarInfo {
     columns: number[];
     /** Width of each encoder segment in pixels (always 200). */
     segmentWidth: number;
-    /** Target frame rate for the animation loop. Pass to `useTick` for matched cadence. */
-    fps: number;
 }
-export interface TouchBarTapPayload {
+export interface TouchStripTapPayload {
     /** Absolute tap position across the full strip width. */
     tapPos: [x: number, y: number];
     hold: boolean;
     /** The encoder column that was touched. */
     column: number;
 }
-export interface TouchBarDialRotatePayload {
+export interface TouchStripDialRotatePayload {
     column: number;
     ticks: number;
     pressed: boolean;
 }
-export interface TouchBarDialPressPayload {
+export interface TouchStripDialPressPayload {
     column: number;
 }
 export interface EventMap {
@@ -205,9 +255,9 @@ export interface EventMap {
         title: string;
         settings: JsonObject;
     };
-    touchBarTap: TouchBarTapPayload;
-    touchBarDialRotate: TouchBarDialRotatePayload;
-    touchBarDialDown: TouchBarDialPressPayload;
-    touchBarDialUp: TouchBarDialPressPayload;
+    touchStripTap: TouchStripTapPayload;
+    touchStripDialRotate: TouchStripDialRotatePayload;
+    touchStripDialDown: TouchStripDialPressPayload;
+    touchStripDialUp: TouchStripDialPressPayload;
 }
 export {};

package/dist/vite.d.ts

@@ -10,17 +10,31 @@ export interface StreamDeckReactOptions extends StreamDeckTargetOptions {
      * each successful build.
      */
     uuid?: string;
+    /**
+     * Path to the plugin `manifest.json`. When omitted, the plugin
+     * auto-detects by scanning the project root for a `*.sdPlugin/manifest.json`.
+     *
+     * Set to `false` to disable manifest type generation entirely.
+     */
+    manifest?: string | false;
 }
 /**
  * Vite plugin for Stream Deck React projects.
  *
- * - Inlines font files (`.ttf`, `.otf`, `.woff`, `.woff2`) imported by the
- *   project into the bundle as `Buffer` instances so no runtime filesystem
- *   access is needed.
- * - Copies platform-specific `@takumi-rs/core` native bindings (`.node` files)
- *   into the bundle output directory.
- * - Strips devtools code in production builds (non-watch mode).
- * - Optionally restarts the Stream Deck plugin after each build when
- *   {@link StreamDeckReactOptions.uuid} is provided.
+ * Responsibilities mapped to Vite lifecycle hooks:
+ *
+ *   configResolved  → detect dev/production mode, set strip flags
+ *   buildStart      → generate streamdeck-env.d.ts from manifest.json
+ *   resolveId       → redirect devtools imports (production) + font imports
+ *   load            → return noop devtools stub + inline font as base64 Buffer
+ *   writeBundle     → copy native .node bindings to output directory
+ *   closeBundle     → restart Stream Deck plugin (optional, via CLI)
+ *
+ * Font inlining:
+ *   `.ttf`, `.otf`, `.woff`, `.woff2` imports are resolved to absolute
+ *   paths and loaded as synthetic ES modules:
+ *     `export default Buffer.from("<base64>", "base64");`
+ *   This eliminates runtime filesystem access in the sandboxed
+ *   Stream Deck Node.js environment.
  */
 export declare function streamDeckReact(options?: StreamDeckReactOptions): Plugin;

package/dist/vite.js

@@ -1,19 +1,27 @@
 import { NOOP_DEVTOOLS_CODE, NOOP_DEVTOOLS_ID, copyNativeBindings, isLibraryDevtoolsImport, shouldStripDevtools } from "./bundler-shared.js";
 import { loadFont, resolveFontId } from "./font-inline.js";
+import { generateManifestTypes } from "./manifest-codegen.js";
 import { resolve } from "node:path";
 import { exec } from "node:child_process";
 //#region src/vite.ts
 /**
 * Vite plugin for Stream Deck React projects.
 *
-* - Inlines font files (`.ttf`, `.otf`, `.woff`, `.woff2`) imported by the
-*   project into the bundle as `Buffer` instances so no runtime filesystem
-*   access is needed.
-* - Copies platform-specific `@takumi-rs/core` native bindings (`.node` files)
-*   into the bundle output directory.
-* - Strips devtools code in production builds (non-watch mode).
-* - Optionally restarts the Stream Deck plugin after each build when
-*   {@link StreamDeckReactOptions.uuid} is provided.
+* Responsibilities mapped to Vite lifecycle hooks:
+*
+*   configResolved  → detect dev/production mode, set strip flags
+*   buildStart      → generate streamdeck-env.d.ts from manifest.json
+*   resolveId       → redirect devtools imports (production) + font imports
+*   load            → return noop devtools stub + inline font as base64 Buffer
+*   writeBundle     → copy native .node bindings to output directory
+*   closeBundle     → restart Stream Deck plugin (optional, via CLI)
+*
+* Font inlining:
+*   `.ttf`, `.otf`, `.woff`, `.woff2` imports are resolved to absolute
+*   paths and loaded as synthetic ES modules:
+*     `export default Buffer.from("<base64>", "base64");`
+*   This eliminates runtime filesystem access in the sandboxed
+*   Stream Deck Node.js environment.
 */
 function streamDeckReact(options = {}) {
 	let resolvedConfig;
@@ -29,6 +37,14 @@ function streamDeckReact(options = {}) {
 			isDevelopment = isWatch || process.env.NODE_ENV === "development";
 			stripDevtools = shouldStripDevtools(isWatch);
 		},
+		buildStart() {
+			const warn = (msg) => resolvedConfig.logger.warn(msg);
+			const result = generateManifestTypes(resolvedConfig.root, options.manifest, warn);
+			if (result) {
+				this.addWatchFile(result.manifestPath);
+				if (result.written) resolvedConfig.logger.info("[@fcannizzaro/streamdeck-react] Generated src/streamdeck-env.d.ts");
+			}
+		},
 		resolveId(source, importer) {
 			if (stripDevtools && isLibraryDevtoolsImport(source, importer)) return NOOP_DEVTOOLS_ID;
 			return resolveFontId(source, importer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcannizzaro/streamdeck-react",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Build Stream Deck plugins with React — render components directly to keys, dials, and touch screens",
   "keywords": [
     "elgato",
@@ -13,7 +13,7 @@
   "bugs": {
     "url": "https://github.com/fcannizzaro/streamdeck-react/issues"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": {
     "name": "Francesco Saverio Cannizzaro",
     "url": "https://github.com/fcannizzaro"
@@ -56,11 +56,10 @@
   },
   "scripts": {
     "build": "vite build",
-    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "bun test ./src"
   },
   "dependencies": {
-    "@elgato/streamdeck": "^2.0.2",
     "@takumi-rs/core": "^0.71.7",
     "@takumi-rs/helpers": "^0.71.7",
     "react-reconciler": "^0.33.0"
@@ -76,12 +75,16 @@
     "vite-plugin-dts": "^4.5.4"
   },
   "peerDependencies": {
+    "@elgato/streamdeck": "^2.0.2",
     "react": "^18.0.0 || ^19.0.0",
     "rollup": "^4.0.0",
     "typescript": "^5",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@elgato/streamdeck": {
+      "optional": true
+    },
     "rollup": {
       "optional": true
     },

package/dist/context/touchbar-context.d.ts

@@ -1,2 +0,0 @@
-import { TouchBarInfo } from '../types';
-export declare const TouchBarContext: import('react').Context<TouchBarInfo>;

package/dist/context/touchbar-context.js

@@ -1,5 +0,0 @@
-import { createContext } from "react";
-//#region src/context/touchbar-context.ts
-var TouchBarContext = createContext(null);
-//#endregion
-export { TouchBarContext };

package/dist/hooks/touchbar.d.ts

@@ -1,6 +0,0 @@
-import { TouchBarInfo, TouchBarTapPayload, TouchBarDialRotatePayload, TouchBarDialPressPayload } from '../types';
-export declare function useTouchBar(): TouchBarInfo;
-export declare function useTouchBarTap(callback: (payload: TouchBarTapPayload) => void): void;
-export declare function useTouchBarDialRotate(callback: (payload: TouchBarDialRotatePayload) => void): void;
-export declare function useTouchBarDialDown(callback: (payload: TouchBarDialPressPayload) => void): void;
-export declare function useTouchBarDialUp(callback: (payload: TouchBarDialPressPayload) => void): void;

package/dist/hooks/touchbar.js

@@ -1,37 +0,0 @@
-import { EventBusContext } from "../context/providers.js";
-import { TouchBarContext } from "../context/touchbar-context.js";
-import { useCallbackRef } from "./internal/useCallbackRef.js";
-import { useContext, useEffect } from "react";
-//#region src/hooks/touchbar.ts
-function useTouchBarEvent(event, callback) {
-	const bus = useContext(EventBusContext);
-	const callbackRef = useCallbackRef(callback);
-	useEffect(() => {
-		const handler = (payload) => {
-			callbackRef.current(payload);
-		};
-		bus.on(event, handler);
-		return () => bus.off(event, handler);
-	}, [
-		bus,
-		callbackRef,
-		event
-	]);
-}
-function useTouchBar() {
-	return useContext(TouchBarContext);
-}
-function useTouchBarTap(callback) {
-	useTouchBarEvent("touchBarTap", callback);
-}
-function useTouchBarDialRotate(callback) {
-	useTouchBarEvent("touchBarDialRotate", callback);
-}
-function useTouchBarDialDown(callback) {
-	useTouchBarEvent("touchBarDialDown", callback);
-}
-function useTouchBarDialUp(callback) {
-	useTouchBarEvent("touchBarDialUp", callback);
-}
-//#endregion
-export { useTouchBar, useTouchBarDialDown, useTouchBarDialRotate, useTouchBarDialUp, useTouchBarTap };

package/dist/roots/touchbar-root.js

@@ -1,175 +0,0 @@
-import { createVContainer } from "../reconciler/vnode.js";
-import { reconciler } from "../reconciler/renderer.js";
-import { renderToRaw, sliceToDataUri } from "../render/pipeline.js";
-import { EventBus } from "../context/event-bus.js";
-import { DeviceContext, EventBusContext, GlobalSettingsContext } from "../context/providers.js";
-import { TouchBarContext } from "../context/touchbar-context.js";
-import { createElement } from "react";
-//#region src/roots/touchbar-root.ts
-var SEGMENT_WIDTH = 200;
-var SEGMENT_HEIGHT = 100;
-var DEFAULT_TOUCHBAR_FPS = 60;
-var TouchBarRoot = class {
-	eventBus = new EventBus();
-	container;
-	fiberRoot;
-	columns = /* @__PURE__ */ new Map();
-	globalSettings;
-	setGlobalSettingsFn;
-	renderDebounceMs;
-	renderConfig;
-	deviceInfo;
-	disposed = false;
-	fps;
-	pluginWrapper;
-	/** Last rendered per-column data URIs. Used by devtools snapshots. */
-	lastSegmentUris = /* @__PURE__ */ new Map();
-	/** Exposes the VContainer for devtools inspection. */
-	get vcontainer() {
-		return this.container;
-	}
-	/** Sorted column numbers for devtools observer. */
-	get columnNumbers() {
-		return [...this.columns.keys()].sort((a, b) => a - b);
-	}
-	/** Column → actionId map for devtools observer. */
-	get columnActionMap() {
-		const map = /* @__PURE__ */ new Map();
-		for (const [col, entry] of this.columns) map.set(col, entry.actionId);
-		return map;
-	}
-	globalSettingsValue;
-	touchBarValue;
-	constructor(component, deviceInfo, initialGlobalSettings, renderConfig, renderDebounceMs, onGlobalSettingsChange, pluginWrapper, touchBarFPS) {
-		this.component = component;
-		this.deviceInfo = deviceInfo;
-		this.globalSettings = { ...initialGlobalSettings };
-		this.renderConfig = renderConfig;
-		this.fps = touchBarFPS ?? DEFAULT_TOUCHBAR_FPS;
-		this.renderDebounceMs = touchBarFPS != null ? Math.max(1, Math.round(1e3 / touchBarFPS)) : renderDebounceMs;
-		this.pluginWrapper = pluginWrapper;
-		this.setGlobalSettingsFn = (partial) => {
-			this.globalSettings = {
-				...this.globalSettings,
-				...partial
-			};
-			this.globalSettingsValue = {
-				settings: this.globalSettings,
-				setSettings: this.setGlobalSettingsFn
-			};
-			onGlobalSettingsChange(this.globalSettings);
-			this.scheduleRerender();
-		};
-		this.globalSettingsValue = {
-			settings: this.globalSettings,
-			setSettings: this.setGlobalSettingsFn
-		};
-		this.touchBarValue = {
-			width: 0,
-			height: SEGMENT_HEIGHT,
-			columns: [],
-			segmentWidth: SEGMENT_WIDTH,
-			fps: this.fps
-		};
-		this.container = createVContainer(() => {
-			this.flush();
-		});
-		this.fiberRoot = reconciler.createContainer(this.container, 0, null, false, null, "", (err) => {
-			console.error("[@fcannizzaro/streamdeck-react] TouchBar uncaught error:", err);
-		}, (err) => {
-			console.error("[@fcannizzaro/streamdeck-react] TouchBar caught error:", err);
-		}, (err) => {
-			console.error("[@fcannizzaro/streamdeck-react] TouchBar recoverable error:", err);
-		}, () => {});
-		this.eventBus.ownerId = `touchbar:${deviceInfo.id}`;
-	}
-	addColumn(column, actionId, sdkAction) {
-		this.columns.set(column, {
-			actionId,
-			sdkAction
-		});
-		this.updateTouchBarInfo();
-		this.scheduleRerender();
-	}
-	removeColumn(column) {
-		this.columns.delete(column);
-		if (this.columns.size === 0) return;
-		this.updateTouchBarInfo();
-		this.scheduleRerender();
-	}
-	get isEmpty() {
-		return this.columns.size === 0;
-	}
-	findColumnByActionId(actionId) {
-		for (const [column, entry] of this.columns) if (entry.actionId === actionId) return column;
-	}
-	updateTouchBarInfo() {
-		const sortedColumns = [...this.columns.keys()].sort((a, b) => a - b);
-		this.touchBarValue = {
-			width: (sortedColumns.length > 0 ? sortedColumns[sortedColumns.length - 1] + 1 : 0) * SEGMENT_WIDTH,
-			height: SEGMENT_HEIGHT,
-			columns: sortedColumns,
-			segmentWidth: SEGMENT_WIDTH,
-			fps: this.fps
-		};
-	}
-	render() {
-		if (this.disposed) return;
-		const element = this.buildTree();
-		reconciler.updateContainer(element, this.fiberRoot, null, () => {});
-	}
-	buildTree() {
-		let child = createElement(this.component);
-		if (this.pluginWrapper) child = createElement(this.pluginWrapper, null, child);
-		return createElement(TouchBarContext.Provider, { value: this.touchBarValue }, createElement(DeviceContext.Provider, { value: this.deviceInfo }, createElement(EventBusContext.Provider, { value: this.eventBus }, createElement(GlobalSettingsContext.Provider, { value: this.globalSettingsValue }, child))));
-	}
-	scheduleRerender() {
-		if (this.disposed) return;
-		this.render();
-	}
-	async flush() {
-		if (this.disposed) return;
-		if (this.renderDebounceMs > 0 && this.container.renderTimer !== null) clearTimeout(this.container.renderTimer);
-		if (this.renderDebounceMs > 0) this.container.renderTimer = setTimeout(async () => {
-			this.container.renderTimer = null;
-			await this.doFlush();
-		}, this.renderDebounceMs);
-		else await this.doFlush();
-	}
-	async doFlush() {
-		if (this.disposed || this.columns.size === 0) return;
-		try {
-			const width = this.touchBarValue.width;
-			if (width === 0) return;
-			const result = await renderToRaw(this.container, width, SEGMENT_HEIGHT, this.renderConfig);
-			if (result === null || this.disposed) return;
-			const feedbackPromises = [];
-			for (const [column, entry] of this.columns) {
-				const sliceUri = sliceToDataUri(result.buffer, result.width, result.height, column, SEGMENT_WIDTH, SEGMENT_HEIGHT);
-				this.lastSegmentUris.set(column, sliceUri);
-				feedbackPromises.push(entry.sdkAction.setFeedback({ canvas: sliceUri }));
-			}
-			await Promise.all(feedbackPromises);
-		} catch (err) {
-			console.error("[@fcannizzaro/streamdeck-react] TouchBar render error:", err);
-		}
-	}
-	updateGlobalSettings(settings) {
-		this.globalSettings = { ...settings };
-		this.globalSettingsValue = {
-			settings: this.globalSettings,
-			setSettings: this.setGlobalSettingsFn
-		};
-		this.scheduleRerender();
-	}
-	unmount() {
-		this.disposed = true;
-		if (this.container.renderTimer !== null) clearTimeout(this.container.renderTimer);
-		this.eventBus.emit("willDisappear", void 0);
-		reconciler.updateContainer(null, this.fiberRoot, null, () => {});
-		this.eventBus.removeAllListeners();
-		this.columns.clear();
-	}
-};
-//#endregion
-export { TouchBarRoot };