@lumy-pack/scene-sieve 0.0.14 → 0.2.0

package/dist/pipeline-worker.mjs

@@ -1,1588 +1,1848 @@
-// src/core/pipeline-worker.ts
-import { parentPort, workerData } from "worker_threads";
-
-// src/core/orchestrator.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { filter as filter6 } from "@winglet/common-utils";
-
-// src/utils/logger.ts
+import { createRequire } from "node:module";
+import { parentPort, workerData } from "node:worker_threads";
+import { randomUUID } from "node:crypto";
+import { filter, map } from "@winglet/common-utils";
 import pc from "picocolors";
-var debugMode = false;
-var jsonMode = false;
+import sharp from "sharp";
+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 src/logging/logger.ts
+let debugMode = false;
+let jsonMode = false;
 function setDebugMode(enabled) {
-  debugMode = enabled;
+	debugMode = enabled;
 }
 function timestamp() {
-  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+	return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
 }
-var logger = {
-  info(message) {
-    if (jsonMode) {
-      process.stderr.write(`${pc.blue("info")} ${message}
-`);
-    } else {
-      console.log(`${pc.blue("info")} ${message}`);
-    }
-  },
-  success(message) {
-    if (jsonMode) {
-      process.stderr.write(`${pc.green("done")} ${message}
-`);
-    } else {
-      console.log(`
-${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}
-`);
-      } else {
-        console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
-      }
-    }
-  }
+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}`);
+	}
 };
 
-// src/core/analyzer.ts
-import { createRequire } from "module";
-import { filter, map } from "@winglet/common-utils";
-import sharp from "sharp";
+//#endregion
+//#region src/constants/pipeline-defaults.ts
+const DEFAULT_THRESHOLD = .5;
+const IOU_THRESHOLD = .9;
 
-// src/constants.ts
-import { tmpdir } from "os";
-import { join } from "path";
-var APP_NAME = "scene-sieve";
-var DEFAULT_COUNT = 20;
-var DEFAULT_THRESHOLD = 0.5;
-var DEFAULT_FPS = 5;
-var DEFAULT_SCALE = 720;
-var DEFAULT_QUALITY = 80;
-var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_LOGISTIC_K = 3;
-var NORMALIZATION_ALPHA = 0.4;
-var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
-var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
-var WORKSPACE_PREFIX = `${APP_NAME}-`;
-var TEMP_BASE_DIR = tmpdir();
-var FRAME_OUTPUT_EXTENSION = ".jpg";
-var FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
-var OPENCV_BATCH_SIZE = 10;
-var DBSCAN_ALPHA = 0.03;
-var DBSCAN_MIN_PTS = 4;
-var IOU_THRESHOLD = 0.9;
-var DECAY_LAMBDA = 0.95;
-var ANIMATION_FRAME_THRESHOLD = 5;
-var MATCH_DISTANCE_THRESHOLD = 0.25;
-var PIXELDIFF_GAUSSIAN_KERNEL = 3;
-var PIXELDIFF_BINARY_THRESHOLD = 30;
-var PIXELDIFF_CONTOUR_MIN_AREA = 100;
-var PIXELDIFF_SAMPLE_SPACING = 8;
-var DEFAULT_MAX_SEGMENT_DURATION = 300;
-var DEFAULT_SEGMENT_CONCURRENCY = 2;
-function getTempWorkspaceDir(sessionId) {
-  return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
-}
+//#endregion
+//#region src/core/analyzer/constants/vision-tuning.ts
+const DBSCAN_ALPHA = .03;
+const DECAY_LAMBDA = .95;
+const MATCH_DISTANCE_THRESHOLD = .25;
 
-// src/core/dbscan.ts
-var UNVISITED = -2;
-var NOISE = -1;
+//#endregion
+//#region src/core/analyzer/clustering/dbscan.ts
+const UNVISITED = -2;
+const NOISE = -1;
+/**
+* DBSCAN clustering with resolution-independent eps.
+* eps = alpha * sqrt(width^2 + height^2)
+*/
 function dbscan(points, imageWidth, imageHeight, alpha, minPts) {
-  if (points.length === 0) {
-    return { labels: [], boundingBoxes: [] };
-  }
-  const eps = (alpha ?? DBSCAN_ALPHA) * Math.sqrt(imageWidth ** 2 + imageHeight ** 2);
-  const epsSquared = eps * eps;
-  const minPoints = minPts ?? DBSCAN_MIN_PTS;
-  const labels = new Array(points.length).fill(UNVISITED);
-  let clusterId = 0;
-  for (let i = 0; i < points.length; i++) {
-    if (labels[i] !== UNVISITED) continue;
-    const neighbors = findNeighbors(points, i, epsSquared);
-    if (neighbors.length < minPoints) {
-      labels[i] = NOISE;
-      continue;
-    }
-    labels[i] = clusterId;
-    const seeds = [...neighbors];
-    const seedSet = new Set(seeds);
-    for (let si = 0; si < seeds.length; si++) {
-      const q = seeds[si];
-      if (labels[q] === NOISE) {
-        labels[q] = clusterId;
-      }
-      if (labels[q] !== UNVISITED) continue;
-      labels[q] = clusterId;
-      const qNeighbors = findNeighbors(points, q, epsSquared);
-      if (qNeighbors.length >= minPoints) {
-        for (const n of qNeighbors) {
-          if (!seedSet.has(n)) {
-            seedSet.add(n);
-            seeds.push(n);
-          }
-        }
-      }
-    }
-    clusterId++;
-  }
-  const boundingBoxes = [];
-  for (let c = 0; c < clusterId; c++) {
-    let minX = Infinity;
-    let minY = Infinity;
-    let maxX = -Infinity;
-    let maxY = -Infinity;
-    for (let i = 0; i < points.length; i++) {
-      if (labels[i] !== c) continue;
-      const p = points[i];
-      if (p.x < minX) minX = p.x;
-      if (p.y < minY) minY = p.y;
-      if (p.x > maxX) maxX = p.x;
-      if (p.y > maxY) maxY = p.y;
-    }
-    boundingBoxes.push({
-      x: minX,
-      y: minY,
-      width: maxX - minX,
-      height: maxY - minY
-    });
-  }
-  return { labels, boundingBoxes };
+	if (points.length === 0) return {
+		labels: [],
+		boundingBoxes: []
+	};
+	const eps = (alpha ?? .03) * Math.sqrt(imageWidth ** 2 + imageHeight ** 2);
+	const epsSquared = eps * eps;
+	const minPoints = minPts ?? 4;
+	const labels = new Array(points.length).fill(UNVISITED);
+	let clusterId = 0;
+	for (let i = 0; i < points.length; i++) {
+		if (labels[i] !== UNVISITED) continue;
+		const neighbors = findNeighbors(points, i, epsSquared);
+		if (neighbors.length < minPoints) {
+			labels[i] = NOISE;
+			continue;
+		}
+		labels[i] = clusterId;
+		const seeds = [...neighbors];
+		const seedSet = new Set(seeds);
+		for (let si = 0; si < seeds.length; si++) {
+			const q = seeds[si];
+			if (labels[q] === NOISE) labels[q] = clusterId;
+			if (labels[q] !== UNVISITED) continue;
+			labels[q] = clusterId;
+			const qNeighbors = findNeighbors(points, q, epsSquared);
+			if (qNeighbors.length >= minPoints) {
+				for (const n of qNeighbors) if (!seedSet.has(n)) {
+					seedSet.add(n);
+					seeds.push(n);
+				}
+			}
+		}
+		clusterId++;
+	}
+	const boundingBoxes = [];
+	for (let c = 0; c < clusterId; c++) {
+		let minX = Infinity;
+		let minY = Infinity;
+		let maxX = -Infinity;
+		let maxY = -Infinity;
+		for (let i = 0; i < points.length; i++) {
+			if (labels[i] !== c) continue;
+			const p = points[i];
+			if (p.x < minX) minX = p.x;
+			if (p.y < minY) minY = p.y;
+			if (p.x > maxX) maxX = p.x;
+			if (p.y > maxY) maxY = p.y;
+		}
+		boundingBoxes.push({
+			x: minX,
+			y: minY,
+			width: maxX - minX,
+			height: maxY - minY
+		});
+	}
+	return {
+		labels,
+		boundingBoxes
+	};
 }
 function findNeighbors(points, idx, epsSquared) {
-  const p = points[idx];
-  const neighbors = [];
-  for (let i = 0; i < points.length; i++) {
-    if (i === idx) continue;
-    const q = points[i];
-    const distSq = (p.x - q.x) ** 2 + (p.y - q.y) ** 2;
-    if (distSq <= epsSquared) {
-      neighbors.push(i);
-    }
-  }
-  return neighbors;
+	const p = points[idx];
+	const neighbors = [];
+	for (let i = 0; i < points.length; i++) {
+		if (i === idx) continue;
+		const q = points[i];
+		if ((p.x - q.x) ** 2 + (p.y - q.y) ** 2 <= epsSquared) neighbors.push(i);
+	}
+	return neighbors;
 }
 
-// src/core/analyzer.ts
-var OPENCV_INIT_TIMEOUT_MS = 3e4;
-var require2 = createRequire(import.meta.url);
-var cvReady = null;
+//#endregion
+//#region src/core/analyzer/features/feature-diff.ts
+/**
+* Match prev to next with Hamming k=2, crossCheck=false and strict ratio 0.25.
+* @param cvLib - Initialized OpenCV runtime.
+* @param prev - Previous frame's live features, owned by the caller.
+* @param next - Next frame's live features, owned by the caller.
+* @returns Unmatched next-frame coordinates without changing input ownership.
+* @throws Propagates matching errors after releasing temporary native handles.
+*/
+function computeNewPoints(cvLib, prev, next) {
+	let matcher = null;
+	let matches = null;
+	try {
+		const matchedIndices = /* @__PURE__ */ new Set();
+		if (prev.descriptors.rows > 0 && next.descriptors.rows > 0) try {
+			matcher = new cvLib.BFMatcher(cvLib.NORM_HAMMING, false);
+			matches = new cvLib.DMatchVectorVector();
+			matcher.knnMatch(prev.descriptors, next.descriptors, matches, 2);
+			for (let i = 0; i < matches.size(); i++) {
+				const pair = matches.get(i);
+				try {
+					if (pair.size() < 2) continue;
+					const best = pair.get(0);
+					const second = pair.get(1);
+					if (best.distance < .25 * second.distance) matchedIndices.add(best.trainIdx);
+				} finally {
+					pair.delete();
+				}
+			}
+		} finally {
+			matcher?.delete();
+		}
+		const points = [];
+		for (let i = 0; i < next.keypoints.size(); i++) if (!matchedIndices.has(i)) {
+			const { x, y } = next.keypoints.get(i).pt;
+			points.push({
+				x,
+				y
+			});
+		}
+		return points;
+	} finally {
+		matches?.delete();
+	}
+}
+
+//#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;
 async function ensureOpenCV() {
-  if (!cvReady) {
-    cvReady = (async () => {
-      const cvObj = require2("@techstark/opencv-js");
-      delete cvObj.then;
-      if (cvObj.Mat) return cvObj;
-      return new Promise((resolve2, reject) => {
-        const timeout = setTimeout(() => {
-          reject(new Error("OpenCV WASM initialization timed out after 30s"));
-        }, OPENCV_INIT_TIMEOUT_MS);
-        cvObj.onRuntimeInitialized = () => {
-          clearTimeout(timeout);
-          resolve2(cvObj);
-        };
-      });
-    })();
-  }
-  return cvReady;
+	if (!cvReady) cvReady = (async () => {
+		const cvObj = require("@techstark/opencv-js");
+		delete cvObj.then;
+		if (cvObj.Mat) return cvObj;
+		return new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error("OpenCV WASM initialization timed out after 30s"));
+			}, OPENCV_INIT_TIMEOUT_MS);
+			cvObj.onRuntimeInitialized = () => {
+				clearTimeout(timeout);
+				resolve(cvObj);
+			};
+		});
+	})();
+	return cvReady;
 }
 async function preprocessFrame(framePath, scale) {
-  const { data, info } = await sharp(framePath).resize({ width: scale, withoutEnlargement: true }).grayscale().blur(1).raw().toBuffer({ resolveWithObject: true });
-  return {
-    data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
-    width: info.width,
-    height: info.height
-  };
+	const { data, info } = await sharp(framePath).resize({
+		width: scale,
+		withoutEnlargement: true
+	}).grayscale().blur(1).raw().toBuffer({ resolveWithObject: true });
+	return {
+		data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+		width: info.width,
+		height: info.height
+	};
 }
 function computeIoU(a, b) {
-  const ix1 = Math.max(a.x, b.x);
-  const iy1 = Math.max(a.y, b.y);
-  const ix2 = Math.min(a.x + a.width, b.x + b.width);
-  const iy2 = Math.min(a.y + a.height, b.y + b.height);
-  const iw = Math.max(0, ix2 - ix1);
-  const ih = Math.max(0, iy2 - iy1);
-  const intersection = iw * ih;
-  if (intersection === 0) return 0;
-  const aArea = a.width * a.height;
-  const bArea = b.width * b.height;
-  const union = aArea + bArea - intersection;
-  return union === 0 ? 0 : intersection / union;
+	const ix1 = Math.max(a.x, b.x);
+	const iy1 = Math.max(a.y, b.y);
+	const ix2 = Math.min(a.x + a.width, b.x + b.width);
+	const iy2 = Math.min(a.y + a.height, b.y + b.height);
+	const intersection = Math.max(0, ix2 - ix1) * Math.max(0, iy2 - iy1);
+	if (intersection === 0) return 0;
+	const union = a.width * a.height + b.width * b.height - intersection;
+	return union === 0 ? 0 : intersection / union;
 }
 var IoUTracker = class {
-  constructor(fps = DEFAULT_FPS, iouThreshold = IOU_THRESHOLD, animationThreshold = ANIMATION_FRAME_THRESHOLD) {
-    this.fps = fps;
-    this.iouThreshold = iouThreshold;
-    this.animationThreshold = animationThreshold;
-  }
-  regions = [];
-  extractedAnimations = [];
-  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 <= 0.01 && !matched.has(i)) {
-        this.collectAnimation(region);
-      }
-    }
-    this.regions = filter(
-      this.regions,
-      (r, i) => r.weight > 0.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",
-        // 기본값으로 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) {
-        const iou = computeIoU(box, region.box);
-        if (iou > this.iouThreshold) {
-          maxWeight = Math.max(maxWeight, region.weight);
-        }
-      }
-    }
-    return maxWeight;
-  }
+	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 < MATCH_DISTANCE_THRESHOLD * 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.
+*
+* When AKAZE produces sparse results (typical for UI screen recordings
+* where form fields, dropdowns, or overlays change), this function
+* detects changed regions via cv.absdiff and generates synthetic
+* Point2D[] that feed into the existing DBSCAN → IoU → G(t) pipeline.
+*
+* Algorithm:
+* 1. absdiff(frame1, frame2) → grayscale difference
+* 2. GaussianBlur → reduce JPEG compression noise
+* 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();
-  try {
-    mat1.data.set(frame1.data);
-    mat2.data.set(frame2.data);
-    cv.absdiff(mat1, mat2, diff);
-    const ksize = new cv.Size(
-      PIXELDIFF_GAUSSIAN_KERNEL,
-      PIXELDIFF_GAUSSIAN_KERNEL
-    );
-    cv.GaussianBlur(diff, blurred, ksize, 0);
-    cv.threshold(
-      blurred,
-      binary,
-      PIXELDIFF_BINARY_THRESHOLD,
-      255,
-      cv.THRESH_BINARY
-    );
-    cv.findContours(
-      binary,
-      contours,
-      hierarchy,
-      cv.RETR_EXTERNAL,
-      cv.CHAIN_APPROX_SIMPLE
-    );
-    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 < PIXELDIFF_CONTOUR_MIN_AREA) continue;
-      for (let y = rect.y; y < rect.y + rect.height; y += PIXELDIFF_SAMPLE_SPACING) {
-        for (let x = rect.x; x < rect.x + rect.width; x += PIXELDIFF_SAMPLE_SPACING) {
-          points.push({ x, y });
-        }
-      }
-    }
-    return points;
-  } finally {
-    mat1.delete();
-    mat2.delete();
-    diff.delete();
-    blurred.delete();
-    binary.delete();
-    contours.delete();
-    hierarchy.delete();
-  }
+	const cv = cvLib;
+	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);
+		const ksize = new cv.Size(3, 3);
+		cv.GaussianBlur(diff, blurred, ksize, 0);
+		cv.threshold(blurred, binary, 30, 255, cv.THRESH_BINARY);
+		cv.findContours(binary, contours, hierarchy, cv.RETR_EXTERNAL, cv.CHAIN_APPROX_SIMPLE);
+		const points = [];
+		for (let c = 0; c < contours.size(); c++) {
+			const contour = contours.get(c);
+			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();
+	}
 }
 function computeInformationGain(clusters, clusterPoints, imageArea, animationIndices, animationWeights) {
-  if (clusters.length === 0) return 0;
-  let gain = 0;
-  for (let i = 0; i < clusters.length; i++) {
-    const box = clusters[i];
-    const clusterArea = box.width * box.height;
-    if (clusterArea <= 0) continue;
-    const normalizedArea = clusterArea / imageArea;
-    const featureDensity = clusterPoints[i] / clusterArea;
-    let contribution = normalizedArea * featureDensity;
-    if (animationIndices.has(i)) {
-      const animWeight = animationWeights[i] ?? 0;
-      contribution *= 1 - animWeight;
-    }
-    gain += contribution;
-  }
-  return gain;
+	if (clusters.length === 0) return 0;
+	let gain = 0;
+	for (let i = 0; i < clusters.length; i++) {
+		const box = clusters[i];
+		const clusterArea = box.width * box.height;
+		if (clusterArea <= 0) continue;
+		let contribution = clusterArea / imageArea * (clusterPoints[i] / clusterArea);
+		if (animationIndices.has(i)) {
+			const animWeight = animationWeights[i] ?? 0;
+			contribution *= 1 - animWeight;
+		}
+		gain += contribution;
+	}
+	return gain;
 }
-async function analyzeBatch(cvLib, frames, 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;
-        }
-      }
-      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
-      });
-    }
-  }
-  return edges;
+/**
+* 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 = [];
+	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 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();
+	}
 }
+/**
+* Analyze adjacent frame pairs to compute information gain scores (G(t)).
+* Processes frames in batches for memory efficiency.
+*
+* Pipeline:
+* 1. AKAZE Feature Set Difference
+* 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: [] };
-  logger.debug(
-    `Analyzing ${frames.length} frames in batches of ${OPENCV_BATCH_SIZE}`
-  );
-  const cvLib = await ensureOpenCV();
-  const edges = [];
-  const tracker = new IoUTracker(
-    ctx.options.fps,
-    ctx.options.iouThreshold,
-    ctx.options.animationThreshold
-  );
-  const scale = ctx.options.scale;
-  for (let i = 0; i < frames.length - 1; i += OPENCV_BATCH_SIZE) {
-    const batchEnd = Math.min(i + OPENCV_BATCH_SIZE + 1, frames.length);
-    const batch = frames.slice(i, batchEnd);
-    const batchEdges = await analyzeBatch(cvLib, batch, scale, tracker, i);
-    edges.push(...batchEdges);
-    const progress = Math.min(
-      100,
-      (i + OPENCV_BATCH_SIZE) / (frames.length - 1) * 100
-    );
-    ctx.emitProgress(progress);
-  }
-  const animations = tracker.flushAndGetAnimations();
-  logger.debug(
-    `Computed ${edges.length} score edges and ${animations.length} animations`
-  );
-  return { edges, animations };
+	const { frames } = ctx;
+	if (frames.length < 2) return {
+		edges: [],
+		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.effectiveFps ?? ctx.options.fps, ctx.options.iouThreshold, ctx.options.animationThreshold);
+	const scale = ctx.options.scale;
+	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,
+		analysisResolution
+	};
 }
 
-// src/core/extractor.ts
-import { readdir } from "fs/promises";
-import { join as join2 } from "path";
-import { path as ffprobePath } from "@ffprobe-installer/ffprobe";
-import { filter as filter2, map as map2 } from "@winglet/common-utils";
-import { execa } from "execa";
-import ffmpegPath from "ffmpeg-static";
+//#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)))
+				}
+			};
+		})
+	};
+}
 
-// src/utils/paths.ts
-import { mkdir, stat } from "fs/promises";
-import { homedir } from "os";
-import { basename, extname, resolve } from "path";
+//#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 });
+	await mkdir(dirPath, { recursive: true });
 }
 async function fileExists(filePath) {
-  try {
-    await stat(filePath);
-    return true;
-  } catch {
-    return false;
-  }
+	try {
+		await stat(filePath);
+		return true;
+	} catch {
+		return false;
+	}
 }
+/**
+* Expand leading ~ to homedir. Node's path.resolve() does not expand ~,
+* so paths like ~/Desktop/foo depend on process.cwd() and can produce
+* different results when run from different directories.
+*/
 function expandTilde(p) {
-  if (p === "~") return homedir();
-  if (p.startsWith("~/") || p.startsWith("~\\")) {
-    return resolve(homedir(), p.slice(2));
-  }
-  return p;
+	if (p === "~") return homedir();
+	if (p.startsWith("~/") || p.startsWith("~\\")) return resolve(homedir(), p.slice(2));
+	return p;
 }
+/**
+* Resolve path to absolute. Expands ~ to homedir first so that the result
+* does not depend on process.cwd().
+*/
 function resolveAbsolute(p) {
-  return resolve(expandTilde(p));
+	return resolve(expandTilde(p));
 }
+/**
+* Derive default output directory name from input file path.
+* e.g., /path/to/video.mp4 -> /path/to/video_scenes
+*/
 function deriveOutputPath(inputPath) {
-  const dir = resolve(inputPath, "..");
-  const name = basename(inputPath, extname(inputPath));
-  return resolve(dir, `${name}_scenes`);
+	return resolve(resolve(inputPath, ".."), `${basename(inputPath, extname(inputPath))}_scenes`);
 }
 
-// src/core/extractor.ts
+//#endregion
+//#region src/core/extractor/extractor.ts
+/**
+* Extract frames from video/GIF using FFmpeg.
+* @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) {
-  const framesDir = join2(ctx.workspacePath, "frames");
-  const { inputPath, fps, maxFrames, scale } = ctx.options;
-  if (!inputPath) {
-    throw new Error("inputPath is required for frame extraction");
-  }
-  const exists = await fileExists(inputPath);
-  if (!exists) {
-    throw new Error(`Input file not found: ${inputPath}`);
-  }
-  const metadata = await getVideoMetadata(inputPath).catch((err) => {
-    logger.debug(`ffprobe failed: ${err.message}`);
-    return null;
-  });
-  if (!metadata || !metadata.format) {
-    throw new Error(`Could not read file metadata: ${inputPath}`);
-  }
-  const formatName = metadata.format.format_name ?? "";
-  const duration = parseFloat(metadata.format.duration ?? "0");
-  const hasVideoStream = metadata.streams?.some((s) => s.codec_type === "video") ?? false;
-  if (!hasVideoStream) {
-    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);
-  let effectiveFps = fps;
-  if (duration > 0) {
-    const fpsCap = maxFrames / duration;
-    effectiveFps = Math.min(fps, fpsCap);
-    effectiveFps = Math.max(0.5, effectiveFps);
-    logger.debug(
-      `FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
-    );
-  }
-  const frames = await extractByFps(
-    inputPath,
-    framesDir,
-    effectiveFps,
-    scale,
-    duration
-  );
-  ctx.emitProgress(100);
-  logger.debug(`Extracted ${frames.length} frames`);
-  return frames;
+	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");
+	if (!await fileExists(inputPath)) throw new Error(`Input file not found: ${inputPath}`);
+	const metadata = await getVideoMetadata(inputPath).catch((err) => {
+		logger.debug(`ffprobe failed: ${err.message}`);
+		return null;
+	});
+	if (!metadata || !metadata.format) throw new Error(`Could not read file metadata: ${inputPath}`);
+	const formatName = metadata.format.format_name ?? "";
+	const duration = parseFloat(metadata.format.duration ?? "0");
+	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 = frameLimit / duration;
+		effectiveFps = Math.min(fps, fpsCap);
+		logger.debug(`FPS: ${fps} → effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`);
+	}
+	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) {
-  const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
-  await execa(ffmpegPath, [
-    "-i",
-    inputPath,
-    "-vf",
-    `fps=${fps},scale=-1:${scale}`,
-    "-q:v",
-    "2",
-    outputPattern
-  ]);
-  return buildFrameList(outputDir, 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",
+		inputPath,
+		"-vf",
+		`fps=${fps},scale=-1:${scale}`,
+		"-q:v",
+		"2",
+		"-frames:v",
+		String(frameLimit),
+		outputPattern
+	]);
+	return buildFrameList(outputDir, fps);
 }
 async function getVideoMetadata(inputPath) {
-  const { stdout } = await execa(ffprobePath, [
-    "-v",
-    "quiet",
-    "-print_format",
-    "json",
-    "-show_format",
-    "-show_streams",
-    inputPath
-  ]);
-  return JSON.parse(stdout);
+	const { stdout } = await execa(path, [
+		"-v",
+		"quiet",
+		"-print_format",
+		"json",
+		"-show_format",
+		"-show_streams",
+		inputPath
+	]);
+	return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, duration) {
-  const files = await readdir(framesDir);
-  const jpgFiles = filter2(files, (f) => f.endsWith(".jpg")).sort();
-  if (jpgFiles.length === 0) {
-    return [];
-  }
-  return map2(jpgFiles, (file, index) => ({
-    id: index,
-    timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
-    extractPath: join2(framesDir, file)
-  }));
+/**
+* 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: index / effectiveFps,
+		extractPath: join(framesDir, file)
+	}));
 }
-async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration) {
-  const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
-  await execa(ffmpegPath, [
-    "-ss",
-    String(startTime),
-    "-i",
-    inputPath,
-    "-t",
-    String(duration),
-    "-vf",
-    `fps=${fps},scale=-1:${scale}`,
-    "-q:v",
-    "2",
-    outputPattern
-  ]);
-  return buildFrameList(outputDir, duration);
+/**
+* Extract frames from a specific time range of a video using FFmpeg.
+* Uses input seeking (-ss before -i) for fast seek + -t for duration.
+*
+* @param inputPath - Path to the video file
+* @param outputDir - Directory to write extracted frames
+* @param fps - Frames per second for extraction
+* @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, frameLimit = Math.ceil(duration * fps)) {
+	const outputPattern = join(outputDir, FRAME_FILENAME_PATTERN);
+	await execa(ffmpegPath, [
+		"-ss",
+		String(startTime),
+		"-i",
+		inputPath,
+		"-t",
+		String(duration),
+		"-vf",
+		`fps=${fps},scale=-1:${scale}`,
+		"-q:v",
+		"2",
+		"-frames:v",
+		String(frameLimit),
+		outputPattern
+	]);
+	return buildFrameList(outputDir, fps);
 }
 
-// src/core/input-resolver.ts
-import { join as join4 } from "path";
+//#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}`);
+	}
+}
 
-// src/core/workspace.ts
-import { readdir as readdir2, rename, rm, stat as stat2, writeFile } from "fs/promises";
-import { join as join3 } from "path";
-import { map as map3 } from "@winglet/common-utils";
-import sharp2 from "sharp";
+//#endregion
+//#region src/core/workspace/workspace.ts
 async function createWorkspace(sessionId) {
-  const workspacePath = getTempWorkspaceDir(sessionId);
-  await ensureDir(join3(workspacePath, "frames"));
-  await ensureDir(join3(workspacePath, "output"));
-  return workspacePath;
+	const workspacePath = getTempWorkspaceDir(sessionId);
+	await ensureDir(join(workspacePath, "frames"));
+	await ensureDir(join(workspacePath, "output"));
+	return workspacePath;
 }
 async function finalizeOutput(ctx, selectedFrames) {
-  const stagingDir = join3(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 = join3(stagingDir, fileName);
-    await sharp2(frame.extractPath).jpeg({ quality, mozjpeg: true }).toFile(destPath);
-    outputFiles.push(join3(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: map3(ctx.animations || [], (anim) => ({
-      ...anim,
-      startFrameId: anim.startFrameId + 1,
-      endFrameId: anim.endFrameId + 1,
-      durationMs: Math.round(anim.durationMs)
-    }))
-  };
-  const metadataPath = join3(stagingDir, ".metadata.json");
-  await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
-  outputFiles.push(join3(outputPath, ".metadata.json"));
-  await ensureDir(join3(outputPath, ".."));
-  await rm(outputPath, { recursive: true, force: true });
-  await rename(stagingDir, outputPath);
-  return outputFiles;
+	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 { video, animations } = await buildVideoMetadata(ctx, selectedFrames, ctx.analysisResolution);
+	const metadata = {
+		video,
+		frames: framesMetadata,
+		animations: map(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 = join3(
-    parentWorkspacePath,
-    "segments",
-    String(segmentIndex)
-  );
-  await ensureDir(join3(segmentPath, "frames"));
-  return segmentPath;
+	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 {
-  }
+	if (!workspacePath) return;
+	try {
+		await rm(workspacePath, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
 }
-var STALE_THRESHOLD_MS = 60 * 60 * 1e3;
+/**
+* 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 = join3(workspacePath, "input");
-  await ensureDir(inputDir);
-  const tempPath = join3(inputDir, "input.mp4");
-  await writeFile(tempPath, buffer);
-  return tempPath;
+	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 = join3(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 = join3(framesDir, filename);
-    await writeFile(extractPath, frames[i]);
-    frameNodes.push({ id: i, timestamp: i, extractPath });
-  }
-  return frameNodes;
+	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
+		});
+	}
+	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(
-    map3(
-      frameNodes,
-      (f) => sharp2(f.extractPath).jpeg({ quality, mozjpeg: true }).toBuffer()
-    )
-  );
+	return Promise.all(map(frameNodes, (f) => sharp(f.extractPath).jpeg({
+		quality,
+		mozjpeg: true
+	}).toBuffer()));
 }
 
-// src/core/input-resolver.ts
-function resolveOptions(options2) {
-  const mode = options2.mode;
-  const inputPath = mode === "file" ? resolveAbsolute(options2.inputPath) : void 0;
-  const outputPath = options2.outputPath ?? (inputPath ? deriveOutputPath(inputPath) : join4(process.cwd(), "scene-sieve-output"));
-  const threshold = options2.threshold ?? DEFAULT_THRESHOLD;
-  if (threshold <= 0 || threshold > 1) {
-    throw new Error(
-      `threshold must be in range (0, 1], received: ${threshold}`
-    );
-  }
-  const pruneMode = "threshold-with-cap";
-  return {
-    mode,
-    inputPath,
-    count: options2.count ?? DEFAULT_COUNT,
-    threshold,
-    pruneMode,
-    outputPath,
-    fps: options2.fps ?? DEFAULT_FPS,
-    maxFrames: options2.maxFrames ?? DEFAULT_MAX_FRAMES,
-    scale: options2.scale ?? DEFAULT_SCALE,
-    quality: options2.quality ?? DEFAULT_QUALITY,
-    iouThreshold: options2.iouThreshold ?? IOU_THRESHOLD,
-    animationThreshold: options2.animationThreshold ?? ANIMATION_FRAME_THRESHOLD,
-    debug: options2.debug ?? false,
-    maxSegmentDuration: options2.maxSegmentDuration ?? DEFAULT_MAX_SEGMENT_DURATION,
-    concurrency: options2.concurrency ?? DEFAULT_SEGMENT_CONCURRENCY
-  };
+//#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;
+	return {
+		mode,
+		inputPath,
+		count: options.count ?? 20,
+		threshold,
+		pruneMode: "threshold-with-cap",
+		outputPath,
+		fps: options.fps ?? 5,
+		maxFrames: options.maxFrames ?? 300,
+		scale: options.scale ?? 720,
+		quality: options.quality ?? 80,
+		iouThreshold: options.iouThreshold ?? .9,
+		animationThreshold: options.animationThreshold ?? 5,
+		debug: options.debug ?? false,
+		maxSegmentDuration: options.maxSegmentDuration ?? 300,
+		concurrency: options.concurrency ?? 2
+	};
 }
-async function resolveInput(options2, workspacePath) {
-  if (options2.mode === "file") {
-    return {
-      frames: [],
-      resolvedInputPath: resolveAbsolute(options2.inputPath)
-    };
-  }
-  if (options2.mode === "buffer") {
-    const resolvedInputPath = await writeInputBuffer(
-      options2.inputBuffer,
-      workspacePath
-    );
-    return { frames: [], resolvedInputPath };
-  }
-  if (options2.mode === "frames") {
-    const frames = await writeInputFrames(options2.inputFrames, workspacePath);
-    return { frames };
-  }
-  throw new Error(`Unsupported input mode: ${options2.mode}`);
+/**
+* Resolve the input source to a list of FrameNode[].
+*
+* - '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 {
+		frames: [],
+		resolvedInputPath: resolveAbsolute(options.inputPath)
+	};
+	if (options.mode === "buffer") return {
+		frames: [],
+		resolvedInputPath: await writeInputBuffer(options.inputBuffer, 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}`);
 }
 
-// src/core/pruner.ts
-import { filter as filter4, map as map5 } from "@winglet/common-utils";
-
-// src/utils/math.ts
-import { filter as filter3, map as map4 } from "@winglet/common-utils";
+//#endregion
+//#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.
+*
+* This model combines two mathematical approaches to provide a stable "relative" threshold:
+*
+* 1. Logistic-Robust-Z (Intensity):
+*    Calculates Z-scores using Median and Median Absolute Deviation (MAD).
+*    Maps these to a sigmoid (logistic) curve. This suppresses noise (scores near median)
+*    and highlights significant signals (outliers) without letting extreme outliers
+*    crush other meaningful transitions.
+*
+* 2. CDF / Percentile Rank (Relative Position):
+*    Maps each score to its percentile rank in the sequence. This ensures that 't'
+*    always has a consistent meaning as a "relative rank" regardless of absolute values.
+*
+* The final score is a weighted sum (NORMALIZATION_ALPHA) of both.
+*
+* @param items - Array of items with scores to normalize
+* @returns normalized scores array (same length as input)
+*/
 function normalizeScores(items) {
-  if (items.length === 0) return [];
-  const safeScores = map4(
-    items,
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const positiveScores = filter3(safeScores, (s) => s > 0);
-  if (positiveScores.length === 0) return safeScores;
-  const sorted = [...positiveScores].sort((a, b) => a - b);
-  if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
-    const min = sorted[0];
-    const max = sorted[sorted.length - 1];
-    if (max === min) return map4(safeScores, (s) => s > 0 ? 1 : 0);
-    return map4(
-      safeScores,
-      (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
-    );
-  }
-  const median = sorted[Math.floor(sorted.length / 2)];
-  const absoluteDiffs = map4(positiveScores, (v) => Math.abs(v - median));
-  const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
-  const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
-  const logisticZ = map4(safeScores, (s) => {
-    if (s <= 0) return 0;
-    if (scale === 0) return 1;
-    const z = (s - median) / scale;
-    return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
-  });
-  const cdf = map4(safeScores, (s) => {
-    if (s <= 0) return 0;
-    const rank = sorted.findIndex((v) => v >= s);
-    return rank / sorted.length;
-  });
-  return map4(
-    logisticZ,
-    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
-  );
+	if (items.length === 0) return [];
+	const safeScores = map(items, (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0);
+	const positiveScores = filter(safeScores, (s) => s > 0);
+	if (positiveScores.length === 0) return safeScores;
+	const sorted = [...positiveScores].sort((a, b) => a - b);
+	if (positiveScores.length <= 10) {
+		const min = sorted[0];
+		const max = sorted[sorted.length - 1];
+		if (max === min) return map(safeScores, (s) => s > 0 ? 1 : 0);
+		return map(safeScores, (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1)));
+	}
+	const median = sorted[Math.floor(sorted.length / 2)];
+	const absoluteDiffs = map(positiveScores, (v) => Math.abs(v - median));
+	const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
+	const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
+	const logisticZ = map(safeScores, (s) => {
+		if (s <= 0) return 0;
+		if (scale === 0) return 1;
+		const z = (s - median) / scale;
+		return 1 / (1 + Math.exp(-3 * z));
+	});
+	const cdf = map(safeScores, (s) => {
+		if (s <= 0) return 0;
+		return lowerBound(sorted, s) / sorted.length;
+	});
+	return map(logisticZ, (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA);
 }
 
-// src/utils/min-heap.ts
+//#endregion
+//#region src/core/pruner/heap/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);
-    }
-    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;
-    }
-  }
+	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);
+		}
+		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;
+		}
+	}
 };
 
