@lumy-pack/scene-sieve 0.0.1 → 0.0.3

package/dist/cli.mjs

@@ -21,7 +21,8 @@ var logger = {
     console.log(`${pc.blue("info")} ${message}`);
   },
   success(message) {
-    console.log(`${pc.green("done")} ${message}`);
+    console.log(`
+${pc.green("done")} ${message}`);
   },
   warn(message) {
     console.warn(`${pc.yellow("warn")} ${message}`);
@@ -44,10 +45,12 @@ import sharp from "sharp";
 import { tmpdir } from "os";
 import { join } from "path";
 var APP_NAME = "scene-sieve";
-var DEFAULT_COUNT = 5;
+var DEFAULT_COUNT = 20;
+var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
+var NORMALIZATION_PERCENTILE = 0.9;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = tmpdir();
 var SUPPORTED_VIDEO_EXTENSIONS = [
@@ -67,6 +70,10 @@ var IOU_THRESHOLD = 0.9;
 var DECAY_LAMBDA = 0.95;
 var ANIMATION_FRAME_THRESHOLD = 5;
 var MATCH_DISTANCE_THRESHOLD = 0.75;
+var PIXELDIFF_GAUSSIAN_KERNEL = 3;
+var PIXELDIFF_BINARY_THRESHOLD = 30;
+var PIXELDIFF_CONTOUR_MIN_AREA = 100;
+var PIXELDIFF_SAMPLE_SPACING = 8;
 function getTempWorkspaceDir(sessionId) {
   return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
 }
@@ -326,6 +333,60 @@ async function computeAKAZEDiff(cvLib, frame1, frame2) {
     if (matches) matches.delete();
   }
 }
+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();
+  }
+}
 function computeInformationGain(clusters, clusterPoints, imageArea, animationIndices, animationWeights) {
   if (clusters.length === 0) return 0;
   let gain = 0;
@@ -360,8 +421,28 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
         preprocessed[i],
         preprocessed[i + 1]
       );
-      const dbscanResult = dbscan(sNew, imageWidth, imageHeight);
-      const clusters = dbscanResult.boundingBoxes;
+      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) {
@@ -379,7 +460,9 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
         animationIndices,
         animationWeights
       );
