@fcannizzaro/streamdeck-react 0.1.10 → 0.1.12

package/dist/render/cache.js

@@ -1,15 +1,147 @@
 //#region src/render/cache.ts
+var FNV_OFFSET_BASIS = 2166136261;
+var FNV_PRIME = 16777619;
+var SENTINEL_NULL = 1314212940;
+var SENTINEL_UNDEF = 1431192646;
+var SENTINEL_NAN = 1314999841;
+var SENTINEL_TRUE = 1414681925;
+var SENTINEL_FALSE = 1178684499;
+var SENTINEL_ARRAY = 1095914073;
+var SENTINEL_OBJECT = 1329744468;
+var STRIDE_THRESHOLD = 4096;
+var STRIDE = 16;
+/**
+* Hash a raw byte buffer (Uint8Array or Buffer) or string.
+*
+* For buffers larger than {@link STRIDE_THRESHOLD} bytes, uses strided
+* FNV-1a sampling (every 16th byte) — at 30fps this adds <1ms even
+* for 320KB TouchStrip buffers.
+*
+* Strings and small buffers always use full byte-by-byte FNV-1a.
+*/
 function fnv1a(input) {
-	let hash = 2166136261;
+	let hash = FNV_OFFSET_BASIS;
 	if (typeof input === "string") for (let i = 0; i < input.length; i++) {
 		hash ^= input.charCodeAt(i);
-		hash = Math.imul(hash, 16777619);
+		hash = Math.imul(hash, FNV_PRIME);
 	}
-	else for (let i = 0; i < input.length; i++) {
+	else if (input.length > STRIDE_THRESHOLD) {
+		hash = fnv1aU32(input.length, hash);
+		for (let i = 0; i < input.length; i += STRIDE) {
+			const end = Math.min(i + 4, input.length);
+			for (let j = i; j < end; j++) {
+				hash ^= input[j];
+				hash = Math.imul(hash, FNV_PRIME);
+			}
+		}
+	} else for (let i = 0; i < input.length; i++) {
 		hash ^= input[i];
-		hash = Math.imul(hash, 16777619);
+		hash = Math.imul(hash, FNV_PRIME);
 	}
 	return hash >>> 0;
 }
+/** Feed a string into a running FNV-1a hash. */
+function fnv1aString(str, hash) {
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.charCodeAt(i);
+		hash = Math.imul(hash, FNV_PRIME);
+	}
+	return hash;
+}
+/** Feed a uint32 value into a running FNV-1a hash (4 bytes, big-endian). */
+function fnv1aU32(value, hash) {
+	hash ^= value >>> 24 & 255;
+	hash = Math.imul(hash, FNV_PRIME);
+	hash ^= value >>> 16 & 255;
+	hash = Math.imul(hash, FNV_PRIME);
+	hash ^= value >>> 8 & 255;
+	hash = Math.imul(hash, FNV_PRIME);
+	hash ^= value & 255;
+	hash = Math.imul(hash, FNV_PRIME);
+	return hash;
+}
+var MAX_HASH_DEPTH = 10;
+/** Hash an arbitrary JS value into a running FNV-1a hash. */
+function hashValue(value, hash, depth = 0) {
+	if (depth > MAX_HASH_DEPTH) return hash;
+	if (value === null) return fnv1aU32(SENTINEL_NULL, hash);
+	if (value === void 0) return fnv1aU32(SENTINEL_UNDEF, hash);
+	switch (typeof value) {
+		case "string": return fnv1aString(value, hash);
+		case "number":
+			if (Number.isNaN(value)) return fnv1aU32(SENTINEL_NAN, hash);
+			return fnv1aString(String(value), hash);
+		case "boolean": return fnv1aU32(value ? SENTINEL_TRUE : SENTINEL_FALSE, hash);
+		case "function":
+		case "symbol": return hash;
+		case "object": {
+			if (Array.isArray(value)) {
+				hash = fnv1aU32(SENTINEL_ARRAY, hash);
+				hash = fnv1aU32(value.length, hash);
+				for (let i = 0; i < value.length; i++) hash = hashValue(value[i], hash, depth + 1);
+				return hash;
+			}
+			hash = fnv1aU32(SENTINEL_OBJECT, hash);
+			const keys = Object.keys(value).sort();
+			hash = fnv1aU32(keys.length, hash);
+			for (const key of keys) {
+				const v = value[key];
+				if (typeof v === "function" || typeof v === "symbol") continue;
+				hash = fnv1aString(key, hash);
+				hash = hashValue(v, hash, depth + 1);
+			}
+			return hash;
+		}
+		default: return fnv1aString(String(value), hash);
+	}
+}
+/**
+* Compute (or return cached) Merkle hash for a single VNode.
+* The hash incorporates: type, text, props (sorted, functions skipped),
+* children count, and children hashes (recursive).
+*/
+function computeHash(node) {
+	if (node._hashValid && node._hash !== void 0) return node._hash;
+	let hash = FNV_OFFSET_BASIS;
+	hash = fnv1aString(node.type, hash);
+	if (node.text !== void 0) hash = fnv1aString(node.text, hash);
+	const keys = node._sortedPropKeys ??= Object.keys(node.props).sort();
+	for (const key of keys) {
+		const value = node.props[key];
+		if (typeof value === "function" || typeof value === "symbol") continue;
+		hash = fnv1aString(key, hash);
+		hash = hashValue(value, hash);
+	}
+	hash = fnv1aU32(node.children.length, hash);
+	for (const child of node.children) hash = fnv1aU32(computeHash(child), hash);
+	node._hash = hash >>> 0;
+	node._hashValid = true;
+	return node._hash;
+}
+/**
+* Compute the Merkle hash for an entire VContainer tree.
+* Returns 0 for empty containers.
+*/
+function computeTreeHash(container) {
+	if (container.children.length === 0) return 0;
+	let hash = FNV_OFFSET_BASIS;
+	hash = fnv1aU32(container.children.length, hash);
+	for (const child of container.children) hash = fnv1aU32(computeHash(child), hash);
+	return hash >>> 0;
+}
+function computeCacheKey(treeHash, width, height, dpr, format) {
+	let key = treeHash;
+	key = fnv1aU32(width, key);
+	key = fnv1aU32(height, key);
+	key = fnv1aU32(Math.round(dpr * 100), key);
+	key = fnv1aString(format, key);
+	return key >>> 0;
+}
+function computeTouchStripSegmentCacheKey(treeHash, width, height, dpr, columns) {
+	let key = computeCacheKey(treeHash, width, height, dpr, "png");
+	key = fnv1aU32(columns.length, key);
+	for (const col of columns) key = fnv1aU32(col, key);
+	return key >>> 0;
+}
 //#endregion