-// src/core/pruner.ts
+//#endregion
+//#region src/core/pruner/pruner.ts
+/**
+* Edge-aware greedy merge with re-linking — O(N log N).
+*
+* 1. Build a doubly-linked list of frames
+* 2. Insert all edges into a min-heap
+* 3. Pop the lowest-score edge (most similar pair)
+* 4. Remove the later frame (tgtId), re-link neighbors
+* 5. Push synthetic edge with score = max(left, right)
+* 6. Repeat until surviving count === targetCount
+* 7. First and last frames are never removed (boundary preservation)
+*
+* Stale heap entries (involving removed frames) are lazily skipped on pop.
+*/
 function pruneTo(graph, frames, targetCount) {
-  if (frames.length <= targetCount) {
-    return new Set(map5(frames, (f) => f.id));
-  }
-  const prev = /* @__PURE__ */ new Map();
-  const next = /* @__PURE__ */ new Map();
-  for (let i = 0; i < frames.length; i++) {
-    if (i > 0) prev.set(frames[i].id, frames[i - 1].id);
-    if (i < frames.length - 1) next.set(frames[i].id, frames[i + 1].id);
-  }
-  const edgeScore = /* @__PURE__ */ new Map();
-  const heap = new MinHeap();
-  for (const edge of graph) {
-    edgeScore.set(`${edge.sourceId}:${edge.targetId}`, edge.score);
-    heap.push({
-      score: edge.score,
-      srcId: edge.sourceId,
-      tgtId: edge.targetId
-    });
-  }
-  const surviving = new Set(map5(frames, (f) => f.id));
-  const firstId = frames[0].id;
-  const lastId = frames[frames.length - 1].id;
-  while (surviving.size > targetCount && heap.size > 0) {
-    const entry = heap.pop();
-    if (!surviving.has(entry.srcId) || !surviving.has(entry.tgtId)) continue;
-    const key = `${entry.srcId}:${entry.tgtId}`;
-    if (edgeScore.get(key) !== entry.score) continue;
-    if (entry.tgtId === firstId || entry.tgtId === lastId) continue;
-    surviving.delete(entry.tgtId);
-    edgeScore.delete(key);
-    const tgtNext = next.get(entry.tgtId);
-    if (tgtNext !== void 0) {
-      const rightKey = `${entry.tgtId}:${tgtNext}`;
-      const rightScore = edgeScore.get(rightKey) ?? 0;
-      edgeScore.delete(rightKey);
-      const newScore = Math.max(entry.score, rightScore);
-      edgeScore.set(`${entry.srcId}:${tgtNext}`, newScore);
-      heap.push({ score: newScore, srcId: entry.srcId, tgtId: tgtNext });
-      next.set(entry.srcId, tgtNext);
-      prev.set(tgtNext, entry.srcId);
-    } else {
-      next.delete(entry.srcId);
-    }
-    prev.delete(entry.tgtId);
-    next.delete(entry.tgtId);
-  }
-  return surviving;
+	if (frames.length <= targetCount) return new Set(map(frames, (f) => f.id));
+	const prev = /* @__PURE__ */ new Map();
+	const next = /* @__PURE__ */ new Map();
+	for (let i = 0; i < frames.length; i++) {
+		if (i > 0) prev.set(frames[i].id, frames[i - 1].id);
+		if (i < frames.length - 1) next.set(frames[i].id, frames[i + 1].id);
+	}
+	const edgeScore = /* @__PURE__ */ new Map();
+	const heap = new MinHeap();
+	for (const edge of graph) {
+		edgeScore.set(`${edge.sourceId}:${edge.targetId}`, edge.score);
+		heap.push({
+			score: edge.score,
+			srcId: edge.sourceId,
+			tgtId: edge.targetId
+		});
+	}
+	const surviving = new Set(map(frames, (f) => f.id));
+	const firstId = frames[0].id;
+	const lastId = frames[frames.length - 1].id;
+	while (surviving.size > targetCount && heap.size > 0) {
+		const entry = heap.pop();
+		if (!surviving.has(entry.srcId) || !surviving.has(entry.tgtId)) continue;
+		const key = `${entry.srcId}:${entry.tgtId}`;
+		if (edgeScore.get(key) !== entry.score) continue;
+		if (entry.tgtId === firstId || entry.tgtId === lastId) continue;
+		surviving.delete(entry.tgtId);
+		edgeScore.delete(key);
+		const tgtNext = next.get(entry.tgtId);
+		if (tgtNext !== void 0) {
+			const rightKey = `${entry.tgtId}:${tgtNext}`;
+			const rightScore = edgeScore.get(rightKey) ?? 0;
+			edgeScore.delete(rightKey);
+			const newScore = Math.max(entry.score, rightScore);
+			edgeScore.set(`${entry.srcId}:${tgtNext}`, newScore);
+			heap.push({
+				score: newScore,
+				srcId: entry.srcId,
+				tgtId: tgtNext
+			});
+			next.set(entry.srcId, tgtNext);
+			prev.set(tgtNext, entry.srcId);
+		} else next.delete(entry.srcId);
+		prev.delete(entry.tgtId);
+		next.delete(entry.tgtId);
+	}
+	return surviving;
 }
