framefields 2.8.1 → 2.9.2

package/dist/{src-B0KFNjj4.mjs → src-DFEqficI.mjs}

@@ -1,12 +1,12 @@
 import { G as ProgrammaticSignal, K as Signal, Mt as frameArraySignal, N as MediaSignalRecorder, St as createVirtualMedia, pt as appendOperation, rn as mediaSourceTime, tn as mediaSourceRange, y as Effect$1, yn as resolveFrameRequest } from "./dist-BlIrsfcn.mjs";
-import { F as getPrimitiveGeometry, K as mediaDecoderCache, N as generateExtrudedTextGeometry, Z as parseSvgPathToSegments, _ as buildShapeSvgPath, gt as Path3D, p as SlugFontCache, q as parseColor$1, z as inputStore } from "./dist-CFe1fC9l.mjs";
-import { a as preflightMediaTime, n as decodeAudioSource } from "./dist-BbwtlSZO.mjs";
-import { t as FontManager } from "./fonts-C1mgtkCa.mjs";
+import { F as getPrimitiveGeometry, K as mediaDecoderCache, N as generateExtrudedTextGeometry, Z as parseSvgPathToSegments, _ as buildShapeSvgPath, gt as Path3D, p as SlugFontCache, q as parseColor$1, z as inputStore } from "./dist-C1cCW7Bt.mjs";
+import { a as preflightMediaTime, n as decodeAudioSource } from "./dist-C8Xq3zgx.mjs";
+import { t as FontManager } from "./fonts-BW0pPcvJ.mjs";
 import { s as TensorPipeline } from "./dist-Buaaj-Ul.mjs";