-export { fnv1a };
+export { computeCacheKey, computeTouchStripSegmentCacheKey, computeTreeHash, fnv1a };

package/dist/render/image-cache.d.ts

@@ -0,0 +1,54 @@
+export interface CacheStats {
+    /** Number of entries currently in the cache. */
+    entries: number;
+    /** Current memory usage in bytes. */
+    bytes: number;
+    /** Maximum memory budget in bytes. */
+    maxBytes: number;
+    /** Total cache hits since creation or last reset. */
+    hits: number;
+    /** Total cache misses since creation or last reset. */
+    misses: number;
+}
+/**
+ * Byte-bounded LRU cache. Evicts least-recently-used entries when the
+ * total byte size exceeds `maxBytes`.
+ *
+ * Generic over value type: use `string` for data URI caching (keys/dials),
+ * `Buffer` for raw RGBA caching (TouchStrip).
+ */
+export declare class ImageCache<V = string> {
+    private maxBytes;
+    private map;
+    private head;
+    private tail;
+    private currentBytes;
+    private _hits;
+    private _misses;
+    constructor(maxBytes: number);
+    /** Retrieve a cached value. Returns `undefined` on miss. Promotes to MRU on hit. */
+    get(key: number): V | undefined;
+    /** Insert or update a cache entry. Evicts LRU entries if over budget. */
+    set(key: number, value: V, byteSize: number): void;
+    /** Clear all entries and reset stats. */
+    clear(): void;
+    /** Current cache statistics. */
+    get stats(): CacheStats;
+    private moveToHead;
+    private evictTail;
+    private evictUntilUnderBudget;
+}
+/** Get or create the shared image cache for data URIs. */
+export declare function getImageCache(maxBytes?: number): ImageCache<string>;
+/** Get or create the shared TouchStrip raw buffer cache. */
+export declare function getTouchStripCache(maxBytes?: number): ImageCache<Buffer>;
+/**
+ * Get or create the shared TouchStrip segment URI cache.
+ * Stores sorted `[column, dataUri]` tuples per tree hash + column config.
+ */
+export declare function getTouchStripSegmentCache(maxBytes?: number): ImageCache<Array<[number, string]>>;
+export declare function getImageCacheStats(): CacheStats;
+export declare function getTouchStripCacheStats(): CacheStats;
+export declare function getTouchStripSegmentCacheStats(): CacheStats;
+/** Reset all caches (for testing or config changes). */
+export declare function resetCaches(): void;