+/**
+* Non-Maximum Suppression (NMS) for consecutive edge runs.
+*
+* Consecutive edges share overlapping frames (edge i: frame i->i+1,
+* edge i+1: frame i+1->i+2), so consecutive passing edges indicate
+* the same visual transition region. This function groups consecutive
+* passing edge indices into "runs" and keeps all distinct peaks per run.
+*
+* Multi-peak detection: within each run, strict local maxima (score higher
+* than both neighbors) are identified. Each local maximum represents a
+* distinct visual transition. If no strict local maxima exist (plateau or
+* monotonic sequence), the global peak of the run is selected as fallback.
+*
+* Single-element runs are unaffected (isolated transitions preserved).
+*
+* @param graph - full ScoreEdge array (for targetId lookup)
+* @param passingIndices - edge indices that passed threshold filtering (sorted ascending)
+* @param normalizedScores - normalized score array (same length as graph)
+* @returns Set of targetIds to add to surviving set (one or more per run)
+*/
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
-  const result = /* @__PURE__ */ new Set();
-  let runStart = 0;
-  while (runStart < passingIndices.length) {
-    let runEnd = runStart;
-    while (runEnd + 1 < passingIndices.length && passingIndices[runEnd + 1] === passingIndices[runEnd] + 1) {
-      runEnd++;
-    }
-    const runLen = runEnd - runStart + 1;
-    if (runLen === 1) {
-      result.add(graph[passingIndices[runStart]].targetId);
-    } else {
-      const peaks = [];
-      for (let j = runStart; j <= runEnd; j++) {
-        const idx = passingIndices[j];
-        const score = normalizedScores[idx];
-        const prevScore = j > runStart ? normalizedScores[passingIndices[j - 1]] : -Infinity;
-        const nextScore = j < runEnd ? normalizedScores[passingIndices[j + 1]] : -Infinity;
-        if (score > prevScore && score > nextScore) {
-          peaks.push(idx);
-        }
-      }
-      if (peaks.length > 0) {
-        for (const peakIdx of peaks) {
-          result.add(graph[peakIdx].targetId);
-        }
-      } else {
-        let peakIdx = passingIndices[runStart];
-        for (let j = runStart + 1; j <= runEnd; j++) {
-          const idx = passingIndices[j];
-          if (normalizedScores[idx] > normalizedScores[peakIdx]) {
-            peakIdx = idx;
-          }
-        }
-        result.add(graph[peakIdx].targetId);
-      }
-    }
-    runStart = runEnd + 1;
-  }
-  return result;
+	const result = /* @__PURE__ */ new Set();
+	let runStart = 0;
+	while (runStart < passingIndices.length) {
+		let runEnd = runStart;
+		while (runEnd + 1 < passingIndices.length && passingIndices[runEnd + 1] === passingIndices[runEnd] + 1) runEnd++;
+		if (runEnd - runStart + 1 === 1) result.add(graph[passingIndices[runStart]].targetId);
+		else {
+			const peaks = [];
+			for (let j = runStart; j <= runEnd; j++) {
+				const idx = passingIndices[j];
+				const score = normalizedScores[idx];
+				const prevScore = j > runStart ? normalizedScores[passingIndices[j - 1]] : -Infinity;
+				const nextScore = j < runEnd ? normalizedScores[passingIndices[j + 1]] : -Infinity;
+				if (score > prevScore && score > nextScore) peaks.push(idx);
+			}
+			if (peaks.length > 0) for (const peakIdx of peaks) result.add(graph[peakIdx].targetId);
+			else {
+				let peakIdx = passingIndices[runStart];
+				for (let j = runStart + 1; j <= runEnd; j++) {
+					const idx = passingIndices[j];
+					if (normalizedScores[idx] > normalizedScores[peakIdx]) peakIdx = idx;
+				}
+				result.add(graph[peakIdx].targetId);
+			}
+		}
+		runStart = runEnd + 1;
+	}
+	return result;
 }
