@camstack/addon-pipeline 1.1.53 → 1.1.55

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

@@ -1,7 +1,81 @@
-import { n as isWorkerRequest } from "../worker-protocol-pk7qdYXt.mjs";
+import { n as isWorkerRequest } from "../worker-protocol-CyVJTZEO.mjs";
 import { pathToFileURL } from "node:url";
 import * as fs from "node:fs";
 import * as path$1 from "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 {
@@ -16,6 +90,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;
 	/**
@@ -100,11 +178,154 @@ 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/native-lease-store.ts
+/**
+* A hard-capped-by-bytes, TTL-and-release map from worker frameId → retained
+* RAM frame. Insertion-ordered (`Map`), so budget eviction is FIFO by age.
+*/
+var NativeLeaseStore = class {
+	entries = /* @__PURE__ */ new Map();
+	budgetBytes;
+	ttlMs;
+	now;
+	bytes = 0;
+	constructor(options) {
+		this.budgetBytes = options.budgetBytes;
+		this.ttlMs = options.ttlMs;
+		this.now = options.now ?? Date.now;
+	}
+	/** `false` when the store is disabled (`budgetBytes <= 0`). */
+	get enabled() {
+		return this.budgetBytes > 0;
+	}
+	/** Number of retained leases (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** Total resident bytes across all retained leases (tests / metrics). */
+	get totalBytes() {
+		return this.bytes;
+	}
+	/**
+	* Take ownership of `frame` under `frameId`. Returns `true` when the store
+	* took ownership (caller MUST NOT free), `false` when the store is disabled
+	* (`budgetBytes <= 0`) and the frame was freed here — the caller then keeps
+	* today's GPU-surface-ring path. Sweeps expired leases first, then evicts the
+	* oldest while the total exceeds the budget.
+	*/
+	put(frameId, frame) {
+		if (!this.enabled) {
+			frame.free();
+			return false;
+		}
+		this.drop(frameId);
+		this.sweepExpired();
+		this.entries.set(frameId, {
+			frame,
+			insertedAt: this.now()
+		});
+		this.bytes += frame.byteLength;
+		while (this.bytes > this.budgetBytes && this.entries.size > 0) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.drop(oldest);
+		}
+		return true;
+	}
+	/**
+	* The retained frame for `frameId`, or `null` if never leased, already
+	* released/evicted, OR aged past its TTL (an expired lease is freed + dropped
+	* here so a caller that reads it just after expiry does not resurrect it).
+	*/
+	get(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return null;
+		if (this.now() - entry.insertedAt > this.ttlMs) {
+			this.drop(frameId);
+			return null;
+		}
+		return entry.frame;
+	}
+	/** Free + drop the lease for `frameId` (the prompt release path). Idempotent. */
+	release(frameId) {
+		this.drop(frameId);
+	}
+	/** Free + drop every lease older than the TTL. */
+	sweepExpired() {
+		const cutoff = this.now() - this.ttlMs;
+		for (const [frameId, entry] of this.entries) if (entry.insertedAt < cutoff) this.drop(frameId);
+	}
+	/** Free + drop every retained lease. Idempotent (re-dial + teardown call it). */
+	clear() {
+		for (const entry of this.entries.values()) entry.frame.free();
+		this.entries.clear();
+		this.bytes = 0;
+	}
+	/** Free + remove one entry, keeping the byte tally exact. */
+	drop(frameId) {
+		const entry = this.entries.get(frameId);
+		if (!entry) return;
+		this.entries.delete(frameId);
+		this.bytes -= entry.frame.byteLength;
+		entry.frame.free();
+	}
+};
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -130,11 +351,59 @@ var FrameSlot = class {
 * NOT `$process`)". Raw `process.on('message')` / `process.send` are the
 * correct, sanctioned mechanism for this specific file only.
 */
+/** Wrap a software YUV420P frame as a lease entry (byte size ≈ w×h×1.5). */
+function toLeasedNavFrame(frame) {
+	return {
+		frame,
+		byteLength: Math.ceil(frame.width * frame.height * 1.5),
+		free: () => frame.free()
+	};
+}
 /** Re-dial backoff on a transient dial error/EOF (mirrors the decoder's PULL_REDIAL_MS). */
 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)));
