@camstack/addon-pipeline 1.1.52 → 1.1.54

package/dist/{dist-B-pQhc30.js → dist-BbaoC680.js}

@@ -4627,7 +4627,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-b4Jf2n33.mjs
+//#region ../types/dist/sleep-BC9Yqte7.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -11420,6 +11420,7 @@ var PipelineAddonSchemaSchema = object({
 	defaultModelId: string(),
 	defaultModelIdByFormat: record(string(), string()).optional(),
 	enabledByDefault: boolean().optional(),
+	backfillIntoExistingOverrides: boolean().optional(),
 	defaultConfidence: number(),
 	group: string().optional(),
 	configSchema: array(ConfigFieldBridge).readonly().optional()
@@ -11889,6 +11890,25 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(ZoneSchema).read
 	auth: "admin"
 }), object({ zones: array(ZoneSchema).readonly() });
 /**
+* A bounding box in NORMALIZED [0,1] frame coordinates for `getNativeCrop`. The
+* decode worker resolves it against the RETAINED native frame's real pixel dims,
+* so the caller supplies only the detection-res bbox divided by the detection
+* dims — no native resolution to plumb.
+*/
+var NativeCropBboxSchema = object({
+	x: number(),
+	y: number(),
+	w: number(),
+	h: number()
+});
+/** Result of a best-effort native-resolution crop (`getNativeCrop`). */
+var NativeCropResultSchema = object({
+	/** Packed rgb (24-bit) pixels of the crop. */
+	bytes: _instanceof(Uint8Array),
+	width: number().int().positive(),
+	height: number().int().positive()
+});
+/**
 * Per-camera tunable ranges + defaults. Single source of truth used
 * by both the Zod data schema (validation + default fallback) and
 * the device settings UI (slider min/max/step). Touch one place and
@@ -12192,7 +12212,22 @@ var pipelineRunnerCapability = {
 		/** All per-camera metrics in one round-trip. */
 		getAllCameraMetrics: method(_void(), array(CameraMetricsWithDeviceIdSchema).readonly()),
 		/** List the deviceIds currently attached to this runner. */