package/dist/render/image-cache.js

@@ -0,0 +1,144 @@
+//#region src/render/image-cache.ts
+/**
+* Byte-bounded LRU cache. Evicts least-recently-used entries when the
+* total byte size exceeds `maxBytes`.
+*
+* Generic over value type: use `string` for data URI caching (keys/dials),
+* `Buffer` for raw RGBA caching (TouchStrip).
+*/
+var ImageCache = class {
+	map = /* @__PURE__ */ new Map();
+	head = null;
+	tail = null;
+	currentBytes = 0;
+	_hits = 0;
+	_misses = 0;
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	/** Retrieve a cached value. Returns `undefined` on miss. Promotes to MRU on hit. */
+	get(key) {
+		const entry = this.map.get(key);
+		if (entry == null) {
+			this._misses++;
+			return;
+		}
+		this._hits++;
+		this.moveToHead(entry);
+		return entry.value;
+	}
+	/** Insert or update a cache entry. Evicts LRU entries if over budget. */
+	set(key, value, byteSize) {
+		const existing = this.map.get(key);
+		if (existing != null) {
+			this.currentBytes -= existing.byteSize;
+			existing.value = value;
+			existing.byteSize = byteSize;
+			this.currentBytes += byteSize;
+			this.moveToHead(existing);
+			this.evictUntilUnderBudget();
+			return;
+		}
+		while (this.currentBytes + byteSize > this.maxBytes && this.tail != null) this.evictTail();
+		if (byteSize > this.maxBytes) return;
+		const entry = {
+			key,
+			value,
+			byteSize,
+			prev: null,
+			next: this.head
+		};
+		if (this.head != null) this.head.prev = entry;
+		this.head = entry;
+		if (this.tail == null) this.tail = entry;
+		this.map.set(key, entry);
+		this.currentBytes += byteSize;
+	}
+	/** Clear all entries and reset stats. */
+	clear() {
+		this.map.clear();
+		this.head = null;
+		this.tail = null;
+		this.currentBytes = 0;
+		this._hits = 0;
+		this._misses = 0;
+	}
+	/** Current cache statistics. */
+	get stats() {
+		return {
+			entries: this.map.size,
+			bytes: this.currentBytes,
+			maxBytes: this.maxBytes,
+			hits: this._hits,
+			misses: this._misses
+		};
+	}
+	moveToHead(entry) {
+		if (entry === this.head) return;
+		if (entry.prev != null) entry.prev.next = entry.next;
+		if (entry.next != null) entry.next.prev = entry.prev;
+		if (entry === this.tail) this.tail = entry.prev;
+		entry.prev = null;
+		entry.next = this.head;
+		if (this.head != null) this.head.prev = entry;
+		this.head = entry;
+	}
+	evictTail() {
+		if (this.tail == null) return;
+		const evicted = this.tail;
+		this.tail = evicted.prev;
+		if (this.tail != null) this.tail.next = null;
+		else this.head = null;
+		this.currentBytes -= evicted.byteSize;
+		this.map.delete(evicted.key);
+	}
+	evictUntilUnderBudget() {
+		while (this.currentBytes > this.maxBytes && this.tail != null) this.evictTail();
+	}
+};
+var DEFAULT_IMAGE_CACHE_MAX_BYTES = 16 * 1024 * 1024;
+var DEFAULT_TOUCH_STRIP_CACHE_MAX_BYTES = 8 * 1024 * 1024;
+/** Shared image cache for key/dial data URIs. */
+var imageCache = null;
+/** Shared raw buffer cache for TouchStrip RGBA data. */
+var touchStripCache = null;
+/** Shared segment URI cache for TouchStrip shared-strip renders. */
+var touchStripSegmentCache = null;
+/** Get or create the shared image cache for data URIs. */
+function getImageCache(maxBytes) {
+	if (imageCache == null) imageCache = new ImageCache(maxBytes ?? DEFAULT_IMAGE_CACHE_MAX_BYTES);
+	return imageCache;
+}
+/** Get or create the shared TouchStrip raw buffer cache. */
+function getTouchStripCache(maxBytes) {
+	if (touchStripCache == null) touchStripCache = new ImageCache(maxBytes ?? DEFAULT_TOUCH_STRIP_CACHE_MAX_BYTES);
+	return touchStripCache;
+}
+/**
+* Get or create the shared TouchStrip segment URI cache.
+* Stores sorted `[column, dataUri]` tuples per tree hash + column config.
+*/
+function getTouchStripSegmentCache(maxBytes) {
+	if (touchStripSegmentCache == null) touchStripSegmentCache = new ImageCache(maxBytes ?? DEFAULT_TOUCH_STRIP_CACHE_MAX_BYTES);
+	return touchStripSegmentCache;
+}
+function createEmptyStats(maxBytes) {
+	return {
+		entries: 0,
+		bytes: 0,
+		maxBytes,
+		hits: 0,
+		misses: 0
+	};
+}
+function getImageCacheStats() {
+	return imageCache?.stats ?? createEmptyStats(DEFAULT_IMAGE_CACHE_MAX_BYTES);
+}
+function getTouchStripCacheStats() {
+	return touchStripCache?.stats ?? createEmptyStats(DEFAULT_TOUCH_STRIP_CACHE_MAX_BYTES);
+}
+function getTouchStripSegmentCacheStats() {
+	return touchStripSegmentCache?.stats ?? createEmptyStats(DEFAULT_TOUCH_STRIP_CACHE_MAX_BYTES);
+}
+//#endregion
+export { getImageCache, getImageCacheStats, getTouchStripCache, getTouchStripCacheStats, getTouchStripSegmentCache, getTouchStripSegmentCacheStats };