+})();
+/**
+* Hard RAM budget (bytes) for the native-frame LEASE store — the primary
+* native-crop survival window. Unlike {@link NATIVE_RING_CAP} (GPU surfaces,
+* leak-prone → tiny), a lease is a downloaded RAM copy, so the window is sized
+* by memory, not a 2-frame count, and the late cross-process crop reliably
+* hits. The primary eviction is the {@link NATIVE_LEASE_TTL_MS} TTL — a 64MB
+* budget held only ~5 native 4K frames (~0.2s), which the late crop still
+* outran; the budget is now a HIGH safety ceiling (default 1024MB) so the TTL
+* is the effective cap and the ~40-200ms crop reliably lands within it.
+* `CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB` (default 1024); `0` DISABLES the
+* lease and falls back to the {@link NATIVE_RING_CAP} GPU ring (today's path).
+*/
+var NATIVE_LEASE_BUDGET_BYTES = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_BUDGET_MB"]);
+	return (Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 1024) * 1024 * 1024;
+})();
+/**
+* TTL (ms) after which a native-frame lease is treated as a miss and reclaimed.
+* The backstop that bounds in-flight RAM even if the explicit `releaseNativeLease`
+* is dropped — comfortably longer than the detection inference + crop round-trip
+* (~40-200ms). `CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS` (default 500).
+*/
+var NATIVE_LEASE_TTL_MS = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_LEASE_TTL_MS"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 500;
+})();
+/**
 * 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`.
@@ -272,37 +541,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.
 *
@@ -384,6 +622,53 @@ 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);
+	/**
+	* PRIMARY native-frame survival window — a bounded RAM copy of each shipped
+	* detection frame, keyed by frameId, held until release / TTL / budget
+	* eviction. Replaces the tiny GPU {@link nativeRing} as the default (the ring
+	* is used only when the lease is disabled via a 0 budget). Because it holds
+	* DOWNLOADED (system-memory) frames, retaining a large window has no VAAPI
+	* surface-pool starvation risk. Cleared on every re-dial + teardown.
+	*/
+	leaseStore = new NativeLeaseStore({
+		budgetBytes: NATIVE_LEASE_BUDGET_BYTES,
+		ttlMs: NATIVE_LEASE_TTL_MS
+	});
+	/**
+	* DEDICATED full-frame GPU→system download filtergraph
+	* (`scale_<be>=iw:ih,hwdownload,format=nv12,format=yuv420p`) used ONLY to
+	* materialize a HW surface into a leasable software frame at NATIVE
+	* resolution (no scale). Kept separate from the detection/native-crop filters
+	* (different geometry). Same dispose discipline: closed on every re-dial
+	* ({@link closeInput}) + teardown, since it references the decoder's per-dial
+	* `hw_frames_ctx`.
+	*/
+	nativeLeaseDownloadFilter = null;
+	nativeLeaseDownloadFilterKey = "";
+	/** 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}. */
@@ -416,7 +701,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.captureNativeFrame(frameId, frame) });
 	/**
 	* Mirrors whether `this.frames` currently has a pull waiting, so
 	* `teardown` knows to resolve it with `{kind:'ended'}` — `FrameSlot`
@@ -442,6 +727,12 @@ 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 "releaseNativeLease":
+				this.leaseStore.release(message.frameId);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -466,6 +757,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) {
@@ -480,7 +774,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;
 	}
@@ -530,6 +824,207 @@ 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.leaseStore.get(frameId)?.frame ?? this.resolveRetainedFrame(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
+			});
+		}
+	}
+	/** The GPU-ring or reserved-slot frame for `frameId` (lease-disabled / newest paths). */
+	resolveRetainedFrame(frameId) {
+		return this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+	}
+	/**
+	* Retain a just-superseded DELIVERED frame for later native crops. Transfers
+	* ownership from the {@link FrameSlot} (the caller MUST NOT free when this
+	* returns `true`).
+	*
+	* - Lease ENABLED (default): materialize a SOFTWARE RAM copy and put it in the
+	*   {@link leaseStore}. A HW surface is downloaded to system memory ONCE here
+	*   (freeing the GPU surface immediately — no VAAPI-pool pin); a software frame
+	*   is leased directly. A download failure still consumes ownership (freed
+	*   here) so the slot never double-frees — the crop simply misses → fallback.
+	* - Lease DISABLED (`budget 0`): fall back to today's tiny GPU {@link nativeRing}.
+	*/
+	captureNativeFrame(frameId, frame) {
+		if (!this.leaseStore.enabled) return this.nativeRing.retain(frameId, frame);
+		if (frame.isHwFrame()) {
+			const software = this.downloadToSoftware(frame);
+			frame.free();
+			if (!software) return true;
+			this.leaseStore.put(frameId, toLeasedNavFrame(software));
+			return true;
+		}
+		this.leaseStore.put(frameId, toLeasedNavFrame(frame));
+		return true;
+	}
+	/**
+	* Download a HW surface to a NATIVE-resolution software YUV420P frame via the
+	* dedicated full-frame download filtergraph. Returns the software frame (owned
+	* by the caller) or `null` on any failure (the lease is then simply skipped).
+	* `processAllSync` only refs the input surface, so the caller frees it after.
+	*/
+	downloadToSoftware(frame) {
+		const nav = this.nav;
+		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 first = outputs[0] ?? null;
+			for (let i = 1; i < outputs.length; i++) outputs[i]?.free();
+			return first;
+		} catch (err) {
+			this.emitStderr(`decode-worker-child: native lease download failed — ${errMessage(err)}\n`);
+			return null;
+		}
+	}
+	/** Build-once / reuse the full-frame GPU→system YUV420P download filtergraph. */
+	ensureLeaseDownloadFilter(nav, scaleFilter, srcW, srcH) {
+		const key = `${srcW}x${srcH}`;
+		const cached = this.nativeLeaseDownloadFilter;
+		if (cached && key === this.nativeLeaseDownloadFilterKey) return cached;
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
+		const description = `${scaleFilter}=w=iw:h=ih,hwdownload,format=nv12,format=yuv420p`;
+		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
+		this.nativeLeaseDownloadFilter = filter;
+		this.nativeLeaseDownloadFilterKey = key;
+		return filter;
+	}
+	/** 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);
@@ -883,6 +1378,14 @@ var DecodeWorkerChild = class {
 	* the next dial's first `toBuffer`.
 	*/
 	closeInput() {
+		this.nativeRing.clear();
+		this.leaseStore.clear();
+		this.nativeLeaseDownloadFilter?.close();
+		this.nativeLeaseDownloadFilter = null;
+		this.nativeLeaseDownloadFilterKey = "";
+		this.nativeCropHwFilter?.close();
+		this.nativeCropHwFilter = null;
+		this.nativeCropHwFilterKey = "";
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";