@lumy-pack/scene-sieve 0.1.0 → 0.2.1

package/dist/pipeline-worker.mjs

@@ -4,14 +4,15 @@ import { randomUUID } from "node:crypto";
 import { filter, map } from "@winglet/common-utils";
 import pc from "picocolors";
 import sharp from "sharp";
-import { homedir, tmpdir } from "node:os";
-import { basename, extname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
 import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+import { homedir, tmpdir } from "node:os";
 import { path } from "@ffprobe-installer/ffprobe";
 import { execa } from "execa";
 import ffmpegPath from "ffmpeg-static";
 
-//#region src/utils/logger.ts
+//#region src/logging/logger.ts
 let debugMode = false;
 let jsonMode = false;
 function setDebugMode(enabled) {
@@ -36,31 +37,32 @@ const logger = {
 		console.error(`${pc.red("error")} ${message}`);
 	},
 	debug(message) {
-		if (debugMode) if (jsonMode) process.stderr.write(`${pc.gray(`[${timestamp()}] debug`)} ${message}\n`);
-		else console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+		if (debugMode) {
+			if (jsonMode) process.stderr.write(`${pc.gray(`[${timestamp()}] debug`)} ${message}\n`);
+			else console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+		}
 	}
 };
 
 //#endregion
-//#region src/constants.ts
-const APP_NAME = "scene-sieve";
+//#region src/constants/pipeline-defaults.ts
 const DEFAULT_THRESHOLD = .5;
-const NORMALIZATION_ALPHA = .4;
-const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
-const WORKSPACE_PREFIX = `${APP_NAME}-`;
-const TEMP_BASE_DIR = tmpdir();
-const FRAME_OUTPUT_EXTENSION = ".jpg";
-const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
-const DBSCAN_ALPHA = .03;
 const IOU_THRESHOLD = .9;
+/** Tile-height fraction used for label font size. */
+const SHEET_LABEL_HEIGHT_RATIO = .07;
+/** Fixed contact sheet output name. */
+const SHEET_FILE_NAME = "sheet.jpg";
+/** Fixed metadata document output name. */
+const METADATA_FILE_NAME = ".metadata.json";
+
+//#endregion
+//#region src/core/analyzer/constants/vision-tuning.ts
+const DBSCAN_ALPHA = .03;
 const DECAY_LAMBDA = .95;
 const MATCH_DISTANCE_THRESHOLD = .25;
-function getTempWorkspaceDir(sessionId) {
-	return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
-}
 
 //#endregion
-//#region src/core/dbscan.ts
+//#region src/core/analyzer/clustering/dbscan.ts
 const UNVISITED = -2;
 const NOISE = -1;
 /**
@@ -140,7 +142,106 @@ function findNeighbors(points, idx, epsSquared) {
 }
 
 //#endregion
-//#region src/core/analyzer.ts
+//#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();
+	}
+}
+
+//#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();
+	}
+}
+
+//#endregion
+//#region src/core/analyzer/analyzer.ts
 const OPENCV_INIT_TIMEOUT_MS = 3e4;
 const require = createRequire(import.meta.url);
 let cvReady = null;
@@ -263,77 +364,6 @@ var IoUTracker = class {
 		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.
 *
@@ -348,17 +378,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);
@@ -369,22 +412,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) {
@@ -403,47 +450,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(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(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: filter(clusters, (_, ci) => !animationIndices.has(ci)),
+					animatedRegions: filter(clusters, (_, ci) => animationIndices.has(ci))
+				};
+				const animationWeights = 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 = 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)).
@@ -454,35 +545,82 @@ 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
 	};
 }
 
 //#endregion
-//#region src/utils/paths.ts
+//#region src/constants/package-version.ts
+/** Source constants are two levels below the manifest; runtime bundles are one level below. */
+const manifestPath = existsSync(new URL("../package.json", import.meta.url)) ? "../package.json" : "../../package.json";
+/** Runtime manifest version shared by CLI responses and metadata documents. */
+const PACKAGE_VERSION = createRequire(import.meta.url)(manifestPath).version;
+
+//#endregion
+//#region src/core/constants/workspace-layout.ts
+/**
+* Temp workspace naming and frame file layout for pipeline runs.
+*/
+const APP_NAME = "scene-sieve";
+const WORKSPACE_PREFIX = `${APP_NAME}-`;
+const TEMP_BASE_DIR = tmpdir();
+const FRAME_OUTPUT_EXTENSION = ".jpg";
+const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+function getTempWorkspaceDir(sessionId) {
+	return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
+}
+
+//#endregion
+//#region src/core/utils/filesystem/paths.ts
 async function ensureDir(dirPath) {
 	await mkdir(dirPath, { recursive: true });
 }
@@ -516,17 +654,579 @@ function resolveAbsolute(p) {
 * e.g., /path/to/video.mp4 -> /path/to/video_scenes
 */
 function deriveOutputPath(inputPath) {
-	return resolve(resolve(inputPath, ".."), `${basename(inputPath, extname(inputPath))}_scenes`);
+	const dir = resolve(inputPath, "..");
+	const name = basename(inputPath, extname(inputPath));
+	return resolve(dir, `${name}_scenes`);
+}
+
+//#endregion
+//#region src/core/workspace/workspace.ts
+async function createWorkspace(sessionId) {
+	const workspacePath = getTempWorkspaceDir(sessionId);
+	await ensureDir(join(workspacePath, "frames"));
+	await ensureDir(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 = 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 = join(stagingDir, fileName);
+		await sharp(frame.extractPath).jpeg({
+			quality,
+			mozjpeg: true
+		}).toFile(destPath);
+		outputFiles.push(join(outputPath, fileName));
+	}
+	if (sheetBuffer) {
+		await writeFile(join(stagingDir, SHEET_FILE_NAME), sheetBuffer);
+		outputFiles.push(join(outputPath, SHEET_FILE_NAME));
+	}
+	const metadataPath = join(stagingDir, METADATA_FILE_NAME);
+	await writeFile(metadataPath, JSON.stringify(document, null, 2));
+	outputFiles.push(join(outputPath, METADATA_FILE_NAME));
+	await ensureDir(join(outputPath, ".."));
+	await rm(outputPath, {
+		recursive: true,
+		force: true
+	});
+	await rename(stagingDir, outputPath);
+	return outputFiles;
+}
+async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
+	const segmentPath = join(parentWorkspacePath, "segments", String(segmentIndex));
+	await ensureDir(join(segmentPath, "frames"));
+	return segmentPath;
+}
+async function cleanupWorkspace(workspacePath) {
+	if (!workspacePath) return;
+	try {
+		await 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 = join(workspacePath, "input");
+	await ensureDir(inputDir);
+	const tempPath = join(inputDir, "input.mp4");
+	await 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 = 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 = join(framesDir, filename);
+		await 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(map(frameNodes, (f) => sharp(f.extractPath).jpeg({
+		quality,
+		mozjpeg: true
+	}).toBuffer()));
 }
 
 //#endregion
-//#region src/core/extractor.ts
+//#region src/core/utils/metadata/change/union-area/y-coverage-tree.ts
+/** Internal sweep helper retaining cover counts and lengths between sorted y bounds. */
+var 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;
+}
+
+//#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 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
+	}));
+}
+
+//#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)))
+	};
+}
+
+//#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 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);
+}
+
+//#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(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
+	};
+}
+
+//#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(map(graph, (edge) => [`${edge.sourceId}:${edge.targetId}`, edge]));
+	const candidateIndices = new Map(map(frames, (frame, index) => [frame.id, index]));
+	const padding = Math.max(4, String(frames.length).length);
+	return 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
+		};
+	});
+}
+
+//#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
+		}
+	};
+}
+
+//#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: 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) } : {}
+	};
+}
+
+//#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 sharp(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 ? basename(ctx.options.inputPath) : null,
+				mode: ctx.options.mode
+			}
+		},
+		animations: (ctx.animations ?? []).map((animation) => ({
+			...animation,
+			boundingBox: scaleBoundingBox(animation.boundingBox, sx, sy, width, height)
+		}))
+	};
+}
+
+//#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>`);
+}
+
+//#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}`;
+}
+
+//#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
+	};
+}
+
+//#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(map(items, async (frame, index) => {
+		const tile = sharp(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 sharp({ 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: map(items, (frame) => frame.id + 1),
+			sampled
+		}
+	};
+}
+
+//#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 } : {}
+	};
+}
+
+//#endregion
+//#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 = join(ctx.workspacePath, "frames");
 	const { inputPath, fps, maxFrames, scale } = ctx.options;
 	if (!inputPath) throw new Error("inputPath is required for frame extraction");
