@lumy-pack/scene-sieve 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -6,6 +6,14 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") {
 		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
@@ -20,7 +28,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
@@ -33,66 +41,72 @@ picocolors = __toESM(picocolors, 1);
 let node_module = require("node:module");
 let sharp = require("sharp");
 sharp = __toESM(sharp, 1);
-let node_os = require("node:os");
-let node_path = require("node:path");
+let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_os = require("node:os");
 let _ffprobe_installer_ffprobe = require("@ffprobe-installer/ffprobe");
 let execa = require("execa");
 let ffmpeg_static = require("ffmpeg-static");
 ffmpeg_static = __toESM(ffmpeg_static, 1);
 
-//#region src/utils/logger.ts
-let debugMode = false;
-let jsonMode = false;
+//#region src/logging/logger.ts
 function setDebugMode(enabled) {
 	debugMode = enabled;
 }
 function timestamp() {
 	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
 }
-const logger = {
-	info(message) {
-		if (jsonMode) process.stderr.write(`${picocolors.default.blue("info")} ${message}\n`);
-		else console.log(`${picocolors.default.blue("info")} ${message}`);
-	},
-	success(message) {
-		if (jsonMode) process.stderr.write(`${picocolors.default.green("done")} ${message}\n`);
-		else console.log(`\n${picocolors.default.green("done")} ${message}`);
-	},
-	warn(message) {
-		console.warn(`${picocolors.default.yellow("warn")} ${message}`);
-	},
-	error(message) {
-		console.error(`${picocolors.default.red("error")} ${message}`);
-	},
-	debug(message) {
-		if (debugMode) if (jsonMode) process.stderr.write(`${picocolors.default.gray(`[${timestamp()}] debug`)} ${message}\n`);
-		else console.log(`${picocolors.default.gray(`[${timestamp()}] debug`)} ${message}`);
-	}
-};
+var debugMode, jsonMode, logger;
+var init_logger = __esmMin((() => {
+	debugMode = false;
+	jsonMode = false;
+	logger = {
+		info(message) {
+			if (jsonMode) process.stderr.write(`${picocolors.default.blue("info")} ${message}\n`);
+			else console.log(`${picocolors.default.blue("info")} ${message}`);
+		},
+		success(message) {
+			if (jsonMode) process.stderr.write(`${picocolors.default.green("done")} ${message}\n`);
+			else console.log(`\n${picocolors.default.green("done")} ${message}`);
+		},
+		warn(message) {
+			console.warn(`${picocolors.default.yellow("warn")} ${message}`);
+		},
+		error(message) {
+			console.error(`${picocolors.default.red("error")} ${message}`);
+		},
+		debug(message) {
+			if (debugMode) {
+				if (jsonMode) process.stderr.write(`${picocolors.default.gray(`[${timestamp()}] debug`)} ${message}\n`);
+				else console.log(`${picocolors.default.gray(`[${timestamp()}] debug`)} ${message}`);
+			}
+		}
+	};
+}));
 
 //#endregion