+/**
+* 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.
+* 3. Non-Maximum Suppression groups consecutive passing edges and keeps
+*    only the peak per run, preventing near-duplicate frame selection
+*    from a single visual transition.
+*
+* First and last frames are always preserved (boundary protection).
+*/
 function pruneByThreshold(graph, frames, threshold) {
-  if (frames.length === 0) return /* @__PURE__ */ new Set();
-  const surviving = /* @__PURE__ */ new Set();
-  surviving.add(frames[0].id);
-  surviving.add(frames[frames.length - 1].id);
-  const normalized = normalizeScores(graph);
-  const passingIndices = [];
-  for (let i = 0; i < graph.length; i++) {
-    if (normalized[i] >= threshold) {
-      passingIndices.push(i);
-    }
-  }
-  const nmsTargets = suppressConsecutiveRuns(graph, passingIndices, normalized);
-  for (const id of nmsTargets) {
-    surviving.add(id);
-  }
-  return surviving;
+	if (frames.length === 0) return /* @__PURE__ */ new Set();
+	const surviving = /* @__PURE__ */ new Set();
+	surviving.add(frames[0].id);
+	surviving.add(frames[frames.length - 1].id);
+	const normalized = normalizeScores(graph);
+	const passingIndices = [];
+	for (let i = 0; i < graph.length; i++) if (normalized[i] >= threshold) passingIndices.push(i);
+	const nmsTargets = suppressConsecutiveRuns(graph, passingIndices, normalized);
+	for (const id of nmsTargets) surviving.add(id);
+	return surviving;
 }
