@camstack/addon-pipeline 1.1.53 → 1.1.54

package/dist/audio-analyzer/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-DWb62H5U.js");
+const require_dist = require("../dist-BbaoC680.js");
 const require_node_topology_platform = require("../node-topology-platform-CFZ7F4xW.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let node_fs = require("node:fs");

package/dist/audio-analyzer/index.mjs

@@ -1,5 +1,5 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { C as mapAudioLabelToMacro, I as errMsg, L as BaseAddon, U as hydrateSchema, h as audioAnalyzerCapability, l as HF_BASE_URL, m as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, o as DEFAULT_AUDIO_ANALYZER_CONFIG } from "../dist-BalxNwOt.mjs";
+import { C as mapAudioLabelToMacro, I as errMsg, L as BaseAddon, U as hydrateSchema, h as audioAnalyzerCapability, l as HF_BASE_URL, m as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, o as DEFAULT_AUDIO_ANALYZER_CONFIG } from "../dist-CEcTeu1h.mjs";
 import { t as pickNodePlatformArch } from "../node-topology-platform-BkR_k6WT.mjs";
 import { r as downloadFile } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import * as fs from "node:fs";

package/dist/detection-pipeline/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-DWb62H5U.js");
+const require_dist = require("../dist-BbaoC680.js");
 const require_node_topology_platform = require("../node-topology-platform-CFZ7F4xW.js");
 const require_model_download_service_C_IHWnXx = require("../model-download-service-C-IHWnXx-BLXzxpRB.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
@@ -3723,6 +3723,93 @@ function bboxShortSide(bbox) {
 	return Math.min(bbox[2] - bbox[0], bbox[3] - bbox[1]);
 }
 /**
+* Padded region (clamped to the frame) around a face bbox — the area a native
+* crop must cover so the warp has room around a tilted / edge face. Mirrors the
+* padding {@link alignFaceCrop} applies internally (`padRatio` default 0.4), so
+* the native and fallback paths sample the same neighbourhood.
+*/
+function paddedFaceRegion(faceBbox, imageWidth, imageHeight, padRatio = .4) {
+	const bw = faceBbox[2] - faceBbox[0];
+	const bh = faceBbox[3] - faceBbox[1];
+	const padX = bw * padRatio;
+	const padY = bh * padRatio;
+	return {
+		left: Math.max(0, Math.floor(faceBbox[0] - padX)),
+		top: Math.max(0, Math.floor(faceBbox[1] - padY)),
+		right: Math.min(imageWidth, Math.ceil(faceBbox[2] + padX)),
+		bottom: Math.min(imageHeight, Math.ceil(faceBbox[3] + padY))
+	};
+}
+/**
+* Warp a raw RGB crop of `region` (native-resolution pixels of exactly that
+* detection-space region) so `landmarksImageSpace` land on the ArcFace
+* template. Landmarks are mapped from image space into the crop's local pixel
+* space by the per-axis region→crop scale (handles `maxWidth` downscale of the
+* native crop). Channels default to RGB (3) — the format the decode worker's
+* native surface produces.
+*/
+async function alignFaceCropFromRgb(rgb, region, landmarksImageSpace, opts = {}) {
+	const outSize = opts.outSize ?? 112;
+	const quality = opts.quality ?? 95;
+	const channels = opts.channels ?? 3;
+	const regionW = region.right - region.left;
+	const regionH = region.bottom - region.top;
+	if (regionW < 1 || regionH < 1) throw new Error(`alignFaceCropFromRgb: degenerate region ${regionW}x${regionH}`);
+	if (rgb.width < 2 || rgb.height < 2) throw new Error(`alignFaceCropFromRgb: degenerate crop ${rgb.width}x${rgb.height}`);
+	const scaleX = rgb.width / regionW;
+	const scaleY = rgb.height / regionH;
+	const localLandmarks = landmarksImageSpace.map((l) => ({
+		x: (l.x - region.left) * scaleX,
+		y: (l.y - region.top) * scaleY
+	}));
+	const aligned = warpToTemplate({
+		data: rgb.bytes,
+		width: rgb.width,
+		height: rgb.height,
+		channels
+	}, localLandmarks, opts.template ?? ARCFACE_TEMPLATE_112, outSize);
+	return {
+		jpeg: await (0, sharp.default)(Buffer.from(aligned.data), { raw: {
+			width: aligned.width,
+			height: aligned.height,
+			channels: aligned.channels
+		} }).jpeg({ quality }).toBuffer(),
+		width: aligned.width,
+		height: aligned.height
+	};
+}
+/**
+* Produce a landmark-aligned face crop, preferring a NATIVE-resolution crop
+* (design B — the quality win) and FALLING BACK to today's downscaled
+* full-frame alignment on any native miss/error (never worse than before).
+*
+* The native path requests the padded face region from `nativeCropProvider`
+* (a best-effort local cap round-trip bound to this frame), warps the native
+* pixels; the fallback path re-uses {@link alignFaceCrop} on the downscaled
+* JPEG. ArcFace input is a fixed `outSize`×`outSize` either way — only the crop
+* SOURCE changes, so model cost is unchanged.
+*/
+async function buildAlignedFaceCrop(args) {
+	if (args.nativeCropProvider) try {
+		const region = paddedFaceRegion(args.faceBbox, args.imageWidth, args.imageHeight);
+		const roi = {
+			x: region.left / args.imageWidth,
+			y: region.top / args.imageHeight,
+			w: (region.right - region.left) / args.imageWidth,
+			h: (region.bottom - region.top) / args.imageHeight
+		};
+		const native = await args.nativeCropProvider(roi, args.nativeMaxWidth);
+		if (native && native.width >= 2 && native.height >= 2 && native.bytes.length >= native.width * native.height * 3) return {
+			...await alignFaceCropFromRgb(native, region, args.landmarksImageSpace, { outSize: args.outSize }),
+			source: "native"
+		};
+	} catch {}
+	return {
+		...await alignFaceCrop(args.fullFrameJpeg, args.faceBbox, args.landmarksImageSpace, args.imageWidth, args.imageHeight, { outSize: args.outSize }),
+		source: "fallback"
+	};
+}
+/**
 * Produce an aligned 112x112 JPEG of a face from the full-frame JPEG and the
 * face's 5 landmarks (in absolute image-space coordinates). Decodes a padded
 * region around the face bbox to raw RGB, warps to the ArcFace template, and
@@ -4149,6 +4236,14 @@ function formatTopResult(output) {
 * resolution — a deeper change tracked separately.
 */
 var DEFAULT_MIN_FACE_SIZE_PX = 28;
+/**
+* Cap (px) on the width of the NATIVE face crop fetched for embedding (design
+* B). The arcface input is a fixed 112² warp, so a wider native crop buys no
+* embedding quality past a modest margin but does inflate the per-face transport
+* of the best-effort native-crop round-trip. 320px keeps a distant face well
+* above the downscaled detection resolution while bounding the crop payload.
+*/
+var NATIVE_FACE_CROP_MAX_WIDTH = 320;
 var PipelineExecutor = class {
 	opts;
 	constructor(opts) {
@@ -4178,7 +4273,7 @@ var PipelineExecutor = class {
 	*
 	* @returns FrameResult + optional trace
 	*/
-	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts) {
+	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeFaceCropProvider) {
 		const startMs = Date.now();
 		const verbosity = runOpts?.traceVerbosity ?? "off";
 		const traceBuilder = new ExecutionTraceBuilder(verbosity, deviceId, imageWidth, imageHeight, this.opts.engineRuntime);
@@ -4216,7 +4311,7 @@ var PipelineExecutor = class {
 					continue;
 				}
 				try {
-					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 				} catch (err) {
 					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 						tags: { deviceId },
@@ -4318,7 +4413,7 @@ var PipelineExecutor = class {
 		});
 		return output;
 	}
-	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg) {
+	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider) {
 		for (const child of children) {
 			if (!this.matchesInputClasses(parentDetection.macroClass, child.inputClasses)) continue;
 			const minParentScore = child.settings?.minParentScore ?? child.definition?.defaultMinParentScore;
@@ -4345,7 +4440,18 @@ var PipelineExecutor = class {
 					}
 					const lms = parentDetection.landmarks;
 					if (lms && lms.length >= 5) {
-						const aligned = await alignFaceCrop(fullFrameJpeg, parentDetection.bbox, lms, imageWidth, imageHeight, { outSize: modelEntry.inputSize.width });
+						const aligned = await buildAlignedFaceCrop({
+							fullFrameJpeg,
+							faceBbox: parentDetection.bbox,
+							landmarksImageSpace: lms,
+							imageWidth,
+							imageHeight,
+							outSize: modelEntry.inputSize.width,
+							...nativeFaceCropProvider ? {
+								nativeCropProvider: nativeFaceCropProvider,
+								nativeMaxWidth: NATIVE_FACE_CROP_MAX_WIDTH
+							} : {}
+						});
 						cropJpegBuf = aligned.jpeg;
 						cropW = aligned.width;
 						cropH = aligned.height;
@@ -4379,7 +4485,7 @@ var PipelineExecutor = class {
 								y: l.y + py1
 							}));
 						}
-						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 					}
 				}
 			} catch (err) {
@@ -5871,6 +5977,38 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			debug: { totalInferenceMs: 0 }
 		};
 	}