-import { a as COCO17_KEYPOINT_NAMES, d as VisionNode, f as VisionRunner, g as pinNodeToObject, h as pinNodeToLandmark, m as mergeSubjectMask, n as CLIP_SUBJECT, p as analyzeSequence, u as VisionBundle } from "./renderer-BD25uND8.mjs";
-import { G as mediaSignalSampler, K as mergeAnimationTracks, N as collectNodeOps, P as compositorToProgram, W as lintComposition, f as LayerAnimation, q as sampleMediaTimeSignal } from "./program-Cq4gP9Dd.mjs";
-import { C as effectFactories, H as Dither, I as ColorBalance, K as Iridescence, L as ColorKey, M as CRT, R as Contour, S as Vision, T as Ascii, Y as LayerStyle, _ as SelectiveColor, a as CustomEffect, at as Posterize, b as TileOffset, c as GradientMap, d as Levels, et as OpArt, f as Modulate, g as SSAO, h as Relight3D, ht as Vignette, i as Curves, it as Pixelate, l as HalftoneScreen, m as PBRGlass, nt as Painterly, o as DepthOfField, ot as ProceduralVFX, p as MotionBlur, pt as Toon, q as Kaleidoscope, r as Crop, s as FilmGrain, st as RGBSplit, t as ApplyLUT, u as HighPass, v as ShadowsHighlights, w as Blur, x as UnsharpMask, y as TemporalDeflicker } from "./effects-CCyfjbhZ.mjs";
-import { a as HeadlessMediaRenderer, n as renderFrameGrid } from "./renderer-BeFiQfzV.mjs";
+import { _ as pinNodeToObject, a as COCO17_KEYPOINT_NAMES, d as VisionNode, f as VisionRunner, g as pinNodeToLandmark, h as mergeSubjectMask, m as maskObject, n as CLIP_SUBJECT, p as analyzeSequence, u as VisionBundle } from "./renderer-B2P1vgb7.mjs";
+import { G as mediaSignalSampler, K as mergeAnimationTracks, N as collectNodeOps, P as compositorToProgram, W as lintComposition, f as LayerAnimation, q as sampleMediaTimeSignal } from "./program-CKpKkllV.mjs";
+import { C as effectFactories, H as Dither, I as ColorBalance, K as Iridescence, L as ColorKey, M as CRT, R as Contour, S as Vision, T as Ascii, Y as LayerStyle, _ as SelectiveColor, a as CustomEffect, at as Posterize, b as TileOffset, c as GradientMap, d as Levels, et as OpArt, f as Modulate, g as SSAO, h as Relight3D, ht as Vignette, i as Curves, it as Pixelate, l as HalftoneScreen, m as PBRGlass, nt as Painterly, o as DepthOfField, ot as ProceduralVFX, p as MotionBlur, pt as Toon, q as Kaleidoscope, r as Crop, s as FilmGrain, st as RGBSplit, t as ApplyLUT, u as HighPass, v as ShadowsHighlights, w as Blur, x as UnsharpMask, y as TemporalDeflicker } from "./effects-CemgqEPv.mjs";
+import { a as HeadlessMediaRenderer, n as renderFrameGrid } from "./renderer-DPAD6fL1.mjs";
 import { z, z as z$2 } from "zod";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -1337,6 +1337,19 @@ function translatePath(d, dx, dy) {
 /** Frames looked back over to bridge a gap where the person is lost. */
 const HOLD = 24;
 const CACHE_VERSION = 1;
+let visionSam;
+let clipVisionIds = 0;
+/**
+* SAM lives in `@framefields/vision-sam`, an optional peer (SAM 3's weights are under Meta's SAM License), so it
+* is imported only when a clip asks for `sam2` or `sam3`.
+*/
+function loadVisionSam() {
+	visionSam ??= import("@framefields/vision-sam").catch((cause) => {
+		visionSam = void 0;
+		throw new Error("Prompted sam2/sam3 tracking needs the optional @framefields/vision-sam package. Install it next to framefields.", { cause });
+	});
+	return visionSam;
+}
 /**
 * Vision results for one clip, computed per frame on demand and shared by
 * everything that reads the clip: physics, layout, signals. Unlike the
@@ -1367,6 +1380,20 @@ var ClipVision = class {
 	cell;
 	queue = Promise.resolve();
 	runner;
+	sam2Tracker;
+	sam2Frame = -1;
+	sam3Tracker;
+	sam3Frame = -1;
+	sam;
+	/** Clips walk their source independently, so each owns a decoder (requests to one supersede). */
+	decoderId = `clip-vision#${++clipVisionIds}#`;
+	signalBundle;
+	publishedSignals = /* @__PURE__ */ new Set();
+	signalMaskFrame = -1;
+	/** Masks of `signalMaskFrame` by track ID (0: all tracks merged). */
+	signalMasks = /* @__PURE__ */ new Map();
+	/** Prompted track count per source frame, including frames where every track is absent. */
+	trackCounts = /* @__PURE__ */ new Map();
 	cacheLoaded;
 	unsaved = 0;
 	unsavedSubjects = 0;
@@ -1380,13 +1407,80 @@ var ClipVision = class {
 	/** @internal Use `comp.vision(source, options)`. */
 	constructor(source, fps, options = {}) {
 		this.source = source;
-		this.options = options;
+		if (options.sam2 && options.sam3) throw new Error("Choose one prompted backend: sam2 or sam3.");
+		this.options = options.sam2 ? {
+			...options,
+			sam2: {
+				...options.sam2,
+				prompts: options.sam2.prompts.map((prompt) => ({
+					...prompt,
+					points: prompt.points.map((point) => ({ ...point }))
+				}))
+			}
+		} : options.sam3 ? {
+			...options,
+			sam3: {
+				...options.sam3,
+				prompts: (options.sam3.prompts ?? (options.sam3.text ? [{
+					frame: 0,
+					text: options.sam3.text
+				}] : [])).map((prompt) => ({
+					...prompt,
+					...prompt.points ? { points: prompt.points.map((point) => ({ ...point })) } : {}
+				}))
+			}
+		} : options;
 		this.compositionFps = fps;
 		this.fps = options.fps ?? fps;
 		this.startFrame = Math.round(options.startFrame ?? 0);
 		this.trimStartSec = options.trimStartSec ?? 0;
-		this.smoothing = Math.max(0, Math.round(options.smoothing ?? 2));
+		this.smoothing = Math.max(0, Math.round(options.smoothing ?? (options.sam2 || options.sam3 ? 0 : 2)));
 		this.cell = Math.max(1, Math.round(options.maskCell ?? 8));
+		if (options.sam2 || options.sam3) this.wantSubjects = true;
+	}
+	/** @internal Explicit selections must never fall back to another detected subject. */
+	get exact() {
+		return this.options.sam2 !== void 0 || this.options.sam3 !== void 0;
+	}
+	/** Object, mask and optional pose signals on the composition clock, in source geometry. */
+	get signals() {
+		this.keepSubjects();
+		this.signalBundle ??= new VisionBundle({
+			fps: this.compositionFps,
+			totalFrames: Number.MAX_SAFE_INTEGER,
+			maskSource: (frame) => this.trackIds(frame).flatMap((id) => {
+				const mask = this.maskAt(frame, id);
+				return mask && mask.area > 0 ? [mask] : [];
+			}),
+			matteSource: (frame) => {
+				const mask = this.maskAt(frame);
+				return mask ? {
+					mask: mask.mask,
+					width: mask.width,
+					height: mask.height,
+					coverage: mask.coverage
+				} : void 0;
+			}
+		});
+		return this.signalBundle;
+	}
+	decoder() {
+		return mediaDecoderCache.getVideo(this.source, true, this.decoderId);
+	}
+	/** Free inference sessions and the decoder. Analysed frames remain readable; later frames replay memory. */
+	release() {
+		mediaDecoderCache.clearNode(this.decoderId);
+		this.sam2Tracker?.release();
+		this.sam2Tracker = void 0;
+		this.sam2Frame = -1;
+		this.sam3Tracker?.release();
+		this.sam3Tracker = void 0;
+		this.sam3Frame = -1;
+		this.runner?.close();
+		this.runner = void 0;
+		this.signalMaskFrame = -1;
+		this.signalMasks.clear();
+		this.publishedSignals.clear();
 	}
 	/** The tracked person in source pixels; `.place()` maps it into the composition. */
 	get person() {
@@ -1400,13 +1494,22 @@ var ClipVision = class {
 	*/
 	ready(frame, toFrame = frame) {
 		const [from, to] = this.window(frame, toFrame);
-		this.queue = this.queue.then(() => this.compute(from, to));
-		return this.queue;
+		const run$1 = this.queue.then(async () => {
+			try {
+				await this.compute(from, to);
+			} catch (error) {
+				this.release();
+				throw error;
+			}
+			if (this.signalBundle) this.publishSignals(Math.min(frame, toFrame), Math.max(frame, toFrame));
+		});
+		this.queue = run$1.catch(() => void 0);
+		return run$1;
 	}
 	/** True when composition frame `frame` can be read synchronously. */
 	isReady(frame) {
 		const [from, to] = this.window(frame, frame);
-		for (let c = from; c <= to; c++) if (!this.results.has(c)) return false;
+		for (let c = from; c <= to; c++) if (!this.analysed(c)) return false;
 		return true;
 	}
 	/**
@@ -1423,9 +1526,8 @@ var ClipVision = class {
 	* subjects kept, null when it holds no subject.
 	*/
 	subject(frame, fps) {
-		const c = frame * this.fps / fps;
-		if (!this.options.timeRemap && Math.abs(c - Math.round(c)) > 1e-6) return void 0;
-		const sourceFrame = this.options.timeRemap ? Math.floor(c + 1e-6) : Math.round(c);
+		const sourceFrame = this.sourceFrame(frame, fps);
+		if (sourceFrame === void 0) return void 0;
 		const s = this.subjects.get(sourceFrame);
 		if (s === void 0) return s;
 		if (s === null || !this.sourceWidth) return null;
@@ -1433,7 +1535,7 @@ var ClipVision = class {
 		const height = this.sourceHeight;
 		return {
 			category: s.category,
-			mask: decodeRuns(s, width * height),
+			mask: subjectAlpha(s, width * height),
 			width,
 			height,
 			area: s.area,
@@ -1441,6 +1543,45 @@ var ClipVision = class {
 			detectionIndex: -1
 		};
 	}
+	/**
+	* @internal The pose matched to the subject at a source frame of the clip
+	* (`frame` at `fps`), normalized to the source size, for a render-time
+	* skeleton: undefined until that frame and its smoothing window are
+	* analysed, null when no pose matched there.
+	*/
+	pose(frame, fps) {
+		const c = this.sourceFrame(frame, fps);
+		if (c === void 0 || !this.tracksPose || !this.sourceWidth) return;
+		for (let g = c - this.smoothing; g <= c + this.smoothing; g++) if (!this.results.has(Math.max(0, g))) return void 0;
+		if (!this.results.get(c)?.kp) return null;
+		const width = this.sourceWidth;
+		const height = this.sourceHeight;
+		return {
+			width,
+			height,
+			keypoints: Array.from({ length: 17 }, (_, k) => {
+				const [x, y, visibility] = this.keypoint(k, c);
+				return {
+					x: x / width,
+					y: y / height,
+					visibility
+				};
+			})
+		};
+	}
+	/** Whether frames carry keypoints: on by default, opt-in for prompted (SAM) clips. */
+	get tracksPose() {
+		return this.exact ? this.options.pose === true : this.options.pose ?? true;
+	}
+	/**
+	* The analysed source frame a render-time read at `frame` (at `fps`) maps to;
+	* undefined for an unprompted clip read between its analysed frames.
+	*/
+	sourceFrame(frame, fps) {
+		const c = frame * this.fps / fps;
+		if (!this.exact && !this.options.timeRemap && Math.abs(c - Math.round(c)) > 1e-6) return void 0;
+		return this.options.timeRemap || this.exact ? Math.floor(c + 1e-6) : Math.round(c);
+	}
 	/** Composition frame → clip frame (fractional). */
 	clipFrame(frame) {
 		if (this.options.timeRemap) return mediaSourceTime(this.options.timeRemap, this.localFrame(frame), this.compositionFps) * this.fps;
@@ -1459,7 +1600,17 @@ var ClipVision = class {
 	analysed(c) {
 		return this.results.has(c) && (!this.wantSubjects || this.subjects.has(c));
 	}
+	/** Loads `@framefields/vision-sam` and validates the prompts once, on first use. */
+	prompted() {
+		this.sam ??= loadVisionSam().then((sam) => {
+			if (this.options.sam2) sam.validateSam2Prompts(this.options.sam2.prompts);
+			if (this.options.sam3) sam.validateSam3Prompts(this.options.sam3);
+			return sam;
+		});
+		return this.sam;
+	}
 	async compute(from, to) {
+		if (this.exact) await this.prompted();
 		this.cacheLoaded ??= this.loadCache();
 		await this.cacheLoaded;
 		if (this.wantSubjects) {
@@ -1469,7 +1620,15 @@ var ClipVision = class {
 		let missing = false;
 		for (let c = from; c <= to; c++) if (!this.analysed(c)) missing = true;
 		if (!missing) return;
-		const wantPose = this.options.pose ?? true;
+		if (this.options.sam2) {
+			await this.computeSam2(to);
+			return;
+		}
+		if (this.options.sam3) {
+			await this.computeSam3(to);
+			return;
+		}
+		const wantPose = this.tracksPose;
 		const wantMask = this.options.mask ?? true;
 		this.runner ??= VisionRunner.create({
 			modelsDir: this.options.modelsDir,
@@ -1477,7 +1636,7 @@ var ClipVision = class {
 			...this.options.confidence !== void 0 && { confidence: this.options.confidence },
 			...this.options.variant !== void 0 && { variant: this.options.variant }
 		});
-		const decoder = mediaDecoderCache.getVideo(this.source, true, "clip-vision");
+		const decoder = this.decoder();
 		for (let c = from; c <= to; c++) {
 			if (this.analysed(c)) continue;
 			const image = await decodedPixels(await decoder.getFrame(c / this.fps));
@@ -1532,6 +1691,221 @@ var ClipVision = class {
 		if (this.unsaved > 0) await this.saveCache();
 		if (this.unsavedSubjects > 0) await this.saveSubjects();
 	}
+	async computeSam2(to) {
+		const settings = this.options.sam2;
+		if (!settings) return;
+		const first = settings.prompts[0]?.frame ?? 0;
+		for (let frame = 0; frame < Math.min(first, to + 1); frame++) {
+			this.results.set(frame, {
+				kp: null,
+				mask: null,
+				score: 0
+			});
+			this.subjects.set(frame, null);
+		}
+		if (to < first) return;
+		const decoder = this.decoder();
+		if (!this.sam2Tracker) {
+			const frameCount = Math.max(1, Math.ceil(await decoder.durationSec() * this.fps - 1e-6));
+			if (settings.prompts.some((prompt) => prompt.frame >= frameCount)) throw new Error("SAM 2 prompt frames must be inside the source video.");
+			const { Sam2Tracker } = await this.prompted();
+			this.sam2Tracker = await Sam2Tracker.create({
+				modelsDir: this.options.modelsDir,
+				baseUrl: this.options.baseUrl,
+				frameCount,
+				model: settings.model
+			});
+			this.sam2Frame = first - 1;
+		}
+		for (let frame = this.sam2Frame + 1; frame <= to; frame++) {
+			const image = await decodedPixels(await decoder.getFrame(frame / this.fps));
+			if (!image) throw new Error(`Cannot decode SAM 2 source frame ${frame}.`);
+			if (!this.sourceWidth) this.setSize(image.width, image.height);
+			const prompt = settings.prompts.find((item) => item.frame === frame);
+			const result$1 = await this.sam2Tracker.process(image, frame, prompt?.points);
+			const kp = this.tracksPose ? await this.matchedPose(image, result$1.mask) : null;
+			this.storeSamFrame(frame, result$1.width, result$1.height, [result$1], kp);
+			if (this.unsaved >= 24) {
+				await this.saveCache();
+				await this.saveSubjects();
+			}
+		}
+		await this.saveCache();
+		await this.saveSubjects();
+	}
+	async computeSam3(to) {
+		const settings = this.options.sam3;
+		if (!settings) return;
+		const first = settings.prompts[0]?.frame ?? 0;
+		for (let frame = 0; frame < Math.min(first, to + 1); frame++) {
+			this.results.set(frame, {
+				kp: null,
+				mask: null,
+				score: 0
+			});
+			this.subjects.set(frame, null);
+		}
+		if (to < first) return;
+		const decoder = this.decoder();
+		if (!this.sam3Tracker) {
+			const frameCount = Math.max(1, Math.ceil(await decoder.durationSec() * this.fps - 1e-6));
+			if (settings.prompts.some((prompt) => prompt.frame >= frameCount)) throw new Error("SAM 3 prompt frames must be inside the source video.");
+			const { Sam3Tracker } = await this.prompted();
+			this.sam3Tracker = await Sam3Tracker.create({
+				modelsDir: this.options.modelsDir,
+				baseUrl: this.options.baseUrl,
+				frameCount,
+				textThreshold: settings.textThreshold,
+				maxObjects: settings.maxObjects,
+				merge: settings.merge,
+				redetect: settings.redetect,
+				precision: settings.precision,
+				acceptLicense: this.options.acceptSamLicense ?? this.options.sam3?.acceptLicense
+			});
+			this.sam3Frame = first - 1;
+		}
+		for (let frame = this.sam3Frame + 1; frame <= to; frame++) {
+			const image = await decodedPixels(await decoder.getFrame(frame / this.fps));
+			if (!image) throw new Error(`Cannot decode SAM 3 source frame ${frame}.`);
+			if (!this.sourceWidth) this.setSize(image.width, image.height);
+			const prompt = settings.prompts.find((item) => item.frame === frame);
+			const result$1 = await this.sam3Tracker.process(image, frame, prompt);
+			const kp = this.tracksPose ? await this.matchedPose(image, unionMask(result$1.objects, image)) : null;
+			this.storeSamFrame(frame, result$1.width, result$1.height, result$1.objects, kp);
+			if (this.unsaved >= 24) {
+				await this.saveCache();
+				await this.saveSubjects();
+			}
+		}
+		await this.saveCache();
+		await this.saveSubjects();
+	}
+	/** Stores a prompted frame: every track's mask as one label map, the union as the subject. */
+	storeSamFrame(frame, width, height, objects, kp) {
+		const labels = new Uint8Array(width * height);
+		const order = [...objects.keys()].sort((a, b) => (objects[a]?.score ?? 0) - (objects[b]?.score ?? 0));
+		for (const index of order) {
+			const mask = objects[index]?.mask;
+			if (!mask) continue;
+			for (let i = 0; i < mask.length; i++) if ((mask[i] ?? 0) >= 128) labels[i] = index + 1;
+		}
+		const union = Uint8Array.from(labels, (id) => id ? 255 : 0);
+		const grid = new Uint8Array(this.cellW * this.cellH);
+		downsampleMean(union, width, height, this.cell, grid, this.cellW, this.cellH);
+		let area$1 = 0;
+		for (const id of labels) if (id) area$1++;
+		const scores = objects.map((o) => 1 / (1 + Math.exp(-o.score)));
+		this.results.set(frame, {
+			kp,
+			mask: grid,
+			score: Math.max(0, ...scores)
+		});
+		this.subjects.set(frame, area$1 > 0 ? {
+			category: this.samCategory(),
+			area: area$1,
+			scores,
+			...encodeRuns(labels)
+		} : null);
+		this.trackCounts.set(frame, objects.length);
+		this.blurred.delete(frame);
+		if (this.options.sam3) this.sam3Frame = frame;
+		else this.sam2Frame = frame;
+		this.unsaved++;
+		this.unsavedSubjects++;
+	}
+	samCategory() {
+		return this.options.sam2?.category ?? this.options.sam3?.category ?? "object";
+	}
+	async matchedPose(image, mask) {
+		this.runner ??= VisionRunner.create({
+			modelsDir: this.options.modelsDir,
+			baseUrl: this.options.baseUrl,
+			variant: this.options.variant
+		});
+		const { people } = await this.runner.pose(image);
+		const match = people.map((person) => ({
+			person,
+			overlap: person.keypoints.reduce((sum, point) => {
+				const x = Math.max(0, Math.min(image.width - 1, Math.round(point.x)));
+				return sum + (mask[Math.max(0, Math.min(image.height - 1, Math.round(point.y))) * image.width + x] ?? 0) / 255 * point.visibility;
+			}, 0)
+		})).sort((a, b) => b.overlap - a.overlap)[0];
+		if (!match || match.overlap < 2) return null;
+		return Float32Array.from(match.person.keypoints.flatMap((point) => [
+			point.x,
+			point.y,
+			point.visibility
+		]));
+	}
+	/** Track IDs at a composition frame: every prompted track, else the one subject. */
+	trackIds(frame) {
+		const c = Math.max(0, Math.floor(this.clipFrame(frame)));
+		const count = this.subjects.get(c)?.scores?.length ?? this.trackCounts.get(c) ?? 1;
+		return Array.from({ length: count }, (_, i) => i + 1);
+	}
+	/** The subject (all tracks merged) or, with `id`, one track's mask, in source pixels. */
+	maskAt(frame, id) {
+		const c = Math.max(0, Math.floor(this.clipFrame(frame)));
+		if (this.signalMaskFrame !== c) {
+			this.signalMaskFrame = c;
+			this.signalMasks.clear();
+		}
+		const hit = this.signalMasks.get(id ?? 0);
+		if (hit) return hit;
+		if (!this.results.has(c) || !this.sourceWidth) return void 0;
+		const stored = this.subjects.get(c);
+		const size$1 = this.sourceWidth * this.sourceHeight;
+		const data = stored ? subjectAlpha(stored, size$1, id) : new Uint8Array(size$1);
+		let area$1 = stored?.area ?? 0;
+		if (id !== void 0 && stored?.scores) {
+			area$1 = 0;
+			for (const alpha of data) if (alpha) area$1++;
+		}
+		const mask = {
+			category: stored?.category ?? this.samCategory(),
+			mask: data,
+			width: this.sourceWidth,
+			height: this.sourceHeight,
+			area: area$1,
+			coverage: area$1 / size$1,
+			detectionIndex: (id ?? 1) - 1,
+			trackId: id ?? 1
+		};
+		this.signalMasks.set(id ?? 0, mask);
+		return mask;
+	}
+	publishSignals(from, to) {
+		const bundle = this.signalBundle;
+		if (!bundle || !this.sourceWidth) return;
+		bundle.setFrameSize(this.sourceWidth, this.sourceHeight);
+		for (let frame = from; frame <= to; frame++) {
+			if (this.publishedSignals.has(frame)) continue;
+			this.publishedSignals.add(frame);
+			const c = Math.max(0, Math.floor(this.clipFrame(frame)));
+			const mask = this.maskAt(frame);
+			if (!mask) continue;
+			const before = bundle.getObjectResult(frame - 1).objects;
+			const scores = this.subjects.get(c)?.scores;
+			const objects = this.trackIds(frame).flatMap((id) => {
+				const track = this.maskAt(frame, id);
+				if (!track) return [];
+				return [maskObject(track, frame, this.compositionFps, scores?.[id - 1] ?? this.results.get(c)?.score ?? 1, before.find((object$1) => object$1.trackId === id))];
+			});
+			bundle.setObjectResult(frame, objects);
+			const object = objects[0] ?? maskObject(mask, frame, this.compositionFps, 0);
+			const kp = this.results.get(c)?.kp;
+			bundle.setPoseResult(frame, { people: kp ? [{
+				score: object.score,
+				boundingBox: object.boundingBox,
+				trackId: 1,
+				keypoints: Array.from({ length: 17 }, (_, i) => ({
+					x: (kp[i * 3] ?? 0) / mask.width,
+					y: (kp[i * 3 + 1] ?? 0) / mask.height,
+					visibility: kp[i * 3 + 2] ?? 0
+				}))
+			}] : [] });
+		}
+	}
 	setSize(width, height) {
 		this.sourceWidth = width;
 		this.sourceHeight = height;
@@ -1591,7 +1965,7 @@ var ClipVision = class {
 		c = Math.max(0, c);
 		if (this.blurred.has(c)) return this.blurred.get(c) ?? null;
 		this.mustHave(c);
-		const mask = bridgedMask(this.results, c, this.smoothing);
+		const mask = this.exact ? this.results.get(c)?.mask ?? null : bridgedMask(this.results, c, this.smoothing);
 		const grid = mask ? boxBlur(mask, this.cellW, this.cellH, 2) : null;
 		this.blurred.set(c, grid);
 		return grid;
@@ -1624,17 +1998,28 @@ var ClipVision = class {
 			const stat = fs$1.statSync(this.source);
 			const dir = this.options.cacheDir ?? process.env.FRAMEFIELDS_VISION_CACHE_DIR ?? path$1.join(os.homedir(), ".cache", "framefields", "vision");
 			const o = this.options;
+			const sam = this.exact ? await this.prompted() : void 0;
 			const key = JSON.stringify([
 				CACHE_VERSION,
 				path$1.resolve(this.source),
 				stat.size,
 				stat.mtimeMs,
 				this.fps,
-				o.pose ?? true,
+				this.tracksPose,
 				o.mask ?? true,
 				this.cell,
 				o.variant ?? "s",
-				o.confidence ?? null
+				o.confidence ?? null,
+				...o.sam2 ? [[
+					sam?.sam2Revision(o.sam2.model),
+					o.sam2,
+					3
+				]] : [],
+				...o.sam3 && sam ? [[
+					sam.sam3Revision(await sam.sam3Precision(void 0, o.sam3.precision)),
+					o.sam3,
+					3
+				]] : []
 			]);
 			const hash = crypto.createHash("sha256").update(key).digest("hex").slice(0, 24);
 			fs$1.mkdirSync(dir, { recursive: true });
@@ -1655,6 +2040,7 @@ var ClipVision = class {
 			this.setSize(json.width, json.height);
 			for (const [c, r] of Object.entries(json.frames)) this.results.set(Number(c), {
 				kp: r.kp ? Float32Array.from(r.kp) : null,
+				score: r.score,
 				mask: r.mask ? new Uint8Array(Buffer.from(r.mask, "base64")) : null
 			});
 		} catch {}
@@ -1666,7 +2052,8 @@ var ClipVision = class {
 		const frames = {};
 		for (const [c, r] of this.results) frames[c] = {
 			kp: r.kp ? Array.from(r.kp, (v) => Math.round(v * 100) / 100) : null,
-			mask: r.mask ? Buffer.from(r.mask).toString("base64") : null
+			mask: r.mask ? Buffer.from(r.mask).toString("base64") : null,
+			score: r.score
 		};
 		const fs$1 = await import("node:fs");
 		const tmp = `${file}.${process.pid}.tmp`;
@@ -1697,6 +2084,7 @@ var ClipVision = class {
 				this.subjects.set(Number(c), s && {
 					category: s.category,
 					area: s.area,
+					...s.scores && { scores: s.scores },
 					values: new Uint8Array(Buffer.from(s.values, "base64")),
 					lengths: new Uint32Array(lengths.buffer.slice(lengths.byteOffset, lengths.byteOffset + lengths.byteLength))
 				});
@@ -1711,6 +2099,7 @@ var ClipVision = class {
 		for (const [c, s] of this.subjects) frames[c] = s && {
 			category: s.category,
 			area: s.area,
+			...s.scores && { scores: s.scores },
 			values: Buffer.from(s.values).toString("base64"),
 			lengths: Buffer.from(s.lengths.buffer, s.lengths.byteOffset, s.lengths.byteLength).toString("base64")
 		};
@@ -1993,6 +2382,18 @@ function boxBlur(src, w, h, r) {
 	}
 	return dst;
 }
+/** A stored subject as 0/255 alpha: label maps merge every track, or keep track `id` only. */
+function subjectAlpha(stored, size$1, id) {
+	const values = decodeRuns(stored, size$1);
+	if (!stored.scores) return values;
+	return values.map((label) => (id === void 0 ? label > 0 : label === id) ? 255 : 0);
+}
+/** Every track's mask merged, for matching one pose to the whole selection. */
+function unionMask(objects, image) {
+	const union = new Uint8Array(image.width * image.height);
+	for (const { mask } of objects) for (let i = 0; i < union.length; i++) union[i] = Math.max(union[i] ?? 0, mask[i] ?? 0);
+	return union;
+}
 
 //#endregion
 //#region src/media-signals.ts
@@ -8199,16 +8600,17 @@ var Composition = class Composition {
 	* frame — physics, particles — always find every frame before it.
 	*/
 	async prepareVision(frame) {
-		this.linkClipMattes();
+		this.linkClipLayers();
 		await Promise.all([...this._clipVision.values()].map((clip) => clip.ready(0, frame)));
 	}
 	/**
-	* Points matte-family `withVision` layers at the `comp.vision` clip they
-	* show, so the cutout reuses that clip's per-frame subject instead of
-	* segmenting the frame again during render. Only layers whose settings
-	* would give the same subject are linked; the rest keep their own pass.
+	* Points matte-family and skeleton `withVision` layers at the `comp.vision`
+	* clip they show, so the cutout reuses that clip's per-frame subject and the
+	* skeleton draws its matched pose, instead of analysing the frame again
+	* during render. Only layers whose settings would give the same subject are
+	* linked; the rest keep their own pass.
 	*/
-	linkClipMattes() {
+	linkClipLayers() {
 		if (this._clipVision.size === 0) return;
 		let layers;
 		const walk = (node) => {
@@ -8220,13 +8622,13 @@ var Composition = class Composition {
 					return [op.id, op];
 				}));
 				const layer = layers.get(n.id);
-				const clip = this.clipForMatte(n.src ?? n.inputHandleId, n.vision, {
+				const clip = this.clipForLayer(n.src ?? n.inputHandleId, n.vision, {
 					trimStartSec: n.trimStartSec,
 					startFrame: layer?.startFrame ?? n.startFrame,
 					timeRemap: layer?.timeRemap
 				});
 				if (clip) {
-					clip.keepSubjects();
+					if (n.vision.mode !== "skeleton") clip.keepSubjects();
 					Object.defineProperty(n.vision, CLIP_SUBJECT, {
 						value: clip,
 						enumerable: false,
@@ -8238,13 +8640,21 @@ var Composition = class Composition {
 		};
 		for (const child of this.children) walk(child);
 	}
-	clipForMatte(source, v, layer) {
+	/** The `comp.vision` clip a matte or skeleton layer of the same source reads instead of analysing. */
+	clipForLayer(source, v, layer) {
 		const mode = v.mode ?? "passthrough";
-		if (mode !== "matte" && mode !== "mask" && mode !== "crop") return;
-		if (v.matteSource === "selfie" || v.keyBackground === true || v.classes !== void 0 || v.enablePose === true || v.enableMatte === true || v.visionBundle !== void 0 || (v.maskThreshold ?? .5) !== .5 || v.featherRadius !== void 0) return;
+		const skeleton = mode === "skeleton";
+		if (mode !== "matte" && mode !== "mask" && mode !== "crop" && !skeleton) return;
+		if (v.classes !== void 0 || v.enableMatte === true || v.visionBundle !== void 0 || !skeleton && (v.matteSource === "selfie" || v.keyBackground === true || v.enablePose === true || (v.maskThreshold ?? .5) !== .5 || v.featherRadius !== void 0)) return;
 		for (const clip of this._clipVision.values()) {
 			const o = clip.options;
-			if (clip.source === source && clip.startFrame === (layer.startFrame ?? 0) && clip.trimStartSec === (layer.trimStartSec ?? 0) && remapKey(o.timeRemap) === remapKey(layer.timeRemap) && (o.variant ?? "s") === (v.variant ?? "s") && (o.confidence ?? .3) === (v.confidence ?? .3)) return clip;
+			if (clip.source === source && clip.startFrame === (layer.startFrame ?? 0) && clip.trimStartSec === (layer.trimStartSec ?? 0) && remapKey(o.timeRemap) === remapKey(layer.timeRemap) && (o.variant ?? "s") === (v.variant ?? "s") && (o.confidence ?? .3) === (v.confidence ?? .3)) {
+				if (skeleton && !clip.tracksPose) {
+					if (clip.exact) throw new Error("A skeleton layer of a prompted comp.vision clip needs `pose: true` on that clip.");
+					continue;
+				}
+				return clip;
+			}
 		}
 	}
 	/**
@@ -9457,4 +9867,4 @@ const Effect = Object.assign(Effect$1, effectFactories, {
 
 //#endregion
 export { glyphAnimator as $, wordRanges as $t, boilKeys as A, squigglePath as At, defineTheme as B, themes as Bt, audioLevelsSchema as C, span as Cn, scaleFrames as Ct, basePropsSchema as D, FRAMEFIELDS_AI_PROXY_URL as Dn, springKeys as Dt, bandEdges as E, ApiError as En, springAt as Et, constantExpression as F, surfaceFill as Ft, elevationStyle as G, transparent as Gt, drawOnKeys as H, toPathData as Ht, contrastRatio as I, targetPoint as It, evaluateEase as J, windowExpression as Jt, ellipsePath as K, typingFrames as Kt, cover as L, targetSchema as Lt, boxPath as M, staggerRanks as Mt, catmullRom as N, stepExpression as Nt, beats as O, ValidationError as On, springSettleFrames as Ot, chain as P, supersede as Pt, frameSpan as Q, wobblePoints as Qt, defineComponent as R, textLayout as Rt, ascending as S, size as Sn, safeArea as St, bakeSamples as T, sup as Tn, smoothRelease as Tt, ease as U, toSeconds as Ut, dist as V, toFrames as Vt, elevate as W, transformPathData as Wt, exitAnimation as X, withDefaults as Xt, evaluateGlyphExpression as Y, withAlpha as Yt, findRange as Z, within as Zt, after as _, italic as _n, resampleBands as _t, Media as a, PhysicsWorld2D as an, last as at, arcPath as b, parseMarkup as bn, rng as bt, section as c, Layer3D as cn, lineShift as ct, analyzeAudio as d, PersonTrack as dn, offsetCues as dt, Styles as en, hashRng as et, KeyBook as f, DEFAULT_CHART_COLORS as fn, parseColor as ft, UNIT_INDEX as g, color as gn, rendererChars as gt, Track as h, code as hn, rangeRects as ht, Light as i, PhysicsBody2D as in, isLight as it, boundsOf as j, staggerOffsets as jt, bind as k, ai as kn, springTrack as kt, bindComponent as l, Particles as ln, luminance as lt, SAFE_INSETS as m, bold as mn, quantize as mt, Effect as n, PhysicsBody3D as nn, holdFirstKeys as nt, blurRegion as o, Lighting as on, lerp2 as ot, MOTION_PRESETS as p, accent as pn, pulseKeys as pt, enterAnimation as q, valueAt as qt, Layer as r, PhysicsWorld3D as rn, inkOn as rt, editTrackedRegion as s, Transition as sn, linePath as st, Composition as t, Physics as tn, hashString as tt, z$2 as u, ClipVision as un, mix as ut, analyzeChannels as v, mark as vn, resolveMotion as vt, bakeFunction as w, sub as wn, scheduleExpression as wt, arrowPaths as x, rich as xn, round as xt, anchorPoint as y, normalizeTextSpans as yn, resolveTarget as yt, defineMeta as z, themeFrames as zt };
-//# sourceMappingURL=src-B0KFNjj4.mjs.map
+//# sourceMappingURL=src-DFEqficI.mjs.map