package/dist/render/metrics.d.ts

@@ -0,0 +1,57 @@
+export interface RenderMetrics {
+    /** Total flush() calls (render attempts). */
+    flushCount: number;
+    /** Flushes that reached the Takumi renderer. */
+    renderCount: number;
+    /** Tree hash cache hits (Phase 3). */
+    cacheHitCount: number;
+    /** Skipped due to clean tree — dirty flag check (Phase 2). */
+    dirtySkipCount: number;
+    /** Skipped due to identical output — post-render FNV-1a dedup. */
+    hashDedupCount: number;
+    /** Average Takumi render time in milliseconds. */
+    avgRenderMs: number;
+    /** Peak (worst-case) render time in milliseconds. */
+    peakRenderMs: number;
+    /** Image cache memory usage in bytes. */
+    imageCacheBytes: number;
+    /** TouchStrip cache memory usage in bytes. */
+    touchStripCacheBytes: number;
+}
+declare class MetricsCollector {
+    private _flushCount;
+    private _renderCount;
+    private _cacheHitCount;
+    private _dirtySkipCount;
+    private _hashDedupCount;
+    private _totalRenderMs;
+    private _peakRenderMs;
+    private _lastFlush;
+    private _lastRender;
+    private _lastCacheHit;
+    private _lastDirtySkip;
+    private _lastHashDedup;
+    private _lastTotalRenderMs;
+    private _reportTimer;
+    private _enabled;
+    /** Enable periodic reporting. Call once during plugin init in debug mode. */
+    enable(): void;
+    /** Disable periodic reporting and clear the timer. */
+    disable(): void;
+    /** Record a flush attempt (before any skip checks). */
+    recordFlush(): void;
+    /** Record a dirty-skip (container was clean). */
+    recordDirtySkip(): void;
+    /** Record an image cache hit. */
+    recordCacheHit(): void;
+    /** Record a post-render hash dedup (identical output). */
+    recordHashDedup(): void;
+    /** Record a completed render with its duration in milliseconds. */
+    recordRender(renderMs: number): void;
+    /** Get current snapshot of all metrics (cumulative). */
+    snapshot(): RenderMetrics;
+    /** Log a summary to console (called periodically). Computes deltas since last report. */
+    private report;
+}
+export declare const metrics: MetricsCollector;
+export {};