@@ -541,19 +1241,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 = join(outputDir, FRAME_FILENAME_PATTERN);
 	await execa(ffmpegPath, [
 		"-i",
@@ -562,9 +1273,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 execa(path, [
@@ -578,12 +1291,19 @@ async function getVideoMetadata(inputPath) {
 	]);
 	return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, duration) {
-	const jpgFiles = filter(await 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 readdir(framesDir);
+	const jpgFiles = filter(files, (f) => f.endsWith(".jpg")).sort();
 	if (jpgFiles.length === 0) return [];
 	return map(jpgFiles, (file, index) => ({
 		id: index,
-		timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
+		timestamp: index / effectiveFps,
 		extractPath: join(framesDir, file)
 	}));
 }
@@ -597,9 +1317,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 = join(outputDir, FRAME_FILENAME_PATTERN);
 	await execa(ffmpegPath, [
 		"-ss",
@@ -612,139 +1333,145 @@ 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);
 }
 
 //#endregion
-//#region src/core/workspace.ts
-async function createWorkspace(sessionId) {
-	const workspacePath = getTempWorkspaceDir(sessionId);
-	await ensureDir(join(workspacePath, "frames"));
-	await ensureDir(join(workspacePath, "output"));
-	return workspacePath;
-}
-async function finalizeOutput(ctx, selectedFrames) {
-	const stagingDir = 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 = join(stagingDir, fileName);
-		await sharp(frame.extractPath).jpeg({
-			quality,
-			mozjpeg: true
-		}).toFile(destPath);
-		outputFiles.push(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: map(ctx.animations || [], (anim) => ({
-			...anim,
-			startFrameId: anim.startFrameId + 1,
-			endFrameId: anim.endFrameId + 1,
-			durationMs: Math.round(anim.durationMs)
-		}))
-	};
-	await writeFile(join(stagingDir, ".metadata.json"), JSON.stringify(metadata, null, 2));
-	outputFiles.push(join(outputPath, ".metadata.json"));
-	await ensureDir(join(outputPath, ".."));
-	await rm(outputPath, {
-		recursive: true,
-		force: true
-	});
-	await rename(stagingDir, outputPath);
-	return outputFiles;
-}
-async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
-	const segmentPath = join(parentWorkspacePath, "segments", String(segmentIndex));
-	await ensureDir(join(segmentPath, "frames"));
-	return segmentPath;
-}
-async function cleanupWorkspace(workspacePath) {
-	if (!workspacePath) return;
-	try {
-		await 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 = join(workspacePath, "input");
-	await ensureDir(inputDir);
-	const tempPath = join(inputDir, "input.mp4");
-	await writeFile(tempPath, buffer);
-	return tempPath;
-}
+//#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 = join(workspacePath, "frames");
-	await ensureDir(framesDir);
-	const frameNodes = [];
-	for (let i = 0; i < frames.length; i++) {
-		const extractPath = join(framesDir, `frame_${String(i).padStart(6, "0")}${FRAME_OUTPUT_EXTENSION}`);
-		await 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(map(frameNodes, (f) => sharp(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}`);
 }
 
 //#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) : 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,
@@ -754,7 +1481,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
 	};
 }
 /**
@@ -763,6 +1497,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 {
@@ -773,12 +1511,42 @@ 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 sharp(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}`);
 }
 
 //#endregion
-//#region src/utils/math.ts
+//#region src/core/pruner/scoring/normalize-scores.ts
+const NORMALIZATION_ALPHA = .4;
+const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
+/**
+* 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.
 *
@@ -823,13 +1591,13 @@ function normalizeScores(items) {
 	});
 	const cdf = map(safeScores, (s) => {
 		if (s <= 0) return 0;
-		return sorted.findIndex((v) => v >= s) / sorted.length;
+		return lowerBound(sorted, s) / sorted.length;
 	});
-	return map(logisticZ, (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA);
+	return map(logisticZ, (z, i) => z * .6 + cdf[i] * NORMALIZATION_ALPHA);
 }
 
 //#endregion
-//#region src/utils/min-heap.ts
+//#region src/core/pruner/heap/min-heap.ts
 /**
 * Generic binary min-heap.
 *
@@ -880,7 +1648,7 @@ var MinHeap = class {
 };
 
 //#endregion
-//#region src/core/pruner.ts
+//#region src/core/pruner/pruner.ts
 /**
 * Edge-aware greedy merge with re-linking — O(N log N).
 *
@@ -994,7 +1762,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.
@@ -1059,7 +1827,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 }
 
 //#endregion
-//#region src/utils/concurrency.ts
+//#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.
@@ -1081,7 +1849,7 @@ function concurrencyLimit(limit) {
 }
 
 //#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.
@@ -1095,53 +1863,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;
 }
 /**
@@ -1160,44 +1937,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 = [];
@@ -1206,62 +1997,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) {
@@ -1272,6 +2074,7 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 			maxFrames: segment.allocatedFrames
 		},
 		workspacePath: segmentWorkspacePath,
+		effectiveFps: segment.effectiveFps,
 		frames,
 		graph: [],
 		status: "ANALYZING",
@@ -1283,19 +2086,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, join(workspacePath, "frames"), segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration);
+	const framesDir = 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
 	};
 }
 /**
@@ -1335,7 +2145,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);
@@ -1344,6 +2154,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,
@@ -1351,27 +2164,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) {
@@ -1385,9 +2191,15 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 }
 
 //#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();
@@ -1407,50 +2219,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 = 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) {
@@ -1465,7 +2274,7 @@ async function runPipeline(options) {
 }
 
 //#endregion
-//#region src/core/pipeline-worker.ts
+//#region src/core/orchestrator/worker/pipeline-worker.ts
 runPipeline({
 	...workerData,
 	onProgress: (phase, percent) => {