@lumy-pack/scene-sieve 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -3,65 +3,76 @@ 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 { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
 import { path } from "@ffprobe-installer/ffprobe";
 import { execa } from "execa";
 import ffmpegPath from "ffmpeg-static";
+import { homedir, tmpdir } from "node:os";
+
+//#region \0rolldown/runtime.js
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
 
-//#region src/utils/logger.ts
-let debugMode = false;
-let jsonMode = false;
+//#endregion
+//#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(`${pc.blue("info")} ${message}\n`);
-		else console.log(`${pc.blue("info")} ${message}`);
-	},
-	success(message) {
-		if (jsonMode) process.stderr.write(`${pc.green("done")} ${message}\n`);
-		else console.log(`\n${pc.green("done")} ${message}`);
-	},
-	warn(message) {
-		console.warn(`${pc.yellow("warn")} ${message}`);
-	},
-	error(message) {
-		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}`);
-	}
-};
+var debugMode, jsonMode, logger;
+var init_logger = __esmMin((() => {
+	debugMode = false;
+	jsonMode = false;
+	logger = {
+		info(message) {
+			if (jsonMode) process.stderr.write(`${pc.blue("info")} ${message}\n`);
+			else console.log(`${pc.blue("info")} ${message}`);
+		},
+		success(message) {
+			if (jsonMode) process.stderr.write(`${pc.green("done")} ${message}\n`);
+			else console.log(`\n${pc.green("done")} ${message}`);
+		},
+		warn(message) {
+			console.warn(`${pc.yellow("warn")} ${message}`);
+		},
+		error(message) {
+			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}`);
+		}
+	};
+}));
 
 //#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 = 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 join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