-      logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
+      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,
@@ -424,12 +507,13 @@ async function analyzeFrames(ctx) {
 // src/core/extractor.ts
 import { readdir } from "fs/promises";
 import { join as join2 } from "path";
-import ffmpeg from "fluent-ffmpeg";
-import ffmpegStatic from "ffmpeg-static";
 import { path as ffprobePath } from "@ffprobe-installer/ffprobe";
+import { execa } from "execa";
+import ffmpegPath from "ffmpeg-static";
 
 // src/utils/paths.ts
 import { mkdir, stat } from "fs/promises";
+import { homedir } from "os";
 import { basename, extname, resolve } from "path";
 async function ensureDir(dirPath) {
   await mkdir(dirPath, { recursive: true });
@@ -442,6 +526,16 @@ async function fileExists(filePath) {
     return false;
   }
 }
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return resolve(homedir(), p.slice(2));
+  }
+  return p;
+}
+function resolveAbsolute(p) {
+  return resolve(expandTilde(p));
+}
 function deriveOutputPath(inputPath) {
   const dir = resolve(inputPath, "..");
   const name = basename(inputPath, extname(inputPath));
@@ -452,8 +546,6 @@ function isSupportedFile(filePath, extensions) {
 }
 
 // src/core/extractor.ts
-if (ffmpegStatic) ffmpeg.setFfmpegPath(ffmpegStatic);
-ffmpeg.setFfprobePath(ffprobePath);
 async function extractFrames(ctx) {
   const framesDir = join2(ctx.workspacePath, "frames");
   const { inputPath, fps, scale } = ctx.options;
@@ -464,7 +556,10 @@ async function extractFrames(ctx) {
   if (!exists) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
-  const allExtensions = [...SUPPORTED_VIDEO_EXTENSIONS, ...SUPPORTED_GIF_EXTENSIONS];
+  const allExtensions = [
+    ...SUPPORTED_VIDEO_EXTENSIONS,
+    ...SUPPORTED_GIF_EXTENSIONS
+  ];
   if (!isSupportedFile(inputPath, allExtensions)) {
     throw new Error(`Unsupported file format: ${inputPath}`);
   }
@@ -490,35 +585,43 @@ async function extractFrames(ctx) {
 }
 async function extractIFrames(inputPath, outputDir, scale) {
   const outputPattern = join2(outputDir, "frame_%06d.jpg");
-  await new Promise((resolve2, reject) => {
-    ffmpeg(inputPath).outputOptions([
-      `-vf select='eq(pict_type,I)',scale=-1:${scale}`,
-      "-vsync vfr",
-      "-q:v 2"
-    ]).output(outputPattern).on("end", () => resolve2()).on("error", (err) => reject(err)).run();
-  });
+  await execa(ffmpegPath, [
+    "-i",
+    inputPath,
+    "-vf",
+    `select='eq(pict_type,I)',scale=-1:${scale}`,
+    "-vsync",
+    "vfr",
+    "-q:v",
+    "2",
+    outputPattern
+  ]);
   return buildFrameList(outputDir, inputPath);
 }
 async function extractByFps(inputPath, outputDir, fps, scale) {
   const outputPattern = join2(outputDir, "frame_%06d.jpg");
-  await new Promise((resolve2, reject) => {
-    ffmpeg(inputPath).outputOptions([
-      `-vf fps=${fps},scale=-1:${scale}`,
-      "-q:v 2"
-    ]).output(outputPattern).on("end", () => resolve2()).on("error", (err) => reject(err)).run();
-  });
+  await execa(ffmpegPath, [
+    "-i",
+    inputPath,
+    "-vf",
+    `fps=${fps},scale=-1:${scale}`,
+    "-q:v",
+    "2",
+    outputPattern
+  ]);
   return buildFrameList(outputDir, inputPath);
 }
 async function getVideoDuration(inputPath) {
-  return new Promise((resolve2, reject) => {
-    ffmpeg.ffprobe(inputPath, (err, metadata) => {
-      if (err) {
-        reject(err);
-        return;
-      }
-      resolve2(metadata.format.duration ?? 0);
-    });
-  });
+  const { stdout } = await execa(ffprobePath, [
+    "-v",
+    "quiet",
+    "-print_format",
+    "json",
+    "-show_format",
+    inputPath
+  ]);
+  const metadata = JSON.parse(stdout);
+  return parseFloat(metadata.format?.duration ?? "0");
 }
 async function buildFrameList(framesDir, inputPath) {
   const files = await readdir(framesDir);
@@ -530,7 +633,9 @@ async function buildFrameList(framesDir, inputPath) {
   try {
     duration = await getVideoDuration(inputPath);
   } catch {
-    logger.debug("Could not determine video duration; using frame index for timestamps");
+    logger.debug(
+      "Could not determine video duration; using frame index for timestamps"
+    );
   }
   return jpgFiles.map((file, index) => ({
     id: index,
@@ -605,17 +710,15 @@ async function readFramesAsBuffers(frameNodes, quality) {
 // src/core/input-resolver.ts
 function resolveOptions(options) {
   const mode = options.mode;
-  const inputPath = mode === "file" ? options.inputPath : void 0;
+  const inputPath = mode === "file" ? resolveAbsolute(options.inputPath) : void 0;
   const outputPath = options.outputPath ?? (inputPath ? deriveOutputPath(inputPath) : join4(process.cwd(), "scene-sieve-output"));
-  const threshold = options.threshold;
-  if (threshold !== void 0 && (threshold <= 0 || threshold > 1)) {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  if (threshold <= 0 || threshold > 1) {
     throw new Error(
       `threshold must be in range (0, 1], received: ${threshold}`
     );
   }
-  const hasThreshold = threshold !== void 0;
-  const hasExplicitCount = options.count !== void 0;
-  const pruneMode = hasThreshold && hasExplicitCount ? "threshold-with-cap" : hasThreshold ? "threshold" : "count";
+  const pruneMode = "threshold-with-cap";
   return {
     mode,
     inputPath,
@@ -631,10 +734,16 @@ function resolveOptions(options) {
 }
 async function resolveInput(options, workspacePath) {
   if (options.mode === "file") {
-    return { frames: [], resolvedInputPath: options.inputPath };
+    return {
+      frames: [],
+      resolvedInputPath: resolveAbsolute(options.inputPath)
+    };
   }
   if (options.mode === "buffer") {
-    const resolvedInputPath = await writeInputBuffer(options.inputBuffer, workspacePath);
+    const resolvedInputPath = await writeInputBuffer(
+      options.inputBuffer,
+      workspacePath
+    );
     return { frames: [], resolvedInputPath };
   }
   if (options.mode === "frames") {
@@ -703,7 +812,11 @@ function pruneTo(graph, frames, targetCount) {
   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 });
+    heap.push({
+      score: edge.score,
+      srcId: edge.sourceId,
+      tgtId: edge.targetId
+    });
   }
   const surviving = new Set(frames.map((f) => f.id));
   const firstId = frames[0].id;
@@ -739,9 +852,55 @@ function normalizeScores(graph) {
   const safeScores = graph.map(
     (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
   );
-  const maxScore = Math.max(...safeScores);
-  if (maxScore === 0) return safeScores;
-  return safeScores.map((s) => s / maxScore);
+  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
+  if (sorted.length === 0) return safeScores;
+  const pIdx = Math.min(
+    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
+    sorted.length - 1
+  );
+  const refScore = sorted[pIdx];
+  return safeScores.map((s) => Math.min(s / refScore, 1));
+}
+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;
 }
 function pruneByThreshold(graph, frames, threshold) {
   if (frames.length === 0) return /* @__PURE__ */ new Set();
@@ -749,11 +908,16 @@ function pruneByThreshold(graph, frames, threshold) {
   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) {
-      surviving.add(graph[i].targetId);
+      passingIndices.push(i);
     }
   }
+  const nmsTargets = suppressConsecutiveRuns(graph, passingIndices, normalized);
+  for (const id of nmsTargets) {
+    surviving.add(id);
+  }
   return surviving;
 }
 function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
@@ -837,35 +1001,22 @@ async function runPipeline(options) {
     ctx.status = "ANALYZING";
     ctx.graph = await analyzeFrames(ctx);
     ctx.status = "PRUNING";
-    let survivingIds;
-    switch (resolvedOptions.pruneMode) {
-      case "threshold-with-cap":
-        survivingIds = pruneByThresholdWithCap(
-          ctx.graph,
-          ctx.frames,
-          resolvedOptions.threshold,
-          resolvedOptions.count
-        );
-        break;
-      case "threshold":
-        survivingIds = pruneByThreshold(
-          ctx.graph,
-          ctx.frames,
-          resolvedOptions.threshold
-        );
-        break;
-      case "count":
-      default:
-        survivingIds = pruneTo(ctx.graph, ctx.frames, resolvedOptions.count);
-        break;
-    }
+    const survivingIds = pruneByThresholdWithCap(
+      ctx.graph,
+      ctx.frames,
+      resolvedOptions.threshold,
+      resolvedOptions.count
+    );
     const prunedFrames = ctx.frames.filter((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);
+      outputBuffers = await readFramesAsBuffers(
+        prunedFrames,
+        resolvedOptions.quality
+      );
       ctx.emitProgress(100);
     } else {
       outputFiles = await finalizeOutput(ctx, prunedFrames);
@@ -901,7 +1052,10 @@ async function runPipeline(options) {
 var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
 var program = new Command();
-program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version).argument("<input>", "Input video or GIF file path").option("-n, --count <number>", "Number of frames to keep (default: 5 when no --threshold)").option("-t, --threshold <number>", "Normalized threshold 0~1 (keeps frames above ratio of max change; combine with -n to cap result count)").option("-o, --output <path>", "Output directory path").option("--fps <number>", "Fallback FPS for frame extraction", "5").option("-s, --scale <number>", "Scale size for vision analysis", "720").option("-q, --quality <number>", "JPEG output quality 1-100", "80").option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
+program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version).argument("<input>", "Input video or GIF file path").option("-n, --count <number>", "Max number of frames to keep (default: 20)").option(
+  "-t, --threshold <number>",
+  "Normalized threshold 0~1 (default: 0.5; keeps frames above ratio of max change)"
+).option("-o, --output <path>", "Output directory path").option("--fps <number>", "Fallback FPS for frame extraction", "5").option("-s, --scale <number>", "Scale size for vision analysis", "720").option("-q, --quality <number>", "JPEG output quality 1-100", "80").option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
   const { default: ora } = await import("ora");
   const { default: cliProgress } = await import("cli-progress");
   const spinner = ora("Initializing...").start();
@@ -933,8 +1087,12 @@ program.name("scene-sieve").description("Extract key frames from video and GIF f
       `
 Done! ${result.originalFramesCount} frames -> ${result.prunedFramesCount} scenes (${result.executionTimeMs}ms)`
     );
-    console.log(`Output: ${result.outputFiles[0]?.replace(/\/[^/]+$/, "/")}`);
-    result.outputFiles.forEach((f) => console.log(`  - ${f}`));
+    if (opts.debug) {
+      console.log(
+        `Output: ${result.outputFiles[0]?.replace(/\/[^/]+$/, "/")}`
+      );
+      result.outputFiles.forEach((f) => console.log(`  - ${f}`));
+    }
   } catch (error) {
     spinner.fail(
       `Failed: ${error instanceof Error ? error.message : String(error)}`

package/dist/constants.d.ts

@@ -1,8 +1,10 @@
 export declare const APP_NAME = "scene-sieve";
-export declare const DEFAULT_COUNT = 5;
+export declare const DEFAULT_COUNT = 20;
+export declare const DEFAULT_THRESHOLD = 0.5;
 export declare const DEFAULT_FPS = 5;
 export declare const DEFAULT_SCALE = 720;
 export declare const DEFAULT_QUALITY = 80;
+export declare const NORMALIZATION_PERCENTILE = 0.9;
 export declare const WORKSPACE_PREFIX = "scene-sieve-";
 export declare const TEMP_BASE_DIR: string;
 export declare const SUPPORTED_VIDEO_EXTENSIONS: string[];
@@ -17,4 +19,8 @@ export declare const IOU_THRESHOLD = 0.9;
 export declare const DECAY_LAMBDA = 0.95;
 export declare const ANIMATION_FRAME_THRESHOLD = 5;
 export declare const MATCH_DISTANCE_THRESHOLD = 0.75;
+export declare const PIXELDIFF_GAUSSIAN_KERNEL = 3;
+export declare const PIXELDIFF_BINARY_THRESHOLD = 30;
+export declare const PIXELDIFF_CONTOUR_MIN_AREA = 100;
+export declare const PIXELDIFF_SAMPLE_SPACING = 8;
 export declare function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/analyzer.d.ts

@@ -1,5 +1,6 @@
 import type { BoundingBox, ProcessContext, ScoreEdge } from '../types/index.js';
 import type { Point2D } from './dbscan.js';
+type CvLib = typeof import('@techstark/opencv-js');
 export declare function preprocessFrame(framePath: string, scale: number): Promise<{
     data: Uint8Array;
     width: number;
@@ -15,6 +16,30 @@ export interface AKAZEResult {
     sNew: Point2D[];
     sLoss: Point2D[];
 }
+/**
+ * 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[]
+ */
+export declare function computePixelDiff(cvLib: CvLib, frame1: {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}, frame2: {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}): Point2D[];
 export declare function computeInformationGain(clusters: BoundingBox[], clusterPoints: number[], imageArea: number, animationIndices: Set<number>, animationWeights: number[]): number;
 /**
  * Analyze adjacent frame pairs to compute information gain scores (G(t)).
@@ -27,3 +52,4 @@ export declare function computeInformationGain(clusters: BoundingBox[], clusterP
  * 4. G(t) Information Gain Scoring
  */
 export declare function analyzeFrames(ctx: ProcessContext): Promise<ScoreEdge[]>;
+export {};

package/dist/core/index.d.ts

@@ -1,7 +1,7 @@
 export { runPipeline } from './orchestrator.js';
-export { analyzeFrames, computeIoU, computeInformationGain } from './analyzer.js';
+export { analyzeFrames, computeIoU, computeInformationGain, } from './analyzer.js';
 export { extractFrames } from './extractor.js';
-export { pruneTo, pruneByThreshold, pruneByThresholdWithCap } from './pruner.js';
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner.js';
 export { dbscan } from './dbscan.js';
 export type { Point2D } from './dbscan.js';
 export { resolveInput, resolveOptions } from './input-resolver.js';

package/dist/core/input-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { FrameNode, SieveOptions, ResolvedOptions } from '../types/index.js';
+import type { FrameNode, ResolvedOptions, SieveOptions } from '../types/index.js';
 export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
 /**
  * Resolve the input source to a list of FrameNode[].

package/dist/core/pruner.d.ts

@@ -14,17 +14,36 @@ import type { FrameNode, ScoreEdge } from '../types/index.js';
  */
 export declare function pruneTo(graph: ScoreEdge[], frames: FrameNode[], targetCount: number): Set<number>;
 /**
- * Threshold-based pruning — O(N).
+ * Non-Maximum Suppression (NMS) for consecutive edge runs.
  *
- * Scores are normalized to [0, 1] via max-normalization.
- * threshold=0.5 means "keep frames where the change is at least 50%
- * of the maximum change observed in this sequence".
+ * 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.
  *
- * First and last frames are always preserved (boundary protection).
+ * 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).
  *
- * Unlike pruneTo (which targets an exact count via greedy merge),
- * this function has no count limit — every significant scene transition
- * above the threshold is 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)
+ */
+export declare function suppressConsecutiveRuns(graph: ScoreEdge[], passingIndices: number[], normalizedScores: number[]): Set<number>;
+/**
+ * Threshold-based pruning with NMS -- O(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).
  */
 export declare function pruneByThreshold(graph: ScoreEdge[], frames: FrameNode[], threshold: number): Set<number>;
 /**