+/**
+* Combined threshold + count pruning -- 2-stage pipeline.
+*
+* Stage 1: pruneByThreshold -- keep all frames with normalized score >= threshold
+* Stage 2: if result exceeds maxCount, rebuild subgraph with synthetic edges
+*          (min-score over each gap) and apply pruneTo on the surviving subset
+*
+* Edge reconstruction: for consecutive survivors A, B with removed frames
+* [x1, x2, ...] between them, the synthetic edge score is:
+*   min(score(A->x1), score(x1->x2), ..., score(xN->B))
+* This preserves the "weakest link" semantics.
+*/
 function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
-  const thresholdSurvivors = pruneByThreshold(graph, frames, threshold);
-  if (thresholdSurvivors.size <= maxCount) {
-    return thresholdSurvivors;
-  }
-  const survivingFrames = filter4(frames, (f) => thresholdSurvivors.has(f.id));
-  const idToOrigIdx = /* @__PURE__ */ new Map();
-  for (let i = 0; i < frames.length; i++) {
-    idToOrigIdx.set(frames[i].id, i);
-  }
-  const edgeLookup = /* @__PURE__ */ new Map();
-  for (const e of graph) {
-    edgeLookup.set(`${e.sourceId}:${e.targetId}`, e.score);
-  }
-  const syntheticEdges = [];
-  for (let i = 0; i < survivingFrames.length - 1; i++) {
-    const srcSurvivor = survivingFrames[i];
-    const tgtSurvivor = survivingFrames[i + 1];
-    const srcOrigIdx = idToOrigIdx.get(srcSurvivor.id);
-    const tgtOrigIdx = idToOrigIdx.get(tgtSurvivor.id);
-    let minScore = Infinity;
-    for (let j = srcOrigIdx; j < tgtOrigIdx; j++) {
-      const fromId = frames[j].id;
-      const toId = frames[j + 1].id;
-      const score = edgeLookup.get(`${fromId}:${toId}`) ?? 0;
-      if (score < minScore) {
-        minScore = score;
-      }
-    }
-    syntheticEdges.push({
-      sourceId: srcSurvivor.id,
-      targetId: tgtSurvivor.id,
-      score: minScore === Infinity ? 0 : minScore
-    });
-  }
-  return pruneTo(syntheticEdges, survivingFrames, maxCount);
+	const thresholdSurvivors = pruneByThreshold(graph, frames, threshold);
+	if (thresholdSurvivors.size <= maxCount) return thresholdSurvivors;
+	const survivingFrames = filter(frames, (f) => thresholdSurvivors.has(f.id));
+	const idToOrigIdx = /* @__PURE__ */ new Map();
+	for (let i = 0; i < frames.length; i++) idToOrigIdx.set(frames[i].id, i);
+	const edgeLookup = /* @__PURE__ */ new Map();
+	for (const e of graph) edgeLookup.set(`${e.sourceId}:${e.targetId}`, e.score);
+	const syntheticEdges = [];
+	for (let i = 0; i < survivingFrames.length - 1; i++) {
+		const srcSurvivor = survivingFrames[i];
+		const tgtSurvivor = survivingFrames[i + 1];
+		const srcOrigIdx = idToOrigIdx.get(srcSurvivor.id);
+		const tgtOrigIdx = idToOrigIdx.get(tgtSurvivor.id);
+		let minScore = Infinity;
+		for (let j = srcOrigIdx; j < tgtOrigIdx; j++) {
+			const fromId = frames[j].id;
+			const toId = frames[j + 1].id;
+			const score = edgeLookup.get(`${fromId}:${toId}`) ?? 0;
+			if (score < minScore) minScore = score;
+		}
+		syntheticEdges.push({
+			sourceId: srcSurvivor.id,
+			targetId: tgtSurvivor.id,
+			score: minScore === Infinity ? 0 : minScore
+		});
+	}
+	return pruneTo(syntheticEdges, survivingFrames, maxCount);
 }
 
