@camstack/addon-pipeline 1.2.107 → 1.2.115

package/dist/{addon-utils-Vv2dCqA2.js → addon-utils-C0ht2KPO.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-L-1LMGQs.js");
+const require_dist = require("./dist-BqIbYW1A.js");
 require("node:crypto");
 let node_path = require("node:path");
 node_path = require_dist.__toESM(node_path, 1);
@@ -6,7 +6,7 @@ let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_util = require("node:util");
 let node_zlib = require("node:zlib");
-//#region ../system/dist/file-data-plane-CuE_hBli.mjs
+//#region ../system/dist/file-data-plane-BhKdxJgf.mjs
 function isNonEmptyFile(filePath) {
 	return node_fs.existsSync(filePath) && node_fs.statSync(filePath).size > 0;
 }
@@ -32,21 +32,56 @@ function buildHeaders(url) {
 	if (hfToken && url.includes("huggingface.co")) headers["Authorization"] = `Bearer ${hfToken}`;
 	return headers;
 }
-/**
-* Download a single file from a URL to a destination path.
-* Uses native fetch() (Node 22+) which handles redirects natively.
-* Streams to disk with optional progress callback.
-* Returns the destination path. Skips download if file already exists.
-*/
-async function downloadFile(url, destPath, onProgress) {
+var DEFAULT_MAX_REDIRECTS = 5;
+function normalizeDownloadOptions(third) {
+	if (typeof third === "function") return { onProgress: third };
+	return third ?? {};
+}
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function resolveRedirectUrl(current, location) {
+	return new URL(location, current);
+}
+async function downloadFile(url, destPath, onProgressOrOptions) {
 	if (node_fs.existsSync(destPath)) return destPath;
+	const opts = normalizeDownloadOptions(onProgressOrOptions);
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
 	node_fs.mkdirSync(node_path.dirname(destPath), { recursive: true });
 	const tmpPath = destPath + ".downloading";
 	try {
-		const response = await fetch(url, {
-			redirect: "follow",
-			headers: buildHeaders(url)
-		});
+		let current = url;
+		const seen = /* @__PURE__ */ new Set();
+		let response;
+		const manual = opts.redirectPolicy !== void 0;
+		for (let hop = 0; hop <= maxRedirects; hop++) {
+			const parsed = new URL(current);
+			if (opts.redirectPolicy) opts.redirectPolicy(parsed, hop);
+			if (seen.has(parsed.href)) throw new Error(`Redirect loop detected at ${parsed.href}`);
+			seen.add(parsed.href);
+			const controller = opts.timeoutMs !== void 0 ? new AbortController() : void 0;
+			const timer = controller && opts.timeoutMs !== void 0 ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
+			try {
+				response = await fetchImpl(current, {
+					redirect: manual ? "manual" : "follow",
+					headers: buildHeaders(current),
+					...controller ? { signal: controller.signal } : {}
+				});
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+			if (manual && isRedirectStatus(response.status)) {
+				const location = response.headers.get("location");
+				if (!location) throw new Error(`Redirect ${response.status} missing Location header`);
+				if (hop >= maxRedirects) throw new Error(`Too many redirects (max ${maxRedirects}) downloading ${url}`);
+				current = resolveRedirectUrl(current, location).href;
+				continue;
+			}
+			break;
+		}
+		if (!response) throw new Error(`No response downloading ${url}`);
+		if (manual && isRedirectStatus(response.status)) throw new Error(`Too many redirects (max ${maxRedirects}) downloading ${url}`);
 		if (!response.ok) throw new Error(`HTTP ${response.status} downloading ${url}`);
 		if (!response.body) throw new Error(`No response body from ${url}`);
 		const total = parseInt(response.headers.get("content-length") ?? "0", 10);
@@ -57,9 +92,10 @@ async function downloadFile(url, destPath, onProgress) {
 			for (;;) {
 				const { done, value } = await reader.read();
 				if (done || !value) break;
-				fileStream.write(value);
 				downloaded += value.length;
-				onProgress?.(downloaded, total);
+				if (opts.maxBytes !== void 0 && downloaded > opts.maxBytes) throw new Error(`Downloaded ${downloaded} bytes exceeds the ${opts.maxBytes}-byte limit`);
+				fileStream.write(value);
+				opts.onProgress?.(downloaded, total);
 			}
 		} finally {
 			fileStream.end();

package/dist/{addon-utils-A2S9D7pu.mjs → addon-utils-CgBCF-mE.mjs}

@@ -5,7 +5,7 @@ import * as fs from "node:fs";
 import { createReadStream, promises } from "node:fs";
 import { promisify } from "node:util";
 import { brotliCompress, constants, gzip } from "node:zlib";
-//#region ../system/dist/file-data-plane-CuE_hBli.mjs
+//#region ../system/dist/file-data-plane-BhKdxJgf.mjs
 function isNonEmptyFile(filePath) {
 	return fs.existsSync(filePath) && fs.statSync(filePath).size > 0;
 }
@@ -31,21 +31,56 @@ function buildHeaders(url) {
 	if (hfToken && url.includes("huggingface.co")) headers["Authorization"] = `Bearer ${hfToken}`;
 	return headers;
 }
-/**
-* Download a single file from a URL to a destination path.
-* Uses native fetch() (Node 22+) which handles redirects natively.
-* Streams to disk with optional progress callback.
-* Returns the destination path. Skips download if file already exists.
-*/
-async function downloadFile(url, destPath, onProgress) {
+var DEFAULT_MAX_REDIRECTS = 5;
+function normalizeDownloadOptions(third) {
+	if (typeof third === "function") return { onProgress: third };
+	return third ?? {};
+}
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function resolveRedirectUrl(current, location) {
+	return new URL(location, current);
+}
+async function downloadFile(url, destPath, onProgressOrOptions) {
 	if (fs.existsSync(destPath)) return destPath;
+	const opts = normalizeDownloadOptions(onProgressOrOptions);
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
 	fs.mkdirSync(path$1.dirname(destPath), { recursive: true });
 	const tmpPath = destPath + ".downloading";
 	try {
-		const response = await fetch(url, {
-			redirect: "follow",
-			headers: buildHeaders(url)
-		});
+		let current = url;
+		const seen = /* @__PURE__ */ new Set();
+		let response;
+		const manual = opts.redirectPolicy !== void 0;
+		for (let hop = 0; hop <= maxRedirects; hop++) {
+			const parsed = new URL(current);
+			if (opts.redirectPolicy) opts.redirectPolicy(parsed, hop);
+			if (seen.has(parsed.href)) throw new Error(`Redirect loop detected at ${parsed.href}`);
+			seen.add(parsed.href);
+			const controller = opts.timeoutMs !== void 0 ? new AbortController() : void 0;
+			const timer = controller && opts.timeoutMs !== void 0 ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
+			try {
+				response = await fetchImpl(current, {
+					redirect: manual ? "manual" : "follow",
+					headers: buildHeaders(current),
+					...controller ? { signal: controller.signal } : {}
+				});
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+			if (manual && isRedirectStatus(response.status)) {
+				const location = response.headers.get("location");
+				if (!location) throw new Error(`Redirect ${response.status} missing Location header`);
+				if (hop >= maxRedirects) throw new Error(`Too many redirects (max ${maxRedirects}) downloading ${url}`);
+				current = resolveRedirectUrl(current, location).href;
+				continue;
+			}
+			break;
+		}
+		if (!response) throw new Error(`No response downloading ${url}`);
+		if (manual && isRedirectStatus(response.status)) throw new Error(`Too many redirects (max ${maxRedirects}) downloading ${url}`);
 		if (!response.ok) throw new Error(`HTTP ${response.status} downloading ${url}`);
 		if (!response.body) throw new Error(`No response body from ${url}`);
 		const total = parseInt(response.headers.get("content-length") ?? "0", 10);
@@ -56,9 +91,10 @@ async function downloadFile(url, destPath, onProgress) {
 			for (;;) {
 				const { done, value } = await reader.read();
 				if (done || !value) break;
-				fileStream.write(value);
 				downloaded += value.length;
-				onProgress?.(downloaded, total);
+				if (opts.maxBytes !== void 0 && downloaded > opts.maxBytes) throw new Error(`Downloaded ${downloaded} bytes exceeds the ${opts.maxBytes}-byte limit`);
+				fileStream.write(value);
+				opts.onProgress?.(downloaded, total);
 			}
 		} finally {
 			fileStream.end();

package/dist/audio-analyzer/index.js

@@ -2,9 +2,9 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-L-1LMGQs.js");
-const require_process_memory = require("../process-memory-CgrbLo3l.js");
-const require_addon_utils = require("../addon-utils-Vv2dCqA2.js");
+const require_dist = require("../dist-BqIbYW1A.js");
+const require_process_memory = require("../process-memory-45juuHpN.js");
+const require_addon_utils = require("../addon-utils-C0ht2KPO.js");
 let node_path = require("node:path");
 node_path = require_dist.__toESM(node_path);
 let node_fs = require("node:fs");

package/dist/audio-analyzer/index.mjs

@@ -1,7 +1,7 @@
 import { n as __require } from "../chunk-DnnnRqeS.mjs";
-import { A as audioAnalyzerCapability, Et as hydrateSchema, _ as HF_BASE_URL, ct as resolvePoolMemoryPolicy, ht as errMsg, k as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, q as mapAudioLabelToMacro, s as DEFAULT_AUDIO_ANALYZER_CONFIG, x as PoolMemoryWatchdog, xt as BaseAddon } from "../dist-CkXAzTZ2.mjs";
-import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-DlSOzuHP.mjs";
-import { i as downloadFile } from "../addon-utils-A2S9D7pu.mjs";
+import { A as audioAnalyzerCapability, Et as hydrateSchema, _ as HF_BASE_URL, ct as resolvePoolMemoryPolicy, ht as errMsg, k as audioAnalysisCapability, n as AUDIO_BACKEND_CHOICES, q as mapAudioLabelToMacro, s as DEFAULT_AUDIO_ANALYZER_CONFIG, x as PoolMemoryWatchdog, xt as BaseAddon } from "../dist-DGQkkWc6.mjs";
+import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-BtT7WfbJ.mjs";
+import { i as downloadFile } from "../addon-utils-CgBCF-mE.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs";
 //#region src/audio-analyzer/audio-pipeline.ts

package/dist/detection-pipeline/index.js

@@ -2,11 +2,11 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-L-1LMGQs.js");
-const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-DwAho7HD.js");
-const require_lazy_sharp = require("../lazy-sharp-DfbyQxET.js");
-const require_process_memory = require("../process-memory-CgrbLo3l.js");
-const require_addon_utils = require("../addon-utils-Vv2dCqA2.js");
+const require_dist = require("../dist-BqIbYW1A.js");
+const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-ylMGpz48.js");
+const require_lazy_sharp = require("../lazy-sharp-cOsy7l_P.js");
+const require_process_memory = require("../process-memory-45juuHpN.js");
+const require_addon_utils = require("../addon-utils-C0ht2KPO.js");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 let node_child_process = require("node:child_process");
@@ -264,7 +264,13 @@ var OBJECT_DETECTION_STEP_ID = "object-detection";
 * `null` → the caller substitutes the step's own `defaultModelId` (`yolo26n`).
 * INTEL NPU + iGPU default to OUR YOLOv9 (int8 @320): yolo26 does NOT compile on
 * the Intel NPU (arch incompat → 0 frames), while yolov9 runs on it (~298 fps
-* measured). Apple ANE stays on yolo26 until the CoreML yolov9 build lands.
+* measured). Apple ANE uses the CoreML yolov9 @320 build.
+*
+* Do **not** promote these ids to `yolov9m-640` / `*-640`. The controlled
+* evaluation recovered 0/3 misses at the current 0.50 threshold and failed the
+* false-positive and capacity gates — see
+* `docs/benchmarks/pipeline-frame-model-eval.md`. 640 remains an explicit
+* operator pick, not a hardware-aware default.
 */
 var MODEL_BY_CLASS = {
 	"apple-ane": "yolov9m-320",
@@ -1374,7 +1380,7 @@ function macroOfMinConfidenceKey(key) {
 */
 function reachableMacros(def, entry) {
 	if (entry.labels.length === 0) return void 0;
-	const map = def.classMap;
+	const map = entry.classMap ?? def.classMap;
 	if (!map) return new Set(entry.labels.map((l) => l.id));
 	if (map.preserveOriginal) return void 0;
 	const macros = /* @__PURE__ */ new Set();
@@ -1394,7 +1400,7 @@ function reachableMacros(def, entry) {
 */
 function collectClassMapDropWarning(def, entry) {
 	if (entry.labels.length === 0) return null;
-	const map = def.classMap;
+	const map = entry.classMap ?? def.classMap;
 	if (!map || map.preserveOriginal) return null;
 	const unmapped = entry.labels.filter((l) => map.mapping[l.id] === void 0).map((l) => l.id);
 	if (unmapped.length === 0) return null;
@@ -4170,7 +4176,7 @@ function applyChildOutput(parent, childStep, output, stepLatencyMs, ctx) {
 	switch (output.kind) {
 		case "detections":
 			if (childStep.definition.slot === "refiner") {
-				const classMap = childStep.definition.classMap?.mapping;
+				const classMap = childStep.effectiveClassMap?.mapping;
 				const parentMacro = parent.macroClass;
 				const best = output.detections.filter((d) => {
 					if (d.mask === void 0) return false;
@@ -4510,6 +4516,29 @@ function reprojectCropZoneDetections(output, cropOrigin) {
 		}))
 	};
 }
+function reprojectViewDetections(output, geometry) {
+	const mapPoint = (x, y) => ({
+		x: geometry.sourceCrop.left + x / geometry.scale.x,
+		y: geometry.sourceCrop.top + y / geometry.scale.y
+	});
+	return {
+		kind: "detections",
+		detections: output.detections.map((det) => {
+			const origin = mapPoint(det.bbox[0], det.bbox[1]);
+			const end = mapPoint(det.bbox[2], det.bbox[3]);
+			return {
+				...det,
+				bbox: [
+					origin.x,
+					origin.y,
+					end.x,
+					end.y
+				],
+				...det.landmarks ? { landmarks: det.landmarks.map((landmark) => mapPoint(landmark.x, landmark.y)) } : {}
+			};
+		})
+	};
+}
 var PipelineExecutor = class {
 	opts;
 	/** Bounds the full-frame-guard drop log: first example per (device,
@@ -4571,7 +4600,7 @@ var PipelineExecutor = class {
 	*
 	* @returns FrameResult + optional trace
 	*/
-	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeCropProvider, cropZoneBbox) {
+	async run(tree, rootInput, fullFrameJpegProvider, imageWidth, imageHeight, deviceId, runOpts, nativeCropProvider, cropZoneBbox, rootInputViewProvider) {
 		const startMs = Date.now();
 		const verbosity = runOpts?.traceVerbosity ?? "off";
 		const traceBuilder = new ExecutionTraceBuilder(verbosity, deviceId, imageWidth, imageHeight, this.opts.engineRuntime);
@@ -4619,18 +4648,20 @@ var PipelineExecutor = class {
 		};
 		for (const rootStep of tree.roots) {
 			if (debug) console.log(`[executor] rootStep=${rootStep.stepId} settings=${JSON.stringify(rootStep.settings ?? {})}`);
-			const cropPrep = rootStep.definition.extractMode === "crop-zone" && cropZoneBbox !== void 0 ? await this.prepareCropZoneInput(cropZoneBbox, fullFrameJpegProvider, imageWidth, imageHeight, deviceId) : null;
+			const rootCrop = rootStep.definition.extractMode === "crop-zone" ? cropZoneBbox : void 0;
+			const rootView = rootInputViewProvider ? await rootInputViewProvider(rootStep, rootCrop) : null;
+			const cropPrep = !rootView && rootCrop !== void 0 ? await this.prepareCropZoneInput(rootCrop, fullFrameJpegProvider, imageWidth, imageHeight, deviceId) : null;
 			const rootStart = Date.now();
-			const rawRootOutput = await this.executeStep(rootStep, cropPrep?.input ?? withInferenceDeviceId(rootInput, deviceId), cropPrep?.width ?? imageWidth, cropPrep?.height ?? imageHeight, "full-frame", void 0, void 0, traceBuilder, stepTimings, poolAgg, rootShed);
+			const rawRootOutput = await this.executeStep(rootStep, rootView?.input ?? cropPrep?.input ?? withInferenceDeviceId(rootInput, deviceId), rootView?.width ?? cropPrep?.width ?? imageWidth, rootView?.height ?? cropPrep?.height ?? imageHeight, "full-frame", void 0, void 0, traceBuilder, stepTimings, poolAgg, rootShed);
 			const rootMs = Date.now() - rootStart;
 			if (rawRootOutput === null) continue;
-			const rootOutput = cropPrep && rawRootOutput.kind === "detections" ? reprojectCropZoneDetections(rawRootOutput, cropPrep.origin) : rawRootOutput;
+			const rootOutput = rootView && rawRootOutput.kind === "detections" ? reprojectViewDetections(rawRootOutput, rootView.geometry) : cropPrep && rawRootOutput.kind === "detections" ? reprojectCropZoneDetections(rawRootOutput, cropPrep.origin) : rawRootOutput;
 			if (rootOutput.kind !== "detections") {
 				if (isEnrichmentOutput(rootOutput)) {
 					const mutable = this.synthesizeRootDetection(rootOutput, rootStep, idGen, rootMs, imageWidth, imageHeight);
 					applyChildOutput(mutable, rootStep, rootOutput, rootMs, ctx);
 					try {
-						await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, runOpts?.plane, deviceId, nativeCropProvider);
+						await this.executeChildren(rootStep.children, mutable, rootView?.jpegProvider ?? fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, runOpts?.plane, deviceId, nativeCropProvider);
 					} catch (err) {
 						this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 							tags: { deviceId },
@@ -4648,12 +4679,12 @@ var PipelineExecutor = class {
 			}
 			for (const det of rootOutput.detections) {
 				const mutable = toMutableRootDetection(det, rootStep, idGen, rootMs);
-				if (rootStep.definition.classMap) {
-					const mapped = rootStep.definition.classMap.mapping[det.class];
+				if (rootStep.effectiveClassMap) {
+					const mapped = rootStep.effectiveClassMap.mapping[det.class];
 					if (mapped) {
 						mutable.originalClass = det.class;
 						mutable.macroClass = mapped;
-					} else if (!rootStep.definition.classMap.preserveOriginal) {
+					} else if (!rootStep.effectiveClassMap.preserveOriginal) {
 						(discarded ??= []).push({
 							bbox: [
 								mutable.bbox[0],
@@ -4735,7 +4766,7 @@ var PipelineExecutor = class {
 					}
 				});
 				try {
-					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, runOpts?.plane, deviceId, nativeCropProvider);
+					await this.executeChildren(rootStep.children, mutable, rootView?.jpegProvider ?? fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg, runOpts?.plane, deviceId, nativeCropProvider);
 				} catch (err) {
 					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
 						tags: { deviceId },
@@ -5155,6 +5186,59 @@ function capitalize(s) {
 	return s.charAt(0).toUpperCase() + s.slice(1);
 }
 //#endregion
+//#region src/session-decode/frame-view-payload.ts
+var FRAME_VIEW_PAYLOAD_POLICY = "jpeg";
+//#endregion
+//#region src/detection-pipeline/root-frame-view.ts
+/** Resolve the pre-padding content requested from the decode worker for one root. */
+function resolveRootFrameViewSpec(model, source, crop, format = FRAME_VIEW_PAYLOAD_POLICY) {
+	const sourceWidth = crop?.width ?? source.width;
+	const sourceHeight = crop?.height ?? source.height;
+	if (model.preprocessMode !== "letterbox") return {
+		...crop ? { crop } : {},
+		content: {
+			width: model.inputSize.width,
+			height: model.inputSize.height
+		},
+		fit: "stretch",
+		format
+	};
+	const scale = Math.min(model.inputSize.width / sourceWidth, model.inputSize.height / sourceHeight);
+	return {
+		...crop ? { crop } : {},
+		content: {
+			width: Math.max(1, Math.round(sourceWidth * scale)),
+			height: Math.max(1, Math.round(sourceHeight * scale))
+		},
+		fit: "contain",
+		format
+	};
+}
+//#endregion
+//#region src/detection-pipeline/frame-ref-view-provider.ts
+var LocalFrameRefMissError = class extends Error {
+	reason;
+	constructor(reason) {
+		super(`local frameRef miss: ${reason}`);
+		this.reason = reason;
+		this.name = "LocalFrameRefMissError";
+	}
+};
+/** Bind one registry lease for all heterogeneous roots of a pipeline invocation. */
+function createRootFrameViewResolver(registry, ref) {
+	const lease = registry.acquire(ref);
+	if (!lease) throw new LocalFrameRefMissError(ref.registryId === registry.registryId ? "stale-ref" : "foreign-registry");
+	const resolve = async (root, crop) => {
+		const model = root.definition.models.find((candidate) => candidate.id === root.modelId);
+		if (!model) throw new Error(`frame view model not found: ${root.modelId}`);
+		const spec = resolveRootFrameViewSpec(model, ref, crop);
+		const result = await lease.resolve(spec);
+		if (result.kind === "miss") throw new LocalFrameRefMissError(result.reason);
+		return result;
+	};
+	return Object.assign(resolve, { release: (reason) => lease.release(reason) });
+}
+//#endregion
 //#region src/detection-pipeline/pipeline/native-crop-compose.ts
 /** Clamp `v` into `[lo, hi]`. */
 function clamp(v, lo, hi) {
@@ -5194,23 +5278,32 @@ function composeCropRoiToFrameNorm(roi, cropFrameSpace, frameWidth, frameHeight)
 //#endregion
 //#region src/detection-pipeline/pipeline/tree-builder.ts
 /**
+* Effective class map for `(definition, modelId)` without writing back to the
+* shared StepDefinition. Custom models missing from `definition.models` are
+* resolved through the optional registry callback.
+*/
+function resolveEffectiveClassMap(definition, modelId, resolveModel) {
+	return (definition.models.find((model) => model.id === modelId) ?? resolveModel?.(definition.id, modelId))?.classMap ?? definition.classMap;
+}
+/**
 * Build an executable tree from user config.
 *
 * @param steps - User-configured pipeline steps (from PipelineDefaultStep[])
 * @param getEngine - Function that returns an IInferenceEngine for a step ID.
 *                    Throws if step not loaded.
 */
-function buildExecutableTree(steps, getEngine) {
-	return { roots: steps.filter((s) => s.enabled).filter((s) => s.slot !== "audio-classifier").map((s) => buildNode(s, getEngine)) };
+function buildExecutableTree(steps, getEngine, resolveModel) {
+	return { roots: steps.filter((s) => s.enabled).filter((s) => s.slot !== "audio-classifier").map((s) => buildNode(s, getEngine, resolveModel)) };
 }
-function buildNode(step, getEngine) {
+function buildNode(step, getEngine, resolveModel) {
 	const definition = require_event_loop_stall_monitor.getStepDefinition(step.addonId);
 	const engine = getEngine(step.addonId);
-	const children = (step.children ?? []).filter((c) => c.enabled).map((c) => buildNode(c, getEngine));
+	const children = (step.children ?? []).filter((c) => c.enabled).map((c) => buildNode(c, getEngine, resolveModel));
 	const mergedSettings = {
 		...collectSchemaDefaults(step.addonId),
 		...step.settings
 	};
+	const effectiveClassMap = resolveEffectiveClassMap(definition, step.modelId, resolveModel);
 	return {
 		stepId: step.addonId,
 		definition,
@@ -5219,7 +5312,8 @@ function buildNode(step, getEngine) {
 		inputClasses: definition.inputClasses ?? [],
 		enabled: step.enabled,
 		children,
-		...Object.keys(mergedSettings).length > 0 ? { settings: mergedSettings } : {}
+		...Object.keys(mergedSettings).length > 0 ? { settings: mergedSettings } : {},
+		...effectiveClassMap !== void 0 ? { effectiveClassMap } : {}
 	};
 }
 /**
@@ -7098,17 +7192,30 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		let jpegProvider;
 		const sources = [
 			input.frame ? "frame" : null,
+			input.frameRef ? "frameRef" : null,
 			input.frameHandle ? "frameHandle" : null,
 			input.image ? "image" : null,
 			input.imageBase64 ? "imageBase64" : null,
 			input.referenceImage ? "referenceImage" : null
 		].filter((s) => s !== null);
-		if (sources.length === 0) throw new Error("runPipeline requires exactly one of: frame, frameHandle, image, imageBase64, referenceImage");
+		if (sources.length === 0) throw new Error("runPipeline requires exactly one of: frame, frameRef, frameHandle, image, imageBase64, referenceImage");
 		if (sources.length > 1) throw new Error(`runPipeline received conflicting image sources: ${sources.join(", ")}`);
 		if (input.frameHandle) return this.emptyFrameHandleResult(input);
 		const runtimeFrame = input.frame ?? void 0;
+		const runtimeFrameRef = input.frameRef;
 		const decodeT0 = performance.now();
-		if (runtimeFrame) {
+		if (runtimeFrameRef) {
+			imageWidth = runtimeFrameRef.width;
+			imageHeight = runtimeFrameRef.height;
+			rootInput = {
+				kind: "jpeg",
+				data: Buffer.alloc(0)
+			};
+			jpegProvider = async () => {
+				throw new Error("frameRef root view was requested before model resolution");
+			};
+			emit(`FrameRef: ${imageWidth}×${imageHeight} (${runtimeFrameRef.format})`);
+		} else if (runtimeFrame) {
 			const frame = runtimeFrame;
 			imageWidth = frame.width;
 			imageHeight = frame.height;
@@ -7308,9 +7415,9 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				emit(`All models loaded`);
 			}
 			emit("Running inference...");
-			const tree = buildExecutableTree(benchmarkSteps, (stepId) => dispatchFactory.getEngine(stepId));
+			const tree = buildExecutableTree(benchmarkSteps, (stepId) => dispatchFactory.getEngine(stepId), this.customModelResolver);
 			setupMs = performance.now() - wallT0 - decodeMs;
-			const isRuntime = Boolean(runtimeFrame);
+			const isRuntime = Boolean(runtimeFrame || runtimeFrameRef);
 			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;
@@ -7321,10 +7428,42 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				const proxy = this.deviceProxies.get(effectiveDeviceId);
 				if (proxy) cropZoneBbox = resolvePackageCropBbox(proxy.state.zones.value?.zones ?? [], proxy.state.zoneRules.value?.package ?? [], imageWidth, imageHeight) ?? void 0;
 			}
-			const { result, trace } = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, {
-				traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full",
-				plane: input.plane
-			}, nativeCropProvider, cropZoneBbox);
+			let frameViewResolver;
+			let rootInputViewProvider;
+			if (runtimeFrameRef) {
+				frameViewResolver = createRootFrameViewResolver(require_event_loop_stall_monitor.localFrameRegistry, runtimeFrameRef);
+				rootInputViewProvider = async (root, crop) => {
+					const view = await frameViewResolver(root, crop ? {
+						left: crop[0],
+						top: crop[1],
+						width: crop[2] - crop[0],
+						height: crop[3] - crop[1]
+					} : void 0);
+					const data = Buffer.from(view.data.buffer, view.data.byteOffset, view.data.byteLength);
+					return {
+						input: {
+							kind: "jpeg",
+							data
+						},
+						jpegProvider: async () => data,
+						width: view.width,
+						height: view.height,
+						geometry: view.geometry
+					};
+				};
+			}
+			let executionSucceeded = false;
+			let execution;
+			try {
+				execution = await executor.run(effectiveTree, rootInput, jpegProvider, imageWidth, imageHeight, effectiveDeviceId, {
+					traceVerbosity: isRuntime ? this.eventBus ? "summary" : "off" : "full",
+					plane: input.plane
+				}, nativeCropProvider, cropZoneBbox, rootInputViewProvider);
+				executionSucceeded = true;
+			} finally {
+				frameViewResolver?.release(executionSucceeded ? "success" : "error");
+			}
+			const { result, trace } = execution;
 			if (isRuntime) {
 				if (trace && this.eventBus) this.eventBus.emit(require_dist.createEvent(require_dist.EventCategory.PipelineTrace, {
 					type: "device",