framefields 2.8.0 → 2.9.0

package/dist/{renderer-BD25uND8.mjs → renderer-B0piZg9r.mjs}

@@ -7,14 +7,14 @@ import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 
-//#region ../vision/dist/registry-CSFimt7C.mjs
+//#region ../vision/dist/registry-RNCQoD9e.mjs
 const hf = (repo, revision, path$1) => `https://huggingface.co/${repo}/resolve/${revision}/${path$1}`;
 const RTMDET_INS_REPO = "tori29umai/rtmdet-ins-onnx-person-masks";
 const RTMDET_INS_REV = "e5218e8d47d7c50077f27f9893a28e0ef2ad5656";
 const RTMDET_INS_SOURCE = "RTMDet-Ins (OpenMMLab mmdetection, Apache-2.0), mmdeploy ONNX export";
 const RTMO_SOURCE = "RTMO (OpenMMLab mmpose, Apache-2.0), ONNX export";
 const SELFIE_SOURCE = "MediaPipe Selfie Segmenter (Google, Apache-2.0), ONNX export";
-const VISION_MODELS = {
+const models = {
 	"rtmdet-ins-t": {
 		key: "rtmdet-ins-t",
 		family: "rtmdet-ins",
@@ -96,6 +96,7 @@ const VISION_MODELS = {
 		source: SELFIE_SOURCE
 	}
 };
+const VISION_MODELS = models;
 /**
 * Resolves the model for a task. `detect` and `segment` share RTMDet-Ins (one forward pass
 * yields both); `matte` picks the landscape Selfie Segmenter for wide frames.
@@ -190,7 +191,7 @@ const COCO_CLASSES = [
 ];
 
 //#endregion
-//#region ../vision/dist/src-DNIUH8PT.mjs
+//#region ../vision/dist/src-Bfz8DtoR.mjs
 function computeIoU(boxA, boxB) {
 	const xA = Math.max(boxA.originX, boxB.originX);
 	const yA = Math.max(boxA.originY, boxB.originY);
@@ -712,6 +713,10 @@ const PREPROCESS_BY_FAMILY = {
 		padValue: 0
 	}
 };
+/** True for the families `VisionRunner` can preprocess and decode itself. */
+function isPreprocessFamily(family) {
+	return Object.hasOwn(PREPROCESS_BY_FAMILY, family);
+}
 function preprocessSpec(family, input) {
 	return {
 		...PREPROCESS_BY_FAMILY[family],
@@ -1611,6 +1616,7 @@ var VisionModelStore = class {
 	_verify;
 	_fetch;
 	_onProgress;
+	_acceptLicense;
 	_inflight = /* @__PURE__ */ new Map();
 	_buffers = /* @__PURE__ */ new Map();
 	_status = /* @__PURE__ */ new Map();
@@ -1623,29 +1629,34 @@ var VisionModelStore = class {
 		this._verify = options.verify !== false;
 		this._fetch = options.fetchImpl ?? globalThis.fetch;
 		this._onProgress = options.onProgress;
+		this._acceptLicense = options.acceptLicense === true;
 	}
 	get modelsDir() {
 		return this._modelsDir;
 	}
 	pathFor(key) {
-		return join(this._modelsDir, VISION_MODELS[key].filename);
+		return join(this._modelsDir, this.descriptor(key).filename);
 	}
 	descriptor(key) {
-		return VISION_MODELS[key];
+		const desc = VISION_MODELS[key];
+		if (!desc) throw new Error(`Vision model '${key}' is not registered in the model store.`);
+		return desc;
 	}
 	/** The URL `ensure(key)` downloads from (mirror when `baseUrl` is set). */
 	urlFor(key) {
-		const desc = VISION_MODELS[key];
+		const desc = this.descriptor(key);
 		if (!this._baseUrl) return desc.url;
 		return `${this._baseUrl.replace(/\/+$/, "")}/${desc.filename}`;
 	}
 	/** True when a complete cached file exists (exact registry size when verifying). */
 	has(key) {
-		const targetPath = this.pathFor(key);
+		const desc = VISION_MODELS[key];
+		if (!desc) return false;
+		const targetPath = join(this._modelsDir, desc.filename);
 		if (!existsSync(targetPath)) return false;
 		try {
 			const size = statSync(targetPath).size;
-			return this._verify ? size === VISION_MODELS[key].bytes : size > 0;
+			return this._verify ? size === desc.bytes : size > 0;
 		} catch {
 			return false;
 		}
@@ -1685,11 +1696,15 @@ var VisionModelStore = class {
 		await Promise.all([...new Set(keys)].map((key) => this.ensure(key)));
 	}
 	async load(key) {
+		const desc = this.descriptor(key);
 		const targetPath = this.pathFor(key);
 		if (this.has(key)) {
 			this._status.set(key, "ready");
 			return this.readBuffer(key, targetPath);
 		}
+		if (desc.license && desc.license !== "Apache-2.0") {
+			if (!this._acceptLicense && process.env.FRAMEFIELDS_ACCEPT_SAM_LICENSE !== "1") throw new Error(`License agreement required for model "${key}":\nThis model is licensed under "${desc.license}".\nTo download and use this model, you must accept its license terms by passing 'acceptLicense: true' or setting FRAMEFIELDS_ACCEPT_SAM_LICENSE=1.`);
+		}
 		const downloadUrl = this.urlFor(key);
 		this._status.set(key, "downloading");
 		if (!existsSync(dirname(targetPath))) mkdirSync(dirname(targetPath), { recursive: true });
@@ -1751,6 +1766,98 @@ var VisionModelStore = class {
 		this._buffers.clear();
 	}
 };
+/**
+* Minimal ONNX protobuf wire-format helpers: split a message into fields,
+* read strings, write length-delimited fields. Only what the graph editors
+* (onnx-subgraph.ts, onnx-float16.ts) need; unknown fields are copied as raw
+* bytes, so nothing else in a model is touched.
+*/
+const MODEL_GRAPH$1 = 7;
+const GRAPH_NODE$1 = 1;
+const GRAPH_INITIALIZER = 5;
+const GRAPH_INPUT$1 = 11;
+const GRAPH_OUTPUT$1 = 12;
+const GRAPH_VALUE_INFO = 13;
+const NODE_INPUT$1 = 1;
+const NODE_OUTPUT$2 = 2;
+const VALUE_INFO_NAME = 1;
+const TENSOR_NAME = 8;
+const WIRE_VARINT = 0;
+const WIRE_I64 = 1;
+const WIRE_LEN = 2;
+const WIRE_I32 = 5;
+function readVarint(buf, pos) {
+	let value = 0;
+	let scale = 1;
+	for (;;) {
+		if (pos >= buf.length) throw new Error("ONNX model: truncated varint");
+		const byte = buf[pos++];
+		value += (byte & 127) * scale;
+		if (byte < 128) return [value, pos];
+		scale *= 128;
+	}
+}
+function fields(buf) {
+	const out = [];
+	let pos = 0;
+	while (pos < buf.length) {
+		const start = pos;
+		const [tag, afterTag] = readVarint(buf, pos);
+		pos = afterTag;
+		const number$1 = Math.floor(tag / 8);
+		const wire = tag & 7;
+		let body = buf.subarray(pos, pos);
+		if (wire === WIRE_VARINT) pos = readVarint(buf, pos)[1];
+		else if (wire === WIRE_I64) pos += 8;
+		else if (wire === WIRE_I32) pos += 4;
+		else if (wire === WIRE_LEN) {
+			const [length, afterLength] = readVarint(buf, pos);
+			body = buf.subarray(afterLength, afterLength + length);
+			pos = afterLength + length;
+		} else throw new Error(`ONNX model: unsupported wire type ${wire}`);
+		if (pos > buf.length) throw new Error("ONNX model: truncated field");
+		out.push({
+			number: number$1,
+			wire,
+			raw: buf.subarray(start, pos),
+			body
+		});
+	}
+	return out;
+}
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+function strings(buf, number$1) {
+	return fields(buf).filter((f) => f.number === number$1 && f.wire === WIRE_LEN).map((f) => decoder.decode(f.body));
+}
+function firstString(buf, number$1) {
+	return strings(buf, number$1)[0];
+}
+function varint(value) {
+	const bytes = [];
+	while (value >= 128) {
+		bytes.push(value % 128 | 128);
+		value = Math.floor(value / 128);
+	}
+	bytes.push(value);
+	return bytes;
+}
+function lengthDelimited(number$1, payload) {
+	const head = [...varint(number$1 * 8 + WIRE_LEN), ...varint(payload.length)];
+	const out = new Uint8Array(head.length + payload.length);
+	out.set(head, 0);
+	out.set(payload, head.length);
+	return out;
+}
+function concat(parts) {
+	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
 /** Neutral fallbacks so signal evaluators always have a well-formed frame to read. */
 function createNeutralObjectResult() {
 	return {
@@ -1941,98 +2048,6 @@ function maskLogits(head, anchor, out) {
 	return logits;
 }
 /**
-* Minimal ONNX protobuf wire-format helpers: split a message into fields,
-* read strings, write length-delimited fields. Only what the graph editors
-* (onnx-subgraph.ts, onnx-float16.ts) need; unknown fields are copied as raw
-* bytes, so nothing else in a model is touched.
-*/
-const MODEL_GRAPH = 7;
-const GRAPH_NODE = 1;
-const GRAPH_INITIALIZER = 5;
-const GRAPH_INPUT = 11;
-const GRAPH_OUTPUT = 12;
-const GRAPH_VALUE_INFO = 13;
-const NODE_INPUT = 1;
-const NODE_OUTPUT$1 = 2;
-const VALUE_INFO_NAME = 1;
-const TENSOR_NAME = 8;
-const WIRE_VARINT = 0;
-const WIRE_I64 = 1;
-const WIRE_LEN = 2;
-const WIRE_I32 = 5;
-function readVarint(buf, pos) {
-	let value = 0;
-	let scale = 1;
-	for (;;) {
-		if (pos >= buf.length) throw new Error("ONNX model: truncated varint");
-		const byte = buf[pos++];
-		value += (byte & 127) * scale;
-		if (byte < 128) return [value, pos];
-		scale *= 128;
-	}
-}
-function fields(buf) {
-	const out = [];
-	let pos = 0;
-	while (pos < buf.length) {
-		const start = pos;
-		const [tag, afterTag] = readVarint(buf, pos);
-		pos = afterTag;
-		const number = Math.floor(tag / 8);
-		const wire = tag & 7;
-		let body = buf.subarray(pos, pos);
-		if (wire === WIRE_VARINT) pos = readVarint(buf, pos)[1];
-		else if (wire === WIRE_I64) pos += 8;
-		else if (wire === WIRE_I32) pos += 4;
-		else if (wire === WIRE_LEN) {
-			const [length, afterLength] = readVarint(buf, pos);
-			body = buf.subarray(afterLength, afterLength + length);
-			pos = afterLength + length;
-		} else throw new Error(`ONNX model: unsupported wire type ${wire}`);
-		if (pos > buf.length) throw new Error("ONNX model: truncated field");
-		out.push({
-			number,
-			wire,
-			raw: buf.subarray(start, pos),
-			body
-		});
-	}
-	return out;
-}
-const decoder = new TextDecoder();
-const encoder = new TextEncoder();
-function strings(buf, number) {
-	return fields(buf).filter((f) => f.number === number && f.wire === WIRE_LEN).map((f) => decoder.decode(f.body));
-}
-function firstString(buf, number) {
-	return strings(buf, number)[0];
-}
-function varint(value) {
-	const bytes = [];
-	while (value >= 128) {
-		bytes.push(value % 128 | 128);
-		value = Math.floor(value / 128);
-	}
-	bytes.push(value);
-	return bytes;
-}
-function lengthDelimited(number, payload) {
-	const head = [...varint(number * 8 + WIRE_LEN), ...varint(payload.length)];
-	const out = new Uint8Array(head.length + payload.length);
-	out.set(head, 0);
-	out.set(payload, head.length);
-	return out;
-}
-function concat(parts) {
-	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
-	let offset = 0;
-	for (const part of parts) {
-		out.set(part, offset);
-		offset += part.length;
-	}
-	return out;
-}
-/**
 * Cuts an ONNX model down to the nodes that compute a chosen set of tensors,
 * which become the graph's outputs. Works on the protobuf wire format directly
 * (only the fields it needs are decoded; everything else is copied byte for
@@ -2054,13 +2069,13 @@ function floatOutput(name) {
 */
 function extractSubgraph(model, outputs) {
 	const modelFields = fields(model);
-	const graphField = modelFields.find((f) => f.number === MODEL_GRAPH && f.wire === WIRE_LEN);
+	const graphField = modelFields.find((f) => f.number === MODEL_GRAPH$1 && f.wire === WIRE_LEN);
 	if (!graphField) throw new Error("ONNX model has no graph");
 	const graphFields = fields(graphField.body);
-	const nodes = graphFields.filter((f) => f.number === GRAPH_NODE).map((f) => ({
+	const nodes = graphFields.filter((f) => f.number === GRAPH_NODE$1).map((f) => ({
 		field: f,
-		inputs: strings(f.body, NODE_INPUT),
-		outputs: strings(f.body, NODE_OUTPUT$1)
+		inputs: strings(f.body, NODE_INPUT$1),
+		outputs: strings(f.body, NODE_OUTPUT$2)
 	}));
 	const producer = /* @__PURE__ */ new Map();
 	nodes.forEach((node, index) => {
@@ -2088,7 +2103,7 @@ function extractSubgraph(model, outputs) {
 	const parts = [];
 	let nodeIndex = 0;
 	for (const f of graphFields) switch (f.number) {
-		case GRAPH_NODE:
+		case GRAPH_NODE$1:
 			if (keepNode.has(nodeIndex)) parts.push(f.raw);
 			nodeIndex++;
 			break;
@@ -2097,18 +2112,66 @@ function extractSubgraph(model, outputs) {
 			if (name !== void 0 && needed.has(name)) parts.push(f.raw);
 			break;
 		}
-		case GRAPH_INPUT:
+		case GRAPH_INPUT$1:
 		case GRAPH_VALUE_INFO: {
 			const name = firstString(f.body, VALUE_INFO_NAME);
 			if (name !== void 0 && needed.has(name)) parts.push(f.raw);
 			break;
 		}
-		case GRAPH_OUTPUT: break;
+		case GRAPH_OUTPUT$1: break;
 		default: parts.push(f.raw);
 	}
-	for (const name of outputs) parts.push(lengthDelimited(GRAPH_OUTPUT, valueInfo.get(name) ?? floatOutput(name)));
+	for (const name of outputs) parts.push(lengthDelimited(GRAPH_OUTPUT$1, valueInfo.get(name) ?? floatOutput(name)));
 	const graph = concat(parts);
-	return concat(modelFields.map((f) => f === graphField ? lengthDelimited(MODEL_GRAPH, graph) : f.raw));
+	return concat(modelFields.map((f) => f === graphField ? lengthDelimited(MODEL_GRAPH$1, graph) : f.raw));
+}
+const MODEL_IR_VERSION = 1;
+const MODEL_OPSET_IMPORT = 8;
+const MODEL_GRAPH = 7;
+const OPSET_VERSION = 2;
+const GRAPH_NODE = 1;
+const GRAPH_NAME = 2;
+const GRAPH_INPUT = 11;
+const GRAPH_OUTPUT = 12;
+const NODE_INPUT = 1;
+const NODE_OUTPUT$1 = 2;
+const NODE_OP_TYPE$1 = 4;
+const VALUE_NAME = 1;
+const VALUE_TYPE = 2;
+const TYPE_TENSOR = 1;
+const TENSOR_ELEM_TYPE = 1;
+const TENSOR_SHAPE = 2;
+const SHAPE_DIM = 1;
+const DIM_VALUE = 1;
+const FLOAT = 1;
+const text = (field, value) => lengthDelimited(field, encoder.encode(value));
+const number = (field, value) => new Uint8Array([...varint(field * 8), ...varint(value)]);
+function floatVector(name) {
+	const dim = lengthDelimited(SHAPE_DIM, number(DIM_VALUE, 1));
+	const tensor = concat([number(TENSOR_ELEM_TYPE, FLOAT), lengthDelimited(TENSOR_SHAPE, dim)]);
+	return concat([text(VALUE_NAME, name), lengthDelimited(VALUE_TYPE, lengthDelimited(TYPE_TENSOR, tensor))]);
+}
+let probe;
+/**
+* A one-node ONNX model (`y = Identity(x)`, float[1]). Creating a session from it tells
+* whether an execution provider works here before any real model is downloaded.
+*/
+function probeModel() {
+	probe ??= concat([
+		number(MODEL_IR_VERSION, 8),
+		lengthDelimited(MODEL_OPSET_IMPORT, number(OPSET_VERSION, 13)),
+		lengthDelimited(MODEL_GRAPH, concat([
+			lengthDelimited(GRAPH_NODE, concat([
+				text(NODE_INPUT, "x"),
+				text(NODE_OUTPUT$1, "y"),
+				text(NODE_OP_TYPE$1, "Identity")
+			])),
+			text(GRAPH_NAME, "probe"),
+			lengthDelimited(GRAPH_INPUT, floatVector("x")),
+			lengthDelimited(GRAPH_OUTPUT, floatVector("y"))
+		]))
+	]);
+	return probe;
 }
 /**
 * onnxruntime-web 1.30's WebGPU EP computes grouped convolutions wrong in its
@@ -2151,7 +2214,7 @@ function tensorDims(tensor) {
 function needsNchwLayout(model) {
 	let graph;
 	try {
-		graph = fields(model).find((f) => f.number === MODEL_GRAPH && f.wire === WIRE_LEN);
+		graph = fields(model).find((f) => f.number === MODEL_GRAPH$1 && f.wire === WIRE_LEN);
 	} catch {
 		return true;
 	}
@@ -2161,7 +2224,7 @@ function needsNchwLayout(model) {
 	for (const f of fields(graph.body)) if (f.number === GRAPH_INITIALIZER) {
 		const name = firstString(f.body, TENSOR_NAME);
 		if (name !== void 0) dims.set(name, tensorDims(f.body));
-	} else if (f.number === GRAPH_NODE) {
+	} else if (f.number === GRAPH_NODE$1) {
 		const op = firstString(f.body, NODE_OP_TYPE);
 		if (op !== "Conv" && op !== "Constant") continue;
 		const attributes = fields(f.body).filter((a) => a.number === NODE_ATTRIBUTE).map((a) => a.body);
@@ -2175,7 +2238,7 @@ function needsNchwLayout(model) {
 		const groupAttr = attributes.find((a) => firstString(a, ATTR_NAME) === "group");
 		const groupField = groupAttr && fields(groupAttr).find((a) => a.number === ATTR_I);
 		const group = groupField ? varintValues(groupField)[0] ?? 1 : 1;
-		const weight = strings(f.body, NODE_INPUT)[1];
+		const weight = strings(f.body, NODE_INPUT$1)[1];
 		if (group > 1 && weight) convs.push({
 			weight,
 			group
@@ -2222,42 +2285,58 @@ var WebGPUProvider = class {
 		});
 		return this._ortPromise;
 	}
-	async createSession(modelBytes) {
-		const ort = await this.ort();
-		let session;
+	async createOrtSession(ort, modelBytes, options) {
 		try {
 			const device = this.device;
 			const layout = needsNchwLayout(modelBytes) ? "NCHW" : "NHWC";
-			session = await ort.InferenceSession.create(modelBytes, {
+			return await ort.InferenceSession.create(modelBytes, {
 				executionProviders: this._providers.map((name) => withProviderOptions(name, device, layout)),
 				graphOptimizationLevel: "all",
+				externalData: options?.externalData?.map(({ path: path$1, data }) => ({
+					path: path$1,
+					data
+				})),
 				logSeverityLevel: 3
 			});
 		} catch (err) {
 			if (!this._wasmFallback || !this._providers.includes("webgpu")) throw err;
-			session = await ort.InferenceSession.create(modelBytes, {
+			return await ort.InferenceSession.create(modelBytes, {
 				executionProviders: ["wasm"],
 				graphOptimizationLevel: "all",
+				externalData: options?.externalData?.map(({ path: path$1, data }) => ({
+					path: path$1,
+					data
+				})),
 				logSeverityLevel: 3
 			});
 		}
-		return {
-			run: async (input) => {
-				const inputName = session.inputNames.includes(input.name) ? input.name : session.inputNames[0] ?? input.name;
-				const tensor = input.gpuBuffer && ort.Tensor.fromGpuBuffer ? ort.Tensor.fromGpuBuffer(input.gpuBuffer, {
+	}
+	async createSession(modelBytes, options) {
+		const ort = await this.ort();
+		const session = await exclusive(ort, () => this.createOrtSession(ort, modelBytes, options));
+		const runMany = async (inputs) => {
+			const feeds = {};
+			for (const input of inputs) {
+				const name = inputs.length === 1 && !session.inputNames.includes(input.name) ? session.inputNames[0] ?? input.name : input.name;
+				if (input.gpuBuffer && !(input.data instanceof Float32Array)) throw new Error("GPU-buffer vision inputs must be float32.");
+				feeds[name] = input.gpuBuffer && ort.Tensor.fromGpuBuffer ? ort.Tensor.fromGpuBuffer(input.gpuBuffer, {
 					dataType: "float32",
 					dims: [...input.dims]
-				}) : new ort.Tensor("float32", input.data, [...input.dims]);
-				const results = await session.run({ [inputName]: tensor });
-				const outputs = {};
-				for (const [name, tensor$1] of Object.entries(results)) outputs[name] = {
-					data: tensor$1.data,
-					dims: [...tensor$1.dims]
-				};
-				return outputs;
-			},
+				}) : new ort.Tensor(input.data instanceof Uint8Array ? "bool" : input.data instanceof BigInt64Array ? "int64" : input.data instanceof Int32Array ? "int32" : "float32", input.data, [...input.dims]);
+			}
+			const results = await exclusive(ort, () => session.run(feeds));
+			const outputs = {};
+			for (const [name, tensor] of Object.entries(results)) outputs[name] = {
+				data: tensor.data,
+				dims: [...tensor.dims]
+			};
+			return outputs;
+		};
+		return {
+			run: (input) => runMany([input]),
+			runMany,
 			release: () => {
-				session.release();
+				exclusive(ort, () => session.release());
 			}
 		};
 	}
@@ -2279,6 +2358,17 @@ function withProviderOptions(name, device, preferredLayout) {
 		preferredLayout
 	};
 }
+/**
+* ORT Web's WebGPU build takes one call at a time per runtime: a concurrent session create
+* throws, and a run entered while another awaits the GPU corrupts its wasm heap. Every
+* create, run and release on one module therefore queues here.
+*/
+const queues = /* @__PURE__ */ new WeakMap();
+function exclusive(ort, call) {
+	const result = (queues.get(ort) ?? Promise.resolve()).then(call, call);
+	queues.set(ort, result.catch(() => void 0));
+	return result;
+}
 const ORT_WEBGPU_SPECIFIER = "onnxruntime-web/webgpu";
 const WEBGPU_SPECIFIER = "webgpu";
 let nodeWebGPUReady;
@@ -2377,10 +2467,15 @@ var NodeWebGPUProvider = class {
 			loader
 		});
 	}
-	createSession(modelBytes) {
-		return this._inner.createSession(modelBytes);
+	createSession(modelBytes, options) {
+		return this._inner.createSession(modelBytes, options);
 	}
 };
+/** Where a provider's sessions run: its own answer, else WebGPU for WebGPU providers, else CPU. */
+function sessionCompute(provider) {
+	if (provider.backend) return provider.backend();
+	return Promise.resolve(provider.kind === "webgpu" ? "webgpu" : "cpu");
+}
 let defaultProvider;
 let visionDevice;
 /**
@@ -2427,22 +2522,30 @@ var AutoSessionProvider = class {
 	get device() {
 		return this._resolved?.device;
 	}
-	async createSession(modelBytes) {
-		if (this._resolved) return this._resolved.createSession(modelBytes);
-		if (!this._resolving) {
-			this._resolving = this.resolve(modelBytes);
-			this._resolving.catch(() => {
-				this._resolving = void 0;
-			});
-			const { provider: provider$1, first } = await this._resolving;
-			this._resolved = provider$1;
-			if (first) return first;
-			return provider$1.createSession(modelBytes);
-		}
-		const { provider } = await this._resolving;
-		return provider.createSession(modelBytes);
+	async createSession(modelBytes, options) {
+		if (this._resolved) return this._resolved.createSession(modelBytes, options);
+		if (this._resolving) return (await this._resolving).provider.createSession(modelBytes, options);
+		const { provider, first } = await this.start(modelBytes, options);
+		return first ?? provider.createSession(modelBytes, options);
+	}
+	/** Where sessions run. Before the first session it decides with a one-node probe graph. */
+	async backend() {
+		if (!this._resolved && !this._resolving) (await this.start(probeModel())).first?.release();
+		const provider = this._resolved ?? (await this._resolving)?.provider;
+		if (!provider) throw new Error("No vision backend could be resolved.");
+		return sessionCompute(provider);
+	}
+	start(modelBytes, options) {
+		const resolving = this.resolve(modelBytes, options);
+		this._resolving = resolving;
+		resolving.then(({ provider }) => {
+			this._resolved = provider;
+		}, () => {
+			this._resolving = void 0;
+		});
+		return resolving;
 	}
-	async resolve(modelBytes) {
+	async resolve(modelBytes, options) {
 		const backend = requestedVisionBackend();
 		if (backend === "cpu") {
 			reportBackend({
@@ -2457,14 +2560,23 @@ var AutoSessionProvider = class {
 				backend: "cuda",
 				sharedDevice: false
 			});
-			return { provider: new NodeSessionProvider({ executionProviders: ["cuda", "cpu"] }) };
+			return { provider: cudaProvider() };
 		}
+		if (backend === "auto" && await hasNvidiaDriver()) try {
+			const first = await new NodeSessionProvider({ executionProviders: ["cuda"] }).createSession(modelBytes, options);
+			reportBackend({
+				backend: "cuda",
+				sharedDevice: false
+			});
+			first.release();
+			return { provider: cudaProvider() };
+		} catch {}
 		const webgpu = new NodeWebGPUProvider({
 			wasmFallback: false,
 			device: visionDevice
 		});
 		try {
-			const first = await webgpu.createSession(modelBytes);
+			const first = await webgpu.createSession(modelBytes, options);
 			reportBackend({
 				backend: "webgpu",
 				sharedDevice: !!visionDevice
@@ -2484,6 +2596,20 @@ var AutoSessionProvider = class {
 		}
 	}
 };
+function cudaProvider() {
+	return new NodeSessionProvider({ executionProviders: ["cuda", "cpu"] });
+}
+/** True on Linux with the NVIDIA kernel driver loaded (checked without touching CUDA). */
+async function hasNvidiaDriver() {
+	if (typeof process === "undefined" || process.platform !== "linux") return false;
+	try {
+		const { access } = await import("node:fs/promises");
+		await access("/proc/driver/nvidia/version");
+		return true;
+	} catch {
+		return false;
+	}
+}
 let processProvider;
 /**
 * The provider for a runner created without one: GPU if possible, otherwise CPU.
@@ -2509,7 +2635,7 @@ async function availableCpus() {
 async function cgroupCpuQuota() {
 	if (typeof process === "undefined" || process.platform !== "linux") return;
 	const { readFile: readFile$1 } = await import("node:fs/promises");
-	const read = (path$1) => readFile$1(path$1, "utf8").then((text) => text.trim(), () => void 0);
+	const read = (path$1) => readFile$1(path$1, "utf8").then((text$1) => text$1.trim(), () => void 0);
 	const toCpus = (quota, period) => quota > 0 && period > 0 ? Math.ceil(quota / period) : void 0;
 	const v2 = await read("/sys/fs/cgroup/cpu.max");
 	if (v2 !== void 0) {
@@ -2539,6 +2665,9 @@ var NodeSessionProvider = class {
 	constructor(options = {}) {
 		this._executionProviders = options.executionProviders ?? ["cpu"];
 	}
+	backend() {
+		return Promise.resolve(this._executionProviders.includes("cuda") ? "cuda" : "cpu");
+	}
 	ortPromise;
 	async ort() {
 		if (!this.ortPromise) this.ortPromise = import("onnxruntime-node").catch((err) => {
@@ -2547,28 +2676,39 @@ var NodeSessionProvider = class {
 		});
 		return this.ortPromise;
 	}
-	async createSession(modelBytes) {
+	async createSession(modelBytes, options) {
 		const ort = await this.ort();
 		const threads = await cpuSessionThreads();
 		const session = await ort.InferenceSession.create(modelBytes, {
 			executionProviders: [...this._executionProviders],
+			externalData: options?.externalData?.map(({ path: path$1, data }) => ({
+				path: path$1,
+				data
+			})),
 			graphOptimizationLevel: "all",
 			...threads !== void 0 ? {
 				intraOpNumThreads: threads,
 				interOpNumThreads: 1
 			} : {}
 		});
+		const runMany = async (inputs) => {
+			const feeds = {};
+			for (const input of inputs) {
+				const name = inputs.length === 1 && !session.inputNames.includes(input.name) ? session.inputNames[0] ?? input.name : input.name;
+				if (input.gpuBuffer) throw new Error("CPU vision sessions do not accept GPU buffers.");
+				feeds[name] = input.data instanceof Uint8Array ? new ort.Tensor("bool", input.data, [...input.dims]) : input.data instanceof BigInt64Array ? new ort.Tensor("int64", input.data, [...input.dims]) : input.data instanceof Int32Array ? new ort.Tensor("int32", input.data, [...input.dims]) : new ort.Tensor("float32", input.data, [...input.dims]);
+			}
+			const results = await session.run(feeds);
+			const outputs = {};
+			for (const [name, tensor] of Object.entries(results)) outputs[name] = {
+				data: tensor.data,
+				dims: [...tensor.dims]
+			};
+			return outputs;
+		};
 		return {
-			run: async (input) => {
-				const feeds = { [session.inputNames.includes(input.name) ? input.name : session.inputNames[0] ?? input.name]: new ort.Tensor("float32", input.data, [...input.dims]) };
-				const results = await session.run(feeds);
-				const outputs = {};
-				for (const [name, tensor] of Object.entries(results)) outputs[name] = {
-					data: tensor.data,
-					dims: [...tensor.dims]
-				};
-				return outputs;
-			},
+			run: (input) => runMany([input]),
+			runMany,
 			release: () => {
 				session.release();
 			}
@@ -2770,6 +2910,7 @@ var VisionRunner = class VisionRunner$1 {
 	async inferNow(key, frame) {
 		const session = await this.session(key);
 		const desc = VISION_MODELS[key];
+		if (!isPreprocessFamily(desc.family)) throw new Error(`VisionRunner cannot run '${desc.family}' models; use the family's own tracker (e.g. Sam2Tracker or Sam3Tracker from @framefields/vision-sam).`);
 		const spec = preprocessSpec(desc.family, desc.input);
 		const dims = [
 			1,
@@ -3033,6 +3174,51 @@ function boundsOverlap(a, b) {
 	if (iw <= 0 || ih <= 0) return 0;
 	return iw * ih / Math.min(boundsArea(a), boundsArea(b));
 }
+/** Tracked-object geometry of one selected mask (bounds, center, velocity), with no detector involved; the track ID is the mask's (default 1). */
+function maskObject(mask, frame, fps, score, previous) {
+	let left = mask.width, top = mask.height, right = -1, bottom = -1;
+	for (let y$1 = 0; y$1 < mask.height; y$1++) for (let x$1 = 0; x$1 < mask.width; x$1++) {
+		if ((mask.mask[y$1 * mask.width + x$1] ?? 0) < 128) continue;
+		left = Math.min(left, x$1);
+		top = Math.min(top, y$1);
+		right = Math.max(right, x$1);
+		bottom = Math.max(bottom, y$1);
+	}
+	const active = right >= 0;
+	const x = active ? left : 0, y = active ? top : 0;
+	const width = active ? right - left + 1 : 0, height = active ? bottom - top + 1 : 0;
+	const centerX = x + width / 2, centerY = y + height / 2;
+	const vx = active && previous?.active ? (centerX - previous.centerX) * fps : 0;
+	const vy = active && previous?.active ? (centerY - previous.centerY) * fps : 0;
+	return {
+		trackId: mask.trackId ?? 1,
+		category: mask.category,
+		score,
+		boundingBox: {
+			originX: x,
+			originY: y,
+			width,
+			height,
+			normalizedX: x / mask.width,
+			normalizedY: y / mask.height,
+			normalizedWidth: width / mask.width,
+			normalizedHeight: height / mask.height
+		},
+		centerX,
+		centerY,
+		normalizedCenterX: centerX / mask.width,
+		normalizedCenterY: centerY / mask.height,
+		velocity: {
+			vx,
+			vy
+		},
+		speed: Math.hypot(vx, vy),
+		age: frame + 1,
+		hits: frame + 1,
+		active,
+		isCoasting: false
+	};
+}
 var SpatialLandmarkTransformer = class {
 	width;
 	height;
@@ -3177,6 +3363,9 @@ var VisionBundle = class {
 	_height;
 	_transformer;
 	_stencilTexture;
+	_maskSource;
+	_matteSource;
+	_cameraFov;
 	_poseCache = /* @__PURE__ */ new Map();
 	_objectCache = /* @__PURE__ */ new Map();
 	_maskCache = /* @__PURE__ */ new Map();
@@ -3188,6 +3377,9 @@ var VisionBundle = class {
 	_maskTrackCache = /* @__PURE__ */ new Map();
 	_registeredSignals = /* @__PURE__ */ new Set();
 	constructor(options = {}) {
+		this._maskSource = options.maskSource;
+		this._matteSource = options.matteSource;
+		this._cameraFov = options.cameraFov ?? 60;
 		this._totalFrames = options.totalFrames ?? 120;
 		this._fps = options.fps ?? 24;
 		this._width = options.width ?? 1920;
@@ -3815,6 +4007,18 @@ var VisionBundle = class {
 			}
 		};
 	}
+	/** Update source geometry once a lazily decoded clip's size is known. */
+	setFrameSize(width, height) {
+		if (this._width === width && this._height === height) return;
+		this._width = width;
+		this._height = height;
+		this._transformer = new SpatialLandmarkTransformer({
+			width,
+			height,
+			fov: this._cameraFov
+		});
+		this.invalidateSignals();
+	}
 	setStencilTexture(texture) {
 		this._stencilTexture = texture;
 	}
@@ -3865,14 +4069,14 @@ var VisionBundle = class {
 		this.invalidateSignals();
 	}
 	getMaskResult(frame) {
-		return this.latestAtOrBefore(this._maskCache, frame) ?? [];
+		return this._maskSource?.(frame) ?? this.latestAtOrBefore(this._maskCache, frame) ?? [];
 	}
 	setMatteResult(frame, matte) {
 		this._matteCache.set(this.clamp(frame), matte);
 		this.invalidateSignals();
 	}
 	getMatteResult(frame) {
-		return this.latestAtOrBefore(this._matteCache, frame);
+		return this._matteSource?.(frame) ?? this.latestAtOrBefore(this._matteCache, frame);
 	}
 	/**
 	* Serializable snapshot of one frame's object / class / mask signals.
@@ -4107,7 +4311,7 @@ var VisionNode = class VisionNode$1 {
 };
 
 //#endregion
-//#region ../../nodes/node-vision/dist/renderers-ZqeB-LTu.mjs
+//#region ../../nodes/node-vision/dist/renderers-D1ixy3z3.mjs
 let scratchValues = new Uint8Array(0);
 let scratchLengths = new Uint32Array(0);
 function encodeMask(mask, width, height) {
@@ -4849,8 +5053,14 @@ const VisionWebGPURenderer = async (args) => {
 	let personMatte;
 	let currentPoseRes;
 	let subject;
-	if (fromClip) subject = selectSubject(clipSubject ?? void 0, nodeKeyStr, frameIdx);
-	else if (cached) {
+	if (fromClip) {
+		subject = clipSubject ?? void 0;
+		if (subject) lastSubjectByNode.set(nodeKeyStr, {
+			mask: subject,
+			frame: frameIdx
+		});
+		else lastSubjectByNode.delete(nodeKeyStr);
+	} else if (cached) {
 		frameObjects = cached.objects;
 		if (wantsDetection) visionBundle?.setObjectResult(frameIdx, {
 			objects: cached.objects,
@@ -5062,10 +5272,12 @@ const VisionWebGPURenderer = async (args) => {
 * uv, so it fits any target of the same aspect. Other shapes fall back.
 */
 function clipSubjectFor(effect, frame, fps, width, height) {
-	const subject = (effect?.[CLIP_SUBJECT])?.subject(frame, fps);
+	const source = effect?.[CLIP_SUBJECT];
+	const subject = source?.subject(frame, fps);
 	if (!subject) return subject;
 	const aspect = subject.width / subject.height / (width / height);
-	return Math.abs(aspect - 1) < .01 ? subject : void 0;
+	if (Math.abs(aspect - 1) < .01) return subject;
+	if (source?.exact) throw new Error("A prompted clip matte requires the source aspect ratio. Apply layout cropping after the source matte.");
 }
 /** Adapts a Selfie Segmenter matte to the instance-mask shape the composite path takes. */
 function personMatteAsMask(matte) {
@@ -5084,5 +5296,5 @@ function personMatteAsMask(matte) {
 var renderers_default = defineRenderer({ WebGPURenderer: VisionWebGPURenderer });
 
 //#endregion
-export { COCO_CLASSES as _, COCO17_KEYPOINT_NAMES as a, SpatialLandmarkTransformer as c, VisionNode as d, VisionRunner as f, pinNodeToObject as g, pinNodeToLandmark as h, COCO17_KEYPOINTS as i, TemporalObjectTracker as l, mergeSubjectMask as m, CLIP_SUBJECT as n, PoseSkeletonRenderer as o, analyzeSequence as p, COCO17_BONES as r, SegmentationTexturePool as s, renderers_default as t, VisionBundle as u };
-//# sourceMappingURL=renderer-BD25uND8.mjs.map
+export { pinNodeToObject as _, COCO17_KEYPOINT_NAMES as a, SpatialLandmarkTransformer as c, VisionNode as d, VisionRunner as f, pinNodeToLandmark as g, mergeSubjectMask as h, COCO17_KEYPOINTS as i, TemporalObjectTracker as l, maskObject as m, CLIP_SUBJECT as n, PoseSkeletonRenderer as o, analyzeSequence as p, COCO17_BONES as r, SegmentationTexturePool as s, renderers_default as t, VisionBundle as u, COCO_CLASSES as v };
+//# sourceMappingURL=renderer-B0piZg9r.mjs.map