package/dist/render/metrics.js

@@ -0,0 +1,98 @@
+import { getImageCacheStats, getTouchStripCacheStats, getTouchStripSegmentCacheStats } from "./image-cache.js";
+//#region src/render/metrics.ts
+var REPORT_INTERVAL_MS = 1e4;
+var MetricsCollector = class {
+	_flushCount = 0;
+	_renderCount = 0;
+	_cacheHitCount = 0;
+	_dirtySkipCount = 0;
+	_hashDedupCount = 0;
+	_totalRenderMs = 0;
+	_peakRenderMs = 0;
+	_lastFlush = 0;
+	_lastRender = 0;
+	_lastCacheHit = 0;
+	_lastDirtySkip = 0;
+	_lastHashDedup = 0;
+	_lastTotalRenderMs = 0;
+	_reportTimer = null;
+	_enabled = false;
+	/** Enable periodic reporting. Call once during plugin init in debug mode. */
+	enable() {
+		if (this._enabled) return;
+		this._enabled = true;
+		this._reportTimer = setInterval(() => {
+			this.report();
+		}, REPORT_INTERVAL_MS);
+		if (typeof this._reportTimer === "object" && "unref" in this._reportTimer) this._reportTimer.unref();
+	}
+	/** Disable periodic reporting and clear the timer. */
+	disable() {
+		if (this._reportTimer != null) {
+			clearInterval(this._reportTimer);
+			this._reportTimer = null;
+		}
+		this._enabled = false;
+	}
+	/** Record a flush attempt (before any skip checks). */
+	recordFlush() {
+		this._flushCount++;
+	}
+	/** Record a dirty-skip (container was clean). */
+	recordDirtySkip() {
+		this._dirtySkipCount++;
+	}
+	/** Record an image cache hit. */
+	recordCacheHit() {
+		this._cacheHitCount++;
+	}
+	/** Record a post-render hash dedup (identical output). */
+	recordHashDedup() {
+		this._hashDedupCount++;
+	}
+	/** Record a completed render with its duration in milliseconds. */
+	recordRender(renderMs) {
+		this._renderCount++;
+		this._totalRenderMs += renderMs;
+		if (renderMs > this._peakRenderMs) this._peakRenderMs = renderMs;
+	}
+	/** Get current snapshot of all metrics (cumulative). */
+	snapshot() {
+		const imageStats = getImageCacheStats();
+		const touchStripStats = getTouchStripCacheStats();
+		const segmentStats = getTouchStripSegmentCacheStats();
+		return {
+			flushCount: this._flushCount,
+			renderCount: this._renderCount,
+			cacheHitCount: this._cacheHitCount,
+			dirtySkipCount: this._dirtySkipCount,
+			hashDedupCount: this._hashDedupCount,
+			avgRenderMs: this._renderCount > 0 ? this._totalRenderMs / this._renderCount : 0,
+			peakRenderMs: this._peakRenderMs,
+			imageCacheBytes: imageStats.bytes,
+			touchStripCacheBytes: touchStripStats.bytes + segmentStats.bytes
+		};
+	}
+	/** Log a summary to console (called periodically). Computes deltas since last report. */
+	report() {
+		const dFlush = this._flushCount - this._lastFlush;
+		if (dFlush === 0) return;
+		const dRender = this._renderCount - this._lastRender;
+		const dCacheHit = this._cacheHitCount - this._lastCacheHit;
+		const dDirtySkip = this._dirtySkipCount - this._lastDirtySkip;
+		const dHashDedup = this._hashDedupCount - this._lastHashDedup;
+		const dTotalMs = this._totalRenderMs - this._lastTotalRenderMs;
+		const skipRate = dFlush > 0 ? ((dDirtySkip + dCacheHit + dHashDedup) / dFlush * 100).toFixed(1) : "0";
+		const avgMs = dRender > 0 ? (dTotalMs / dRender).toFixed(1) : "0.0";
+		console.log(`[@fcannizzaro/streamdeck-react] Metrics (${REPORT_INTERVAL_MS / 1e3}s): flushes=${dFlush} renders=${dRender} cacheHits=${dCacheHit} dirtySkips=${dDirtySkip} hashDedups=${dHashDedup} skipRate=${skipRate}% avgRender=${avgMs}ms peak=${this._peakRenderMs.toFixed(1)}ms imgCache=${(getImageCacheStats().bytes / 1024).toFixed(0)}KB tbCache=${((getTouchStripCacheStats().bytes + getTouchStripSegmentCacheStats().bytes) / 1024).toFixed(0)}KB`);
+		this._lastFlush = this._flushCount;
+		this._lastRender = this._renderCount;
+		this._lastCacheHit = this._cacheHitCount;
+		this._lastDirtySkip = this._dirtySkipCount;
+		this._lastHashDedup = this._hashDedupCount;
+		this._lastTotalRenderMs = this._totalRenderMs;
+	}
+};
+var metrics = new MetricsCollector();
+//#endregion
+export { metrics };

