@camstack/addon-pipeline 1.1.52 → 1.1.54

package/dist/pipeline-runner/index.mjs

@@ -1,7 +1,7 @@
-import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, K as makeSourceBrokerId, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-DM6-eQRs.mjs";
-import { n as isRemoteRestream, r as profileForStreamId, t as RemoteSourcePlane } from "../remote-source-plane-DivMEw6Y.mjs";
+import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, K as makeSourceBrokerId, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-CEcTeu1h.mjs";
+import { n as isRemoteRestream, r as profileForStreamId, t as RemoteSourcePlane } from "../remote-source-plane-CNCqC_XG.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
-import { t as isWorkerReply } from "../worker-protocol-pk7qdYXt.mjs";
+import { t as isWorkerReply } from "../worker-protocol-DGIt_waM.mjs";
 import { DecoderFrameRingSink, FrameRingReaderCache, unlinkSegment } from "@camstack/shm-ring";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -1451,6 +1451,9 @@ var SessionDecodeSession = class {
 	frameTimeoutMs;
 	pendingPull = null;
 	pendingToBuffers = /* @__PURE__ */ new Map();
+	/** Outstanding `nativeCrop` requests, keyed by the monotonic `requestId`. */
+	pendingNativeCrops = /* @__PURE__ */ new Map();
+	nextNativeCropId = 1;
 	exited = false;
 	sigkillTimer = null;
 	pullTimeoutTimer = null;
@@ -1515,6 +1518,30 @@ var SessionDecodeSession = class {
 			}
 		});
 	}