-// src/core/segmenter.ts
-import { randomUUID } from "crypto";
-import { join as join5 } from "path";
-import { filter as filter5, map as map6 } from "@winglet/common-utils";
-
-// src/utils/concurrency.ts
+//#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.
+*/
 function concurrencyLimit(limit) {
-  limit = Math.max(1, limit);
-  let active = 0;
-  const queue = [];
-  return async (fn) => {
-    while (active >= limit) {
-      await new Promise((resolve2) => queue.push(resolve2));
-    }
-    active++;
-    try {
-      return await fn();
-    } finally {
-      active--;
-      queue.shift()?.();
-    }
-  };
+	limit = Math.max(1, limit);
+	let active = 0;
+	const queue = [];
+	return async (fn) => {
+		while (active >= limit) await new Promise((resolve) => queue.push(resolve));
+		active++;
+		try {
+			return await fn();
+		} finally {
+			active--;
+			queue.shift()?.();
+		}
+	};
 }
 
-// src/core/segmenter.ts
+//#endregion
+//#region src/core/segmenter/segmenter.ts
+/**
+* Determine whether segmentation should be used.
+* Returns false for frames mode and GIF files.
+* Actual duration check happens inside runSegmentedPipeline after metadata fetch.
+*/
 function shouldSegment(resolvedOptions, originalOptions) {
-  if (resolvedOptions.mode === "frames") return false;
-  if (originalOptions.mode === "file") {
-    if (originalOptions.inputPath.toLowerCase().endsWith(".gif")) return false;
-  }
-  return true;
+	if (resolvedOptions.mode === "frames") return false;
+	if (originalOptions.mode === "file") {
+		if (originalOptions.inputPath.toLowerCase().endsWith(".gif")) return false;
+	}
+	return true;
 }