-//#region src/constants.ts
-const APP_NAME = "scene-sieve";
-const DEFAULT_THRESHOLD = .5;
-const NORMALIZATION_ALPHA = .4;
-const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
-const WORKSPACE_PREFIX = `${APP_NAME}-`;
-const TEMP_BASE_DIR = (0, node_os.tmpdir)();
-const FRAME_OUTPUT_EXTENSION = ".jpg";
-const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
-const DBSCAN_ALPHA = .03;
-const IOU_THRESHOLD = .9;
-const DECAY_LAMBDA = .95;
-const MATCH_DISTANCE_THRESHOLD = .25;
-function getTempWorkspaceDir(sessionId) {
-	return (0, node_path.join)(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
-}
+//#region src/constants/pipeline-defaults.ts
+var DEFAULT_THRESHOLD, IOU_THRESHOLD, SHEET_LABEL_HEIGHT_RATIO, SHEET_FILE_NAME, METADATA_FILE_NAME;
+var init_pipeline_defaults = __esmMin((() => {
+	DEFAULT_THRESHOLD = .5;
+	IOU_THRESHOLD = .9;
+	SHEET_LABEL_HEIGHT_RATIO = .07;
+	SHEET_FILE_NAME = "sheet.jpg";
+	METADATA_FILE_NAME = ".metadata.json";
+}));
+
+//#endregion
+//#region src/core/analyzer/constants/vision-tuning.ts
+var DBSCAN_ALPHA, DECAY_LAMBDA, MATCH_DISTANCE_THRESHOLD;
+var init_vision_tuning = __esmMin((() => {
+	DBSCAN_ALPHA = .03;
+	DECAY_LAMBDA = .95;
+	MATCH_DISTANCE_THRESHOLD = .25;
+}));
 
 //#endregion
-//#region src/core/dbscan.ts
-const UNVISITED = -2;
-const NOISE = -1;
+//#region src/core/analyzer/clustering/dbscan.ts
 /**
 * DBSCAN clustering with resolution-independent eps.
 * eps = alpha * sqrt(width^2 + height^2)
@@ -168,12 +182,118 @@ function findNeighbors(points, idx, epsSquared) {
 	}
 	return neighbors;
 }
+var UNVISITED, NOISE;
+var init_dbscan = __esmMin((() => {
+	init_vision_tuning();
+	UNVISITED = -2;
+	NOISE = -1;
+}));
+
+//#endregion
+//#region src/core/analyzer/features/feature-diff.ts
+/**
+* Match prev to next with Hamming k=2, crossCheck=false and strict ratio 0.25.
+* @param cvLib - Initialized OpenCV runtime.
+* @param prev - Previous frame's live features, owned by the caller.
+* @param next - Next frame's live features, owned by the caller.
+* @returns Unmatched next-frame coordinates without changing input ownership.
+* @throws Propagates matching errors after releasing temporary native handles.
+*/
+function computeNewPoints(cvLib, prev, next) {
+	let matcher = null;
+	let matches = null;
+	try {
+		const matchedIndices = /* @__PURE__ */ new Set();
+		if (prev.descriptors.rows > 0 && next.descriptors.rows > 0) try {
+			matcher = new cvLib.BFMatcher(cvLib.NORM_HAMMING, false);
+			matches = new cvLib.DMatchVectorVector();
+			matcher.knnMatch(prev.descriptors, next.descriptors, matches, 2);
+			for (let i = 0; i < matches.size(); i++) {
+				const pair = matches.get(i);
+				try {
+					if (pair.size() < 2) continue;
+					const best = pair.get(0);
+					const second = pair.get(1);
+					if (best.distance < .25 * second.distance) matchedIndices.add(best.trainIdx);
+				} finally {
+					pair.delete();
+				}
+			}
+		} finally {
+			matcher?.delete();
+		}
+		const points = [];
+		for (let i = 0; i < next.keypoints.size(); i++) if (!matchedIndices.has(i)) {
+			const { x, y } = next.keypoints.get(i).pt;
+			points.push({
+				x,
+				y
+			});
+		}
+		return points;
+	} finally {
+		matches?.delete();
+	}
+}
+var init_feature_diff = __esmMin((() => {
+	init_vision_tuning();
+}));
+
+//#endregion
+//#region src/core/analyzer/features/frame-features.ts
+/**
+* Detect one frame's features without retaining its image or mask.
+* @param cvLib - Initialized OpenCV runtime.
+* @param akaze - Detector owned and released by the caller.
+* @param frame - Grayscale bytes with matching width and height.
+* @returns Feature handles that the caller must delete.
+* @throws Propagates native errors after releasing partial allocations.
+*/
+function computeFrameFeatures(cvLib, akaze, frame) {
+	let image = null;
+	let mask = null;
+	let keypoints = null;
+	let descriptors = null;
+	try {
+		image = new cvLib.Mat(frame.height, frame.width, cvLib.CV_8UC1);
+		image.data.set(frame.data);
+		mask = new cvLib.Mat();
+		keypoints = new cvLib.KeyPointVector();
+		descriptors = new cvLib.Mat();
+		akaze.detectAndCompute(image, mask, keypoints, descriptors);
+		const ownedKeypoints = keypoints;
+		const ownedDescriptors = descriptors;
+		let deleted = false;
+		const features = {
+			width: frame.width,
+			height: frame.height,
+			keypoints: ownedKeypoints,
+			descriptors: ownedDescriptors,
+			/** Release the transferred handles exactly once. */
+			delete() {
+				if (deleted) return;
+				deleted = true;
+				try {
+					ownedKeypoints.delete();
+				} finally {
+					ownedDescriptors.delete();
+				}
+			}
+		};
+		keypoints = null;
+		descriptors = null;
+		return features;
+	} finally {
+		image?.delete();
+		mask?.delete();
+		keypoints?.delete();
+		descriptors?.delete();
+	}
+}
+var init_frame_features = __esmMin((() => {}));
 
 //#endregion
-//#region src/core/analyzer.ts
-const OPENCV_INIT_TIMEOUT_MS = 3e4;
-const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
-let cvReady = null;
+//#region src/core/analyzer/analyzer.ts
 async function ensureOpenCV() {
 	if (!cvReady) cvReady = (async () => {
 		const cvObj = require$1("@techstark/opencv-js");
@@ -212,158 +332,6 @@ function computeIoU(a, b) {
 	const union = a.width * a.height + b.width * b.height - intersection;
 	return union === 0 ? 0 : intersection / union;
 }
-var IoUTracker = class {
-	fps;
-	iouThreshold;
-	animationThreshold;
-	regions = [];
-	extractedAnimations = [];
-	constructor(fps = 5, iouThreshold = IOU_THRESHOLD, animationThreshold = 5) {
-		this.fps = fps;
-		this.iouThreshold = iouThreshold;
-		this.animationThreshold = animationThreshold;
-	}
-	update(boxes, pairIndex) {
-		const animationIndices = /* @__PURE__ */ new Set();
-		const matched = /* @__PURE__ */ new Set();
-		for (let bi = 0; bi < boxes.length; bi++) {
-			const box = boxes[bi];
-			let bestIoU = 0;
-			let bestRegionIdx = -1;
-			for (let ri = 0; ri < this.regions.length; ri++) {
-				if (matched.has(ri)) continue;
-				const iou = computeIoU(box, this.regions[ri].box);
-				if (iou > bestIoU) {
-					bestIoU = iou;
-					bestRegionIdx = ri;
-				}
-			}
-			if (bestIoU > this.iouThreshold && bestRegionIdx !== -1) {
-				const region = this.regions[bestRegionIdx];
-				const gap = pairIndex - region.lastSeen;
-				region.box = box;
-				region.consecutiveCount++;
-				region.lastSeen = pairIndex;
-				region.weight *= Math.pow(DECAY_LAMBDA, gap);
-				matched.add(bestRegionIdx);
-				if (region.consecutiveCount >= this.animationThreshold) animationIndices.add(bi);
-			} else this.regions.push({
-				box,
-				consecutiveCount: 1,
-				firstSeen: pairIndex,
-				lastSeen: pairIndex,
-				weight: 1
-			});
-		}
-		for (let ri = 0; ri < this.regions.length; ri++) if (!matched.has(ri)) {
-			const gap = pairIndex - this.regions[ri].lastSeen;
-			this.regions[ri].weight *= Math.pow(DECAY_LAMBDA, gap);
-		}
-		for (let i = 0; i < this.regions.length; i++) {
-			const region = this.regions[i];
-			if (region.weight <= .01 && !matched.has(i)) this.collectAnimation(region);
-		}
-		this.regions = (0, _winglet_common_utils.filter)(this.regions, (r, i) => r.weight > .01 || matched.has(i));
-		return animationIndices;
-	}
-	collectAnimation(region) {
-		if (region.consecutiveCount >= this.animationThreshold) {
-			const durationMs = region.consecutiveCount / this.fps * 1e3;
-			this.extractedAnimations.push({
-				type: "loading_spinner",
-				boundingBox: region.box,
-				startFrameId: region.firstSeen,
-				endFrameId: region.lastSeen,
-				durationMs
-			});
-		}
-	}
-	flushAndGetAnimations() {
-		for (const region of this.regions) this.collectAnimation(region);
-		this.regions = [];
-		return this.extractedAnimations;
-	}
-	getAnimationWeight(boxIndex, boxes) {
-		if (boxIndex >= boxes.length) return 0;
-		const box = boxes[boxIndex];
-		let maxWeight = 0;
-		for (const region of this.regions) if (region.consecutiveCount >= this.animationThreshold) {
-			if (computeIoU(box, region.box) > this.iouThreshold) maxWeight = Math.max(maxWeight, region.weight);
-		}
-		return maxWeight;
-	}
-};
-async function computeAKAZEDiff(cvLib, frame1, frame2) {
-	const cv = cvLib;
-	const mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
-	mat1.data.set(frame1.data);
-	const mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
-	mat2.data.set(frame2.data);
-	const kp1 = new cvLib.KeyPointVector();
-	const kp2 = new cvLib.KeyPointVector();
-	const desc1 = new cvLib.Mat();
-	const desc2 = new cvLib.Mat();
-	const mask1 = new cvLib.Mat();
-	const mask2 = new cvLib.Mat();
-	const akaze = new cvLib.AKAZE();
-	let matches = null;
-	try {
-		akaze.detectAndCompute(mat1, mask1, kp1, desc1);
-		akaze.detectAndCompute(mat2, mask2, kp2, desc2);
-		const matchedKp1Indices = /* @__PURE__ */ new Set();
-		const matchedKp2Indices = /* @__PURE__ */ new Set();
-		if (desc1.rows > 0 && desc2.rows > 0) {
-			const matcher = new cvLib.BFMatcher(cvLib.NORM_HAMMING, false);
-			try {
-				matches = new cvLib.DMatchVectorVector();
-				matcher.knnMatch(desc1, desc2, matches, 2);
-				for (let i = 0; i < matches.size(); i++) {
-					const pair = matches.get(i);
-					if (pair.size() < 2) continue;
-					const m0 = pair.get(0);
-					const m1 = pair.get(1);
-					if (m0.distance < .25 * m1.distance) {
-						matchedKp1Indices.add(m0.queryIdx);
-						matchedKp2Indices.add(m0.trainIdx);
-					}
-				}
-			} finally {
-				matcher.delete();
-			}
-		}
-		const sNew = [];
-		for (let i = 0; i < kp2.size(); i++) if (!matchedKp2Indices.has(i)) {
-			const pt = kp2.get(i).pt;
-			sNew.push({
-				x: pt.x,
-				y: pt.y
-			});
-		}
-		const sLoss = [];
-		for (let i = 0; i < kp1.size(); i++) if (!matchedKp1Indices.has(i)) {
-			const pt = kp1.get(i).pt;
-			sLoss.push({
-				x: pt.x,
-				y: pt.y
-			});
-		}
-		return {
-			sNew,
-			sLoss
-		};
-	} finally {
-		mat1.delete();
-		mat2.delete();
-		kp1.delete();
-		kp2.delete();
-		desc1.delete();
-		desc2.delete();
-		mask1.delete();
-		mask2.delete();
-		akaze.delete();
-		if (matches) matches.delete();
-	}
-}
 /**
 * Pixel-level difference fallback for AKAZE blind spots.
 *
@@ -378,17 +346,30 @@ async function computeAKAZEDiff(cvLib, frame1, frame2) {
 * 3. threshold → binary mask of significant changes
 * 4. findContours → bounding rects of changed regions
 * 5. Grid sampling within each bounding rect → Point2D[]
+*
+* @param cvLib - Initialized OpenCV runtime shared by the analyzer.
+* @param frame1 - Previous grayscale frame, with the same dimensions as frame2.
+* @param frame2 - Next grayscale frame, with the same dimensions as frame1.
+* @returns Grid-sampled points from changed regions.
+* @throws Propagates allocation or OpenCV errors after releasing acquired handles.
 */
 function computePixelDiff(cvLib, frame1, frame2) {
 	const cv = cvLib;
-	const mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
-	const mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
-	const diff = new cv.Mat();
-	const blurred = new cv.Mat();
-	const binary = new cv.Mat();
-	const contours = new cv.MatVector();
-	const hierarchy = new cv.Mat();
+	let mat1 = null;
+	let mat2 = null;
+	let diff = null;
+	let blurred = null;
+	let binary = null;
+	let contours = null;
+	let hierarchy = null;
 	try {
+		mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
+		mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
+		diff = new cv.Mat();
+		blurred = new cv.Mat();
+		binary = new cv.Mat();
+		contours = new cv.MatVector();
+		hierarchy = new cv.Mat();
 		mat1.data.set(frame1.data);
 		mat2.data.set(frame2.data);
 		cv.absdiff(mat1, mat2, diff);
@@ -399,22 +380,26 @@ function computePixelDiff(cvLib, frame1, frame2) {
 		const points = [];
 		for (let c = 0; c < contours.size(); c++) {
 			const contour = contours.get(c);
-			const rect = cv.boundingRect(contour);
-			if (rect.width * rect.height < 100) continue;
-			for (let y = rect.y; y < rect.y + rect.height; y += 8) for (let x = rect.x; x < rect.x + rect.width; x += 8) points.push({
-				x,
-				y
-			});
+			try {
+				const rect = cv.boundingRect(contour);
+				if (rect.width * rect.height < 100) continue;
+				for (let y = rect.y; y < rect.y + rect.height; y += 8) for (let x = rect.x; x < rect.x + rect.width; x += 8) points.push({
+					x,
+					y
+				});
+			} finally {
+				contour.delete();
+			}
 		}
 		return points;
 	} finally {
-		mat1.delete();
-		mat2.delete();
-		diff.delete();
-		blurred.delete();
-		binary.delete();
-		contours.delete();
-		hierarchy.delete();
+		mat1?.delete();
+		mat2?.delete();
+		diff?.delete();
+		blurred?.delete();
+		binary?.delete();
+		contours?.delete();
+		hierarchy?.delete();
 	}
 }
 function computeInformationGain(clusters, clusterPoints, imageArea, animationIndices, animationWeights) {
@@ -433,47 +418,91 @@ function computeInformationGain(clusters, clusterPoints, imageArea, animationInd
 	}
 	return gain;
 }
-async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
+/**
+* Analyze one batch, retaining its boundary frame for the following batch.
+* @param cvLib - Initialized OpenCV runtime.
+* @param akaze - Detector owned by analyzeFrames.
+* @param frames - Boundary frame followed by new adjacent frames.
+* @param carry - Boundary bytes and live features transferred from the previous batch.
+* @param scale - Maximum preprocessing width.
+* @param tracker - Stateful animation tracker shared across batches.
+* @param pairOffset - Global position of this batch's first pair.
+* @returns Scores, pair failure count, and ownership of the final frame's features.
+*/
+async function analyzeBatch(cvLib, akaze, frames, carry, scale, tracker, pairOffset) {
 	const edges = [];
-	const preprocessed = await Promise.all((0, _winglet_common_utils.map)(frames, (f) => preprocessFrame(f.extractPath, scale)));
-	const imageWidth = preprocessed[0]?.width ?? scale;
-	const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
-	const imageArea = imageWidth * imageHeight;
-	for (let i = 0; i < frames.length - 1; i++) {
-		const pairIndex = pairOffset + i;
-		try {
-			const { sNew } = await computeAKAZEDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
-			let dbscanResult = dbscan(sNew, imageWidth, imageHeight);
-			let clusters = dbscanResult.boundingBoxes;
-			if (clusters.length === 0) {
-				const pixelDiffPoints = computePixelDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
-				if (pixelDiffPoints.length > 0) {
-					logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id}: pixel-diff fallback (${pixelDiffPoints.length} points)`);
-					dbscanResult = dbscan(pixelDiffPoints, imageWidth, imageHeight, void 0, 2);
-					clusters = dbscanResult.boundingBoxes;
+	let failures = 0;
+	let prev = carry?.features ?? null;
+	let next = null;
+	try {
+		const preprocessed = await Promise.all((0, _winglet_common_utils.map)(frames, (f, index) => index === 0 && carry ? carry.preprocessed : preprocessFrame(f.extractPath, scale)));
+		const imageWidth = preprocessed[0]?.width ?? scale;
+		const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
+		const imageArea = imageWidth * imageHeight;
+		for (let i = 0; i < frames.length - 1; i++) {
+			const pairIndex = pairOffset + i;
+			try {
+				prev ??= computeFrameFeatures(cvLib, akaze, preprocessed[i]);
+				next = computeFrameFeatures(cvLib, akaze, preprocessed[i + 1]);
+				const sNew = computeNewPoints(cvLib, prev, next);
+				let dbscanResult = dbscan(sNew, imageWidth, imageHeight);
+				let clusters = dbscanResult.boundingBoxes;
+				if (clusters.length === 0) {
+					const pixelDiffPoints = computePixelDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
+					if (pixelDiffPoints.length > 0) {
+						logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id}: pixel-diff fallback (${pixelDiffPoints.length} points)`);
+						dbscanResult = dbscan(pixelDiffPoints, imageWidth, imageHeight, void 0, 2);
+						clusters = dbscanResult.boundingBoxes;
+					}
 				}
+				const clusterPointCounts = new Array(clusters.length).fill(0);
+				for (const label of dbscanResult.labels) if (label >= 0) clusterPointCounts[label]++;
+				const animationIndices = tracker.update(clusters, pairIndex);
+				const change = {
+					regions: (0, _winglet_common_utils.filter)(clusters, (_, ci) => !animationIndices.has(ci)),
+					animatedRegions: (0, _winglet_common_utils.filter)(clusters, (_, ci) => animationIndices.has(ci))
+				};
+				const animationWeights = (0, _winglet_common_utils.map)(clusters, (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0);
+				const score = computeInformationGain(clusters, clusterPointCounts, imageArea, animationIndices, animationWeights);
+				logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
+				edges.push({
+					sourceId: frames[i].id,
+					targetId: frames[i + 1].id,
+					score,
+					change
+				});
+			} catch (err) {
+				logger.warn(`Frame pair analysis failed: ${String(err)}`);
+				failures++;
+				edges.push({
+					sourceId: frames[i].id,
+					targetId: frames[i + 1].id,
+					score: 0
+				});
+			} finally {
+				prev?.delete();
+				prev = next;
+				next = null;
 			}
-			const clusterPointCounts = new Array(clusters.length).fill(0);
-			for (const label of dbscanResult.labels) if (label >= 0) clusterPointCounts[label]++;
-			const animationIndices = tracker.update(clusters, pairIndex);
-			const animationWeights = (0, _winglet_common_utils.map)(clusters, (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0);
-			const score = computeInformationGain(clusters, clusterPointCounts, imageArea, animationIndices, animationWeights);
-			logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
-			edges.push({
-				sourceId: frames[i].id,
-				targetId: frames[i + 1].id,
-				score
-			});
-		} catch (err) {
-			logger.debug(`Frame pair analysis failed: ${String(err)}`);
-			edges.push({
-				sourceId: frames[i].id,
-				targetId: frames[i + 1].id,
-				score: 0
-			});
 		}
+		const result = {
+			edges,
+			failures,
+			analysisResolution: {
+				width: imageWidth,
+				height: imageHeight
+			},
+			carry: prev ? {
+				preprocessed: preprocessed[preprocessed.length - 1],
+				features: prev
+			} : null
+		};
+		prev = null;
+		return result;
+	} finally {
+		prev?.delete();
+		next?.delete();
 	}
-	return edges;
 }
 /**
 * Analyze adjacent frame pairs to compute information gain scores (G(t)).
@@ -484,35 +513,183 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
 * 2. DBSCAN Spatial Clustering
 * 3. Spatio-temporal IoU Tracking
 * 4. G(t) Information Gain Scoring
+* @param ctx - Frames, analysis options, and the progress callback for this run.
+* @returns Adjacent scores and tracked animations in analysis coordinates.
+* @throws Propagates runtime errors and rejects total failure of two or more pairs after cleanup.
 */
 async function analyzeFrames(ctx) {
 	const { frames } = ctx;
 	if (frames.length < 2) return {
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
 	logger.debug(`Analyzing ${frames.length} frames in batches of ${10}`);
 	const cvLib = await ensureOpenCV();
 	const edges = [];
-	const tracker = new IoUTracker(ctx.options.fps, ctx.options.iouThreshold, ctx.options.animationThreshold);
+	const tracker = new IoUTracker(ctx.effectiveFps ?? ctx.options.fps, ctx.options.iouThreshold, ctx.options.animationThreshold);
 	const scale = ctx.options.scale;
-	for (let i = 0; i < frames.length - 1; i += 10) {
-		const batchEnd = Math.min(i + 10 + 1, frames.length);
-		const batchEdges = await analyzeBatch(cvLib, frames.slice(i, batchEnd), scale, tracker, i);
-		edges.push(...batchEdges);
-		const progress = Math.min(100, (i + 10) / (frames.length - 1) * 100);
-		ctx.emitProgress(progress);
+	let akaze = null;
+	let carry = null;
+	let analysisResolution = {
+		width: 0,
+		height: 0
+	};
+	let failures = 0;
+	try {
+		akaze = new cvLib.AKAZE();
+		for (let i = 0; i < frames.length - 1; i += 10) {
+			const batch = [frames[i], ...frames.slice(i + 1, i + 1 + 10)];
+			const result = await analyzeBatch(cvLib, akaze, batch, carry, scale, tracker, i);
+			carry = result.carry;
+			failures += result.failures;
+			if (i === 0) analysisResolution = result.analysisResolution;
+			edges.push(...result.edges);
+			const progress = Math.min(100, (i + 10) / (frames.length - 1) * 100);
+			ctx.emitProgress(progress);
+		}
+	} finally {
+		carry?.features.delete();
+		akaze?.delete();
 	}
+	const pairs = frames.length - 1;
+	if (pairs >= 2 && failures === pairs) throw new Error(`All ${pairs} frame pairs failed analysis`);
 	const animations = tracker.flushAndGetAnimations();
 	logger.debug(`Computed ${edges.length} score edges and ${animations.length} animations`);
 	return {
 		edges,
-		animations
+		animations,
+		analysisResolution
 	};
 }
+var OPENCV_INIT_TIMEOUT_MS, require$1, cvReady, IoUTracker;
+var init_analyzer$1 = __esmMin((() => {
+	init_pipeline_defaults();
+	init_vision_tuning();
+	init_logger();
+	init_dbscan();
+	init_feature_diff();
+	init_frame_features();
+	OPENCV_INIT_TIMEOUT_MS = 3e4;
+	require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+	cvReady = null;
+	IoUTracker = class {
+		fps;
+		iouThreshold;
+		animationThreshold;
+		regions = [];
+		extractedAnimations = [];
+		constructor(fps = 5, iouThreshold = IOU_THRESHOLD, animationThreshold = 5) {
+			this.fps = fps;
+			this.iouThreshold = iouThreshold;
+			this.animationThreshold = animationThreshold;
+		}
+		update(boxes, pairIndex) {
+			const animationIndices = /* @__PURE__ */ new Set();
+			const matched = /* @__PURE__ */ new Set();
+			for (let bi = 0; bi < boxes.length; bi++) {
+				const box = boxes[bi];
+				let bestIoU = 0;
+				let bestRegionIdx = -1;
+				for (let ri = 0; ri < this.regions.length; ri++) {
+					if (matched.has(ri)) continue;
+					const iou = computeIoU(box, this.regions[ri].box);
+					if (iou > bestIoU) {
+						bestIoU = iou;
+						bestRegionIdx = ri;
+					}
+				}
+				if (bestIoU > this.iouThreshold && bestRegionIdx !== -1) {
+					const region = this.regions[bestRegionIdx];
+					const gap = pairIndex - region.lastSeen;
+					region.box = box;
+					region.consecutiveCount++;
+					region.lastSeen = pairIndex;
+					region.weight *= Math.pow(DECAY_LAMBDA, gap);
+					matched.add(bestRegionIdx);
+					if (region.consecutiveCount >= this.animationThreshold) animationIndices.add(bi);
+				} else this.regions.push({
+					box,
+					consecutiveCount: 1,
+					firstSeen: pairIndex,
+					lastSeen: pairIndex,
+					weight: 1
+				});
+			}
+			for (let ri = 0; ri < this.regions.length; ri++) if (!matched.has(ri)) {
+				const gap = pairIndex - this.regions[ri].lastSeen;
+				this.regions[ri].weight *= Math.pow(DECAY_LAMBDA, gap);
+			}
+			for (let i = 0; i < this.regions.length; i++) {
+				const region = this.regions[i];
+				if (region.weight <= .01 && !matched.has(i)) this.collectAnimation(region);
+			}
+			this.regions = (0, _winglet_common_utils.filter)(this.regions, (r, i) => r.weight > .01 || matched.has(i));
+			return animationIndices;
+		}
+		collectAnimation(region) {
+			if (region.consecutiveCount >= this.animationThreshold) {
+				const durationMs = region.consecutiveCount / this.fps * 1e3;
+				this.extractedAnimations.push({
+					type: "loading_spinner",
+					boundingBox: region.box,
+					startFrameId: region.firstSeen,
+					endFrameId: region.lastSeen,
+					durationMs
+				});
+			}
+		}
+		flushAndGetAnimations() {
+			for (const region of this.regions) this.collectAnimation(region);
+			this.regions = [];
+			return this.extractedAnimations;
+		}
+		getAnimationWeight(boxIndex, boxes) {
+			if (boxIndex >= boxes.length) return 0;
+			const box = boxes[boxIndex];
+			let maxWeight = 0;
+			for (const region of this.regions) if (region.consecutiveCount >= this.animationThreshold) {
+				if (computeIoU(box, region.box) > this.iouThreshold) maxWeight = Math.max(maxWeight, region.weight);
+			}
+			return maxWeight;
+		}
+	};
+}));
+
+//#endregion
+//#region src/core/analyzer/index.ts
+var init_analyzer = __esmMin((() => {
+	init_analyzer$1();
+	init_dbscan();
+}));
+
+//#endregion
+//#region src/constants/package-version.ts
+var manifestPath, PACKAGE_VERSION;
+var init_package_version = __esmMin((() => {
+	manifestPath = (0, node_fs.existsSync)(new URL("../package.json", require("url").pathToFileURL(__filename).href)) ? "../package.json" : "../../package.json";
+	PACKAGE_VERSION = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)(manifestPath).version;
+}));
 
 //#endregion
-//#region src/utils/paths.ts
+//#region src/core/constants/workspace-layout.ts
+function getTempWorkspaceDir(sessionId) {
+	return (0, node_path.join)(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
+}
+var APP_NAME, WORKSPACE_PREFIX, TEMP_BASE_DIR, FRAME_OUTPUT_EXTENSION, FRAME_FILENAME_PATTERN;
+var init_workspace_layout = __esmMin((() => {
+	APP_NAME = "scene-sieve";
+	WORKSPACE_PREFIX = `${APP_NAME}-`;
+	TEMP_BASE_DIR = (0, node_os.tmpdir)();
+	FRAME_OUTPUT_EXTENSION = ".jpg";
+	FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+}));
+
+//#endregion
+//#region src/core/utils/filesystem/paths.ts
 async function ensureDir(dirPath) {
 	await (0, node_fs_promises.mkdir)(dirPath, { recursive: true });
 }
@@ -546,17 +723,638 @@ function resolveAbsolute(p) {
 * e.g., /path/to/video.mp4 -> /path/to/video_scenes
 */
 function deriveOutputPath(inputPath) {
-	return (0, node_path.resolve)((0, node_path.resolve)(inputPath, ".."), `${(0, node_path.basename)(inputPath, (0, node_path.extname)(inputPath))}_scenes`);
+	const dir = (0, node_path.resolve)(inputPath, "..");
+	const name = (0, node_path.basename)(inputPath, (0, node_path.extname)(inputPath));
+	return (0, node_path.resolve)(dir, `${name}_scenes`);
+}
+var init_paths = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/workspace/workspace.ts
+async function createWorkspace(sessionId) {
+	const workspacePath = getTempWorkspaceDir(sessionId);
+	await ensureDir((0, node_path.join)(workspacePath, "frames"));
+	await ensureDir((0, node_path.join)(workspacePath, "output"));
+	return workspacePath;
+}
+/**
+* Write selected JPEGs and the supplied document before replacing the output directory.
+* @param ctx - Workspace, quality and destination settings.
+* @param selectedFrames - Frames paired by position with document.frames.
+* @param document - Complete metadata, including the output file names.
+* @param sheetBuffer - Optional JPEG contact sheet bytes to persist unchanged.
+* @returns Selected JPEG paths, optional sheet path and finally the metadata path.
+* @throws Rejects mismatched frame counts and propagates image or filesystem errors.
+*/
+async function finalizeOutput(ctx, selectedFrames, document, sheetBuffer) {
+	if (document.frames.length !== selectedFrames.length) throw new Error("metadata frame count must match selected frame count");
+	const stagingDir = (0, node_path.join)(ctx.workspacePath, "output");
+	const outputPath = ctx.options.outputPath;
+	const quality = ctx.options.quality;
+	const outputFiles = [];
+	for (let i = 0; i < selectedFrames.length; i++) {
+		const frame = selectedFrames[i];
+		const fileName = document.frames[i].fileName;
+		const destPath = (0, node_path.join)(stagingDir, fileName);
+		await (0, sharp.default)(frame.extractPath).jpeg({
+			quality,
+			mozjpeg: true
+		}).toFile(destPath);
+		outputFiles.push((0, node_path.join)(outputPath, fileName));
+	}
+	if (sheetBuffer) {
+		await (0, node_fs_promises.writeFile)((0, node_path.join)(stagingDir, SHEET_FILE_NAME), sheetBuffer);
+		outputFiles.push((0, node_path.join)(outputPath, SHEET_FILE_NAME));
+	}
+	const metadataPath = (0, node_path.join)(stagingDir, METADATA_FILE_NAME);
+	await (0, node_fs_promises.writeFile)(metadataPath, JSON.stringify(document, null, 2));
+	outputFiles.push((0, node_path.join)(outputPath, METADATA_FILE_NAME));
+	await ensureDir((0, node_path.join)(outputPath, ".."));
+	await (0, node_fs_promises.rm)(outputPath, {
+		recursive: true,
+		force: true
+	});
+	await (0, node_fs_promises.rename)(stagingDir, outputPath);
+	return outputFiles;
+}
+async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
+	const segmentPath = (0, node_path.join)(parentWorkspacePath, "segments", String(segmentIndex));
+	await ensureDir((0, node_path.join)(segmentPath, "frames"));
+	return segmentPath;
+}
+async function cleanupWorkspace(workspacePath) {
+	if (!workspacePath) return;
+	try {
+		await (0, node_fs_promises.rm)(workspacePath, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+/**
+* Write a video buffer to a temp file in the workspace and return the path.
+* Used by 'buffer' input mode.
+*/
+async function writeInputBuffer(buffer, workspacePath) {
+	const inputDir = (0, node_path.join)(workspacePath, "input");
+	await ensureDir(inputDir);
+	const tempPath = (0, node_path.join)(inputDir, "input.mp4");
+	await (0, node_fs_promises.writeFile)(tempPath, buffer);
+	return tempPath;
+}
+/**
+* Write an array of frame Buffers as JPG files and return FrameNode[].
+* Used by 'frames' input mode.
+*/
+async function writeInputFrames(frames, workspacePath) {
+	const framesDir = (0, node_path.join)(workspacePath, "frames");
+	await ensureDir(framesDir);
+	const frameNodes = [];
+	for (let i = 0; i < frames.length; i++) {
+		const filename = `frame_${String(i).padStart(6, "0")}${FRAME_OUTPUT_EXTENSION}`;
+		const extractPath = (0, node_path.join)(framesDir, filename);
+		await (0, node_fs_promises.writeFile)(extractPath, frames[i]);
+		frameNodes.push({
+			id: i,
+			timestamp: i,
+			extractPath
+		});
+	}
+	return frameNodes;
+}
+/**
+* Read selected FrameNode files as Buffers with JPEG compression.
+* Used to return output buffers in 'buffer' and 'frames' modes.
+*/
+async function readFramesAsBuffers(frameNodes, quality) {
+	return Promise.all((0, _winglet_common_utils.map)(frameNodes, (f) => (0, sharp.default)(f.extractPath).jpeg({
+		quality,
+		mozjpeg: true
+	}).toBuffer()));
+}
+var init_workspace$1 = __esmMin((() => {
+	init_workspace_layout();
+	init_pipeline_defaults();
+	init_paths();
+}));
+
+//#endregion
+//#region src/core/workspace/index.ts
+var init_workspace = __esmMin((() => {
+	init_workspace$1();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/change/union-area/y-coverage-tree.ts
+var YCoverageTree;
+var init_y_coverage_tree = __esmMin((() => {
+	YCoverageTree = class {
+		bounds;
+		/** Number of whole-node covering intervals, independent of descendants. */
+		counts;
+		/** Covered geometric length for each node, including partially covered children. */
+		lengths;
+		/**
+		* Allocate linear storage for the elementary intervals between coordinates.
+		* @param bounds - At least two sorted unique finite y endpoints.
+		*/
+		constructor(bounds) {
+			this.bounds = bounds;
+			this.counts = Array(4 * bounds.length).fill(0);
+			this.lengths = Array(4 * bounds.length).fill(0);
+		}
+		/** Total active covered y length, in the input coordinate system. */
+		get coveredLength() {
+			return this.lengths[1];
+		}
+		/**
+		* Adjust a nonempty half-open interval and refresh its ancestors' lengths.
+		* @param start - Inclusive endpoint index; 0 <= start < end.
+		* @param end - Exclusive endpoint index; end < bounds.length.
+		* @param delta - One on entry, minus one for the matching departure.
+		* @param node - Internal tree slot; callers use the root default.
+		* @param left - Inclusive endpoint index of this node.
+		* @param right - Exclusive endpoint index of this node.
+		* @returns Nothing; mutates this tree's coverage in O(log n).
+		*/
+		update(start, end, delta, node = 1, left = 0, right = this.bounds.length - 1) {
+			if (start <= left && right <= end) this.counts[node] += delta;
+			else {
+				const middle = Math.floor((left + right) / 2);
+				if (start < middle) this.update(start, end, delta, node * 2, left, middle);
+				if (end > middle) this.update(start, end, delta, node * 2 + 1, middle, right);
+			}
+			this.lengths[node] = this.counts[node] > 0 ? this.bounds[right] - this.bounds[left] : right - left === 1 ? 0 : this.lengths[node * 2] + this.lengths[node * 2 + 1];
+		}
+	};
+}));
+
+//#endregion
+//#region src/core/utils/metadata/change/union-area.ts
+/**
+* Measure rectangle union with an x sweep in O(n log n) time and O(n) space.
+* @param boxes - Finite rectangles; nonpositive dimensions are ignored.
+* @returns Covered area in the input coordinate system, or zero for empty input.
+*/
+function unionArea(boxes) {
+	const events = [];
+	const endpoints = [];
+	for (const box of boxes) {
+		if (!(box.width > 0 && box.height > 0)) continue;
+		const end = box.y + box.height;
+		if (end === box.y) continue;
+		events.push({
+			x: box.x,
+			start: box.y,
+			end,
+			delta: 1
+		});
+		events.push({
+			x: box.x + box.width,
+			start: box.y,
+			end,
+			delta: -1
+		});
+		endpoints.push(box.y, end);
+	}
+	if (events.length === 0) return 0;
+	events.sort((a, b) => a.x - b.x);
+	endpoints.sort((a, b) => a - b);
+	const bounds = endpoints.filter((value, index) => index === 0 || value !== endpoints[index - 1]);
+	const indices = new Map(bounds.map((value, index) => [value, index]));
+	const coverage = new YCoverageTree(bounds);
+	let area = 0;
+	let previousX = events[0].x;
+	for (const event of events) {
+		area += (event.x - previousX) * coverage.coveredLength;
+		coverage.update(indices.get(event.start), indices.get(event.end), event.delta);
+		previousX = event.x;
+	}
+	return area;
+}
+var init_union_area = __esmMin((() => {
+	init_y_coverage_tree();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/build-edge-metadata.ts
+/**
+* Serialize raw candidate edges in graph order.
+* @param graph - Adjacent-pair edges, optionally carrying tracker partitions.
+* @param analysisResolution - Analysis dimensions used for both area fractions.
+* @returns One-based IDs with six-decimal scores and four-decimal clamped ratios.
+*/
+function buildEdgeMetadata(graph, analysisResolution) {
+	const area = analysisResolution.width * analysisResolution.height;
+	return (0, _winglet_common_utils.map)(graph, (edge) => ({
+		sourceFrameId: edge.sourceId + 1,
+		targetFrameId: edge.targetId + 1,
+		score: Math.round(edge.score * 1e6) / 1e6,
+		areaRatio: area > 0 ? Math.round(Math.max(0, Math.min(1, unionArea(edge.change?.regions ?? []) / area)) * 1e4) / 1e4 : 0,
+		animatedAreaRatio: area > 0 ? Math.round(Math.max(0, Math.min(1, unionArea(edge.change?.animatedRegions ?? []) / area)) * 1e4) / 1e4 : 0
+	}));
+}
+var init_build_edge_metadata = __esmMin((() => {
+	init_union_area();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/scale-bounding-box.ts
+/**
+* Convert an analysis box to clamped integer output pixels.
+* @param box - Analysis-space rectangle; the input remains unchanged.
+* @param sx - Horizontal output-to-analysis scale.
+* @param sy - Vertical output-to-analysis scale.
+* @param width - Nonnegative output image width.
+* @param height - Nonnegative output image height.
+* @returns A rectangle contained within the output dimensions.
+*/
+function scaleBoundingBox(box, sx, sy, width, height) {
+	const x = Math.max(0, Math.min(width, Math.round(box.x * sx)));
+	const y = Math.max(0, Math.min(height, Math.round(box.y * sy)));
+	return {
+		x,
+		y,
+		width: Math.max(0, Math.min(width - x, Math.round(box.width * sx))),
+		height: Math.max(0, Math.min(height - y, Math.round(box.height * sy)))
+	};
+}
+var init_scale_bounding_box = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/utils/metadata/change/select-regions.ts
+/**
+* Select distinct positive-area boxes with deterministic area and coordinate ties.
+* @param boxes - Already scaled output rectangles; the input is not mutated.
+* @param limit - Nonnegative maximum number of regions.
+* @returns Largest boxes ordered by area descending, then y, x and width ascending.
+*/
+function selectRegions(boxes, limit) {
+	return (0, _winglet_common_utils.filter)(boxes, (box, index) => box.width > 0 && box.height > 0 && boxes.findIndex((other) => other.x === box.x && other.y === box.y && other.width === box.width && other.height === box.height) === index).sort((a, b) => b.width * b.height - a.width * a.height || a.y - b.y || a.x - b.x || a.width - b.width).slice(0, limit);
+}
+var init_select_regions = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/utils/metadata/change/build-frame-change.ts
+/**
+* Aggregate adjacent-pair evidence across one selected-frame span.
+* @param input - Ordered raw edges, one-based previous ID, skipped count and dimensions.
+* @returns Rounded raw scores, analysis-space union ratio and output-space regions.
+*/
+function buildFrameChange(input) {
+	const { spanEdges, fromFrameId, skippedCandidates, analysisResolution, outputResolution, regionLimit } = input;
+	const boxes = spanEdges.flatMap((edge) => edge.change?.regions ?? []);
+	const area = analysisResolution.width * analysisResolution.height;
+	const peakScore = spanEdges.reduce((peak, edge) => Math.max(peak, edge.score), 0);
+	const sumScore = spanEdges.reduce((sum, edge) => sum + edge.score, 0);
+	const areaRatio = area > 0 ? Math.max(0, Math.min(1, unionArea(boxes) / area)) : 0;
+	const regions = area > 0 ? selectRegions((0, _winglet_common_utils.map)(boxes, (box) => scaleBoundingBox(box, outputResolution.width / analysisResolution.width, outputResolution.height / analysisResolution.height, outputResolution.width, outputResolution.height)), regionLimit) : [];
+	return {
+		fromFrameId,
+		skippedCandidates,
+		peakScore: Math.round(peakScore * 1e6) / 1e6,
+		sumScore: Math.round(sumScore * 1e6) / 1e6,
+		areaRatio: Math.round(areaRatio * 1e4) / 1e4,
+		regions
+	};
+}
+var init_build_frame_change = __esmMin((() => {
+	init_scale_bounding_box();
+	init_select_regions();
+	init_union_area();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/build-frame-metadata.ts
+/**
+* Describe selected frames using candidate adjacency rather than synthetic pruning edges.
+* @param input - Chronological candidates and selections, raw graph and output dimensions.
+* @returns One-based frame summaries with rounded timestamps and nonnegative holds.
+*/
+function buildFrameMetadata(input) {
+	const { frames, graph, selected, originalDurationMs, analysisResolution, outputResolution } = input;
+	const edgesByPair = new Map((0, _winglet_common_utils.map)(graph, (edge) => [`${edge.sourceId}:${edge.targetId}`, edge]));
+	const candidateIndices = new Map((0, _winglet_common_utils.map)(frames, (frame, index) => [frame.id, index]));
+	const padding = Math.max(4, String(frames.length).length);
+	return (0, _winglet_common_utils.map)(selected, (frame, index) => {
+		const timestampMs = Math.round(frame.timestamp * 1e3);
+		const nextTimestampMs = index + 1 < selected.length ? Math.round(selected[index + 1].timestamp * 1e3) : originalDurationMs;
+		const previous = selected[index - 1];
+		const previousIndex = previous ? candidateIndices.get(previous.id) : 0;
+		const currentIndex = candidateIndices.get(frame.id);
+		const spanEdges = [];
+		if (previous) for (let i = previousIndex; i < currentIndex; i++) {
+			const edge = edgesByPair.get(`${frames[i].id}:${frames[i + 1].id}`);
+			if (edge) spanEdges.push(edge);
+		}
+		return {
+			step: index + 1,
+			fileName: `frame_${String(frame.id + 1).padStart(padding, "0")}.jpg`,
+			frameId: frame.id + 1,
+			timestampMs,
+			holdsMs: Math.max(0, nextTimestampMs - timestampMs),
+			change: previous ? buildFrameChange({
+				spanEdges,
+				fromFrameId: previous.id + 1,
+				skippedCandidates: currentIndex - previousIndex - 1,
+				analysisResolution,
+				outputResolution,
+				regionLimit: 5
+			}) : null
+		};
+	});
+}
+var init_build_frame_metadata = __esmMin((() => {
+	init_pipeline_defaults();
+	init_build_frame_change();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/build-tool-metadata.ts
+/**
+* Record the tool and the nine selection and encoding settings in contract order.
+* @param options - Validated pipeline settings; operational options are excluded.
+* @param version - Runtime package version supplied by the I/O boundary.
+* @returns Deterministic tool provenance without paths or execution details.
+*/
+function buildToolMetadata(options, version) {
+	return {
+		name: "@lumy-pack/scene-sieve",
+		version,
+		params: {
+			fps: options.fps,
+			count: options.count,
+			threshold: options.threshold,
+			scale: options.scale,
+			quality: options.quality,
+			maxFrames: options.maxFrames,
+			iouThreshold: options.iouThreshold,
+			animationThreshold: options.animationThreshold,
+			maxSegmentDuration: options.maxSegmentDuration
+		}
+	};
+}
+var init_build_tool_metadata = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/utils/metadata/build-sieve-metadata.ts
+/**
+* Assemble the complete v2 document without I/O or mutation.
+* @param input - Pipeline state, selections, output-space video and zero-based animations.
+* @returns Contract-ordered metadata, omitting unrequested optional keys entirely.
+*/
+function buildSieveMetadata(input) {
+	const { ctx, selected, video, animations, version, sheet } = input;
+	const analysisResolution = ctx.analysisResolution ?? {
+		width: 0,
+		height: 0
+	};
+	return {
+		metadataVersion: 2,
+		tool: buildToolMetadata(ctx.options, version),
+		video,
+		frames: buildFrameMetadata({
+			frames: ctx.frames,
+			graph: ctx.graph,
+			selected,
+			originalDurationMs: video.originalDurationMs,
+			analysisResolution,
+			outputResolution: video.resolution
+		}),
+		animations: (0, _winglet_common_utils.map)(animations, (animation) => ({
+			...animation,
+			startFrameId: animation.startFrameId + 1,
+			endFrameId: animation.endFrameId + 1,
+			durationMs: Math.round(animation.durationMs)
+		})),
+		...sheet ? { sheet } : {},
+		...ctx.options.includeEdges ? { edges: buildEdgeMetadata(ctx.graph, analysisResolution) } : {}
+	};
+}
+var init_build_sieve_metadata = __esmMin((() => {
+	init_pipeline_defaults();
+	init_build_edge_metadata();
+	init_build_frame_metadata();
+	init_build_tool_metadata();
+}));
+
+//#endregion
+//#region src/core/utils/metadata/build-video-metadata.ts
+/**
+* Read output dimensions and build consistent video and animation metadata.
+* JPEG finalization does not resize, so the source dimensions match the output.
+* @param ctx Pipeline state with source duration, effective FPS and analysis-space animations.
+* @param selected Selected frames in output order; the first candidate is the fallback.
+* @param analysisResolution Analysis dimensions; absent or zero dimensions imply no scaling.
+* @returns Video metadata and new output-space animations, retaining zero-based frame IDs.
+* @throws If sharp cannot read the selected or fallback image. Empty input performs no image I/O.
+*/
+async function buildVideoMetadata(ctx, selected, analysisResolution) {
+	const firstFrame = selected[0] ?? ctx.frames[0];
+	const dimensions = firstFrame ? await (0, sharp.default)(firstFrame.extractPath).metadata() : void 0;
+	const width = dimensions?.width ?? 0;
+	const height = dimensions?.height ?? 0;
+	const sx = analysisResolution?.width ? width / analysisResolution.width : 1;
+	const sy = analysisResolution?.height ? height / analysisResolution.height : 1;
+	const lastTimestamp = ctx.frames[ctx.frames.length - 1]?.timestamp ?? 0;
+	const duration = ctx.options.mode === "frames" ? lastTimestamp : ctx.sourceDurationSec ?? lastTimestamp;
+	return {
+		video: {
+			originalDurationMs: Math.round(duration * 1e3),
+			fps: ctx.options.mode === "frames" ? 1 : ctx.effectiveFps ?? ctx.options.fps,
+			resolution: {
+				width,
+				height
+			},
+			candidatesCount: ctx.frames.length,
+			selectedCount: selected.length,
+			source: {
+				fileName: ctx.options.mode === "file" && ctx.options.inputPath ? (0, node_path.basename)(ctx.options.inputPath) : null,
+				mode: ctx.options.mode
+			}
+		},
+		animations: (ctx.animations ?? []).map((animation) => ({
+			...animation,
+			boundingBox: scaleBoundingBox(animation.boundingBox, sx, sy, width, height)
+		}))
+	};
+}
+var init_build_video_metadata = __esmMin((() => {
+	init_scale_bounding_box();
+}));
+
+//#endregion
+//#region src/core/utils/sheet/build-tile-label-svg.ts
+/**
+* Build a tile-sized SVG overlay with a translucent badge and an explicit text baseline.
+* @param text - A formatTileLabel result containing only digits, #, spaces, colons and periods.
+* @param tileWidth - Positive tile canvas width in pixels.
+* @param tileHeight - Positive tile canvas height in pixels.
+* @returns Encoded SVG bytes for a top-left sharp composite overlay.
+*/
+function buildTileLabelSvg(text, tileWidth, tileHeight) {
+	const fontSize = Math.max(8, Math.round(tileHeight * SHEET_LABEL_HEIGHT_RATIO));
+	const padX = Math.round(fontSize * .4);
+	const padY = Math.round(fontSize * .2);
+	const badgeWidth = Math.min(tileWidth, Math.ceil(text.length * fontSize * .6) + 2 * padX);
+	return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${tileWidth}" height="${tileHeight}"><rect x="0" y="0" width="${badgeWidth}" height="${fontSize + 2 * padY}" fill="black" fill-opacity="0.5"/><text x="${padX}" y="${padY + Math.round(fontSize * .8)}" font-family="sans-serif" font-size="${fontSize}" fill="white">${text}</text></svg>`);
+}
+var init_build_tile_label_svg = __esmMin((() => {
+	init_pipeline_defaults();
+}));
+
+//#endregion
+//#region src/core/utils/sheet/format-tile-label.ts
+/**
+* Format a contact sheet label without rounding into the next tenth of a second.
+* @param frameId - One-based candidate frame ID.
+* @param timestampMs - Nonnegative candidate time in milliseconds.
+* @returns A label in the form "#<id> mm:ss.s", allowing minutes beyond two digits.
+*/
+function formatTileLabel(frameId, timestampMs) {
+	const tenths = Math.floor(timestampMs / 100);
+	return `#${frameId} ${String(Math.floor(tenths / 600)).padStart(2, "0")}:${String(Math.floor(tenths / 10) % 60).padStart(2, "0")}.${tenths % 10}`;
+}
+var init_format_tile_label = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/utils/sheet/sample-tile-frames.ts
+/**
+* Sample a sequence uniformly while always retaining both endpoints.
+* @param items - Items in temporal order.
+* @param maxTiles - Validated integer limit of at least two.
+* @returns The original sequence when within the limit, otherwise evenly sampled items.
+*/
+function sampleTileFrames(items, maxTiles) {
+	if (items.length <= maxTiles) return {
+		items,
+		sampled: false
+	};
+	return {
+		items: Array.from({ length: maxTiles }, (_, i) => items[Math.round(i * (items.length - 1) / (maxTiles - 1))]),
+		sampled: true
+	};
+}
+var init_sample_tile_frames = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/utils/sheet/render-contact-sheet.ts
+/**
+* Read selected frame images and render a row-major contact sheet.
+* @param input - Nonempty ordered selections, positive dimensions and validated sheet settings.
+* @returns JPEG bytes and the effective tile layout with one-based frame IDs.
+* @throws Propagates sharp image reading, compositing or encoding errors.
+*/
+async function renderContactSheet(input) {
+	const { selected, resolution, options, quality } = input;
+	const { items, sampled } = sampleTileFrames(selected, options.maxTiles);
+	const columns = Math.min(options.columns, items.length);
+	const rows = Math.ceil(items.length / columns);
+	const tileWidth = options.tileWidth;
+	const tileHeight = Math.max(1, Math.round(tileWidth * resolution.height / resolution.width));
+	const gap = 4;
+	const tiles = await Promise.all((0, _winglet_common_utils.map)(items, async (frame, index) => {
+		const tile = (0, sharp.default)(frame.extractPath).resize(tileWidth, tileHeight, { fit: "fill" });
+		if (options.label) {
+			const text = formatTileLabel(frame.id + 1, Math.round(frame.timestamp * 1e3));
+			tile.composite([{
+				input: buildTileLabelSvg(text, tileWidth, tileHeight),
+				top: 0,
+				left: 0
+			}]);
+		}
+		return {
+			input: await tile.png().toBuffer(),
+			top: gap + Math.floor(index / columns) * (tileHeight + gap),
+			left: gap + index % columns * (tileWidth + gap)
+		};
+	}));
+	return {
+		buffer: await (0, sharp.default)({ create: {
+			width: columns * tileWidth + (columns + 1) * gap,
+			height: rows * tileHeight + (rows + 1) * gap,
+			channels: 3,
+			background: "white"
+		} }).composite(tiles).jpeg({
+			quality,
+			mozjpeg: true
+		}).toBuffer(),
+		metadata: {
+			fileName: SHEET_FILE_NAME,
+			columns,
+			tileWidth,
+			tileHeight,
+			frameIds: (0, _winglet_common_utils.map)(items, (frame) => frame.id + 1),
+			sampled
+		}
+	};
+}
+var init_render_contact_sheet = __esmMin((() => {
+	init_pipeline_defaults();
+	init_build_tile_label_svg();
+	init_format_tile_label();
+	init_sample_tile_frames();
+}));
+
+//#endregion
+//#region src/core/utils/output/finalize-selection.ts
+/**
+* Read output dimensions once, render optional sheets and finalize the shared v2 document.
+* @param ctx - Pipeline state owned by the orchestrator; this function does not mutate it.
+* @param selected - Selected frames in temporal order.
+* @returns Mode-specific output, the document and zero-based API animations.
+* @throws Propagates image, rendering and output I/O errors to the orchestrator.
+*/
+async function finalizeSelection(ctx, selected) {
+	const { video, animations } = await buildVideoMetadata(ctx, selected, ctx.analysisResolution);
+	const sheet = ctx.options.sheet && selected.length > 0 && video.resolution.width > 0 && video.resolution.height > 0 ? await renderContactSheet({
+		selected,
+		resolution: video.resolution,
+		options: ctx.options.sheet,
+		quality: ctx.options.quality
+	}) : void 0;
+	const document = buildSieveMetadata({
+		ctx,
+		selected,
+		video,
+		animations,
+		version: PACKAGE_VERSION,
+		...sheet ? { sheet: sheet.metadata } : {}
+	});
+	if (ctx.options.mode === "file") return {
+		outputFiles: await finalizeOutput(ctx, selected, document, sheet?.buffer),
+		document,
+		animations
+	};
+	return {
+		outputFiles: [],
+		outputBuffers: await readFramesAsBuffers(selected, ctx.options.quality),
+		document,
+		animations,
+		...sheet ? { sheetBuffer: sheet.buffer } : {}
+	};
 }
+var init_finalize_selection = __esmMin((() => {
+	init_package_version();
+	init_workspace();
+	init_build_sieve_metadata();
+	init_build_video_metadata();
+	init_render_contact_sheet();
+}));
 
 //#endregion
-//#region src/core/extractor.ts
+//#region src/core/extractor/extractor.ts
 /**
 * Extract frames from video/GIF using FFmpeg.
-* Always uses FPS-based extraction. For long videos, FPS is automatically
-* reduced to stay within maxFrames budget.
+* @param ctx Pipeline context; records effectiveFps and sourceDurationSec for video input.
+* @returns Extracted candidates, or the unchanged input array in frames mode.
+* @throws When the input is missing, metadata has no video stream, or FFmpeg fails.
 */
 async function extractFrames(ctx) {
+	if (ctx.options.mode === "frames") {
+		ctx.effectiveFps = 1;
+		return ctx.frames;
+	}
 	const framesDir = (0, node_path.join)(ctx.workspacePath, "frames");
 	const { inputPath, fps, maxFrames, scale } = ctx.options;
 	if (!inputPath) throw new Error("inputPath is required for frame extraction");
@@ -571,19 +1369,30 @@ async function extractFrames(ctx) {
 	if (!(metadata.streams?.some((s) => s.codec_type === "video") ?? false)) throw new Error(`No video stream found in file: ${inputPath} (detected format: ${formatName})`);
 	logger.debug(`Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`);
 	await ensureDir(framesDir);
+	const frameLimit = Math.max(2, maxFrames);
 	let effectiveFps = fps;
 	if (duration > 0) {
-		const fpsCap = maxFrames / duration;
+		const fpsCap = frameLimit / duration;
 		effectiveFps = Math.min(fps, fpsCap);
-		effectiveFps = Math.max(.5, effectiveFps);
 		logger.debug(`FPS: ${fps} → effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`);
 	}
-	const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale, duration);
+	ctx.effectiveFps = effectiveFps;
+	ctx.sourceDurationSec = duration;
+	const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale, frameLimit);
 	ctx.emitProgress(100);
 	logger.debug(`Extracted ${frames.length} frames`);
 	return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale, duration) {
+/**
+* Write scaled JPEG candidates through the bundled FFmpeg runtime.
+* @param inputPath Readable video input.
+* @param outputDir Existing frame directory.
+* @param fps Positive effective sampling frequency.
+* @param scale Output image height.
+* @param frameLimit Maximum number of output frames.
+* @returns Candidates with local output-grid timestamps; rejects on extraction failure.
+*/
+async function extractByFps(inputPath, outputDir, fps, scale, frameLimit) {
 	const outputPattern = (0, node_path.join)(outputDir, FRAME_FILENAME_PATTERN);
 	await (0, execa.execa)(ffmpeg_static.default, [
 		"-i",
@@ -592,9 +1401,11 @@ async function extractByFps(inputPath, outputDir, fps, scale, duration) {
 		`fps=${fps},scale=-1:${scale}`,
 		"-q:v",
 		"2",
+		"-frames:v",
+		String(frameLimit),
 		outputPattern
 	]);
-	return buildFrameList(outputDir, duration);
+	return buildFrameList(outputDir, fps);
 }
 async function getVideoMetadata(inputPath) {
 	const { stdout } = await (0, execa.execa)(_ffprobe_installer_ffprobe.path, [
@@ -608,12 +1419,19 @@ async function getVideoMetadata(inputPath) {
 	]);
 	return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, duration) {
-	const jpgFiles = (0, _winglet_common_utils.filter)(await (0, node_fs_promises.readdir)(framesDir), (f) => f.endsWith(".jpg")).sort();
+/**
+* Read sorted JPEG paths and attach local output-grid times.
+* @param framesDir Extracted frame directory; filesystem errors propagate.
+* @param effectiveFps Positive frequency used by the fps filter.
+* @returns Zero-based candidates without a segment seek offset.
+*/
+async function buildFrameList(framesDir, effectiveFps) {
+	const files = await (0, node_fs_promises.readdir)(framesDir);
+	const jpgFiles = (0, _winglet_common_utils.filter)(files, (f) => f.endsWith(".jpg")).sort();
 	if (jpgFiles.length === 0) return [];
 	return (0, _winglet_common_utils.map)(jpgFiles, (file, index) => ({
 		id: index,
-		timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
+		timestamp: index / effectiveFps,
 		extractPath: (0, node_path.join)(framesDir, file)
 	}));
 }
@@ -627,9 +1445,10 @@ async function buildFrameList(framesDir, duration) {
 * @param scale - Height scale for vision analysis
 * @param startTime - Start time in seconds
 * @param duration - Duration in seconds to extract
+* @param frameLimit - Positive output limit; defaults to the range's grid capacity
 * @returns Array of FrameNode with segment-local timestamps (starting from 0)
 */
-async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration) {
+async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration, frameLimit = Math.ceil(duration * fps)) {
 	const outputPattern = (0, node_path.join)(outputDir, FRAME_FILENAME_PATTERN);
 	await (0, execa.execa)(ffmpeg_static.default, [
 		"-ss",
@@ -642,139 +1461,157 @@ async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime
 		`fps=${fps},scale=-1:${scale}`,
 		"-q:v",
 		"2",
+		"-frames:v",
+		String(frameLimit),
 		outputPattern
 	]);
-	return buildFrameList(outputDir, duration);
+	return buildFrameList(outputDir, fps);
 }
+var init_extractor$1 = __esmMin((() => {
+	init_workspace_layout();
+	init_logger();
+	init_paths();
+}));
 
 //#endregion
-//#region src/core/workspace.ts
-async function createWorkspace(sessionId) {
-	const workspacePath = getTempWorkspaceDir(sessionId);
-	await ensureDir((0, node_path.join)(workspacePath, "frames"));
-	await ensureDir((0, node_path.join)(workspacePath, "output"));
-	return workspacePath;
-}
-async function finalizeOutput(ctx, selectedFrames) {
-	const stagingDir = (0, node_path.join)(ctx.workspacePath, "output");
-	const outputPath = ctx.options.outputPath;
-	const quality = ctx.options.quality;
-	const outputFiles = [];
-	const framesMetadata = [];
-	const totalFramesCount = ctx.frames.length;
-	const padding = Math.max(4, String(totalFramesCount).length);
-	for (let i = 0; i < selectedFrames.length; i++) {
-		const frame = selectedFrames[i];
-		const fileName = `frame_${String(frame.id + 1).padStart(padding, "0")}.jpg`;
-		const destPath = (0, node_path.join)(stagingDir, fileName);
-		await (0, sharp.default)(frame.extractPath).jpeg({
-			quality,
-			mozjpeg: true
-		}).toFile(destPath);
-		outputFiles.push((0, node_path.join)(outputPath, fileName));
-		framesMetadata.push({
-			step: i + 1,
-			fileName,
-			frameId: frame.id + 1,
-			timestampMs: Math.round(frame.timestamp * 1e3)
-		});
-	}
-	const metadata = {
-		video: {
-			originalDurationMs: Math.round((ctx.frames.length > 0 ? ctx.frames[ctx.frames.length - 1].timestamp : 0) * 1e3),
-			fps: ctx.options.fps,
-			resolution: {
-				width: ctx.options.scale,
-				height: Math.round(ctx.options.scale * 9 / 16)
-			}
-		},
-		frames: framesMetadata,
-		animations: (0, _winglet_common_utils.map)(ctx.animations || [], (anim) => ({
-			...anim,
-			startFrameId: anim.startFrameId + 1,
-			endFrameId: anim.endFrameId + 1,
-			durationMs: Math.round(anim.durationMs)
-		}))
-	};
-	await (0, node_fs_promises.writeFile)((0, node_path.join)(stagingDir, ".metadata.json"), JSON.stringify(metadata, null, 2));
-	outputFiles.push((0, node_path.join)(outputPath, ".metadata.json"));
-	await ensureDir((0, node_path.join)(outputPath, ".."));
-	await (0, node_fs_promises.rm)(outputPath, {
-		recursive: true,
-		force: true
-	});
-	await (0, node_fs_promises.rename)(stagingDir, outputPath);
-	return outputFiles;
-}
-async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
-	const segmentPath = (0, node_path.join)(parentWorkspacePath, "segments", String(segmentIndex));
-	await ensureDir((0, node_path.join)(segmentPath, "frames"));
-	return segmentPath;
-}
-async function cleanupWorkspace(workspacePath) {
-	if (!workspacePath) return;
-	try {
-		await (0, node_fs_promises.rm)(workspacePath, {
-			recursive: true,
-			force: true
-		});
-	} catch {}
-}
-/**
-* Write a video buffer to a temp file in the workspace and return the path.
-* Used by 'buffer' input mode.
-*/
-async function writeInputBuffer(buffer, workspacePath) {
-	const inputDir = (0, node_path.join)(workspacePath, "input");
-	await ensureDir(inputDir);
-	const tempPath = (0, node_path.join)(inputDir, "input.mp4");
-	await (0, node_fs_promises.writeFile)(tempPath, buffer);
-	return tempPath;
-}
+//#region src/core/extractor/index.ts
+var init_extractor = __esmMin((() => {
+	init_extractor$1();
+}));
+
+//#endregion
+//#region src/core/input-resolver/validation/validate-options.ts
 /**
-* Write an array of frame Buffers as JPG files and return FrameNode[].
-* Used by 'frames' input mode.
+* Reject invalid numeric options before defaults or pipeline effects are applied.
+* @param options - Supplied options; omitted numeric fields use pipeline defaults.
+* @returns Nothing when all supplied numeric fields satisfy their contracts.
+* @throws An input error naming the invalid option and its received value.
 */
-async function writeInputFrames(frames, workspacePath) {
-	const framesDir = (0, node_path.join)(workspacePath, "frames");
-	await ensureDir(framesDir);
-	const frameNodes = [];
-	for (let i = 0; i < frames.length; i++) {
-		const extractPath = (0, node_path.join)(framesDir, `frame_${String(i).padStart(6, "0")}${FRAME_OUTPUT_EXTENSION}`);
-		await (0, node_fs_promises.writeFile)(extractPath, frames[i]);
-		frameNodes.push({
-			id: i,
-			timestamp: i,
-			extractPath
-		});
+function validateOptions(options) {
+	for (const [name, min, max, integer, exclusiveMin, requirement] of [
+		[
+			"count",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		],
+		[
+			"threshold",
+			0,
+			1,
+			false,
+			true,
+			"in range (0, 1] and finite"
+		],
+		[
+			"fps",
+			0,
+			Infinity,
+			false,
+			true,
+			"finite and > 0"
+		],
+		[
+			"maxFrames",
+			2,
+			Infinity,
+			true,
+			false,
+			"an integer >= 2"
+		],
+		[
+			"scale",
+			16,
+			Infinity,
+			true,
+			false,
+			"an integer >= 16"
+		],
+		[
+			"quality",
+			1,
+			100,
+			true,
+			false,
+			"an integer in range [1, 100]"
+		],
+		[
+			"iouThreshold",
+			0,
+			1,
+			false,
+			false,
+			"finite and in range [0, 1]"
+		],
+		[
+			"animationThreshold",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		],
+		[
+			"maxSegmentDuration",
+			0,
+			Infinity,
+			false,
+			true,
+			"finite and > 0"
+		],
+		[
+			"concurrency",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		]
+	]) {
+		const value = options[name];
+		if (value === void 0) continue;
+		if (!Number.isFinite(value) || integer && !Number.isInteger(value) || (exclusiveMin ? value <= min : value < min) || value > max) throw new Error(`${name} must be ${requirement}, received: ${value}`);
 	}
-	return frameNodes;
-}
-/**
-* Read selected FrameNode files as Buffers with JPEG compression.
-* Used to return output buffers in 'buffer' and 'frames' modes.
-*/
-async function readFramesAsBuffers(frameNodes, quality) {
-	return Promise.all((0, _winglet_common_utils.map)(frameNodes, (f) => (0, sharp.default)(f.extractPath).jpeg({
-		quality,
-		mozjpeg: true
-	}).toBuffer()));
+	const sheet = options.sheet;
+	if (sheet === void 0 || typeof sheet === "boolean") return;
+	if (sheet === null || typeof sheet !== "object" || Array.isArray(sheet)) throw new Error(`sheet must be a boolean or an object, received: ${Array.isArray(sheet) ? "array" : String(sheet)}`);
+	for (const [name, min] of [
+		["columns", 1],
+		["tileWidth", 16],
+		["maxTiles", 2]
+	]) {
+		const value = sheet[name];
+		if (value === void 0) continue;
+		if (!Number.isInteger(value) || value < min) throw new Error(`sheet.${name} must be an integer >= ${min}, received: ${value}`);
+	}
+	if (sheet.label !== void 0 && typeof sheet.label !== "boolean") throw new Error(`sheet.label must be a boolean, received: ${sheet.label}`);
 }
+var init_validate_options = __esmMin((() => {}));
 
 //#endregion
-//#region src/core/input-resolver.ts
+//#region src/core/input-resolver/input-resolver.ts
+/**
+* Validate supplied options and resolve defaults and paths for the pipeline.
+* @param options - Mode-specific input and optional numeric settings.
+* @returns Complete pipeline settings with absolute file input paths.
+* @throws An input error if a supplied numeric setting is invalid.
+*/
 function resolveOptions(options) {
+	validateOptions(options);
 	const mode = options.mode;
 	const inputPath = mode === "file" ? resolveAbsolute(options.inputPath) : void 0;
 	const outputPath = options.outputPath ?? (inputPath ? deriveOutputPath(inputPath) : (0, node_path.join)(process.cwd(), "scene-sieve-output"));
 	const threshold = options.threshold ?? .5;
-	if (threshold <= 0 || threshold > 1) throw new Error(`threshold must be in range (0, 1], received: ${threshold}`);
+	const pruneMode = "threshold-with-cap";
+	const sheet = typeof options.sheet === "object" ? options.sheet : {};
 	return {
 		mode,
 		inputPath,
 		count: options.count ?? 20,
 		threshold,
-		pruneMode: "threshold-with-cap",
+		pruneMode,
 		outputPath,
 		fps: options.fps ?? 5,
 		maxFrames: options.maxFrames ?? 300,
@@ -784,7 +1621,14 @@ function resolveOptions(options) {
 		animationThreshold: options.animationThreshold ?? 5,
 		debug: options.debug ?? false,
 		maxSegmentDuration: options.maxSegmentDuration ?? 300,
-		concurrency: options.concurrency ?? 2
+		concurrency: options.concurrency ?? 2,
+		sheet: options.sheet ? {
+			columns: sheet.columns ?? 4,
+			tileWidth: sheet.tileWidth ?? 320,
+			maxTiles: sheet.maxTiles ?? 40,
+			label: sheet.label ?? true
+		} : null,
+		includeEdges: options.includeEdges ?? false
 	};
 }
 /**
@@ -793,6 +1637,10 @@ function resolveOptions(options) {
 * - 'file'   mode: validate file exists and delegate to extractor (caller's responsibility)
 * - 'buffer' mode: write buffer as temp video file, return path via FrameNode trick (empty list)
 * - 'frames' mode: write frame buffers as JPGs, return FrameNode[]
+* @param options - Input source; encoded frames must have matching dimensions.
+* @param workspacePath - Workspace receiving temporary input files.
+* @returns Frame nodes or a resolved video path for extraction.
+* @throws Propagates metadata or write errors and rejects mismatched frame sizes.
 */
 async function resolveInput(options, workspacePath) {
 	if (options.mode === "file") return {
@@ -803,12 +1651,51 @@ async function resolveInput(options, workspacePath) {
 		frames: [],
 		resolvedInputPath: await writeInputBuffer(options.inputBuffer, workspacePath)
 	};
-	if (options.mode === "frames") return { frames: await writeInputFrames(options.inputFrames, workspacePath) };
+	if (options.mode === "frames") {
+		let dimensions;
+		for (const buffer of options.inputFrames) {
+			const { width, height } = await (0, sharp.default)(buffer).metadata();
+			if (dimensions && (width !== dimensions.width || height !== dimensions.height)) throw new Error(`inputFrames must be the same size (${dimensions.width}x${dimensions.height}), received: ${width}x${height}`);
+			dimensions = {
+				width,
+				height
+			};
+		}
+		return { frames: await writeInputFrames(options.inputFrames, workspacePath) };
+	}
 	throw new Error(`Unsupported input mode: ${options.mode}`);
 }
+var init_input_resolver$1 = __esmMin((() => {
+	init_pipeline_defaults();
+	init_paths();
+	init_validate_options();
+	init_workspace();
+}));
+
+//#endregion
+//#region src/core/input-resolver/index.ts
+var init_input_resolver = __esmMin((() => {
+	init_input_resolver$1();
+}));
 
 //#endregion
-//#region src/utils/math.ts
+//#region src/core/pruner/scoring/normalize-scores.ts
+/**
+* Find the first position whose score is at least the requested value.
+* @param sorted - Finite positive scores sorted in ascending order.
+* @param value - A finite positive score present in sorted.
+* @returns The first matching rank, including the first position of any tie.
+*/
+function lowerBound(sorted, value) {
+	let low = 0;
+	let high = sorted.length;
+	while (low < high) {
+		const mid = Math.floor((low + high) / 2);
+		if (sorted[mid] < value) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
 /**
 * Normalize raw scores to [0, 1] range via Robust Hybrid Normalization.
 *
@@ -853,64 +1740,67 @@ function normalizeScores(items) {
 	});
 	const cdf = (0, _winglet_common_utils.map)(safeScores, (s) => {
 		if (s <= 0) return 0;
-		return sorted.findIndex((v) => v >= s) / sorted.length;
+		return lowerBound(sorted, s) / sorted.length;
 	});
-	return (0, _winglet_common_utils.map)(logisticZ, (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA);
+	return (0, _winglet_common_utils.map)(logisticZ, (z, i) => z * .6 + cdf[i] * NORMALIZATION_ALPHA);
 }
+var NORMALIZATION_ALPHA, NORMALIZATION_MAD_COEFFICIENT, NORMALIZATION_MIN_SAMPLE_SIZE;
+var init_normalize_scores = __esmMin((() => {
+	NORMALIZATION_ALPHA = .4;
+	NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+	NORMALIZATION_MIN_SAMPLE_SIZE = 10;
+}));
 
 //#endregion
-//#region src/utils/min-heap.ts
-/**
-* Generic binary min-heap.
-*
-* Elements are ordered by a numeric `score` field.
-* push/pop: O(log N), size: O(1).
-*/
-var MinHeap = class {
-	h = [];
-	get size() {
-		return this.h.length;
-	}
-	push(entry) {
-		this.h.push(entry);
-		this.siftUp(this.h.length - 1);
-	}
-	pop() {
-		const n = this.h.length;
-		if (n === 0) return void 0;
-		const top = this.h[0];
-		const last = this.h.pop();
-		if (n > 1) {
-			this.h[0] = last;
-			this.siftDown(0);
+//#region src/core/pruner/heap/min-heap.ts
+var MinHeap;
+var init_min_heap = __esmMin((() => {
+	MinHeap = class {
+		h = [];
+		get size() {
+			return this.h.length;
 		}
-		return top;
-	}
-	siftUp(i) {
-		while (i > 0) {
-			const p = i - 1 >> 1;
-			if (this.h[p].score <= this.h[i].score) break;
-			[this.h[p], this.h[i]] = [this.h[i], this.h[p]];
-			i = p;
+		push(entry) {
+			this.h.push(entry);
+			this.siftUp(this.h.length - 1);
 		}
-	}
-	siftDown(i) {
-		const n = this.h.length;
-		for (;;) {
-			let m = i;
-			const l = 2 * i + 1;
-			const r = 2 * i + 2;
-			if (l < n && this.h[l].score < this.h[m].score) m = l;
-			if (r < n && this.h[r].score < this.h[m].score) m = r;
-			if (m === i) break;
-			[this.h[m], this.h[i]] = [this.h[i], this.h[m]];
-			i = m;
+		pop() {
+			const n = this.h.length;
+			if (n === 0) return void 0;
+			const top = this.h[0];
+			const last = this.h.pop();
+			if (n > 1) {
+				this.h[0] = last;
+				this.siftDown(0);
+			}
+			return top;
 		}
-	}
-};
+		siftUp(i) {
+			while (i > 0) {
+				const p = i - 1 >> 1;
+				if (this.h[p].score <= this.h[i].score) break;
+				[this.h[p], this.h[i]] = [this.h[i], this.h[p]];
+				i = p;
+			}
+		}
+		siftDown(i) {
+			const n = this.h.length;
+			for (;;) {
+				let m = i;
+				const l = 2 * i + 1;
+				const r = 2 * i + 2;
+				if (l < n && this.h[l].score < this.h[m].score) m = l;
+				if (r < n && this.h[r].score < this.h[m].score) m = r;
+				if (m === i) break;
+				[this.h[m], this.h[i]] = [this.h[i], this.h[m]];
+				i = m;
+			}
+		}
+	};
+}));
 
 //#endregion
-//#region src/core/pruner.ts
+//#region src/core/pruner/pruner.ts
 /**
 * Edge-aware greedy merge with re-linking — O(N log N).
 *
@@ -1024,7 +1914,7 @@ function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
 	return result;
 }
 /**
-* Threshold-based pruning with NMS -- O(N).
+* Threshold-based pruning with NMS -- including normalization, O(N log N).
 *
 * 1. Scores are normalized to [0, 1] via percentile normalization.
 * 2. Edges with normalized score >= threshold are collected.
@@ -1087,9 +1977,19 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 	}
 	return pruneTo(syntheticEdges, survivingFrames, maxCount);
 }
+var init_pruner$1 = __esmMin((() => {
+	init_normalize_scores();
+	init_min_heap();
+}));
 
 //#endregion
-//#region src/utils/concurrency.ts
+//#region src/core/pruner/index.ts
+var init_pruner = __esmMin((() => {
+	init_pruner$1();
+}));
+
+//#endregion
+//#region src/core/segmenter/scheduling/concurrency.ts
 /**
 * Creates a concurrency limiter that runs at most `limit` tasks in parallel.
 * Lightweight replacement for p-limit to avoid external dependency.
@@ -1109,9 +2009,10 @@ function concurrencyLimit(limit) {
 		}
 	};
 }
+var init_concurrency = __esmMin((() => {}));
 
 //#endregion
-//#region src/core/segmenter.ts
+//#region src/core/segmenter/segmenter.ts
 /**
 * Determine whether segmentation should be used.
 * Returns false for frames mode and GIF files.
@@ -1125,53 +2026,62 @@ function shouldSegment(resolvedOptions, originalOptions) {
 	return true;
 }
 /**
-* Compute segment boundaries with overlap, frame allocation, and effectiveFps.
-* Pure function — no I/O.
-*
-* - effectiveFps is uniform across all segments
-* - Overlap: 1 frame at each internal boundary
-* - allocatedFrames total <= maxFrames (last segment adjusted if needed)
+* Partition the global extraction grid into nonempty logical segments.
+* @param totalDuration Positive source duration in seconds.
+* @param maxSegmentDuration Positive logical segment width in seconds.
+* @param maxFrames Candidate budget, defensively raised to at least two.
+* @param fps Positive requested sampling frequency.
+* @returns Contiguous plan indices with grid-aligned seeks and overlap-inclusive limits.
 */
 function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
-	const effectiveFps = Math.max(.5, Math.min(fps, maxFrames / totalDuration));
+	const frameLimit = Math.max(2, maxFrames);
+	const effectiveFps = Math.min(fps, frameLimit / totalDuration);
 	if (totalDuration <= maxSegmentDuration) return [{
 		index: 0,
 		startTime: 0,
 		endTime: totalDuration,
 		duration: totalDuration,
-		allocatedFrames: Math.min(Math.ceil(effectiveFps * totalDuration), maxFrames),
+		allocatedFrames: frameLimit,
 		effectiveFps,
 		overlapBefore: 0,
 		overlapAfter: 0,
 		extractStartTime: 0,
 		extractDuration: totalDuration
 	}];
-	const segmentCount = Math.ceil(totalDuration / maxSegmentDuration);
-	const overlapTime = 1 / effectiveFps;
 	const segments = [];
-	for (let i = 0; i < segmentCount; i++) {
-		const startTime = i * maxSegmentDuration;
-		const endTime = Math.min((i + 1) * maxSegmentDuration, totalDuration);
-		const duration = endTime - startTime;
-		const overlapBefore = i > 0 ? 1 : 0;
-		const overlapAfter = i < segmentCount - 1 ? 1 : 0;
-		const extractStartTime = Math.max(0, startTime - overlapBefore * overlapTime);
-		const extractDuration = Math.min(totalDuration, endTime + overlapAfter * overlapTime) - extractStartTime;
+	for (let slot = 0; slot < frameLimit; slot++) {
+		const timestamp = slot / effectiveFps;
+		if (timestamp >= totalDuration) break;
+		const startTime = Math.floor(timestamp / maxSegmentDuration) * maxSegmentDuration;
+		const previous = segments[segments.length - 1];
+		if (previous?.startTime === startTime) {
+			previous.allocatedFrames++;
+			continue;
+		}
+		const endTime = Math.min(startTime + maxSegmentDuration, totalDuration);
 		segments.push({
-			index: i,
+			index: segments.length,
 			startTime,
 			endTime,
-			duration,
-			allocatedFrames: Math.ceil(effectiveFps * duration),
+			duration: endTime - startTime,
+			allocatedFrames: 1,
 			effectiveFps,
-			overlapBefore,
-			overlapAfter,
-			extractStartTime,
-			extractDuration
+			overlapBefore: 0,
+			overlapAfter: 0,
+			extractStartTime: timestamp,
+			extractDuration: 0
 		});
 	}
-	const totalAllocated = segments.reduce((sum, s) => sum + s.allocatedFrames, 0);
-	if (totalAllocated > maxFrames) segments[segments.length - 1].allocatedFrames -= totalAllocated - maxFrames;
+	let firstSlot = 0;
+	for (const segment of segments) {
+		const nextSlot = firstSlot + segment.allocatedFrames;
+		segment.overlapBefore = segment.index > 0 ? 1 : 0;
+		segment.overlapAfter = segment.index < segments.length - 1 ? 1 : 0;
+		segment.extractStartTime = (firstSlot - segment.overlapBefore) / effectiveFps;
+		segment.extractDuration = (segment.overlapAfter ? Math.min(totalDuration, (nextSlot + 1) / effectiveFps) : totalDuration) - segment.extractStartTime;
+		segment.allocatedFrames += segment.overlapBefore + segment.overlapAfter;
+		firstSlot = nextSlot;
+	}
 	return segments;
 }
 /**
@@ -1190,44 +2100,58 @@ function collectAllFrames(segmentResults) {
 	return allFrames;
 }
 /**
-* Sort frames by timestamp then remove overlap duplicates.
-* Threshold: 1/(effectiveFps * 2) — adaptive to fps (Section 18 note 5).
-* Keeps the first occurrence (earlier segment).
+* Sort frames in place and alias overlap duplicates to the first survivor.
+* @param frames Collected entries whose segment index and local ID identify a frame.
+* @param effectiveFps Positive sampling frequency; half a frame interval is the threshold.
+* @returns Timestamp-ordered survivors and duplicate keys pointing directly to survivor keys.
 */
 function deduplicateFrames(frames, effectiveFps) {
 	frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
 	const dupThreshold = 1 / (effectiveFps * 2);
 	const unique = [];
+	const aliases = /* @__PURE__ */ new Map();
 	for (const entry of frames) {
 		if (unique.length > 0) {
 			const last = unique[unique.length - 1];
-			if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) continue;
+			if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
+				aliases.set(`${entry.segmentIndex}:${entry.localId}`, `${last.segmentIndex}:${last.localId}`);
+				continue;
+			}
 		}
 		unique.push(entry);
 	}
-	return unique;
+	return {
+		unique,
+		aliases
+	};
 }
 /**
-* Assign sequential global IDs to deduplicated frames and build a lookup map.
-* Returns the remapped FrameNode array and the "segmentIndex:localId" -> globalId map.
+* Assign sequential global IDs and retain duplicate local IDs as aliases.
+* @param uniqueFrames Timestamp-ordered survivors with distinct segment/local keys.
+* @param aliases Duplicate keys pointing directly to keys in uniqueFrames.
+* @returns Remapped frames and a global ID lookup covering survivors and duplicates.
 */
-function remapFrameIds(uniqueFrames) {
+function remapFrameIds(uniqueFrames, aliases) {
 	const globalIdMap = /* @__PURE__ */ new Map();
+	const frames = uniqueFrames.map((entry, globalId) => {
+		globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
+		return {
+			id: globalId,
+			timestamp: entry.frame.timestamp,
+			extractPath: entry.frame.extractPath
+		};
+	});
+	for (const [alias, survivor] of aliases) globalIdMap.set(alias, globalIdMap.get(survivor));
 	return {
-		frames: uniqueFrames.map((entry, globalId) => {
-			globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
-			return {
-				id: globalId,
-				timestamp: entry.frame.timestamp,
-				extractPath: entry.frame.extractPath
-			};
-		}),
+		frames,
 		globalIdMap
 	};
 }
 /**
-* Remap edge source/target IDs using the global ID map.
-* Duplicate edges (same source-target pair) retain the higher score.
+* Remap edges, dropping missing endpoints and self loops while keeping the highest pair score.
+* @param segmentResults Segment-local edges in encounter order.
+* @param globalIdMap Survivor and duplicate local keys mapped to global IDs.
+* @returns One edge per surviving directed pair without changing its score.
 */
 function remapEdges(segmentResults, globalIdMap) {
 	const edges = [];
@@ -1236,62 +2160,73 @@ function remapEdges(segmentResults, globalIdMap) {
 		const newSourceId = globalIdMap.get(`${result.segment.index}:${edge.sourceId}`);
 		const newTargetId = globalIdMap.get(`${result.segment.index}:${edge.targetId}`);
 		if (newSourceId === void 0 || newTargetId === void 0) continue;
+		if (newSourceId === newTargetId) continue;
 		const edgeKey = `${newSourceId}-${newTargetId}`;
 		const existingIdx = edgeMap.get(edgeKey);
 		if (existingIdx !== void 0) {
 			if (edges[existingIdx].score < edge.score) edges[existingIdx] = {
+				...edge,
 				sourceId: newSourceId,
-				targetId: newTargetId,
-				score: edge.score
+				targetId: newTargetId
 			};
 		} else {
 			edgeMap.set(edgeKey, edges.length);
 			edges.push({
+				...edge,
 				sourceId: newSourceId,
-				targetId: newTargetId,
-				score: edge.score
+				targetId: newTargetId
 			});
 		}
 	}
 	return edges;
 }
 /**
-* Remap animation startFrameId/endFrameId using the global ID map.
-* Animations whose frame IDs were deduplicated (not in map) are dropped.
+* Remap animations, dropping missing or collapsed endpoints and retaining the first pair entry.
+* @param segmentResults Segment-local tracker entries in encounter order.
+* @param globalIdMap Survivor and duplicate local keys mapped to global IDs.
+* @returns One animation per directed pair with its original tracker duration and metadata.
 */
 function remapAnimations(segmentResults, globalIdMap) {
-	const animations = [];
+	const animations = /* @__PURE__ */ new Map();
 	for (const result of segmentResults) for (const anim of result.animations) {
 		const newStartId = globalIdMap.get(`${result.segment.index}:${anim.startFrameId}`);
 		const newEndId = globalIdMap.get(`${result.segment.index}:${anim.endFrameId}`);
 		if (newStartId === void 0 || newEndId === void 0) continue;
-		animations.push({
+		if (newStartId === newEndId) continue;
+		const animationKey = `${newStartId}-${newEndId}`;
+		if (animations.has(animationKey)) continue;
+		animations.set(animationKey, {
 			...anim,
 			startFrameId: newStartId,
 			endFrameId: newEndId
 		});
 	}
-	return animations;
+	return [...animations.values()];
 }
 /**
 * Merge multiple segment results into a single unified frame/edge/animation set.
-* - Timestamps adjusted using extractStartTime (Section 18 note 1)
-* - Overlap frames deduplicated by threshold 1/(effectiveFps*2) (Section 18 note 5)
-* - Global IDs reassigned after dedup
-* - Duplicate edges keep higher score
+* @param segmentResults Local frames, edges and tracker entries with distinct segment indices.
+* @returns Global timestamp-ordered frames, aliased edges and animations without self loops.
+* Duplicate edges keep the higher score; duplicate animations keep the first tracker entry.
 */
 function mergeSegmentFrames(segmentResults) {
 	if (segmentResults.length === 0) return {
 		frames: [],
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
 	const effectiveFps = segmentResults[0].segment.effectiveFps;
-	const { frames, globalIdMap } = remapFrameIds(deduplicateFrames(collectAllFrames(segmentResults), effectiveFps));
+	const { unique, aliases } = deduplicateFrames(collectAllFrames(segmentResults), effectiveFps);
+	const { frames, globalIdMap } = remapFrameIds(unique, aliases);
 	return {
 		frames,
 		edges: remapEdges(segmentResults, globalIdMap),
-		animations: remapAnimations(segmentResults, globalIdMap)
+		animations: remapAnimations(segmentResults, globalIdMap),
+		analysisResolution: segmentResults[0].analysisResolution
 	};
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {
@@ -1302,6 +2237,7 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 			maxFrames: segment.allocatedFrames
 		},
 		workspacePath: segmentWorkspacePath,
+		effectiveFps: segment.effectiveFps,
 		frames,
 		graph: [],
 		status: "ANALYZING",
@@ -1313,19 +2249,26 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 * Each segment uses an isolated workspace directory.
 */
 async function processSegment(inputPath, segment, workspacePath, resolvedOptions, onProgress) {
-	const frames = await extractFramesForRange(inputPath, (0, node_path.join)(workspacePath, "frames"), segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration);
+	const framesDir = (0, node_path.join)(workspacePath, "frames");
+	const frames = await extractFramesForRange(inputPath, framesDir, segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration, segment.allocatedFrames);
 	if (frames.length < 2) return {
 		segment,
 		frames,
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
-	const { edges, animations } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
+	const ctx = buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress);
+	const { edges, animations, analysisResolution } = await analyzeFrames(ctx);
 	return {
 		segment,
 		frames,
 		edges,
-		animations
+		animations,
+		analysisResolution
 	};
 }
 /**
@@ -1365,7 +2308,7 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 			});
 		})));
 		options.onProgress?.("ANALYZING", 100);
-		const { frames, edges, animations } = mergeSegmentFrames(results);
+		const { frames, edges, animations, analysisResolution } = mergeSegmentFrames(results);
 		logger.debug(`Merged: ${frames.length} frames, ${edges.length} edges, ${animations.length} animations`);
 		options.onProgress?.("PRUNING", 0);
 		const survivingIds = pruneByThresholdWithCap(edges, frames, resolvedOptions.threshold, resolvedOptions.count);
@@ -1374,6 +2317,9 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 		options.onProgress?.("FINALIZING", 0);
 		const ctx = {
 			options: resolvedOptions,
+			effectiveFps: segments[0]?.effectiveFps,
+			sourceDurationSec: totalDuration,
+			analysisResolution,
 			workspacePath: mainWorkspace,
 			frames,
 			graph: edges,
@@ -1381,27 +2327,20 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 			status: "FINALIZING",
 			emitProgress: (percent) => options.onProgress?.("FINALIZING", percent)
 		};
-		let outputFiles = [];
-		let outputBuffers;
-		if (resolvedOptions.mode === "buffer" || resolvedOptions.mode === "frames") outputBuffers = await readFramesAsBuffers(prunedFrames, resolvedOptions.quality);
-		else outputFiles = await finalizeOutput(ctx, prunedFrames);
+		const finalized = await finalizeSelection(ctx, prunedFrames);
 		options.onProgress?.("FINALIZING", 100);
 		logger.success(`Segmented pipeline: ${prunedFrames.length} scenes from ${frames.length} frames (${segments.length} segments)`);
 		return {
 			success: true,
 			originalFramesCount: frames.length,
 			prunedFramesCount: prunedFrames.length,
-			outputFiles,
-			outputBuffers,
-			animations,
-			video: {
-				originalDurationMs: totalDuration * 1e3,
-				fps: resolvedOptions.fps,
-				resolution: {
-					width: resolvedOptions.scale,
-					height: Math.round(resolvedOptions.scale * 9 / 16)
-				}
-			},
+			outputFiles: finalized.outputFiles,
+			outputBuffers: finalized.outputBuffers,
+			video: finalized.document.video,
+			animations: finalized.animations,
+			frames: finalized.document.frames,
+			...finalized.document.sheet ? { sheet: finalized.document.sheet } : {},
+			...finalized.sheetBuffer ? { sheetBuffer: finalized.sheetBuffer } : {},
 			executionTimeMs: Date.now() - pipelineStart
 		};
 	} catch (error) {
@@ -1413,11 +2352,33 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 		else logger.debug(`Debug mode: workspace preserved at ${mainWorkspace}`);
 	}
 }
+var init_segmenter$1 = __esmMin((() => {
+	init_concurrency();
+	init_logger();
+	init_analyzer();
+	init_finalize_selection();
+	init_extractor();
+	init_input_resolver();
+	init_pruner();
+	init_workspace();
+}));
+
+//#endregion
+//#region src/core/segmenter/index.ts
+var init_segmenter = __esmMin((() => {
+	init_segmenter$1();
+}));
 
 //#endregion
-//#region src/core/orchestrator.ts
+//#region src/core/orchestrator/orchestrator.ts
+/**
+* Run the five pipeline stages, delegating segmented inputs to the segmenter.
+* @param options - Mode-specific input and optional pipeline settings.
+* @returns Selected outputs with v2 frame metadata and zero-based API animations.
+* @throws Propagates stage failures after cleaning the workspace unless debug is enabled.
+*/
 async function runPipeline(options) {
-	if (options.debug ?? false) setDebugMode(true);
+	setDebugMode(options.debug ?? false);
 	const resolvedOptions = resolveOptions(options);
 	if (shouldSegment(resolvedOptions, options)) return runSegmentedPipeline(options, resolvedOptions);
 	const startTime = Date.now();
@@ -1437,50 +2398,47 @@ async function runPipeline(options) {
 		logger.debug(`Workspace created: ${ctx.workspacePath}`);
 		ctx.status = "EXTRACTING";
 		const { frames: resolvedFrames, resolvedInputPath } = await resolveInput(options, ctx.workspacePath);
-		if (resolvedOptions.mode === "frames") ctx.frames = resolvedFrames;
-		else ctx.frames = await extractFrames({
-			...ctx,
-			options: {
-				...resolvedOptions,
-				inputPath: resolvedInputPath
-			}
-		});
+		if (resolvedOptions.mode === "frames") {
+			ctx.frames = resolvedFrames;
+			ctx.effectiveFps = 1;
+		} else {
+			const extractCtx = {
+				...ctx,
+				options: {
+					...resolvedOptions,
+					inputPath: resolvedInputPath
+				}
+			};
+			ctx.frames = await extractFrames(extractCtx);
+			ctx.effectiveFps = extractCtx.effectiveFps;
+			ctx.sourceDurationSec = extractCtx.sourceDurationSec;
+		}
 		ctx.emitProgress(100);
 		ctx.status = "ANALYZING";
-		const { edges, animations } = await analyzeFrames(ctx);
+		const { edges, animations, analysisResolution } = await analyzeFrames(ctx);
 		ctx.graph = edges;
 		ctx.animations = animations;
+		ctx.analysisResolution = analysisResolution;
 		ctx.status = "PRUNING";
 		const survivingIds = pruneByThresholdWithCap(ctx.graph, ctx.frames, resolvedOptions.threshold, resolvedOptions.count);
 		const prunedFrames = (0, _winglet_common_utils.filter)(ctx.frames, (f) => survivingIds.has(f.id));
 		ctx.emitProgress(100);
 		ctx.status = "FINALIZING";
-		let outputFiles = [];
-		let outputBuffers;
-		if (resolvedOptions.mode === "buffer" || resolvedOptions.mode === "frames") {
-			outputBuffers = await readFramesAsBuffers(prunedFrames, resolvedOptions.quality);
-			ctx.emitProgress(100);
-		} else {
-			outputFiles = await finalizeOutput(ctx, prunedFrames);
-			ctx.emitProgress(100);
-		}
+		const finalized = await finalizeSelection(ctx, prunedFrames);
+		ctx.emitProgress(100);
 		ctx.status = "SUCCESS";
 		logger.success(`Extracted ${prunedFrames.length} scenes from ${ctx.frames.length} frames`);
 		return {
 			success: true,
 			originalFramesCount: ctx.frames.length,
 			prunedFramesCount: prunedFrames.length,
-			outputFiles,
-			outputBuffers,
-			animations: ctx.animations,
-			video: {
-				originalDurationMs: ctx.frames.length / ctx.options.fps * 1e3,
-				fps: ctx.options.fps,
-				resolution: {
-					width: ctx.options.scale,
-					height: Math.round(ctx.options.scale * 9 / 16)
-				}
-			},
+			outputFiles: finalized.outputFiles,
+			outputBuffers: finalized.outputBuffers,
+			video: finalized.document.video,
+			animations: finalized.animations,
+			frames: finalized.document.frames,
+			...finalized.document.sheet ? { sheet: finalized.document.sheet } : {},
+			...finalized.sheetBuffer ? { sheetBuffer: finalized.sheetBuffer } : {},
 			executionTimeMs: Date.now() - startTime
 		};
 	} catch (error) {
@@ -1493,6 +2451,20 @@ async function runPipeline(options) {
 		else logger.debug(`Debug mode: workspace preserved at ${ctx.workspacePath}`);
 	}
 }
+var init_orchestrator = __esmMin((() => {
+	init_logger();
+	init_analyzer();
+	init_finalize_selection();
+	init_extractor();
+	init_input_resolver();
+	init_pruner();
+	init_segmenter();
+	init_workspace();
+}));
+
+//#endregion
+//#region src/index.ts
+init_orchestrator();
 
 //#endregion
 exports.extractScenes = runPipeline;