+	/**
+	* Send `nativeCrop` for `frameId` and resolve with the crop result, or `null`
+	* on any miss (frame aged out, worker error, or worker already exited). Never
+	* rejects — native crops are strictly best-effort with a free fallback.
+	*/
+	requestNativeCrop(frameId, bbox, maxWidth) {
+		if (this.exited) return Promise.resolve(null);
+		const requestId = this.nextNativeCropId++;
+		return new Promise((resolve) => {
+			this.pendingNativeCrops.set(requestId, { resolve });
+			try {
+				this.child.send({
+					kind: "nativeCrop",
+					requestId,
+					frameId,
+					bbox,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				});
+			} catch {
+				this.pendingNativeCrops.delete(requestId);
+				resolve(null);
+			}
+		});
+	}
 	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
 	teardown() {
 		this.clearPullTimeout();
@@ -1547,6 +1574,16 @@ var SessionDecodeSession = class {
 			case "buffer":
 				this.settleToBuffer(raw.frameId, raw.bytes);
 				return;
+			case "nativeCropResult":
+				this.settleNativeCrop(raw.requestId, {
+					bytes: raw.bytes,
+					width: raw.width,
+					height: raw.height
+				});
+				return;
+			case "nativeCropMiss":
+				this.settleNativeCrop(raw.requestId, null);
+				return;
 			case "error":
 				this.settleError(raw.message, raw.frameId);
 				return;
@@ -1566,6 +1603,15 @@ var SessionDecodeSession = class {
 		}
 		for (const waiters of this.pendingToBuffers.values()) for (const waiter of waiters) waiter.reject(/* @__PURE__ */ new Error("session-decode-coordinator: worker exited before toBuffer reply"));
 		this.pendingToBuffers.clear();
+		for (const waiter of this.pendingNativeCrops.values()) waiter.resolve(null);
+		this.pendingNativeCrops.clear();
+	}
+	/** Settle the `nativeCrop` waiter for `requestId` (dropping unknown/stale ids). */
+	settleNativeCrop(requestId, result) {
+		const waiter = this.pendingNativeCrops.get(requestId);
+		if (!waiter) return;
+		this.pendingNativeCrops.delete(requestId);
+		waiter.resolve(result);
 	}
 	settlePendingPull(outcome) {
 		const waiter = this.pendingPull;
@@ -1697,10 +1743,12 @@ function buildFrameImage(session, reply) {
 		width: reply.width,
 		height: reply.height,
 		format: reply.format,
+		frameId: reply.frameId,
 		toBuffer: async (opts) => {
 			if (closed) throw new Error(`session-decode-coordinator: toBuffer() called on a closed frame (frameId=${reply.frameId})`);
 			return session.requestBuffer(reply.frameId, opts);
 		},
+		nativeCrop: (bbox, maxWidth) => session.requestNativeCrop(reply.frameId, bbox, maxWidth),
 		close: () => {
 			closed = true;
 		}
@@ -1841,7 +1889,9 @@ function startSessionDecodePump(deps) {
 				}
 				try {
 					const decoded = await toDecodedFrame(frame, format);
-					deps.onDecodedFrame(decoded);
+					const image = frame.image;
+					const nativeCrop = image.nativeCrop ? (bbox, maxWidth) => image.nativeCrop(bbox, maxWidth) : void 0;
+					deps.onDecodedFrame(decoded, nativeCrop);
 				} catch (err) {
 					deps.logger.debug("session-decode pump: skipped a frame (decode/consume error)", {
 						tags: { deviceId: deps.source.deviceId },
@@ -1874,6 +1924,40 @@ function startSessionDecodePump(deps) {
 		iterator.return().catch(() => {});
 	};
 }
+var NativeCropRegistry = class {
+	capacity;
+	entries = /* @__PURE__ */ new Map();
+	constructor(capacity = 64) {
+		this.capacity = capacity;
+	}
+	/** Number of registered handles (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** A retention frame is uniquely identified by its segment + slot + committed seq. */
+	key(handle) {
+		return `${handle.shmId}#${handle.slot}#${handle.seq}`;
+	}
+	/** Bind `request` to `handle`; evicts the oldest entry past the cap. */
+	register(handle, request) {
+		const k = this.key(handle);
+		this.entries.delete(k);
+		this.entries.set(k, request);
+		while (this.entries.size > this.capacity) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.entries.delete(oldest);
+		}
+	}
+	/** The requester for `handle`, or `null` if never registered / already evicted. */
+	get(handle) {
+		return this.entries.get(this.key(handle)) ?? null;
+	}
+	/** Drop every entry (node/addon shutdown). */
+	clear() {
+		this.entries.clear();
+	}
+};
 //#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
@@ -2098,6 +2182,13 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	* `resize()`d live in `onConfigChanged`. Null until `onInitialize`.
 	*/
 	spawnGate = null;
+	/**
+	* Node-level map from a retention-ring `FrameHandle` to the decode worker
+	* still holding that frame's NATIVE surface — backs the `getNativeCrop` cap
+	* so post-analysis can cut native-res crops (best-effort; a miss falls back
+	* to the detection-frame crop). See {@link NativeCropRegistry}.
+	*/
+	nativeCropRegistry = new NativeCropRegistry();
 	attached = /* @__PURE__ */ new Map();
 	nodeId = "unknown";
 	metricsSnapshotTimer = null;
@@ -2667,6 +2758,23 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		this.runner?.reportMotion(input.deviceId, input.detected, input.source, input.regions);
 		return { success: true };
 	}
+	/**
+	* Best-effort native-resolution crop for a retention-ring frame (native-crop
+	* feature). Looks the handle up in {@link nativeCropRegistry}; a miss (never
+	* registered, or the worker's tiny native ring already evicted the frame)
+	* returns `null` so the caller falls back to a detection-frame crop. The
+	* worker downloads ONLY the ROI — a full native frame never travels the wire.
+	*/
+	async getNativeCrop(input) {
+		const requester = this.nativeCropRegistry.get(input.handle);
+		if (!requester) return null;
+		const result = await requester(input.bbox, input.maxWidth);
+		return result ? {
+			bytes: result.bytes,
+			width: result.width,
+			height: result.height
+		} : null;
+	}
 	detachInternal(deviceId) {
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
@@ -2986,8 +3094,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 						format: "rgb"
 					},
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
-					onDecodedFrame: (frame) => {
+					onDecodedFrame: (frame, nativeCrop) => {
 						const handle = retentionSink.write(frame) ?? void 0;
+						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
 						this.enqueueSharedDetectionFrame(config.deviceId, frame, handle);
 					}
 				});

package/dist/recorder/index.js

@@ -1,5 +1,5 @@
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-B-pQhc30.js");
+const require_dist = require("../dist-BbaoC680.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let node_child_process = require("node:child_process");

package/dist/recorder/index.mjs

@@ -1,4 +1,4 @@
-import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-DM6-eQRs.mjs";
+import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-CEcTeu1h.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { spawn } from "node:child_process";

package/dist/{remote-source-plane-DivMEw6Y.mjs → remote-source-plane-CNCqC_XG.mjs}

@@ -1,4 +1,4 @@
-import { D as nodePin, I as errMsg, d as RingBuffer } from "./dist-DM6-eQRs.mjs";
+import { D as nodePin, I as errMsg, d as RingBuffer } from "./dist-CEcTeu1h.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**

package/dist/{remote-source-plane-dSe5NlH9.js → remote-source-plane-vN45KFSm.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-B-pQhc30.js");
+const require_dist = require("./dist-BbaoC680.js");
 let node_crypto = require("node:crypto");
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
 /**

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

@@ -1,11 +1,85 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_worker_protocol = require("../worker-protocol-BCfO8gUF.js");
+const require_worker_protocol = require("../worker-protocol-DkL6GDxe.js");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+//#region src/session-decode/crop-geometry.ts
+/** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
+function clampEven(value, min, max) {
+	const bounded = Math.min(Math.max(value, min), max);
+	return bounded - bounded % 2;
+}
+/** Resolve `FrameImageOptions.crop` against the decoded frame's dimensions, defaulting to the full frame. */
+function resolveCropRegion(frameWidth, frameHeight, crop) {
+	const left = clampEven(crop?.left ?? 0, 0, Math.max(0, frameWidth - 2));
+	const top = clampEven(crop?.top ?? 0, 0, Math.max(0, frameHeight - 2));
+	return {
+		left,
+		top,
+		width: clampEven(crop?.width ?? frameWidth - left, 2, frameWidth - left),
+		height: clampEven(crop?.height ?? frameHeight - top, 2, frameHeight - top)
+	};
+}
+/** Resolve `FrameImageOptions.resize`, defaulting to the (already cropped) source dimensions. */
+function resolveResizeTarget(cropWidth, cropHeight, resize) {
+	if (!resize) return {
+		width: cropWidth,
+		height: cropHeight
+	};
+	return {
+		width: Math.max(1, Math.round(resize.width)),
+		height: Math.max(1, Math.round(resize.height))
+	};
+}
+/** Whether `region` covers the entire `srcW x srcH` frame (i.e. no real crop). */
+function isFullFrameRegion(region, srcW, srcH) {
+	return region.left === 0 && region.top === 0 && region.width === srcW && region.height === srcH;
+}
+/**
+* Resolve a NORMALIZED [0,1] bbox against a native frame's real pixel dims into
+* an even-aligned pixel crop region. Clamps the box inside the frame so a
+* padded / slightly-out-of-frame bbox never reads past the plane; a degenerate
+* (zero-area) box is widened to the 2px chroma minimum by
+* {@link resolveCropRegion}'s own clamps.
+*/
+function normalizedBboxToCrop(frameWidth, frameHeight, bbox) {
+	return {
+		left: Math.round(bbox.x * frameWidth),
+		top: Math.round(bbox.y * frameHeight),
+		width: Math.max(2, Math.round(bbox.w * frameWidth)),
+		height: Math.max(2, Math.round(bbox.h * frameHeight))
+	};
+}
+/**
+* Aspect-preserving cap of a native crop region to `maxWidth`. Returns
+* `undefined` (no resize → true native crop) when `maxWidth` is absent or the
+* region is already within it.
+*/
+function resolveNativeCropTarget(region, maxWidth) {
+	if (maxWidth === void 0 || maxWidth <= 0 || region.width <= maxWidth) return void 0;
+	const width = Math.round(maxWidth);
+	return {
+		width,
+		height: Math.max(1, Math.round(width * region.height / region.width))
+	};
+}
+/**
+* Full native-crop geometry: normalized bbox → even-aligned source region +
+* (optionally width-capped) output target. The single mapping the decode worker
+* uses to turn a detection-res bbox into a native-res crop request.
+*/
+function resolveNativeCropGeometry(frameWidth, frameHeight, bbox, maxWidth) {
+	const region = resolveCropRegion(frameWidth, frameHeight, normalizedBboxToCrop(frameWidth, frameHeight, bbox));
+	const resize = resolveNativeCropTarget(region, maxWidth);
+	return {
+		region,
+		target: resolveResizeTarget(region.width, region.height, resize)
+	};
+}
+//#endregion
 //#region src/session-decode/frame-slot.ts
 function toReply(held) {
 	return {
@@ -20,6 +94,10 @@ function toReply(held) {
 * pending-pull flag. One instance per decode-worker child session.
 */
 var FrameSlot = class {
+	retainSuperseded;
+	constructor(options) {
+		this.retainSuperseded = options?.retainSuperseded;
+	}
 	nextFrameId = 1;
 	slot = null;
 	/**
@@ -104,11 +182,61 @@ var FrameSlot = class {
 		const previousReserved = this.reserved;
 		this.reserved = held;
 		this.slot = null;
-		previousReserved?.frame.free();
+		if (previousReserved) {
+			if (!(this.retainSuperseded?.(previousReserved.frameId, previousReserved.frame) ?? false)) previousReserved.frame.free();
+		}
 		return toReply(held);
 	}
 };
 //#endregion
+//#region src/session-decode/native-frame-ring.ts
+/**
+* A hard-capped, insertion-ordered map from worker frameId → retained frame.
+* `capacity <= 0` disables retention entirely (every `retain` frees immediately
+* and returns false) — the safe "keep the ring off" knob.
+*/
+var NativeFrameRing = class {
+	capacity;
+	/** Insertion-ordered (Map preserves insertion order) frameId → frame. */
+	frames = /* @__PURE__ */ new Map();
+	constructor(capacity) {
+		this.capacity = capacity;
+	}
+	/** Number of frames currently retained (for tests / metrics). */
+	get size() {
+		return this.frames.size;
+	}
+	/**
+	* Take ownership of `frame` under `frameId`. Frees the oldest retained frame
+	* when the cap is exceeded (FIFO by frameId insertion). Returns `true` when
+	* the ring took ownership (caller MUST NOT free), `false` when retention is
+	* disabled (`capacity <= 0`) and the caller still owns/should free the frame.
+	*/
+	retain(frameId, frame) {
+		if (this.capacity <= 0) return false;
+		const existing = this.frames.get(frameId);
+		if (existing) existing.free();
+		this.frames.set(frameId, frame);
+		while (this.frames.size > this.capacity) {
+			const oldestKey = this.frames.keys().next().value;
+			if (oldestKey === void 0) break;
+			const oldest = this.frames.get(oldestKey);
+			this.frames.delete(oldestKey);
+			oldest?.free();
+		}
+		return true;
+	}
+	/** The retained frame for `frameId`, or `null` if never retained / already evicted. */
+	get(frameId) {
+		return this.frames.get(frameId) ?? null;
+	}
+	/** Free and drop every retained frame. Idempotent (re-dial + teardown call it). */
+	clear() {
+		for (const frame of this.frames.values()) frame.free();
+		this.frames.clear();
+	}
+};
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -139,6 +267,20 @@ var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
 var METRICS_INTERVAL_MS = 1e4;
 /**
+* Hard cap on the native-frame retention ring (native-res crop feature). Kept
+* DELIBERATELY TINY — its only job is to cover the detection→crop latency
+* (typically 1-4 frames), NOT the full shm ring depth. On the HW path every
+* retained slot pins a GPU/VAAPI surface out of the decoder pool (the historic
+* leak site), so the cap MUST stay small; a miss is free (caller falls back to
+* today's detection-frame crop). Override with `CAMSTACK_SESSION_NATIVE_CROP_RING`
+* (0 disables retention entirely); clamped to [0,4], default 2.
+*/
+var NATIVE_RING_CAP = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_CROP_RING"]);
+	if (!Number.isFinite(raw)) return 2;
+	return Math.min(4, Math.max(0, Math.floor(raw)));
+})();
+/**
 * 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`.
@@ -276,37 +418,6 @@ function backendToHwDeviceConst(backend, consts) {
 		default: return null;
 	}
 }
-/** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
-function clampEven(value, min, max) {
-	const bounded = Math.min(Math.max(value, min), max);
-	return bounded - bounded % 2;
-}
-/** Resolve `FrameImageOptions.crop` against the decoded frame's dimensions, defaulting to the full frame. */
-function resolveCropRegion(frameWidth, frameHeight, crop) {
-	const left = clampEven(crop?.left ?? 0, 0, Math.max(0, frameWidth - 2));
-	const top = clampEven(crop?.top ?? 0, 0, Math.max(0, frameHeight - 2));
-	return {
-		left,
-		top,
-		width: clampEven(crop?.width ?? frameWidth - left, 2, frameWidth - left),
-		height: clampEven(crop?.height ?? frameHeight - top, 2, frameHeight - top)
-	};
-}
-/** Resolve `FrameImageOptions.resize`, defaulting to the (already cropped) source dimensions. */
-function resolveResizeTarget(cropWidth, cropHeight, resize) {
-	if (!resize) return {
-		width: cropWidth,
-		height: cropHeight
-	};
-	return {
-		width: Math.max(1, Math.round(resize.width)),
-		height: Math.max(1, Math.round(resize.height))
-	};
-}
-/** Whether `region` covers the entire `srcW x srcH` frame (i.e. no real crop). */
-function isFullFrameRegion(region, srcW, srcH) {
-	return region.left === 0 && region.top === 0 && region.width === srcW && region.height === srcH;
-}
 /**
 * Build the libav filtergraph description for the GPU crop+scale path.
 *
@@ -388,6 +499,30 @@ var DecodeWorkerChild = class {
 	*/
 	hwFilter = null;
 	hwFilterKey = "";
+	/**
+	* DEDICATED native-crop GPU filtergraph + software scaler, kept SEPARATE from
+	* the detection {@link hwFilter}/{@link scaler} so a native-crop request never
+	* evicts (rebuilds) the hot-path detection filter cache — the crop geometry
+	* differs from the stable detection geometry, so sharing one cache would
+	* thrash it. Same dispose discipline: both are closed on every re-dial
+	* ({@link closeInput}) and on teardown. Rebuilt lazily per crop geometry.
+	*/
+	nativeCropHwFilter = null;
+	nativeCropHwFilterKey = "";
+	nativeCropScaler = null;
+	nativeCropScalerKey = "";
+	/**
+	* Bounded native-frame retention ring — the survival window for a frame's
+	* NATIVE surface between detection (on the shipped small frame) and the crop
+	* request that follows. Hard-capped at {@link NATIVE_RING_CAP}; single
+	* ownership via the {@link FrameSlot} `retainSuperseded` hook (a frame enters
+	* the ring exactly when the slot would otherwise free it). Cleared on every
+	* re-dial + teardown (see {@link closeInput}).
+	*/
+	nativeRing = new NativeFrameRing(NATIVE_RING_CAP);
+	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
+	nativeCropHits = 0;
+	nativeCropMisses = 0;
 	/** Scrypted-style throughput counters (plain integers, no per-frame allocation). */
 	framesDecoded = 0;
 	/** Child-side skips only (HW-guard drops + probe/degrade frees); slot drops add {@link FrameSlot.droppedCount}. */
@@ -420,7 +555,7 @@ var DecodeWorkerChild = class {
 	* the reserve-on-pull invariant (`e3c78a9b`) is unit-tested without
 	* node-av. See that file's doc comment for the full semantics.
 	*/
-	frames = new FrameSlot();
+	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.nativeRing.retain(frameId, frame) });
 	/**
 	* Mirrors whether `this.frames` currently has a pull waiting, so
 	* `teardown` knows to resolve it with `{kind:'ended'}` — `FrameSlot`
@@ -446,6 +581,9 @@ var DecodeWorkerChild = class {
 			case "toBuffer":
 				this.handleToBuffer(message.frameId, message.opts);
 				return;
+			case "nativeCrop":
+				this.handleNativeCrop(message.requestId, message.frameId, message.bbox, message.maxWidth);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -470,6 +608,9 @@ var DecodeWorkerChild = class {
 		this.scaler?.[Symbol.dispose]?.();
 		this.scaler = null;
 		this.scalerKey = "";
+		this.nativeCropScaler?.[Symbol.dispose]?.();
+		this.nativeCropScaler = null;
+		this.nativeCropScalerKey = "";
 		this.hwContext?.[Symbol.dispose]?.();
 		this.hwContext = null;
 		if (this.pendingPull) {
@@ -484,7 +625,7 @@ var DecodeWorkerChild = class {
 		const deliveredDelta = this.framesDelivered - this.lastDeliveredSnapshot;
 		const deliveredFps = Math.round(deliveredDelta / windowMs * 1e3 * 10) / 10;
 		const skipped = this.framesSkipped + this.frames.droppedCount;
-		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 	}
@@ -534,6 +675,145 @@ var DecodeWorkerChild = class {
 			this.sendError(`decode-worker-child: toBuffer failed — ${errMessage(err)}`, frameId);
 		}
 	}
+	/**
+	* Best-effort NATIVE-resolution crop of a still-retained frame. Resolves the
+	* frame from the reserved slot (the latest, most common case) or the
+	* retention ring (an older frame detection has since moved past). A miss
+	* (frame aged out) or ANY crop error replies `nativeCropMiss` so the caller
+	* falls back to today's detection-frame crop — it NEVER degrades the
+	* detection session (unlike {@link hwScaleToBuffer}, which flips the whole
+	* session to software on a GPU-filter error).
+	*/
+	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
+		const frame = this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+		if (!frame) {
+			this.nativeCropMisses++;
+			this.send({
+				kind: "nativeCropMiss",
+				requestId
+			});
+			return;
+		}
+		try {
+			const resolved = this.resolveNativeCrop(frame, bbox, maxWidth);
+			const bytes = frame.isHwFrame() ? this.nativeHwCropToBuffer(frame, resolved) : this.nativeScaleCropToBuffer(frame, resolved);
+			this.nativeCropHits++;
+			this.send({
+				kind: "nativeCropResult",
+				requestId,
+				bytes,
+				width: resolved.target.width,
+				height: resolved.target.height
+			});
+		} catch (err) {
+			this.nativeCropMisses++;
+			this.emitStderr(`decode-worker-child: native crop failed (requestId ${requestId}) — ${errMessage(err)}\n`);
+			this.send({
+				kind: "nativeCropMiss",
+				requestId
+			});
+		}
+	}
+	/** Map a normalized bbox to an even-aligned pixel crop + (optionally capped) target. */
+	resolveNativeCrop(frame, bbox, maxWidth) {
+		return resolveNativeCropGeometry(frame.width, frame.height, bbox, maxWidth);
+	}
+	/**
+	* Software native crop — the leak-free path: offset the retained YUV420P
+	* frame's plane pointers to the crop origin (zero-copy) and scale ONLY the
+	* ROI into a tightly-packed rgb buffer via a DEDICATED scaler (never the
+	* detection {@link scaler}). Mirrors {@link scaleRoiToBuffer}, rgb-fixed.
+	*/
+	nativeScaleCropToBuffer(frame, resolved) {
+		const nav = this.nav;
+		const C = this.consts;
+		if (!nav || !C) throw new Error("node-av not initialized");
+		const { region, target } = resolved;
+		const planes = frame.data;
+		const strides = frame.linesize;
+		const yPlane = planes?.[0];
+		const uPlane = planes?.[1];
+		const vPlane = planes?.[2];
+		if (!yPlane || !uPlane || !vPlane) throw new Error("decode-worker-child: retained frame missing planar YUV420P data");
+		const yStride = strides[0] ?? 0;
+		const cStride = strides[1] ?? 0;
+		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 dstStride = target.width * 3;
+		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height);
+		const scaledHeight = scaler.scaleSync([
+			ySlice,
+			uSlice,
+			vSlice
+		], [
+			yStride,
+			cStride,
+			cStride
+		], 0, region.height, [dstBuffer], [dstStride]);
+		if (scaledHeight < 0) throw new Error(`native crop sws_scale failed: ${scaledHeight}`);
+		if (scaledHeight !== target.height) throw new Error(`native crop scaler produced ${scaledHeight} of ${target.height} rows`);
+		return dstBuffer;
+	}
+	/**
+	* 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
+	* cached filter and, on error, throws WITHOUT degrading the session.
+	*/
+	nativeHwCropToBuffer(frame, resolved) {
+		const { region, target } = resolved;
+		const outputs = this.ensureNativeCropHwFilter(region, target).processAllSync(frame);
+		const first = outputs[0];
+		if (!first) {
+			for (const out of outputs) out.free();
+			throw new Error("native crop GPU filtergraph produced no frame");
+		}
+		try {
+			const plane = first.data?.[0];
+			if (!plane) throw new Error("native crop GPU frame missing packed plane data");
+			return packSinglePlane(plane, first.linesize[0] ?? 0, target.width, target.height, 3);
+		} finally {
+			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}`;
+		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);
+		const initRet = scaler.initContext();
+		if (initRet < 0) {
+			scaler[Symbol.dispose]?.();
+			throw new Error(`native crop sws_init_context failed: ${initRet}`);
+		}
+		this.nativeCropScaler = scaler;
+		this.nativeCropScalerKey = key;
+		return scaler;
+	}
+	/** Build-once / reuse the dedicated native-crop GPU filtergraph (rgb out). */
+	ensureNativeCropHwFilter(region, target) {
+		const nav = this.nav;
+		const scaleFilter = this.gpuScaleFilter;
+		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: native GPU crop requested without a HW context");
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}`;
+		const cached = this.nativeCropHwFilter;
+		if (cached && key === this.nativeCropHwFilterKey) return cached;
+		this.nativeCropHwFilter?.close();
+		this.nativeCropHwFilter = null;
+		this.nativeCropHwFilterKey = "";
+		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24");
+		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
+		this.nativeCropHwFilter = filter;
+		this.nativeCropHwFilterKey = key;
+		return filter;
+	}
 	handleStop() {
 		this.teardown();
 		process.exit(0);
@@ -887,6 +1167,10 @@ var DecodeWorkerChild = class {
 	* the next dial's first `toBuffer`.
 	*/
 	closeInput() {
+		this.nativeRing.clear();
+		this.nativeCropHwFilter?.close();
+		this.nativeCropHwFilter = null;
+		this.nativeCropHwFilterKey = "";
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";