+	/**
+	* Build the design-B native-face-crop provider for a runtime frame. Present
+	* ONLY when the frame arrived as a retention `frameHandle` (the key the owning
+	* pipeline-runner registered the frame's native surface under) and the sibling
+	* `pipeline-runner` cap is reachable via `ctx.api`. Each call is a best-effort
+	* round-trip pinned to the frame's OWNING node (`nodePin(handle.nodeId)` — the
+	* node that decoded it, i.e. THIS node for a local frame, never a cross-node
+	* hop) that returns the native ROI or `null` on a miss; the executor then
+	* falls back to the downscaled crop, so behaviour is never worse than before.
+	*/
+	buildNativeFaceCropProvider(handle) {
+		if (!handle) return void 0;
+		const api = this.addonCtx?.api;
+		if (!api) return void 0;
+		return async (roi, maxWidth) => {
+			try {
+				const native = await api.pipelineRunner.getNativeCrop.query({
+					handle,
+					bbox: roi,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, require_dist.nodePin(handle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return {
+					bytes: native.bytes,
+					width: native.width,
+					height: native.height
+				};
+			} catch {
+				return null;
+			}
+		};
+	}
 	async runPipeline(input, onProgress) {
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
@@ -6127,7 +6265,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const effectiveDeviceId = input.deviceId ?? 0;
 			const deviceOverrides = effectiveDeviceId > 0 ? await this.readDeviceStore(effectiveDeviceId) : {};
 			const effectiveTree = Object.keys(deviceOverrides).length > 0 ? applyDeviceOverridesToTree(tree, "object-detection", deviceOverrides) : tree;
-			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" });
+			const nativeFaceCropProvider = this.buildNativeFaceCropProvider(input.frameHandle);
+			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" }, nativeFaceCropProvider);
 			if (isRuntime) {
 				if (trace && this.eventBus) this.eventBus.emit(require_dist.createEvent(require_dist.EventCategory.PipelineTrace, {
 					type: "device",

package/dist/detection-pipeline/index.mjs

@@ -1,5 +1,5 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { H as createEvent, I as errMsg, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, X as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, q as parseJsonUnknown, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-BalxNwOt.mjs";
+import { D as nodePin, H as createEvent, I as errMsg, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, X as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, q as parseJsonUnknown, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-CEcTeu1h.mjs";
 import { t as pickNodePlatformArch } from "../node-topology-platform-BkR_k6WT.mjs";
 import { a as isModelDownloaded, i as ensureModel, n as deleteModelFromDisk } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
@@ -3715,6 +3715,93 @@ function bboxShortSide(bbox) {
 	return Math.min(bbox[2] - bbox[0], bbox[3] - bbox[1]);
 }
 /**
+* Padded region (clamped to the frame) around a face bbox — the area a native
+* crop must cover so the warp has room around a tilted / edge face. Mirrors the
+* padding {@link alignFaceCrop} applies internally (`padRatio` default 0.4), so
+* the native and fallback paths sample the same neighbourhood.
+*/
+function paddedFaceRegion(faceBbox, imageWidth, imageHeight, padRatio = .4) {
+	const bw = faceBbox[2] - faceBbox[0];
+	const bh = faceBbox[3] - faceBbox[1];
+	const padX = bw * padRatio;
+	const padY = bh * padRatio;
+	return {
+		left: Math.max(0, Math.floor(faceBbox[0] - padX)),
+		top: Math.max(0, Math.floor(faceBbox[1] - padY)),
+		right: Math.min(imageWidth, Math.ceil(faceBbox[2] + padX)),
+		bottom: Math.min(imageHeight, Math.ceil(faceBbox[3] + padY))
+	};
+}
+/**
+* Warp a raw RGB crop of `region` (native-resolution pixels of exactly that
+* detection-space region) so `landmarksImageSpace` land on the ArcFace
+* template. Landmarks are mapped from image space into the crop's local pixel
+* space by the per-axis region→crop scale (handles `maxWidth` downscale of the
+* native crop). Channels default to RGB (3) — the format the decode worker's
+* native surface produces.
+*/
+async function alignFaceCropFromRgb(rgb, region, landmarksImageSpace, opts = {}) {
+	const outSize = opts.outSize ?? 112;
+	const quality = opts.quality ?? 95;
+	const channels = opts.channels ?? 3;
+	const regionW = region.right - region.left;
+	const regionH = region.bottom - region.top;
+	if (regionW < 1 || regionH < 1) throw new Error(`alignFaceCropFromRgb: degenerate region ${regionW}x${regionH}`);
+	if (rgb.width < 2 || rgb.height < 2) throw new Error(`alignFaceCropFromRgb: degenerate crop ${rgb.width}x${rgb.height}`);
+	const scaleX = rgb.width / regionW;
+	const scaleY = rgb.height / regionH;
+	const localLandmarks = landmarksImageSpace.map((l) => ({
+		x: (l.x - region.left) * scaleX,
+		y: (l.y - region.top) * scaleY
+	}));
+	const aligned = warpToTemplate({
+		data: rgb.bytes,
+		width: rgb.width,
+		height: rgb.height,
+		channels
+	}, localLandmarks, opts.template ?? ARCFACE_TEMPLATE_112, outSize);
+	return {
+		jpeg: await sharp(Buffer.from(aligned.data), { raw: {
+			width: aligned.width,
+			height: aligned.height,
+			channels: aligned.channels
+		} }).jpeg({ quality }).toBuffer(),
+		width: aligned.width,
+		height: aligned.height
+	};
+}
+/**
+* Produce a landmark-aligned face crop, preferring a NATIVE-resolution crop
+* (design B — the quality win) and FALLING BACK to today's downscaled
+* full-frame alignment on any native miss/error (never worse than before).
+*
+* The native path requests the padded face region from `nativeCropProvider`
+* (a best-effort local cap round-trip bound to this frame), warps the native
+* pixels; the fallback path re-uses {@link alignFaceCrop} on the downscaled
+* JPEG. ArcFace input is a fixed `outSize`×`outSize` either way — only the crop
+* SOURCE changes, so model cost is unchanged.
+*/
+async function buildAlignedFaceCrop(args) {
+	if (args.nativeCropProvider) try {
+		const region = paddedFaceRegion(args.faceBbox, args.imageWidth, args.imageHeight);
+		const roi = {
+			x: region.left / args.imageWidth,
+			y: region.top / args.imageHeight,
+			w: (region.right - region.left) / args.imageWidth,
+			h: (region.bottom - region.top) / args.imageHeight
+		};
+		const native = await args.nativeCropProvider(roi, args.nativeMaxWidth);
+		if (native && native.width >= 2 && native.height >= 2 && native.bytes.length >= native.width * native.height * 3) return {
+			...await alignFaceCropFromRgb(native, region, args.landmarksImageSpace, { outSize: args.outSize }),
+			source: "native"
+		};
+	} catch {}
+	return {
+		...await alignFaceCrop(args.fullFrameJpeg, args.faceBbox, args.landmarksImageSpace, args.imageWidth, args.imageHeight, { outSize: args.outSize }),
+		source: "fallback"
+	};
+}
+/**
 * Produce an aligned 112x112 JPEG of a face from the full-frame JPEG and the
 * face's 5 landmarks (in absolute image-space coordinates). Decodes a padded
 * region around the face bbox to raw RGB, warps to the ArcFace template, and
@@ -4141,6 +4228,14 @@ function formatTopResult(output) {
 * resolution — a deeper change tracked separately.
 */
 var DEFAULT_MIN_FACE_SIZE_PX = 28;
+/**
+* Cap (px) on the width of the NATIVE face crop fetched for embedding (design
+* B). The arcface input is a fixed 112² warp, so a wider native crop buys no
+* embedding quality past a modest margin but does inflate the per-face transport
+* of the best-effort native-crop round-trip. 320px keeps a distant face well
+* above the downscaled detection resolution while bounding the crop payload.
+*/
+var NATIVE_FACE_CROP_MAX_WIDTH = 320;
 var PipelineExecutor = class {
 	opts;
 	constructor(opts) {
@@ -4170,7 +4265,7 @@ var PipelineExecutor = class {
 	*
 	* @returns FrameResult + optional trace
 	*/
-	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts) {
+	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeFaceCropProvider) {
 		const startMs = Date.now();
 		const verbosity = runOpts?.traceVerbosity ?? "off";
 		const traceBuilder = new ExecutionTraceBuilder(verbosity, deviceId, imageWidth, imageHeight, this.opts.engineRuntime);
@@ -4208,7 +4303,7 @@ var PipelineExecutor = class {
 					continue;
 				}
 				try {
-					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 				} catch (err) {
 					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 						tags: { deviceId },
@@ -4310,7 +4405,7 @@ var PipelineExecutor = class {
 		});
 		return output;
 	}
-	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg) {
+	async executeChildren(children, parentDetection, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider) {
 		for (const child of children) {
 			if (!this.matchesInputClasses(parentDetection.macroClass, child.inputClasses)) continue;
 			const minParentScore = child.settings?.minParentScore ?? child.definition?.defaultMinParentScore;
@@ -4337,7 +4432,18 @@ var PipelineExecutor = class {
 					}
 					const lms = parentDetection.landmarks;
 					if (lms && lms.length >= 5) {
-						const aligned = await alignFaceCrop(fullFrameJpeg, parentDetection.bbox, lms, imageWidth, imageHeight, { outSize: modelEntry.inputSize.width });
+						const aligned = await buildAlignedFaceCrop({
+							fullFrameJpeg,
+							faceBbox: parentDetection.bbox,
+							landmarksImageSpace: lms,
+							imageWidth,
+							imageHeight,
+							outSize: modelEntry.inputSize.width,
+							...nativeFaceCropProvider ? {
+								nativeCropProvider: nativeFaceCropProvider,
+								nativeMaxWidth: NATIVE_FACE_CROP_MAX_WIDTH
+							} : {}
+						});
 						cropJpegBuf = aligned.jpeg;
 						cropW = aligned.width;
 						cropH = aligned.height;
@@ -4371,7 +4477,7 @@ var PipelineExecutor = class {
 								y: l.y + py1
 							}));
 						}
-						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
+						await this.executeChildren(child.children, detail, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, nativeFaceCropProvider);
 					}
 				}
 			} catch (err) {
@@ -5863,6 +5969,38 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			debug: { totalInferenceMs: 0 }
 		};
 	}
+	/**
+	* Build the design-B native-face-crop provider for a runtime frame. Present
+	* ONLY when the frame arrived as a retention `frameHandle` (the key the owning
+	* pipeline-runner registered the frame's native surface under) and the sibling
+	* `pipeline-runner` cap is reachable via `ctx.api`. Each call is a best-effort
+	* round-trip pinned to the frame's OWNING node (`nodePin(handle.nodeId)` — the
+	* node that decoded it, i.e. THIS node for a local frame, never a cross-node
+	* hop) that returns the native ROI or `null` on a miss; the executor then
+	* falls back to the downscaled crop, so behaviour is never worse than before.
+	*/
+	buildNativeFaceCropProvider(handle) {
+		if (!handle) return void 0;
+		const api = this.addonCtx?.api;
+		if (!api) return void 0;
+		return async (roi, maxWidth) => {
+			try {
+				const native = await api.pipelineRunner.getNativeCrop.query({
+					handle,
+					bbox: roi,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, nodePin(handle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return {
+					bytes: native.bytes,
+					width: native.width,
+					height: native.height
+				};
+			} catch {
+				return null;
+			}
+		};
+	}
 	async runPipeline(input, onProgress) {
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
@@ -6119,7 +6257,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const effectiveDeviceId = input.deviceId ?? 0;
 			const deviceOverrides = effectiveDeviceId > 0 ? await this.readDeviceStore(effectiveDeviceId) : {};
 			const effectiveTree = Object.keys(deviceOverrides).length > 0 ? applyDeviceOverridesToTree(tree, "object-detection", deviceOverrides) : tree;
-			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" });
+			const nativeFaceCropProvider = this.buildNativeFaceCropProvider(input.frameHandle);
+			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, { traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full" }, nativeFaceCropProvider);
 			if (isRuntime) {
 				if (trace && this.eventBus) this.eventBus.emit(createEvent(EventCategory.PipelineTrace, {
 					type: "device",

package/dist/{dist-DWb62H5U.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";
@@ -11890,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
@@ -12193,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({
@@ -16443,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(),
@@ -16508,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,
@@ -16533,7 +16587,8 @@ var MediaFileKindEnum = _enum([
 	"fullFrame",
 	"fullFrameBoxed",
 	"faceCrop",
-	"plateCrop"
+	"plateCrop",
+	"keyFrame"
 ]);
 var MediaFileSchema = object({
 	key: string(),
@@ -16554,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(),
@@ -16583,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(),
@@ -18595,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",
@@ -22747,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",
@@ -23275,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",