@fcannizzaro/streamdeck-react 0.1.9 → 0.1.11

package/dist/render/image-cache.js

@@ -0,0 +1,128 @@
+//#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_TOUCHSTRIP_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 native-format (WebP/PNG) renders. */
+var touchstripNativeCache = 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_TOUCHSTRIP_CACHE_MAX_BYTES);
+	return touchstripCache;
+}
+/**
+* Get or create the shared touchstrip native-format segment cache.
+* Stores sorted `[column, dataUri]` tuples per tree hash + column config.
+* Uses the same default budget as the raw touchstrip cache since only one
+* touchstrip rendering path is active at a time.
+*/
+function getTouchstripNativeCache(maxBytes) {
+	if (touchstripNativeCache == null) touchstripNativeCache = new ImageCache(maxBytes ?? DEFAULT_TOUCHSTRIP_CACHE_MAX_BYTES);
+	return touchstripNativeCache;
+}
+//#endregion
+export { getImageCache, getTouchstripCache, getTouchstripNativeCache };

package/dist/render/metrics.d.ts

@@ -0,0 +1,58 @@
+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 _cumFlushCount;
+    private _cumRenderCount;
+    private _cumCacheHitCount;
+    private _cumDirtySkipCount;
+    private _cumHashDedupCount;
+    private _cumTotalRenderMs;
+    private _cumPeakRenderMs;
+    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, never reset). */
+    snapshot(): RenderMetrics;
+    /** Log a summary to console (called periodically). */
+    private report;
+}
+export declare const metrics: MetricsCollector;
+export {};

package/dist/render/metrics.js

@@ -0,0 +1,101 @@
+import { getImageCache, getTouchstripCache, getTouchstripNativeCache } 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;
+	_cumFlushCount = 0;
+	_cumRenderCount = 0;
+	_cumCacheHitCount = 0;
+	_cumDirtySkipCount = 0;
+	_cumHashDedupCount = 0;
+	_cumTotalRenderMs = 0;
+	_cumPeakRenderMs = 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++;
+		this._cumFlushCount++;
+	}
+	/** Record a dirty-skip (container was clean). */
+	recordDirtySkip() {
+		this._dirtySkipCount++;
+		this._cumDirtySkipCount++;
+	}
+	/** Record an image cache hit. */
+	recordCacheHit() {
+		this._cacheHitCount++;
+		this._cumCacheHitCount++;
+	}
+	/** Record a post-render hash dedup (identical output). */
+	recordHashDedup() {
+		this._hashDedupCount++;
+		this._cumHashDedupCount++;
+	}
+	/** Record a completed render with its duration in milliseconds. */
+	recordRender(renderMs) {
+		this._renderCount++;
+		this._cumRenderCount++;
+		this._totalRenderMs += renderMs;
+		this._cumTotalRenderMs += renderMs;
+		if (renderMs > this._peakRenderMs) this._peakRenderMs = renderMs;
+		if (renderMs > this._cumPeakRenderMs) this._cumPeakRenderMs = renderMs;
+	}
+	/** Get current snapshot of all metrics (cumulative, never reset). */
+	snapshot() {
+		const imageStats = getImageCache().stats;
+		const touchstripStats = getTouchstripCache().stats;
+		const nativeStats = getTouchstripNativeCache().stats;
+		return {
+			flushCount: this._cumFlushCount,
+			renderCount: this._cumRenderCount,
+			cacheHitCount: this._cumCacheHitCount,
+			dirtySkipCount: this._cumDirtySkipCount,
+			hashDedupCount: this._cumHashDedupCount,
+			avgRenderMs: this._cumRenderCount > 0 ? this._cumTotalRenderMs / this._cumRenderCount : 0,
+			peakRenderMs: this._cumPeakRenderMs,
+			imageCacheBytes: imageStats.bytes,
+			touchstripCacheBytes: touchstripStats.bytes + nativeStats.bytes
+		};
+	}
+	/** Log a summary to console (called periodically). */
+	report() {
+		if (this._flushCount === 0) return;
+		const m = this.snapshot();
+		const skipRate = m.flushCount > 0 ? ((m.dirtySkipCount + m.cacheHitCount + m.hashDedupCount) / m.flushCount * 100).toFixed(1) : "0";
+		console.log(`[@fcannizzaro/streamdeck-react] Metrics (${REPORT_INTERVAL_MS / 1e3}s): flushes=${m.flushCount} renders=${m.renderCount} cacheHits=${m.cacheHitCount} dirtySkips=${m.dirtySkipCount} hashDedups=${m.hashDedupCount} skipRate=${skipRate}% avgRender=${m.avgRenderMs.toFixed(1)}ms peak=${m.peakRenderMs.toFixed(1)}ms imgCache=${(m.imageCacheBytes / 1024).toFixed(0)}KB tbCache=${(m.touchstripCacheBytes / 1024).toFixed(0)}KB`);
+		this._flushCount = 0;
+		this._renderCount = 0;
+		this._cacheHitCount = 0;
+		this._dirtySkipCount = 0;
+		this._hashDedupCount = 0;
+		this._totalRenderMs = 0;
+		this._peakRenderMs = 0;
+	}
+};
+var metrics = new MetricsCollector();
+//#endregion
+export { metrics };

package/dist/render/pipeline.d.ts

@@ -1,13 +1,56 @@
 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 {
+    vnodeToElementMs: number;
+    fromJsxMs: 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;
+    /** Image format for touchstrip segment encoding. @default "webp" */
+    touchstripImageFormat: OutputFormat;
     /** 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;
+/**
+ * Convert a container's VNode children to Takumi nodes.
+ * Used by the touchstrip native-format path to build the Takumi node tree
+ * once and share it across all N segment renders in a single flush.
+ */
+export declare function buildTakumiChildren(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 {
@@ -18,3 +61,5 @@ export interface RawRenderResult {
 export declare function renderToRaw(container: VContainer, width: number, height: number, config: RenderConfig): Promise<RawRenderResult | null>;
 export declare function cropSlice(raw: Buffer, fullWidth: number, column: number, segmentWidth: number, segmentHeight: number): Buffer;
 export declare function sliceToDataUri(raw: Buffer, fullWidth: number, fullHeight: number, column: number, segmentWidth: number, segmentHeight: number): string;
+export declare function sliceToDataUriAsync(raw: Buffer, fullWidth: number, fullHeight: number, column: number, segmentWidth: number, segmentHeight: number): Promise<string>;
+export declare function renderSegmentToDataUri(container: VContainer, fullWidth: number, segmentHeight: number, column: number, segmentWidth: number, format: OutputFormat, config: RenderConfig, prebuiltTakumiChildren?: TakumiNode[]): Promise<string | null>;