-}
+//#region src/constants/pipeline-defaults.ts
+var DEFAULT_THRESHOLD, IOU_THRESHOLD;
+var init_pipeline_defaults = __esmMin((() => {
+	DEFAULT_THRESHOLD = .5;
+	IOU_THRESHOLD = .9;
+}));
+
+//#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)
@@ -137,12 +148,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.ts
-const OPENCV_INIT_TIMEOUT_MS = 3e4;
-const require = createRequire(import.meta.url);
-let cvReady = null;
+//#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/analyzer.ts
 async function ensureOpenCV() {
 	if (!cvReady) cvReady = (async () => {
 		const cvObj = require("@techstark/opencv-js");
@@ -181,158 +298,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 = 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.
 *
@@ -347,17 +312,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);
@@ -368,22 +346,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) {
@@ -402,47 +384,85 @@ 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]);
+				let dbscanResult = dbscan(computeNewPoints(cvLib, prev, next), 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 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.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)).
@@ -453,35 +473,222 @@ 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, 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 = createRequire(import.meta.url);
+	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 = 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/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
+			}
+		},
+		animations: (ctx.animations ?? []).map((animation) => {
+			const box = animation.boundingBox;
+			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 {
+				...animation,
+				boundingBox: {
+					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_build_video_metadata = __esmMin((() => {}));
+
+//#endregion
+//#region src/core/constants/workspace-layout.ts
+function getTempWorkspaceDir(sessionId) {
+	return 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 = tmpdir();
+	FRAME_OUTPUT_EXTENSION = ".jpg";
+	FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+}));
 
 //#endregion
-//#region src/utils/paths.ts
+//#region src/core/utils/filesystem/paths.ts
 async function ensureDir(dirPath) {
 	await mkdir(dirPath, { recursive: true });
 }
@@ -517,15 +724,21 @@ function resolveAbsolute(p) {
 function deriveOutputPath(inputPath) {
 	return resolve(resolve(inputPath, ".."), `${basename(inputPath, extname(inputPath))}_scenes`);
 }
+var init_paths = __esmMin((() => {}));
 
 //#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 = join(ctx.workspacePath, "frames");
 	const { inputPath, fps, maxFrames, scale } = ctx.options;
 	if (!inputPath) throw new Error("inputPath is required for frame extraction");
@@ -540,19 +753,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",
@@ -561,9 +785,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, [
@@ -577,12 +803,18 @@ async function getVideoMetadata(inputPath) {
 	]);
 	return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, duration) {
+/**
+* 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 jpgFiles = filter(await readdir(framesDir), (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)
 	}));
 }
@@ -596,9 +828,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",
@@ -611,13 +844,124 @@ 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/extractor/index.ts
+var init_extractor = __esmMin((() => {
+	init_extractor$1();
+}));
+
+//#endregion
+//#region src/core/input-resolver/validation/validate-options.ts
+/**
+* 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.
+*/
+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}`);
+	}
 }
+var init_validate_options = __esmMin((() => {}));
 
 //#endregion
-//#region src/core/workspace.ts
+//#region src/core/workspace/workspace.ts
 async function createWorkspace(sessionId) {
 	const workspacePath = getTempWorkspaceDir(sessionId);
 	await ensureDir(join(workspacePath, "frames"));
@@ -648,17 +992,11 @@ async function finalizeOutput(ctx, selectedFrames) {
 			timestampMs: Math.round(frame.timestamp * 1e3)
 		});
 	}
+	const { video, animations } = await buildVideoMetadata(ctx, selectedFrames, ctx.analysisResolution);
 	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)
-			}
-		},
+		video,
 		frames: framesMetadata,
-		animations: map(ctx.animations || [], (anim) => ({
+		animations: map(animations, (anim) => ({
 			...anim,
 			startFrameId: anim.startFrameId + 1,
 			endFrameId: anim.endFrameId + 1,
@@ -729,15 +1067,32 @@ async function readFramesAsBuffers(frameNodes, quality) {
 		mozjpeg: true
 	}).toBuffer()));
 }
+var init_workspace$1 = __esmMin((() => {
+	init_workspace_layout();
+	init_paths();
+	init_build_video_metadata();
+}));
 
 //#endregion
-//#region src/core/input-resolver.ts
+//#region src/core/workspace/index.ts
+var init_workspace = __esmMin((() => {
+	init_workspace$1();
+}));
+
+//#endregion
+//#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}`);
 	return {
 		mode,
 		inputPath,
@@ -762,6 +1117,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 {
@@ -772,12 +1131,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 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}`);
 }
+var init_input_resolver$1 = __esmMin((() => {
+	init_pipeline_defaults();
+	init_paths();
+	init_validate_options();
+	init_workspace();
+}));
 
 //#endregion
-//#region src/utils/math.ts
+//#region src/core/input-resolver/index.ts
+var init_input_resolver = __esmMin((() => {
+	init_input_resolver$1();
+}));
+
+//#endregion
+//#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.
 *
@@ -822,64 +1220,67 @@ 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);
 }
+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).
 *
@@ -993,7 +1394,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.
@@ -1056,9 +1457,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.
@@ -1078,9 +1489,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.
@@ -1094,53 +1506,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;
 }
 /**
@@ -1159,44 +1580,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 = [];
@@ -1205,6 +1640,7 @@ 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) {
@@ -1225,42 +1661,52 @@ function remapEdges(segmentResults, globalIdMap) {
 	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) {
@@ -1271,6 +1717,7 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 			maxFrames: segment.allocatedFrames
 		},
 		workspacePath: segmentWorkspacePath,
+		effectiveFps: segment.effectiveFps,
 		frames,
 		graph: [],
 		status: "ANALYZING",
@@ -1282,19 +1729,24 @@ 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 frames = await extractFramesForRange(inputPath, join(workspacePath, "frames"), 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 { edges, animations, analysisResolution } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
 	return {
 		segment,
 		frames,
 		edges,
-		animations
+		animations,
+		analysisResolution
 	};
 }
 /**
@@ -1334,7 +1786,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);
@@ -1343,6 +1795,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,
@@ -1356,21 +1811,14 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 		else outputFiles = await finalizeOutput(ctx, prunedFrames);
 		options.onProgress?.("FINALIZING", 100);
 		logger.success(`Segmented pipeline: ${prunedFrames.length} scenes from ${frames.length} frames (${segments.length} segments)`);
+		const outputMetadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		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)
-				}
-			},
+			...outputMetadata,
 			executionTimeMs: Date.now() - pipelineStart
 		};
 	} catch (error) {
@@ -1382,11 +1830,27 @@ 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_build_video_metadata();
+	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
 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();
@@ -1406,19 +1870,27 @@ 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));
@@ -1435,21 +1907,14 @@ async function runPipeline(options) {
 		}
 		ctx.status = "SUCCESS";
 		logger.success(`Extracted ${prunedFrames.length} scenes from ${ctx.frames.length} frames`);
+		const metadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		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)
-				}
-			},
+			...metadata,
 			executionTimeMs: Date.now() - startTime
 		};
 	} catch (error) {
@@ -1462,6 +1927,20 @@ async function runPipeline(options) {
 		else logger.debug(`Debug mode: workspace preserved at ${ctx.workspacePath}`);
 	}
 }
+var init_orchestrator = __esmMin((() => {
+	init_logger();
+	init_analyzer();
+	init_build_video_metadata();
+	init_extractor();
+	init_input_resolver();
+	init_pruner();
+	init_segmenter();
+	init_workspace();
+}));
+
+//#endregion
+//#region src/index.ts
+init_orchestrator();
 
 //#endregion
 export { runPipeline as extractScenes };