+/**
+* 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(0.5, Math.min(fps, maxFrames / totalDuration));
-  if (totalDuration <= maxSegmentDuration) {
-    return [
-      {
-        index: 0,
-        startTime: 0,
-        endTime: totalDuration,
-        duration: totalDuration,
-        allocatedFrames: Math.min(
-          Math.ceil(effectiveFps * totalDuration),
-          maxFrames
-        ),
-        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 extractEndTime = Math.min(
-      totalDuration,
-      endTime + overlapAfter * overlapTime
-    );
-    const extractDuration = extractEndTime - extractStartTime;
-    segments.push({
-      index: i,
-      startTime,
-      endTime,
-      duration,
-      allocatedFrames: Math.ceil(effectiveFps * duration),
-      effectiveFps,
-      overlapBefore,
-      overlapAfter,
-      extractStartTime,
-      extractDuration
-    });
-  }
-  const totalAllocated = segments.reduce(
-    (sum, s) => sum + s.allocatedFrames,
-    0
-  );
-  if (totalAllocated > maxFrames) {
-    segments[segments.length - 1].allocatedFrames -= totalAllocated - maxFrames;
-  }
-  return segments;
+	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: frameLimit,
+		effectiveFps,
+		overlapBefore: 0,
+		overlapAfter: 0,
+		extractStartTime: 0,
+		extractDuration: totalDuration
+	}];
+	const segments = [];
+	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: segments.length,
+			startTime,
+			endTime,
+			duration: endTime - startTime,
+			allocatedFrames: 1,
+			effectiveFps,
+			overlapBefore: 0,
+			overlapAfter: 0,
+			extractStartTime: timestamp,
+			extractDuration: 0
+		});
+	}
+	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;
 }
+/**
+* Collect all frames from every segment, adjusting timestamps by extractStartTime.
+*/
 function collectAllFrames(segmentResults) {
-  const allFrames = [];
-  for (const result of segmentResults) {
-    for (const frame of result.frames) {
-      allFrames.push({
-        frame: {
-          ...frame,
-          // Use extractStartTime for timestamp correction (Section 18 note 1)
-          timestamp: frame.timestamp + result.segment.extractStartTime
-        },
-        segmentIndex: result.segment.index,
-        localId: frame.id
-      });
-    }
-  }
-  return allFrames;
+	const allFrames = [];
+	for (const result of segmentResults) for (const frame of result.frames) allFrames.push({
+		frame: {
+			...frame,
+			timestamp: frame.timestamp + result.segment.extractStartTime
+		},
+		segmentIndex: result.segment.index,
+		localId: frame.id
+	});
+	return allFrames;
 }
+/**
+* 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 = [];
-  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;
-      }
-    }
-    unique.push(entry);
-  }
-  return unique;
+	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) {
+				aliases.set(`${entry.segmentIndex}:${entry.localId}`, `${last.segmentIndex}:${last.localId}`);
+				continue;
+			}
+		}
+		unique.push(entry);
+	}
+	return {
+		unique,
+		aliases
+	};
 }
-function remapFrameIds(uniqueFrames) {
-  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
-    };
-  });
-  return { frames, globalIdMap };
+/**
+* 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, 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,
+		globalIdMap
+	};
 }
+/**
+* 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 = [];
-  const edgeMap = /* @__PURE__ */ new Map();
-  for (const result of segmentResults) {
-    for (const edge of result.edges) {
-      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;
-      const edgeKey = `${newSourceId}-${newTargetId}`;
-      const existingIdx = edgeMap.get(edgeKey);
-      if (existingIdx !== void 0) {
-        if (edges[existingIdx].score < edge.score) {
-          edges[existingIdx] = {
-            sourceId: newSourceId,
-            targetId: newTargetId,
-            score: edge.score
-          };
-        }
-      } else {
-        edgeMap.set(edgeKey, edges.length);
-        edges.push({
-          sourceId: newSourceId,
-          targetId: newTargetId,
-          score: edge.score
-        });
-      }
-    }
-  }
-  return edges;
+	const edges = [];
+	const edgeMap = /* @__PURE__ */ new Map();
+	for (const result of segmentResults) for (const edge of result.edges) {
+		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] = {
+				sourceId: newSourceId,
+				targetId: newTargetId,
+				score: edge.score
+			};
+		} else {
+			edgeMap.set(edgeKey, edges.length);
+			edges.push({
+				sourceId: newSourceId,
+				targetId: newTargetId,
+				score: edge.score
+			});
+		}
+	}
+	return edges;
 }
+/**
+* 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 = [];
-  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({
-        ...anim,
-        startFrameId: newStartId,
-        endFrameId: newEndId
-      });
-    }
-  }
-  return 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;
+		if (newStartId === newEndId) continue;
+		const animationKey = `${newStartId}-${newEndId}`;
+		if (animations.has(animationKey)) continue;
+		animations.set(animationKey, {
+			...anim,
+			startFrameId: newStartId,
+			endFrameId: newEndId
+		});
+	}
+	return [...animations.values()];
 }
+/**
+* Merge multiple segment results into a single unified frame/edge/animation set.
+* @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: [] };
-  }
-  const effectiveFps = segmentResults[0].segment.effectiveFps;
-  const allFrames = collectAllFrames(segmentResults);
-  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
-  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
-  const edges = remapEdges(segmentResults, globalIdMap);
-  const animations = remapAnimations(segmentResults, globalIdMap);
-  return { frames, edges, animations };
+	if (segmentResults.length === 0) return {
+		frames: [],
+		edges: [],
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
+	};
+	const effectiveFps = segmentResults[0].segment.effectiveFps;
+	const { unique, aliases } = deduplicateFrames(collectAllFrames(segmentResults), effectiveFps);
+	const { frames, globalIdMap } = remapFrameIds(unique, aliases);
+	return {
+		frames,
+		edges: remapEdges(segmentResults, globalIdMap),
+		animations: remapAnimations(segmentResults, globalIdMap),
+		analysisResolution: segmentResults[0].analysisResolution
+	};
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {
-  return {
-    options: {
-      ...resolvedOptions,
-      fps: segment.effectiveFps,
-      maxFrames: segment.allocatedFrames
-    },
-    workspacePath: segmentWorkspacePath,
-    frames,
-    graph: [],
-    status: "ANALYZING",
-    emitProgress: onProgress
-  };
+	return {
+		options: {
+			...resolvedOptions,
+			fps: segment.effectiveFps,
+			maxFrames: segment.allocatedFrames
+		},
+		workspacePath: segmentWorkspacePath,
+		effectiveFps: segment.effectiveFps,
+		frames,
+		graph: [],
+		status: "ANALYZING",
+		emitProgress: onProgress
+	};
 }
+/**
+* Extract frames for a single segment and analyze them.
+* Each segment uses an isolated workspace directory.
+*/
 async function processSegment(inputPath, segment, workspacePath, resolvedOptions, onProgress) {
-  const framesDir = join5(workspacePath, "frames");
-  const frames = await extractFramesForRange(
-    inputPath,
-    framesDir,
-    segment.effectiveFps,
-    resolvedOptions.scale,
-    segment.extractStartTime,
-    segment.extractDuration
-  );
-  if (frames.length < 2) {
-    return { segment, frames, edges: [], animations: [] };
-  }
-  const ctx = buildSegmentContext(
-    segment,
-    frames,
-    workspacePath,
-    resolvedOptions,
-    onProgress
-  );
-  const { edges, animations } = await analyzeFrames(ctx);
-  return { segment, frames, edges, animations };
+	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: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
+	};
+	const { edges, animations, analysisResolution } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
+	return {
+		segment,
+		frames,
+		edges,
+		animations,
+		analysisResolution
+	};
 }
