@camstack/addon-pipeline 1.1.70 → 1.2.0

package/dist/session-decode/decode-worker-child.js

@@ -517,6 +517,87 @@ var NativeLeaseStore = class {
 	}
 };
 //#endregion
+//#region src/session-decode/pinned-rgb-crop.ts
+/**
+* Pure decision/plumbing helpers for the `pinnedRgbCrop` native-crop color fix
+* (DEFAULT OFF — see `CAMSTACK_SESSION_PINNED_RGB_CROP` in `decode-worker-child.ts`).
+*
+* ## The bug this fixes
+*
+* On a HARDWARE decode session the FULL-frame download pins its YUV→RGB
+* conversion to the resolved `(matrix, range)` on the GPU filtergraph
+* (`buildGpuFilterDescription` → `colorConvertFilterOptions`). The native-CROP
+* survival path, however, retains the frame as **YUV420P** and later converts
+* it to RGB with a CPU `SoftwareScaleContext` that node-av exposes NO
+* colorspace-pinning surface for — so it falls back to libswscale's own default
+* coefficients. When the stream carries NO color-matrix metadata
+* (`colorSpace = UNSPECIFIED`, e.g. cam 617), the full frame (pinned bt709/
+* limited via {@link resolveSourceColor}'s defaults) and the crop (CPU-sws
+* default) can resolve DIFFERENTLY → the crop gets a wrong hue / desaturation
+* while the full frame looks right.
+*
+* ## The fix (retain-once-in-pinned-RGB)
+*
+* When the flag is on, the HW→system lease download converts to RGB24 ONCE,
+* pinned to the SAME resolved `(matrix, range)` the full-frame path uses. The
+* later crop is then a pure SPATIAL RGB24→RGB24 crop + resize with NO color
+* math, so it cannot re-resolve color differently than the full frame.
+*
+* These helpers are the PURE decision surface (filter description, cache keys,
+* RAM-budget size) so the plumbing is unit-testable without node-av / ffmpeg.
+* The software-DEGRADE path stays YUV420P (its full frame + crop both use the
+* CPU-sws default, so there is no mismatch to fix there).
+*/
+/**
+* The full-frame GPU→system download filtergraph description.
+*
+* - `color === null` (flag OFF / legacy): download to YUV420P, NO color convert
+*   — byte-for-byte the historical `scale=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`.
+* - `color !== null` (flag ON): pin the SAME resolved src matrix/range + full-
+*   range RGB output the full-frame path pins, converting to rgb24 in one pass.
+*/
+function buildLeaseDownloadDescription(scaleFilter, color) {
+	if (color) return `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,scale=${colorConvertFilterOptions(color)},format=rgb24`;
+	return `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+}
+/**
+* Cache key for the lease-download filtergraph. Flag OFF returns the historical
+* `${srcW}x${srcH}` key byte-for-byte; flag ON folds the resolved color in so a
+* mid-session colorspace/range change rebuilds the pinned-convert graph instead
+* of reusing one pinned to the old color.
+*/
+function leaseDownloadFilterKey(srcW, srcH, color) {
+	return color ? `${srcW}x${srcH}:rgb:${sourceColorKey(color)}` : `${srcW}x${srcH}`;
+}
+/**
+* Cache key for the dedicated native-crop software scaler. YUV420P (flag OFF /
+* degrade) returns the historical `${srcW}x${srcH}->${dstW}x${dstH}` key
+* byte-for-byte; the RGB24 (flag ON) scaler carries an `rgb:` prefix so an RGB
+* scaler and a YUV scaler of identical geometry never alias the same cache slot.
+*/
+function nativeCropScalerKey(srcW, srcH, dstW, dstH, rgb24) {
+	const base = `${srcW}x${srcH}->${dstW}x${dstH}`;
+	return rgb24 ? `rgb:${base}` : base;
+}
+/**
+* Approximate resident bytes of a retained software frame, for the lease
+* RAM-budget tally. RGB24 packs 3 bytes/px (~2x YUV420P's 1.5) — the documented
+* cost of pinned-RGB retention.
+*/
+function retainedFrameBytes(width, height, rgb24) {
+	return rgb24 ? width * height * 3 : Math.ceil(width * height * 1.5);
+}
+/**
+* Byte offset into a PACKED RGB24 plane for a crop origin — the pure spatial
+* math the `pinnedRgbCrop` crop uses to zero-copy view the ROI. Packed RGB24 is
+* a single plane at 3 bytes/px with NO chroma subsampling, so the offset is a
+* plain `top*stride + left*3` — no half-plane arithmetic and, critically, no
+* color conversion (that already happened, pinned, at download time).
+*/
+function rgbCropSourceOffset(top, left, stride) {
+	return top * stride + left * 3;
+}
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -546,7 +627,19 @@ var NativeLeaseStore = class {
 function toLeasedNavFrame(frame) {
 	return {
 		frame,
-		byteLength: Math.ceil(frame.width * frame.height * 1.5),
+		byteLength: retainedFrameBytes(frame.width, frame.height, false),
+		free: () => frame.free()
+	};
+}
+/**
+* Wrap a software RGB24 frame as a lease entry (byte size = w×h×3) — the
+* `pinnedRgbCrop` path. Kept separate from {@link toLeasedNavFrame} so the
+* flag-off YUV420P wrap is untouched.
+*/
+function toLeasedRgbNavFrame(frame) {
+	return {
+		frame,
+		byteLength: retainedFrameBytes(frame.width, frame.height, true),
 		free: () => frame.free()
 	};
 }
@@ -611,6 +704,35 @@ var NATIVE_LEASE_ACTIVITY_WINDOW_MS = (() => {
 	return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 15e3;
 })();
 /**
+* `pinnedRgbCrop` — pinned-color RGB24 native-crop retention. DEFAULT **ON**
+* (2026-07-20 rollout); set `CAMSTACK_SESSION_PINNED_RGB_CROP=0` to opt out.
+*
+* ## What it fixes
+* On a HARDWARE session the full-frame download pins its YUV→RGB conversion to
+* the resolved `(matrix, range)` on the GPU filtergraph, but the native-CROP
+* lease path retains the frame as YUV420P and later converts it with a CPU
+* `SoftwareScaleContext` that node-av gives NO colorspace-pinning surface for —
+* so the crop falls back to libswscale's default coefficients. On a stream with
+* NO color-matrix metadata (`colorSpace = UNSPECIFIED`, e.g. cam 617) the full
+* frame (pinned bt709/limited by {@link resolveSourceColor}'s defaults) and the
+* crop (CPU-sws default) can resolve DIFFERENTLY → the crop gets a wrong hue /
+* desaturation while the full frame looks right.
+*
+* ## What it does when ON
+* The HW→system lease download converts to RGB24 ONCE, pinned to the SAME
+* resolved color the full-frame path uses (see {@link buildLeaseDownloadDescription});
+* the later crop is then a pure SPATIAL RGB24→RGB24 crop + resize with no color
+* math (see {@link nativeScaleCropToBuffer}'s RGB branch), so it cannot diverge.
+*
+* ## Cost
+* A retained RGB24 frame is ~2x the RAM of YUV420P (3 vs 1.5 bytes/px — ~6.2 vs
+* ~3.1 MB per 1080p frame). Retention stays DEMAND-GATED by {@link leaseGate},
+* so cameras nothing is cropping retain nothing regardless of this flag. The
+* software-DEGRADE path is left on YUV420P (its full frame + crop both use the
+* CPU-sws default, so there is no mismatch to fix there).
+*/
+var PINNED_RGB_CROP = process.env["CAMSTACK_SESSION_PINNED_RGB_CROP"] !== "0";
+/**
 * The libav GPU scale filter for a hwaccel backend, or `null` when none is
 * known here — those backends fall back to the software crop+scale path.
 * Mirrors `addon-decoder-ffmpeg/src/ffmpeg-args.ts` `gpuScaleFilterForBackend`.
@@ -1148,7 +1270,7 @@ var DecodeWorkerChild = class {
 			const software = this.downloadToSoftware(frame);
 			frame.free();
 			if (!software) return true;
-			this.leaseStore.put(frameId, toLeasedNavFrame(software));
+			this.leaseStore.put(frameId, PINNED_RGB_CROP ? toLeasedRgbNavFrame(software) : toLeasedNavFrame(software));
 			return true;
 		}
 		this.leaseStore.put(frameId, toLeasedNavFrame(frame));
@@ -1165,7 +1287,9 @@ var DecodeWorkerChild = class {
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) return null;
 		try {
-			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height).processAllSync(frame);
+			const color = PINNED_RGB_CROP ? this.resolveFrameColor(frame) : null;
+			if (color) this.logColorProvenance("hw-crop", color);
+			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height, color).processAllSync(frame);
 			const first = outputs[0] ?? null;
 			for (let i = 1; i < outputs.length; i++) outputs[i]?.free();
 			return first;
@@ -1179,9 +1303,17 @@ var DecodeWorkerChild = class {
 			return null;
 		}
 	}
-	/** Build-once / reuse the full-frame GPU→system YUV420P download filtergraph. */
-	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH) {
-		const key = `${srcW}x${srcH}`;
+	/**
+	* Build-once / reuse the full-frame GPU→system download filtergraph.
+	*
+	* - `color === null` (flag OFF): YUV420P download, byte-for-byte the historical
+	*   `scale=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p` + `${srcW}x${srcH}` key.
+	* - `color !== null` (flag ON): pinned-color RGB24 download; the resolved color
+	*   is folded into the cache key so a mid-session colorspace/range change
+	*   rebuilds the graph instead of reusing one pinned to the old color.
+	*/
+	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH, color) {
+		const key = leaseDownloadFilterKey(srcW, srcH, color);
 		const cached = this.nativeLeaseDownloadFilter;
 		if (cached && key === this.nativeLeaseDownloadFilterKey) {
 			this.leaseDownloadFilterUses++;
@@ -1190,7 +1322,7 @@ var DecodeWorkerChild = class {
 		this.nativeLeaseDownloadFilter?.close();
 		this.nativeLeaseDownloadFilter = null;
 		this.nativeLeaseDownloadFilterKey = "";
-		const description = `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+		const description = buildLeaseDownloadDescription(scaleFilter, color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.nativeLeaseDownloadFilter = filter;
 		this.nativeLeaseDownloadFilterKey = key;
@@ -1212,6 +1344,7 @@ var DecodeWorkerChild = class {
 		const nav = this.nav;
 		const C = this.consts;
 		if (!nav || !C) throw new Error("node-av not initialized");
+		if (frame.format === C.AV_PIX_FMT_RGB24) return this.nativeRgbCropToBuffer(nav, C, frame, resolved);
 		this.logColorProvenance("sw-crop", this.resolveFrameColor(frame));
 		const { region, target } = resolved;
 		const planes = frame.data;
@@ -1225,7 +1358,7 @@ var DecodeWorkerChild = class {
 		const ySlice = yPlane.subarray(region.top * yStride + region.left);
 		const uSlice = uPlane.subarray(region.top / 2 * cStride + region.left / 2);
 		const vSlice = vPlane.subarray(region.top / 2 * cStride + region.left / 2);
-		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height);
+		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height, C.AV_PIX_FMT_YUV420P);
 		const tightStride = target.width * 3;
 		const dstStride = tightStride + 63 & -64;
 		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height + 64);
@@ -1244,6 +1377,31 @@ var DecodeWorkerChild = class {
 		return packSinglePlane(dstBuffer, dstStride, target.width, target.height, 3);
 	}
 	/**
+	* `pinnedRgbCrop` software crop — the retained frame is ALREADY pinned
+	* full-range RGB24 (color resolved once at download), so this is a pure
+	* SPATIAL crop + RGB→RGB resize: offset the single packed plane to the crop
+	* origin (zero-copy) and scale ONLY the ROI. NO color math, NO YUV planes, NO
+	* provenance marker (the conversion happened + was logged at download time).
+	* Mirrors {@link nativeScaleCropToBuffer}'s stride-alignment + tail-slack
+	* discipline exactly (same SIMD-overshoot heap-corruption guard).
+	*/
+	nativeRgbCropToBuffer(nav, C, frame, resolved) {
+		const { region, target } = resolved;
+		const plane = frame.data?.[0];
+		if (!plane) throw new Error("decode-worker-child: retained RGB frame missing packed plane data");
+		const srcStride = frame.linesize[0] ?? 0;
+		const srcSlice = plane.subarray(rgbCropSourceOffset(region.top, region.left, srcStride));
+		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height, C.AV_PIX_FMT_RGB24);
+		const tightStride = target.width * 3;
+		const dstStride = tightStride + 63 & -64;
+		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height + 64);
+		const scaledHeight = scaler.scaleSync([srcSlice], [srcStride], 0, region.height, [dstBuffer], [dstStride]);
+		if (scaledHeight < 0) throw new Error(`native rgb crop sws_scale failed: ${scaledHeight}`);
+		if (scaledHeight !== target.height) throw new Error(`native rgb crop scaler produced ${scaledHeight} of ${target.height} rows`);
+		if (dstStride === tightStride) return dstBuffer.subarray(0, tightStride * target.height);
+		return packSinglePlane(dstBuffer, dstStride, target.width, target.height, 3);
+	}
+	/**
 	* Hardware native crop — run the retained GPU surface through a DEDICATED
 	* crop filtergraph (`hwdownload,format=nv12,crop=…,scale=…,format=rgb24`) and
 	* pack the small result. Mirrors {@link hwScaleToBuffer} but uses its OWN
@@ -1267,16 +1425,23 @@ var DecodeWorkerChild = class {
 			for (const out of outputs) out.free();
 		}
 	}
-	/** Build-once / reuse the dedicated native-crop software scaler (rgb out). */
-	ensureNativeCropScaler(nav, C, srcW, srcH, dstW, dstH) {
-		const key = `${srcW}x${srcH}->${dstW}x${dstH}`;
+	/**
+	* Build-once / reuse the dedicated native-crop software scaler (rgb out).
+	* `srcFmt` parameterizes the SOURCE pixel format so the scaler matches the
+	* retained frame: `AV_PIX_FMT_YUV420P` (flag OFF / degrade — YUV→RGB convert)
+	* or `AV_PIX_FMT_RGB24` (`pinnedRgbCrop` — a pure RGB→RGB spatial resize). The
+	* cache key folds the format in so an RGB and a YUV scaler of identical
+	* geometry never alias one slot (see {@link nativeCropScalerKey}).
+	*/
+	ensureNativeCropScaler(nav, C, srcW, srcH, dstW, dstH, srcFmt) {
+		const key = nativeCropScalerKey(srcW, srcH, dstW, dstH, srcFmt === C.AV_PIX_FMT_RGB24);
 		const cached = this.nativeCropScaler;
 		if (cached && key === this.nativeCropScalerKey) return cached;
 		this.nativeCropScaler?.[Symbol.dispose]?.();
 		this.nativeCropScaler = null;
 		this.nativeCropScalerKey = "";
 		const scaler = new nav.SoftwareScaleContext();
-		scaler.getContext(srcW, srcH, C.AV_PIX_FMT_YUV420P, dstW, dstH, C.AV_PIX_FMT_RGB24, C.SWS_FAST_BILINEAR);
+		scaler.getContext(srcW, srcH, srcFmt, dstW, dstH, C.AV_PIX_FMT_RGB24, C.SWS_FAST_BILINEAR);
 		const initRet = scaler.initContext();
 		if (initRet < 0) {
 			scaler[Symbol.dispose]?.();

package/dist/session-decode/decode-worker-child.mjs

@@ -513,6 +513,87 @@ var NativeLeaseStore = class {
 	}
 };
 //#endregion
+//#region src/session-decode/pinned-rgb-crop.ts
+/**
+* Pure decision/plumbing helpers for the `pinnedRgbCrop` native-crop color fix
+* (DEFAULT OFF — see `CAMSTACK_SESSION_PINNED_RGB_CROP` in `decode-worker-child.ts`).
+*
+* ## The bug this fixes
+*
+* On a HARDWARE decode session the FULL-frame download pins its YUV→RGB
+* conversion to the resolved `(matrix, range)` on the GPU filtergraph
+* (`buildGpuFilterDescription` → `colorConvertFilterOptions`). The native-CROP
+* survival path, however, retains the frame as **YUV420P** and later converts
+* it to RGB with a CPU `SoftwareScaleContext` that node-av exposes NO
+* colorspace-pinning surface for — so it falls back to libswscale's own default
+* coefficients. When the stream carries NO color-matrix metadata
+* (`colorSpace = UNSPECIFIED`, e.g. cam 617), the full frame (pinned bt709/
+* limited via {@link resolveSourceColor}'s defaults) and the crop (CPU-sws
+* default) can resolve DIFFERENTLY → the crop gets a wrong hue / desaturation
+* while the full frame looks right.
+*
+* ## The fix (retain-once-in-pinned-RGB)
+*
+* When the flag is on, the HW→system lease download converts to RGB24 ONCE,
+* pinned to the SAME resolved `(matrix, range)` the full-frame path uses. The
+* later crop is then a pure SPATIAL RGB24→RGB24 crop + resize with NO color
+* math, so it cannot re-resolve color differently than the full frame.
+*
+* These helpers are the PURE decision surface (filter description, cache keys,
+* RAM-budget size) so the plumbing is unit-testable without node-av / ffmpeg.
+* The software-DEGRADE path stays YUV420P (its full frame + crop both use the
+* CPU-sws default, so there is no mismatch to fix there).
+*/
+/**
+* The full-frame GPU→system download filtergraph description.
+*
+* - `color === null` (flag OFF / legacy): download to YUV420P, NO color convert
+*   — byte-for-byte the historical `scale=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`.
+* - `color !== null` (flag ON): pin the SAME resolved src matrix/range + full-
+*   range RGB output the full-frame path pins, converting to rgb24 in one pass.
+*/
+function buildLeaseDownloadDescription(scaleFilter, color) {
+	if (color) return `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,scale=${colorConvertFilterOptions(color)},format=rgb24`;
+	return `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+}
+/**
+* Cache key for the lease-download filtergraph. Flag OFF returns the historical
+* `${srcW}x${srcH}` key byte-for-byte; flag ON folds the resolved color in so a
+* mid-session colorspace/range change rebuilds the pinned-convert graph instead
+* of reusing one pinned to the old color.
+*/
+function leaseDownloadFilterKey(srcW, srcH, color) {
+	return color ? `${srcW}x${srcH}:rgb:${sourceColorKey(color)}` : `${srcW}x${srcH}`;
+}
+/**
+* Cache key for the dedicated native-crop software scaler. YUV420P (flag OFF /
+* degrade) returns the historical `${srcW}x${srcH}->${dstW}x${dstH}` key
+* byte-for-byte; the RGB24 (flag ON) scaler carries an `rgb:` prefix so an RGB
+* scaler and a YUV scaler of identical geometry never alias the same cache slot.
+*/
+function nativeCropScalerKey(srcW, srcH, dstW, dstH, rgb24) {
+	const base = `${srcW}x${srcH}->${dstW}x${dstH}`;
+	return rgb24 ? `rgb:${base}` : base;
+}
+/**
+* Approximate resident bytes of a retained software frame, for the lease
+* RAM-budget tally. RGB24 packs 3 bytes/px (~2x YUV420P's 1.5) — the documented
+* cost of pinned-RGB retention.
+*/
+function retainedFrameBytes(width, height, rgb24) {
+	return rgb24 ? width * height * 3 : Math.ceil(width * height * 1.5);
+}
+/**
+* Byte offset into a PACKED RGB24 plane for a crop origin — the pure spatial
+* math the `pinnedRgbCrop` crop uses to zero-copy view the ROI. Packed RGB24 is
+* a single plane at 3 bytes/px with NO chroma subsampling, so the offset is a
+* plain `top*stride + left*3` — no half-plane arithmetic and, critically, no
+* color conversion (that already happened, pinned, at download time).
+*/
+function rgbCropSourceOffset(top, left, stride) {
+	return top * stride + left * 3;
+}
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -542,7 +623,19 @@ var NativeLeaseStore = class {
 function toLeasedNavFrame(frame) {
 	return {
 		frame,
-		byteLength: Math.ceil(frame.width * frame.height * 1.5),
+		byteLength: retainedFrameBytes(frame.width, frame.height, false),
+		free: () => frame.free()
+	};
+}
+/**
+* Wrap a software RGB24 frame as a lease entry (byte size = w×h×3) — the
+* `pinnedRgbCrop` path. Kept separate from {@link toLeasedNavFrame} so the
+* flag-off YUV420P wrap is untouched.
+*/
+function toLeasedRgbNavFrame(frame) {
+	return {
+		frame,
+		byteLength: retainedFrameBytes(frame.width, frame.height, true),
 		free: () => frame.free()
 	};
 }
@@ -607,6 +700,35 @@ var NATIVE_LEASE_ACTIVITY_WINDOW_MS = (() => {
 	return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 15e3;
 })();
 /**
+* `pinnedRgbCrop` — pinned-color RGB24 native-crop retention. DEFAULT **ON**
+* (2026-07-20 rollout); set `CAMSTACK_SESSION_PINNED_RGB_CROP=0` to opt out.
+*
+* ## What it fixes
+* On a HARDWARE session the full-frame download pins its YUV→RGB conversion to
+* the resolved `(matrix, range)` on the GPU filtergraph, but the native-CROP
+* lease path retains the frame as YUV420P and later converts it with a CPU
+* `SoftwareScaleContext` that node-av gives NO colorspace-pinning surface for —
+* so the crop falls back to libswscale's default coefficients. On a stream with
+* NO color-matrix metadata (`colorSpace = UNSPECIFIED`, e.g. cam 617) the full
+* frame (pinned bt709/limited by {@link resolveSourceColor}'s defaults) and the
+* crop (CPU-sws default) can resolve DIFFERENTLY → the crop gets a wrong hue /
+* desaturation while the full frame looks right.
+*
+* ## What it does when ON
+* The HW→system lease download converts to RGB24 ONCE, pinned to the SAME
+* resolved color the full-frame path uses (see {@link buildLeaseDownloadDescription});
+* the later crop is then a pure SPATIAL RGB24→RGB24 crop + resize with no color
+* math (see {@link nativeScaleCropToBuffer}'s RGB branch), so it cannot diverge.
+*
+* ## Cost
+* A retained RGB24 frame is ~2x the RAM of YUV420P (3 vs 1.5 bytes/px — ~6.2 vs
+* ~3.1 MB per 1080p frame). Retention stays DEMAND-GATED by {@link leaseGate},
+* so cameras nothing is cropping retain nothing regardless of this flag. The
+* software-DEGRADE path is left on YUV420P (its full frame + crop both use the
+* CPU-sws default, so there is no mismatch to fix there).
+*/
+var PINNED_RGB_CROP = process.env["CAMSTACK_SESSION_PINNED_RGB_CROP"] !== "0";
+/**
 * The libav GPU scale filter for a hwaccel backend, or `null` when none is
 * known here — those backends fall back to the software crop+scale path.
 * Mirrors `addon-decoder-ffmpeg/src/ffmpeg-args.ts` `gpuScaleFilterForBackend`.
@@ -1144,7 +1266,7 @@ var DecodeWorkerChild = class {
 			const software = this.downloadToSoftware(frame);
 			frame.free();
 			if (!software) return true;
-			this.leaseStore.put(frameId, toLeasedNavFrame(software));
+			this.leaseStore.put(frameId, PINNED_RGB_CROP ? toLeasedRgbNavFrame(software) : toLeasedNavFrame(software));
 			return true;
 		}
 		this.leaseStore.put(frameId, toLeasedNavFrame(frame));
@@ -1161,7 +1283,9 @@ var DecodeWorkerChild = class {
 		const scaleFilter = this.gpuScaleFilter;
 		if (!nav || !scaleFilter || !this.hwContext) return null;
 		try {
-			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height).processAllSync(frame);
+			const color = PINNED_RGB_CROP ? this.resolveFrameColor(frame) : null;
+			if (color) this.logColorProvenance("hw-crop", color);
+			const outputs = this.ensureLeaseDownloadFilter(nav, scaleFilter, frame.width, frame.height, color).processAllSync(frame);
 			const first = outputs[0] ?? null;
 			for (let i = 1; i < outputs.length; i++) outputs[i]?.free();
 			return first;
@@ -1175,9 +1299,17 @@ var DecodeWorkerChild = class {
 			return null;
 		}
 	}
-	/** Build-once / reuse the full-frame GPU→system YUV420P download filtergraph. */
-	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH) {
-		const key = `${srcW}x${srcH}`;
+	/**
+	* Build-once / reuse the full-frame GPU→system download filtergraph.
+	*
+	* - `color === null` (flag OFF): YUV420P download, byte-for-byte the historical
+	*   `scale=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p` + `${srcW}x${srcH}` key.
+	* - `color !== null` (flag ON): pinned-color RGB24 download; the resolved color
+	*   is folded into the cache key so a mid-session colorspace/range change
+	*   rebuilds the graph instead of reusing one pinned to the old color.
+	*/
+	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH, color) {
+		const key = leaseDownloadFilterKey(srcW, srcH, color);
 		const cached = this.nativeLeaseDownloadFilter;
 		if (cached && key === this.nativeLeaseDownloadFilterKey) {
 			this.leaseDownloadFilterUses++;
@@ -1186,7 +1318,7 @@ var DecodeWorkerChild = class {
 		this.nativeLeaseDownloadFilter?.close();
 		this.nativeLeaseDownloadFilter = null;
 		this.nativeLeaseDownloadFilterKey = "";
-		const description = `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+		const description = buildLeaseDownloadDescription(scaleFilter, color);
 		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
 		this.nativeLeaseDownloadFilter = filter;
 		this.nativeLeaseDownloadFilterKey = key;
@@ -1208,6 +1340,7 @@ var DecodeWorkerChild = class {
 		const nav = this.nav;
 		const C = this.consts;
 		if (!nav || !C) throw new Error("node-av not initialized");
+		if (frame.format === C.AV_PIX_FMT_RGB24) return this.nativeRgbCropToBuffer(nav, C, frame, resolved);
 		this.logColorProvenance("sw-crop", this.resolveFrameColor(frame));
 		const { region, target } = resolved;
 		const planes = frame.data;
@@ -1221,7 +1354,7 @@ var DecodeWorkerChild = class {
 		const ySlice = yPlane.subarray(region.top * yStride + region.left);
 		const uSlice = uPlane.subarray(region.top / 2 * cStride + region.left / 2);
 		const vSlice = vPlane.subarray(region.top / 2 * cStride + region.left / 2);
-		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height);
+		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height, C.AV_PIX_FMT_YUV420P);
 		const tightStride = target.width * 3;
 		const dstStride = tightStride + 63 & -64;
 		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height + 64);
@@ -1240,6 +1373,31 @@ var DecodeWorkerChild = class {
 		return packSinglePlane(dstBuffer, dstStride, target.width, target.height, 3);
 	}
 	/**
+	* `pinnedRgbCrop` software crop — the retained frame is ALREADY pinned
+	* full-range RGB24 (color resolved once at download), so this is a pure
+	* SPATIAL crop + RGB→RGB resize: offset the single packed plane to the crop
+	* origin (zero-copy) and scale ONLY the ROI. NO color math, NO YUV planes, NO
+	* provenance marker (the conversion happened + was logged at download time).
+	* Mirrors {@link nativeScaleCropToBuffer}'s stride-alignment + tail-slack
+	* discipline exactly (same SIMD-overshoot heap-corruption guard).
+	*/
+	nativeRgbCropToBuffer(nav, C, frame, resolved) {
+		const { region, target } = resolved;
+		const plane = frame.data?.[0];
+		if (!plane) throw new Error("decode-worker-child: retained RGB frame missing packed plane data");
+		const srcStride = frame.linesize[0] ?? 0;
+		const srcSlice = plane.subarray(rgbCropSourceOffset(region.top, region.left, srcStride));
+		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height, C.AV_PIX_FMT_RGB24);
+		const tightStride = target.width * 3;
+		const dstStride = tightStride + 63 & -64;
+		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height + 64);
+		const scaledHeight = scaler.scaleSync([srcSlice], [srcStride], 0, region.height, [dstBuffer], [dstStride]);
+		if (scaledHeight < 0) throw new Error(`native rgb crop sws_scale failed: ${scaledHeight}`);
+		if (scaledHeight !== target.height) throw new Error(`native rgb crop scaler produced ${scaledHeight} of ${target.height} rows`);
+		if (dstStride === tightStride) return dstBuffer.subarray(0, tightStride * target.height);
+		return packSinglePlane(dstBuffer, dstStride, target.width, target.height, 3);
+	}
+	/**
 	* Hardware native crop — run the retained GPU surface through a DEDICATED
 	* crop filtergraph (`hwdownload,format=nv12,crop=…,scale=…,format=rgb24`) and
 	* pack the small result. Mirrors {@link hwScaleToBuffer} but uses its OWN
@@ -1263,16 +1421,23 @@ var DecodeWorkerChild = class {
 			for (const out of outputs) out.free();
 		}
 	}
-	/** Build-once / reuse the dedicated native-crop software scaler (rgb out). */
-	ensureNativeCropScaler(nav, C, srcW, srcH, dstW, dstH) {
-		const key = `${srcW}x${srcH}->${dstW}x${dstH}`;
+	/**
+	* Build-once / reuse the dedicated native-crop software scaler (rgb out).
+	* `srcFmt` parameterizes the SOURCE pixel format so the scaler matches the
+	* retained frame: `AV_PIX_FMT_YUV420P` (flag OFF / degrade — YUV→RGB convert)
+	* or `AV_PIX_FMT_RGB24` (`pinnedRgbCrop` — a pure RGB→RGB spatial resize). The
+	* cache key folds the format in so an RGB and a YUV scaler of identical
+	* geometry never alias one slot (see {@link nativeCropScalerKey}).
+	*/
+	ensureNativeCropScaler(nav, C, srcW, srcH, dstW, dstH, srcFmt) {
+		const key = nativeCropScalerKey(srcW, srcH, dstW, dstH, srcFmt === C.AV_PIX_FMT_RGB24);
 		const cached = this.nativeCropScaler;
 		if (cached && key === this.nativeCropScalerKey) return cached;
 		this.nativeCropScaler?.[Symbol.dispose]?.();
 		this.nativeCropScaler = null;
 		this.nativeCropScalerKey = "";
 		const scaler = new nav.SoftwareScaleContext();
-		scaler.getContext(srcW, srcH, C.AV_PIX_FMT_YUV420P, dstW, dstH, C.AV_PIX_FMT_RGB24, C.SWS_FAST_BILINEAR);
+		scaler.getContext(srcW, srcH, srcFmt, dstW, dstH, C.AV_PIX_FMT_RGB24, C.SWS_FAST_BILINEAR);
 		const initRet = scaler.initContext();
 		if (initRet < 0) {
 			scaler[Symbol.dispose]?.();

package/dist/{step-definitions-B7e8rPe3.js → step-definitions-BQG_6dmZ.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-BWn5k0A5.js");
+const require_dist = require("./dist-DWy-H6bo.js");
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";
 var HF_SCRYPTED = "scrypted/plugin-models";
@@ -1273,7 +1273,11 @@ var ObjectDetectionStep = class {
 				max: 1,
 				step: .05,
 				default: .5,
-				showValue: true
+				showValue: true,
+				showWhen: {
+					field: "enabledMacroClasses",
+					includes: "package"
+				}
 			},
 			{
 				type: "slider",

package/dist/{step-definitions-BKm17nce.mjs → step-definitions-CVk19Y0u.mjs}

@@ -1,4 +1,4 @@
-import { a as COCO_TO_MACRO, i as COCO_80_LABELS, r as AUDIO_MACRO_LABELS, w as hfModelUrl } from "./dist-CurVt3xC.mjs";
+import { E as hfModelUrl, a as COCO_TO_MACRO, i as COCO_80_LABELS, r as AUDIO_MACRO_LABELS } from "./dist-DLWXeXC1.mjs";
 //#region src/detection-pipeline/registry/model-catalogs.ts
 var HF_REPO = "camstack/camstack-models";
 var HF_SCRYPTED = "scrypted/plugin-models";
@@ -1273,7 +1273,11 @@ var ObjectDetectionStep = class {
 				max: 1,
 				step: .05,
 				default: .5,
-				showValue: true
+				showValue: true,
+				showWhen: {
+					field: "enabledMacroClasses",
+					includes: "package"
+				}
 			},
 			{
 				type: "slider",

package/dist/stream-broker/_stub.js

@@ -1,8 +1,8 @@
-import { a as e, c as t, d as n, i as r, l as i, n as a, o, r as s, s as c, t as l, u } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_ui_mf_2_library__loadShare__.js-CDBALHSV.mjs";
+import { a as e, c as t, d as n, i as r, l as i, n as a, o, r as s, s as c, t as l, u } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_ui_mf_2_library__loadShare__.js-5Zc9wj-A.mjs";
 import { a as d, i as f, n as p, o as m, r as h, t as g } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react__loadShare__.js-C9j-2lBe.mjs";
 import { n as _, r as v, t as y } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare__react_mf_1_jsx_mf_2_runtime__loadShare__.js-XO0-Pyu6.mjs";
 import { n as b, t as x } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_tanstack_mf_1_react_mf_2_query__loadShare__.js-BO7TIbJV.mjs";
-import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-D68Lj69v.mjs";
+import { t as S } from "./_virtual_mf___mfe_internal__addon_stream_broker_widgets__loadShare___mf_0_camstack_mf_1_types__loadShare__.js-BflyNuZv.mjs";
 //#region ../../node_modules/lucide-react/dist/esm/shared/src/utils.js
 var C = (e) => e.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase(), w = (e) => e.replace(/^([A-Z])|[\s-_]+(\w)/g, (e, t, n) => n ? n.toUpperCase() : t.toLowerCase()), T = (e) => {
 	let t = w(e);

package/dist/stream-broker/{_virtual_mf-localSharedImportMap___mfe_internal__addon_stream_broker_widgets-yAAGMET5.mjs → _virtual_mf-localSharedImportMap___mfe_internal__addon_stream_broker_widgets-CpB1jG0N.mjs}

@@ -3,7 +3,7 @@ import "./dist-CYZr2fwk.mjs";
 var e = {
 	"@camstack/sdk": {
 		name: "@camstack/sdk",
-		version: "1.1.30",
+		version: "1.2.0",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_stream_broker_widgets",
@@ -18,7 +18,7 @@ var e = {
 	},
 	"@camstack/types": {
 		name: "@camstack/types",
-		version: "1.1.57",
+		version: "1.2.0",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_stream_broker_widgets",
@@ -33,7 +33,7 @@ var e = {
 	},
 	"@camstack/ui-library": {
 		name: "@camstack/ui-library",
-		version: "1.1.45",
+		version: "1.2.0",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_stream_broker_widgets",