package/dist/render/pipeline.d.ts

@@ -1,13 +1,48 @@
 import { Renderer, OutputFormat } from '@takumi-rs/core';
-import { VContainer } from '../reconciler/vnode';
+import { Node as TakumiNode } from '@takumi-rs/helpers';
+import { VContainer, VNode } from '../reconciler/vnode';
+import { CacheStats } from './image-cache';
+import { RenderPool } from './render-pool';
+/** Per-render timing and diagnostic data exposed via `RenderConfig.onProfile`. */
+export interface RenderProfile {
+    /** Time to convert VNode tree to Takumi node tree (ms). */
+    vnodeConversionMs: number;
+    takumiRenderMs: number;
+    hashMs: number;
+    base64Ms: number;
+    totalMs: number;
+    skipped: boolean;
+    /** Whether this render was served from the image cache. */
+    cacheHit: boolean;
+    treeDepth: number;
+    nodeCount: number;
+    /** Image cache statistics at the time of this render. */
+    cacheStats: CacheStats | null;
+}
 export interface RenderConfig {
     renderer: Renderer;
     imageFormat: OutputFormat;
     caching: boolean;
     devicePixelRatio: number;
+    /** Enable performance diagnostics (duplicate detection, depth warnings). */
+    debug: boolean;
+    /** Maximum image cache size in bytes. Set to 0 to disable. @default 16777216 (16 MB) */
+    imageCacheMaxBytes: number;
+    /** Maximum TouchStrip cache size in bytes. Set to 0 to disable. @default 8388608 (8 MB) */
+    touchStripCacheMaxBytes: number;
+    /** Worker thread pool for offloading Takumi renders. null = main-thread rendering. */
+    renderPool: RenderPool | null;
     /** DevTools callback. Called after a non-null render with the container and data URI. */
     onRender?: (container: VContainer, dataUri: string) => void;
+    /** Profiling callback. Called after every renderToDataUri / renderToRaw attempt. */
+    onProfile?: (profile: RenderProfile) => void;
 }
+/** Build the root Takumi container wrapping the VNode children. */
+export declare function buildTakumiRoot(container: VContainer): TakumiNode;
+export declare function measureTree(nodes: VNode[]): {
+    depth: number;
+    count: number;
+};
 export declare function bufferToDataUri(buffer: Buffer | Uint8Array, format: string): string;
 export declare function renderToDataUri(container: VContainer, width: number, height: number, config: RenderConfig): Promise<string | null>;
 export interface RawRenderResult {