-		getLocalCameras: method(_void(), array(number()).readonly())
+		getLocalCameras: method(_void(), array(number()).readonly()),
+		/**
+		* Best-effort NATIVE-resolution crop of a retention-ring frame. Given the
+		* `FrameHandle` that rode an inference-result event and a normalized `bbox`,
+		* the runner asks the decode worker still holding that frame's NATIVE
+		* surface to GPU/CPU-crop ONLY the ROI at native res and download just the
+		* crop. Returns `null` on a miss (handle not registered, or the worker's
+		* tiny native-retention ring already evicted the frame) — the caller falls
+		* back to a detection-frame crop. Routed to the frame's owning node by
+		* `handle.nodeId`; NEVER ships a full native frame.
+		*/
+		getNativeCrop: method(object({
+			handle: FrameHandleSchema,
+			bbox: NativeCropBboxSchema,
+			maxWidth: number().int().positive().optional()
+		}), NativeCropResultSchema.nullable())
 	}
 };
 object({
@@ -16442,7 +16477,17 @@ var TrackSchema = object({
 	/** Cumulative normalized distance travelled (0..1 units = full frame width). */
 	totalDistance: number(),
 	state: TrackStateSchema,
-	active: boolean()
+	active: boolean(),
+	/** Deterministic key-event importance score in [0,1] (server-computed at
+	*  track expiry, recomputed on late label). Absent on legacy rows written
+	*  before scoring shipped — consumers degrade to absence / compute-on-read. */
+	importance: number().optional(),
+	/** Id of the track's highest-confidence ObjectEvent (its representative
+	*  "best" frame). Absent when the track produced no object events. */
+	bestEventId: string().optional(),
+	/** Tag of the importance sub-signal that dominated the score
+	*  (identity|dwell|proximity|class|confidence|travel|zone). */
+	importanceReason: string().optional()
 });
 var BaseEventFields = {
 	id: string(),
@@ -16507,8 +16552,18 @@ var ObjectEventSchema = object({
 	frameHeight: number().optional(),
 	/** MediaStore key for the crop attached to this event (if any). */
 	mediaKey: string().optional(),
+	/** Design B: MediaStore key of the track's native-resolution key frame (the
+	*  best-detection full frame). Resolve via the event-media data-plane
+	*  (`/addon/<addonId>/event-media/<keyFrameMediaKey>`) for a detail view that
+	*  draws `bbox` over the native frame. Absent on legacy rows / non-decoded
+	*  sources — consumers fall back to `mediaKey` (the tight crop). */
+	keyFrameMediaKey: string().optional(),
 	/** Populated by B5 (recording playback URL for this event). */
-	mediaUrl: string().optional()
+	mediaUrl: string().optional(),
+	/** The parent track's key-event importance [0,1], propagated to every object
+	*  event of the track (so an event row can be sorted by importance without a
+	*  track join). Absent on legacy rows / before the track was scored. */
+	importance: number().optional()
 });
 var AudioEventSchema = object({
 	...BaseEventFields,
@@ -16532,7 +16587,8 @@ var MediaFileKindEnum = _enum([
 	"fullFrame",
 	"fullFrameBoxed",
 	"faceCrop",
-	"plateCrop"
+	"plateCrop",
+	"keyFrame"
 ]);
 var MediaFileSchema = object({
 	key: string(),
@@ -16553,6 +16609,32 @@ var DeviceEventQueryInput = object({
 	projection: _enum(["full", "slim"]).optional()
 });
 var ObjectEventQueryInput = DeviceEventQueryInput.extend({ classFilter: string().optional() });
+var KeyEventQueryInput = object({
+	deviceId: number(),
+	/** Window lower bound (track firstSeen ≥ since). */
+	since: number(),
+	/** Window upper bound (track firstSeen ≤ until). */
+	until: number(),
+	limit: number().int().min(1).max(200).default(50),
+	/** Drop tracks scoring below this importance. */
+	minImportance: number().min(0).max(1).optional(),
+	/** Restrict to a single class (e.g. 'person'). */
+	classFilter: string().optional()
+});
+var KeyEventSchema = object({
+	/** The representative event id (the track's best ObjectEvent, else its trackId). */
+	id: string(),
+	trackId: string(),
+	/** Track start time (firstSeen). */
+	timestamp: number(),
+	className: string(),
+	label: string().optional(),
+	importance: number(),
+	/** Highest-confidence ObjectEvent id for the track (empty when none). */
+	bestEventId: string(),
+	/** Track lifetime in ms (lastSeen - firstSeen). */
+	windowMs: number().optional()
+});
 var TrackedDetectionSchema = object({
 	trackId: string(),
 	className: string(),
@@ -16582,7 +16664,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), array(TrackSchema).readonly()), method(object({ deviceId: number() }), _void(), {
 	kind: "mutation",
 	auth: "admin"
-}), method(DeviceEventQueryInput, array(MotionEventSchema).readonly()), method(ObjectEventQueryInput, array(ObjectEventSchema).readonly()), method(DeviceEventQueryInput, array(AudioEventSchema).readonly()), method(object({
+}), method(DeviceEventQueryInput, array(MotionEventSchema).readonly()), method(ObjectEventQueryInput, array(ObjectEventSchema).readonly()), method(DeviceEventQueryInput, array(AudioEventSchema).readonly()), method(KeyEventQueryInput, array(KeyEventSchema).readonly()), method(object({
 	deviceId: number(),
 	since: number(),
 	until: number(),
@@ -18594,7 +18676,17 @@ var FaceInfoSchema = object({
 	recognizedIdentityId: string().optional(),
 	identityName: string().optional(),
 	assigned: boolean(),
-	base64: string().optional()
+	base64: string().optional(),
+	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
+	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
+	*  legacy rows written before design B. */
+	faceBbox: BoundingBoxSchema.optional(),
+	/** Design B: MediaStore key of the track's native-resolution key frame.
+	*  Fetch the native JPEG via the event-media data-plane
+	*  (`/addon/<addonId>/event-media/<keyFrameMediaKey>`). Absent when the
+	*  track produced no key frame (e.g. native/onboard source) — the UI falls
+	*  back to the inline `base64` face crop. */
+	keyFrameMediaKey: string().optional()
 });
 var FaceFilterEnum = _enum([
 	"unassigned",
@@ -22746,6 +22838,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getKeyEvents": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.getMotionEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -23274,6 +23372,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineRunner.getNativeCrop": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineRunner.reportMotion": {
 		capName: "pipeline-runner",
 		capScope: "system",

package/dist/{dist-DM6-eQRs.mjs → dist-CEcTeu1h.mjs}

@@ -4627,7 +4627,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-b4Jf2n33.mjs
+//#region ../types/dist/sleep-BC9Yqte7.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -11420,6 +11420,7 @@ var PipelineAddonSchemaSchema = object({
 	defaultModelId: string(),
 	defaultModelIdByFormat: record(string(), string()).optional(),
 	enabledByDefault: boolean().optional(),
+	backfillIntoExistingOverrides: boolean().optional(),
 	defaultConfidence: number(),
 	group: string().optional(),
 	configSchema: array(ConfigFieldBridge).readonly().optional()
@@ -11889,6 +11890,25 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(ZoneSchema).read
 	auth: "admin"
 }), object({ zones: array(ZoneSchema).readonly() });
 /**
+* A bounding box in NORMALIZED [0,1] frame coordinates for `getNativeCrop`. The
+* decode worker resolves it against the RETAINED native frame's real pixel dims,
+* so the caller supplies only the detection-res bbox divided by the detection
+* dims — no native resolution to plumb.
+*/
+var NativeCropBboxSchema = object({
+	x: number(),
+	y: number(),
+	w: number(),
+	h: number()
+});
+/** Result of a best-effort native-resolution crop (`getNativeCrop`). */
+var NativeCropResultSchema = object({
+	/** Packed rgb (24-bit) pixels of the crop. */
+	bytes: _instanceof(Uint8Array),
+	width: number().int().positive(),
+	height: number().int().positive()
+});
+/**
 * Per-camera tunable ranges + defaults. Single source of truth used
 * by both the Zod data schema (validation + default fallback) and
 * the device settings UI (slider min/max/step). Touch one place and
@@ -12192,7 +12212,22 @@ var pipelineRunnerCapability = {
 		/** All per-camera metrics in one round-trip. */
 		getAllCameraMetrics: method(_void(), array(CameraMetricsWithDeviceIdSchema).readonly()),
 		/** List the deviceIds currently attached to this runner. */
-		getLocalCameras: method(_void(), array(number()).readonly())
+		getLocalCameras: method(_void(), array(number()).readonly()),
+		/**
+		* Best-effort NATIVE-resolution crop of a retention-ring frame. Given the
+		* `FrameHandle` that rode an inference-result event and a normalized `bbox`,
+		* the runner asks the decode worker still holding that frame's NATIVE
+		* surface to GPU/CPU-crop ONLY the ROI at native res and download just the
+		* crop. Returns `null` on a miss (handle not registered, or the worker's
+		* tiny native-retention ring already evicted the frame) — the caller falls
+		* back to a detection-frame crop. Routed to the frame's owning node by
+		* `handle.nodeId`; NEVER ships a full native frame.
+		*/
+		getNativeCrop: method(object({
+			handle: FrameHandleSchema,
+			bbox: NativeCropBboxSchema,
+			maxWidth: number().int().positive().optional()
+		}), NativeCropResultSchema.nullable())
 	}
 };
 object({
@@ -16442,7 +16477,17 @@ var TrackSchema = object({
 	/** Cumulative normalized distance travelled (0..1 units = full frame width). */
 	totalDistance: number(),
 	state: TrackStateSchema,
-	active: boolean()
+	active: boolean(),
+	/** Deterministic key-event importance score in [0,1] (server-computed at
+	*  track expiry, recomputed on late label). Absent on legacy rows written
+	*  before scoring shipped — consumers degrade to absence / compute-on-read. */
+	importance: number().optional(),
+	/** Id of the track's highest-confidence ObjectEvent (its representative
+	*  "best" frame). Absent when the track produced no object events. */
+	bestEventId: string().optional(),
+	/** Tag of the importance sub-signal that dominated the score
+	*  (identity|dwell|proximity|class|confidence|travel|zone). */
+	importanceReason: string().optional()
 });
 var BaseEventFields = {
 	id: string(),
@@ -16507,8 +16552,18 @@ var ObjectEventSchema = object({
 	frameHeight: number().optional(),
 	/** MediaStore key for the crop attached to this event (if any). */
 	mediaKey: string().optional(),
+	/** Design B: MediaStore key of the track's native-resolution key frame (the
+	*  best-detection full frame). Resolve via the event-media data-plane
+	*  (`/addon/<addonId>/event-media/<keyFrameMediaKey>`) for a detail view that
+	*  draws `bbox` over the native frame. Absent on legacy rows / non-decoded
+	*  sources — consumers fall back to `mediaKey` (the tight crop). */
+	keyFrameMediaKey: string().optional(),
 	/** Populated by B5 (recording playback URL for this event). */
-	mediaUrl: string().optional()
+	mediaUrl: string().optional(),
+	/** The parent track's key-event importance [0,1], propagated to every object
+	*  event of the track (so an event row can be sorted by importance without a
+	*  track join). Absent on legacy rows / before the track was scored. */
+	importance: number().optional()
 });
 var AudioEventSchema = object({
 	...BaseEventFields,
@@ -16532,7 +16587,8 @@ var MediaFileKindEnum = _enum([
 	"fullFrame",
 	"fullFrameBoxed",
 	"faceCrop",
-	"plateCrop"
+	"plateCrop",
+	"keyFrame"
 ]);
 var MediaFileSchema = object({
 	key: string(),
@@ -16553,6 +16609,32 @@ var DeviceEventQueryInput = object({
 	projection: _enum(["full", "slim"]).optional()
 });
 var ObjectEventQueryInput = DeviceEventQueryInput.extend({ classFilter: string().optional() });
+var KeyEventQueryInput = object({
+	deviceId: number(),
+	/** Window lower bound (track firstSeen ≥ since). */
+	since: number(),
+	/** Window upper bound (track firstSeen ≤ until). */
+	until: number(),
+	limit: number().int().min(1).max(200).default(50),
+	/** Drop tracks scoring below this importance. */
+	minImportance: number().min(0).max(1).optional(),
+	/** Restrict to a single class (e.g. 'person'). */
+	classFilter: string().optional()
+});
+var KeyEventSchema = object({
+	/** The representative event id (the track's best ObjectEvent, else its trackId). */
+	id: string(),
+	trackId: string(),
+	/** Track start time (firstSeen). */
+	timestamp: number(),
+	className: string(),
+	label: string().optional(),
+	importance: number(),
+	/** Highest-confidence ObjectEvent id for the track (empty when none). */
+	bestEventId: string(),
+	/** Track lifetime in ms (lastSeen - firstSeen). */
+	windowMs: number().optional()
+});
 var TrackedDetectionSchema = object({
 	trackId: string(),
 	className: string(),
@@ -16582,7 +16664,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), array(TrackSchema).readonly()), method(object({ deviceId: number() }), _void(), {
 	kind: "mutation",
 	auth: "admin"
-}), method(DeviceEventQueryInput, array(MotionEventSchema).readonly()), method(ObjectEventQueryInput, array(ObjectEventSchema).readonly()), method(DeviceEventQueryInput, array(AudioEventSchema).readonly()), method(object({
+}), method(DeviceEventQueryInput, array(MotionEventSchema).readonly()), method(ObjectEventQueryInput, array(ObjectEventSchema).readonly()), method(DeviceEventQueryInput, array(AudioEventSchema).readonly()), method(KeyEventQueryInput, array(KeyEventSchema).readonly()), method(object({
 	deviceId: number(),
 	since: number(),
 	until: number(),
@@ -18594,7 +18676,17 @@ var FaceInfoSchema = object({
 	recognizedIdentityId: string().optional(),
 	identityName: string().optional(),
 	assigned: boolean(),
-	base64: string().optional()
+	base64: string().optional(),
+	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
+	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
+	*  legacy rows written before design B. */
+	faceBbox: BoundingBoxSchema.optional(),
+	/** Design B: MediaStore key of the track's native-resolution key frame.
+	*  Fetch the native JPEG via the event-media data-plane
+	*  (`/addon/<addonId>/event-media/<keyFrameMediaKey>`). Absent when the
+	*  track produced no key frame (e.g. native/onboard source) — the UI falls
+	*  back to the inline `base64` face crop. */
+	keyFrameMediaKey: string().optional()
 });
 var FaceFilterEnum = _enum([
 	"unassigned",
@@ -22746,6 +22838,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getKeyEvents": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.getMotionEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -23274,6 +23372,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineRunner.getNativeCrop": {
+		capName: "pipeline-runner",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineRunner.reportMotion": {
 		capName: "pipeline-runner",
 		capScope: "system",

package/dist/motion-wasm/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-B-pQhc30.js");
+const require_dist = require("../dist-BbaoC680.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let node_fs = require("node:fs");
 let node_path = require("node:path");

package/dist/motion-wasm/index.mjs

@@ -1,4 +1,4 @@
-import { B as DeviceType, E as motionDetectionCapability, L as BaseAddon, U as hydrateSchema, x as evaluateZoneRules } from "../dist-DM6-eQRs.mjs";
+import { B as DeviceType, E as motionDetectionCapability, L as BaseAddon, U as hydrateSchema, x as evaluateZoneRules } from "../dist-CEcTeu1h.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/pipeline-runner/index.js

@@ -2,10 +2,10 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-B-pQhc30.js");
-const require_remote_source_plane = require("../remote-source-plane-dSe5NlH9.js");
+const require_dist = require("../dist-BbaoC680.js");
+const require_remote_source_plane = require("../remote-source-plane-vN45KFSm.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
-const require_worker_protocol = require("../worker-protocol-BCfO8gUF.js");
+const require_worker_protocol = require("../worker-protocol-DkL6GDxe.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let node_child_process = require("node:child_process");
 let node_url = require("node:url");
@@ -1455,6 +1455,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;
@@ -1519,6 +1522,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();
@@ -1551,6 +1578,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;
@@ -1570,6 +1607,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;
@@ -1701,10 +1747,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;
 		}
@@ -1845,7 +1893,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 },
@@ -1878,6 +1928,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 = {
@@ -2102,6 +2186,13 @@ var PipelineRunnerAddon = class extends require_dist.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;
@@ -2671,6 +2762,23 @@ var PipelineRunnerAddon = class extends require_dist.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;
@@ -2990,8 +3098,9 @@ var PipelineRunnerAddon = class extends require_dist.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);
 					}
 				});