-async function runSegmentedPipeline(options2, resolvedOptions) {
-  const pipelineStart = Date.now();
-  const sessionId = randomUUID();
-  let mainWorkspace = "";
-  try {
-    mainWorkspace = await createWorkspace(sessionId);
-    logger.debug(`Segmented pipeline: workspace at ${mainWorkspace}`);
-    const { resolvedInputPath } = await resolveInput(options2, mainWorkspace);
-    const inputPath = resolvedInputPath ?? resolvedOptions.inputPath;
-    if (!inputPath) {
-      throw new Error("No input path available for segmented pipeline");
-    }
-    const metadata = await getVideoMetadata(inputPath);
-    const totalDuration = parseFloat(metadata.format?.duration ?? "0");
-    if (totalDuration <= 0) {
-      throw new Error(`Invalid video duration: ${totalDuration}`);
-    }
-    logger.debug(`Video duration: ${totalDuration}s`);
-    const segments = computeSegmentPlan(
-      totalDuration,
-      resolvedOptions.maxSegmentDuration,
-      resolvedOptions.maxFrames,
-      resolvedOptions.fps
-    );
-    logger.debug(`Segment plan: ${segments.length} segments`);
-    const limit = concurrencyLimit(resolvedOptions.concurrency);
-    const segmentProgresses = new Array(segments.length).fill(0);
-    const weights = map6(segments, (s) => s.duration / totalDuration);
-    const emitOverallProgress = (phase) => {
-      if (!options2.onProgress) return;
-      const overall = weights.reduce(
-        (sum, w, i) => sum + w * (segmentProgresses[i] ?? 0),
-        0
-      );
-      options2.onProgress(phase, Math.min(100, overall));
-    };
-    options2.onProgress?.("EXTRACTING", 0);
-    const results = await Promise.all(
-      map6(
-        segments,
-        (segment) => limit(async () => {
-          const segWorkspace = await createSegmentWorkspace(
-            mainWorkspace,
-            segment.index
-          );
-          const result = await processSegment(
-            inputPath,
-            segment,
-            segWorkspace,
-            resolvedOptions,
-            (percent) => {
-              segmentProgresses[segment.index] = percent;
-              emitOverallProgress("ANALYZING");
-            }
-          );
-          return result;
-        })
-      )
-    );
-    options2.onProgress?.("ANALYZING", 100);
-    const { frames, edges, animations } = mergeSegmentFrames(results);
-    logger.debug(
-      `Merged: ${frames.length} frames, ${edges.length} edges, ${animations.length} animations`
-    );
-    options2.onProgress?.("PRUNING", 0);
-    const survivingIds = pruneByThresholdWithCap(
-      edges,
-      frames,
-      resolvedOptions.threshold,
-      resolvedOptions.count
-    );
-    const prunedFrames = filter5(frames, (f) => survivingIds.has(f.id));
-    options2.onProgress?.("PRUNING", 100);
-    options2.onProgress?.("FINALIZING", 0);
-    const ctx = {
-      options: resolvedOptions,
-      workspacePath: mainWorkspace,
-      frames,
-      graph: edges,
-      animations,
-      status: "FINALIZING",
-      emitProgress: (percent) => options2.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);
-    }
-    options2.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)
-        }
-      },
-      executionTimeMs: Date.now() - pipelineStart
-    };
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    logger.error(`Segmented pipeline failed: ${err.message}`);
-    throw err;
-  } finally {
-    if (!resolvedOptions.debug) {
-      await cleanupWorkspace(mainWorkspace);
-    } else {
-      logger.debug(`Debug mode: workspace preserved at ${mainWorkspace}`);
-    }
-  }
+/**
+* Full segmented pipeline: metadata → plan → parallel extract+analyze → merge → prune → finalize.
+* Called from runPipeline when shouldSegment() returns true.
+*/
+async function runSegmentedPipeline(options, resolvedOptions) {
+	const pipelineStart = Date.now();
+	const sessionId = randomUUID();
+	let mainWorkspace = "";
+	try {
+		mainWorkspace = await createWorkspace(sessionId);
+		logger.debug(`Segmented pipeline: workspace at ${mainWorkspace}`);
+		const { resolvedInputPath } = await resolveInput(options, mainWorkspace);
+		const inputPath = resolvedInputPath ?? resolvedOptions.inputPath;
+		if (!inputPath) throw new Error("No input path available for segmented pipeline");
+		const metadata = await getVideoMetadata(inputPath);
+		const totalDuration = parseFloat(metadata.format?.duration ?? "0");
+		if (totalDuration <= 0) throw new Error(`Invalid video duration: ${totalDuration}`);
+		logger.debug(`Video duration: ${totalDuration}s`);
+		const segments = computeSegmentPlan(totalDuration, resolvedOptions.maxSegmentDuration, resolvedOptions.maxFrames, resolvedOptions.fps);
+		logger.debug(`Segment plan: ${segments.length} segments`);
+		const limit = concurrencyLimit(resolvedOptions.concurrency);
+		const segmentProgresses = new Array(segments.length).fill(0);
+		const weights = map(segments, (s) => s.duration / totalDuration);
+		const emitOverallProgress = (phase) => {
+			if (!options.onProgress) return;
+			const overall = weights.reduce((sum, w, i) => sum + w * (segmentProgresses[i] ?? 0), 0);
+			options.onProgress(phase, Math.min(100, overall));
+		};
+		options.onProgress?.("EXTRACTING", 0);
+		const results = await Promise.all(map(segments, (segment) => limit(async () => {
+			const segWorkspace = await createSegmentWorkspace(mainWorkspace, segment.index);
+			return await processSegment(inputPath, segment, segWorkspace, resolvedOptions, (percent) => {
+				segmentProgresses[segment.index] = percent;
+				emitOverallProgress("ANALYZING");
+			});
+		})));
+		options.onProgress?.("ANALYZING", 100);
+		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);
+		const prunedFrames = filter(frames, (f) => survivingIds.has(f.id));
+		options.onProgress?.("PRUNING", 100);
+		options.onProgress?.("FINALIZING", 0);
+		const ctx = {
+			options: resolvedOptions,
+			effectiveFps: segments[0]?.effectiveFps,
+			sourceDurationSec: totalDuration,
+			analysisResolution,
+			workspacePath: mainWorkspace,
+			frames,
+			graph: edges,
+			animations,
+			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);
+		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,
+			...outputMetadata,
+			executionTimeMs: Date.now() - pipelineStart
+		};
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		logger.error(`Segmented pipeline failed: ${err.message}`);
+		throw err;
+	} finally {
+		if (!resolvedOptions.debug) await cleanupWorkspace(mainWorkspace);
+		else logger.debug(`Debug mode: workspace preserved at ${mainWorkspace}`);
+	}
 }
 
-// src/core/orchestrator.ts
-async function runPipeline(options2) {
-  const debug = options2.debug ?? false;
-  if (debug) setDebugMode(true);
-  const resolvedOptions = resolveOptions(options2);
-  if (shouldSegment(resolvedOptions, options2)) {
-    return runSegmentedPipeline(options2, resolvedOptions);
-  }
-  const startTime = Date.now();
-  const sessionId = randomUUID2();
-  const ctx = {
-    options: resolvedOptions,
-    workspacePath: "",
-    frames: [],
-    graph: [],
-    status: "INIT",
-    emitProgress: (percent) => {
-      if (options2.onProgress && ctx.status !== "INIT" && ctx.status !== "SUCCESS" && ctx.status !== "FAILED") {
-        options2.onProgress(ctx.status, percent);
-      }
-    }
-  };
-  try {
-    ctx.workspacePath = await createWorkspace(sessionId);
-    logger.debug(`Workspace created: ${ctx.workspacePath}`);
-    ctx.status = "EXTRACTING";
-    const { frames: resolvedFrames, resolvedInputPath } = await resolveInput(
-      options2,
-      ctx.workspacePath
-    );
-    if (resolvedOptions.mode === "frames") {
-      ctx.frames = resolvedFrames;
-    } else {
-      const extractCtx = {
-        ...ctx,
-        options: {
-          ...resolvedOptions,
-          inputPath: resolvedInputPath
-        }
-      };
-      ctx.frames = await extractFrames(extractCtx);
-    }
-    ctx.emitProgress(100);
-    ctx.status = "ANALYZING";
-    const { edges, animations } = await analyzeFrames(ctx);
-    ctx.graph = edges;
-    ctx.animations = animations;
-    ctx.status = "PRUNING";
-    const survivingIds = pruneByThresholdWithCap(
-      ctx.graph,
-      ctx.frames,
-      resolvedOptions.threshold,
-      resolvedOptions.count
-    );
-    const prunedFrames = filter6(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);
-    }
-    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)
-        }
-      },
-      executionTimeMs: Date.now() - startTime
-    };
-  } catch (error) {
-    ctx.status = "FAILED";
-    ctx.error = error instanceof Error ? error : new Error(String(error));
-    logger.error(`Pipeline failed: ${ctx.error.message}`);
-    throw ctx.error;
-  } finally {
-    if (!resolvedOptions.debug) {
-      await cleanupWorkspace(ctx.workspacePath);
-    } else {
-      logger.debug(`Debug mode: workspace preserved at ${ctx.workspacePath}`);
-    }
-  }
+//#endregion
+//#region src/core/orchestrator/orchestrator.ts
+async function runPipeline(options) {
+	setDebugMode(options.debug ?? false);
+	const resolvedOptions = resolveOptions(options);
+	if (shouldSegment(resolvedOptions, options)) return runSegmentedPipeline(options, resolvedOptions);
+	const startTime = Date.now();
+	const sessionId = randomUUID();
+	const ctx = {
+		options: resolvedOptions,
+		workspacePath: "",
+		frames: [],
+		graph: [],
+		status: "INIT",
+		emitProgress: (percent) => {
+			if (options.onProgress && ctx.status !== "INIT" && ctx.status !== "SUCCESS" && ctx.status !== "FAILED") options.onProgress(ctx.status, percent);
+		}
+	};
+	try {
+		ctx.workspacePath = await createWorkspace(sessionId);
+		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;
+			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, 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);
+		}
+		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,
+			...metadata,
+			executionTimeMs: Date.now() - startTime
+		};
+	} catch (error) {
+		ctx.status = "FAILED";
+		ctx.error = error instanceof Error ? error : new Error(String(error));
+		logger.error(`Pipeline failed: ${ctx.error.message}`);
+		throw ctx.error;
+	} finally {
+		if (!resolvedOptions.debug) await cleanupWorkspace(ctx.workspacePath);
+		else logger.debug(`Debug mode: workspace preserved at ${ctx.workspacePath}`);
+	}
 }
 
-// src/core/pipeline-worker.ts
-var options = workerData;
+//#endregion
+//#region src/core/orchestrator/worker/pipeline-worker.ts
 runPipeline({
-  ...options,
-  onProgress: (phase, percent) => {
-    parentPort?.postMessage({
-      type: "progress",
-      phase,
-      percent
-    });
-  }
+	...workerData,
+	onProgress: (phase, percent) => {
+		parentPort?.postMessage({
+			type: "progress",
+			phase,
+			percent
+		});
+	}
 }).then((result) => {
-  parentPort?.postMessage({
-    type: "result",
-    result
-  });
+	parentPort?.postMessage({
+		type: "result",
+		result
+	});
 }).catch((error) => {
-  parentPort?.postMessage({
-    type: "error",
-    message: error instanceof Error ? error.message : String(error)
-  });
+	parentPort?.postMessage({
+		type: "error",
+		message: error instanceof Error ? error.message : String(error)
+	});
 });
+
+//#endregion
+export {  };