@lumy-pack/scene-sieve 0.0.10 → 0.0.12

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.mjs

@@ -173,6 +173,7 @@ var init_dbscan = __esm({
 
 // src/core/analyzer.ts
 import { createRequire } from "module";
+import { filter, map } from "@winglet/common-utils";
 import sharp from "sharp";
 async function ensureOpenCV() {
   if (!cvReady) {
@@ -356,7 +357,7 @@ function computeInformationGain(clusters, clusterPoints, imageArea, animationInd
 async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
   const edges = [];
   const preprocessed = await Promise.all(
-    frames.map((f) => preprocessFrame(f.extractPath, scale))
+    map(frames, (f) => preprocessFrame(f.extractPath, scale))
   );
   const imageWidth = preprocessed[0]?.width ?? scale;
   const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
@@ -398,7 +399,8 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
         }
       }
       const animationIndices = tracker.update(clusters, pairIndex);
-      const animationWeights = clusters.map(
+      const animationWeights = map(
+        clusters,
         (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0
       );
       const score = computeInformationGain(
@@ -524,7 +526,8 @@ var init_analyzer = __esm({
             this.collectAnimation(region);
           }
         }
-        this.regions = this.regions.filter(
+        this.regions = filter(
+          this.regions,
           (r, i) => r.weight > 0.01 || matched.has(i)
         );
         return animationIndices;
@@ -607,6 +610,7 @@ var init_paths = __esm({
 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";
 async function extractFrames(ctx) {
@@ -685,11 +689,11 @@ async function getVideoMetadata(inputPath) {
 }
 async function buildFrameList(framesDir, duration) {
   const files = await readdir(framesDir);
-  const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
+  const jpgFiles = filter2(files, (f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  return jpgFiles.map((file, index) => ({
+  return map2(jpgFiles, (file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
     extractPath: join2(framesDir, file)
@@ -724,6 +728,7 @@ var init_extractor = __esm({
 // 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";
 async function createWorkspace(sessionId) {
   const workspacePath = getTempWorkspaceDir(sessionId);
@@ -764,7 +769,7 @@ async function finalizeOutput(ctx, selectedFrames) {
       }
     },
     frames: framesMetadata,
-    animations: (ctx.animations || []).map((anim) => ({
+    animations: map3(ctx.animations || [], (anim) => ({
       ...anim,
       startFrameId: anim.startFrameId + 1,
       endFrameId: anim.endFrameId + 1,
@@ -831,7 +836,8 @@ async function writeInputFrames(frames, workspacePath) {
 }
 async function readFramesAsBuffers(frameNodes, quality) {
   return Promise.all(
-    frameNodes.map(
+    map3(
+      frameNodes,
       (f) => sharp2(f.extractPath).jpeg({ quality, mozjpeg: true }).toBuffer()
     )
   );
@@ -907,38 +913,42 @@ var init_input_resolver = __esm({
 });
 
 // src/utils/math.ts
+import { filter as filter3, map as map4 } from "@winglet/common-utils";
 function normalizeScores(items) {
   if (items.length === 0) return [];
-  const safeScores = items.map(
+  const safeScores = map4(
+    items,
     (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
   );
-  const positiveScores = safeScores.filter((s) => s > 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 safeScores.map((s) => s > 0 ? 1 : 0);
-    return safeScores.map(
+    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 = positiveScores.map((v) => Math.abs(v - median));
+  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 = safeScores.map((s) => {
+  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 = safeScores.map((s) => {
+  const cdf = map4(safeScores, (s) => {
     if (s <= 0) return 0;
     const rank = sorted.findIndex((v) => v >= s);
     return rank / sorted.length;
   });
-  return logisticZ.map(
+  return map4(
+    logisticZ,
     (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
   );
 }
@@ -1000,9 +1010,10 @@ var init_min_heap = __esm({
 });
 
 // src/core/pruner.ts
+import { filter as filter4, map as map5 } from "@winglet/common-utils";
 function pruneTo(graph, frames, targetCount) {
   if (frames.length <= targetCount) {
-    return new Set(frames.map((f) => f.id));
+    return new Set(map5(frames, (f) => f.id));
   }
   const prev = /* @__PURE__ */ new Map();
   const next = /* @__PURE__ */ new Map();
@@ -1020,7 +1031,7 @@ function pruneTo(graph, frames, targetCount) {
       tgtId: edge.targetId
     });
   }
-  const surviving = new Set(frames.map((f) => f.id));
+  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) {
@@ -1113,7 +1124,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
   if (thresholdSurvivors.size <= maxCount) {
     return thresholdSurvivors;
   }
-  const survivingFrames = frames.filter((f) => thresholdSurvivors.has(f.id));
+  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);
@@ -1180,6 +1191,7 @@ var init_concurrency = __esm({
 // 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";
 function shouldSegment(resolvedOptions, originalOptions) {
   if (resolvedOptions.mode === "frames") return false;
   if (originalOptions.mode === "file") {
@@ -1297,18 +1309,30 @@ function remapEdges(segmentResults, globalIdMap) {
   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}`);
+      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 };
+          edges[existingIdx] = {
+            sourceId: newSourceId,
+            targetId: newTargetId,
+            score: edge.score
+          };
         }
       } else {
         edgeMap.set(edgeKey, edges.length);
-        edges.push({ sourceId: newSourceId, targetId: newTargetId, score: edge.score });
+        edges.push({
+          sourceId: newSourceId,
+          targetId: newTargetId,
+          score: edge.score
+        });
       }
     }
   }
@@ -1318,10 +1342,18 @@ 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}`);
+      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 });
+      animations.push({
+        ...anim,
+        startFrameId: newStartId,
+        endFrameId: newEndId
+      });
     }
   }
   return animations;
@@ -1402,7 +1434,7 @@ async function runSegmentedPipeline(options, resolvedOptions) {
     logger.debug(`Segment plan: ${segments.length} segments`);
     const limit = concurrencyLimit(resolvedOptions.concurrency);
     const segmentProgresses = new Array(segments.length).fill(0);
-    const weights = segments.map((s) => s.duration / totalDuration);
+    const weights = map6(segments, (s) => s.duration / totalDuration);
     const emitOverallProgress = (phase) => {
       if (!options.onProgress) return;
       const overall = weights.reduce(
@@ -1413,7 +1445,8 @@ async function runSegmentedPipeline(options, resolvedOptions) {
     };
     options.onProgress?.("EXTRACTING", 0);
     const results = await Promise.all(
-      segments.map(
+      map6(
+        segments,
         (segment) => limit(async () => {
           const segWorkspace = await createSegmentWorkspace(
             mainWorkspace,
@@ -1445,7 +1478,7 @@ async function runSegmentedPipeline(options, resolvedOptions) {
       resolvedOptions.threshold,
       resolvedOptions.count
     );
-    const prunedFrames = frames.filter((f) => survivingIds.has(f.id));
+    const prunedFrames = filter5(frames, (f) => survivingIds.has(f.id));
     options.onProgress?.("PRUNING", 100);
     options.onProgress?.("FINALIZING", 0);
     const ctx = {
@@ -1519,6 +1552,7 @@ __export(orchestrator_exports, {
   runPipeline: () => runPipeline
 });
 import { randomUUID as randomUUID2 } from "crypto";
+import { filter as filter6 } from "@winglet/common-utils";
 async function runPipeline(options) {
   const debug = options.debug ?? false;
   if (debug) setDebugMode(true);
@@ -1572,7 +1606,7 @@ async function runPipeline(options) {
       resolvedOptions.threshold,
       resolvedOptions.count
     );
-    const prunedFrames = ctx.frames.filter((f) => survivingIds.has(f.id));
+    const prunedFrames = filter6(ctx.frames, (f) => survivingIds.has(f.id));
     ctx.emitProgress(100);
     ctx.status = "FINALIZING";
     let outputFiles = [];
@@ -1636,7 +1670,6 @@ var init_orchestrator = __esm({
 
 // src/cli.ts
 import { createRequire as createRequire2 } from "module";
-import { Command } from "commander";
 
 // ../shared/src/respond.ts
 function respond(command, data, startTime, version2) {
@@ -1667,6 +1700,9 @@ function respondError(command, code, message, startTime, version2, details) {
   process.exitCode = 1;
 }
 
+// src/cli.ts
+import { Command } from "commander";
+
 // src/commands/Sieve.tsx
 import { existsSync } from "fs";
 import { Box as Box2, Text as Text3, useApp } from "ink";
@@ -2182,7 +2218,13 @@ if (process.argv.includes("--describe")) {
 }
 program.parseAsync(process.argv).catch((error) => {
   if (process.argv.includes("--json")) {
-    respondError("extract", SieveErrorCode.UNKNOWN, error.message, Date.now(), version);
+    respondError(
+      "extract",
+      SieveErrorCode.UNKNOWN,
+      error.message,
+      Date.now(),
+      version
+    );
   } else {
     console.error("Fatal error:", error.message);
   }

package/dist/commands/Sieve.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from 'commander';
+import React from 'react';
+export interface SieveViewProps {
+    input: string;
+    count?: number;
+    threshold?: number;
+    output?: string;
+    fps: number;
+    maxFrames: number;
+    scale: number;
+    quality: number;
+    iouThreshold?: number;
+    animationThreshold?: number;
+    maxSegmentDuration?: number;
+    concurrency?: number;
+    debug: boolean;
+}
+export declare function registerSieveCommand(program: Command, version: string): void;
+export declare const SieveView: React.FC<SieveViewProps>;

package/dist/components/PhaseStep.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export type PhaseStatus = 'pending' | 'running' | 'done' | 'failed';
+export interface PhaseState {
+    label: string;
+    status: PhaseStatus;
+    hasProgress: boolean;
+    percent: number;
+    durationMs?: number;
+}
+interface PhaseStepProps {
+    phase: PhaseState;
+}
+export declare const PhaseStep: React.FC<PhaseStepProps>;
+export {};

package/dist/components/ProgressBar.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface ProgressBarProps {
+    percent: number;
+    width?: number;
+}
+export declare const ProgressBar: React.FC<ProgressBarProps>;
+export {};

package/dist/constants.d.ts

@@ -0,0 +1,32 @@
+export declare const APP_NAME = "scene-sieve";
+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 DEFAULT_MAX_FRAMES = 300;
+export declare const NORMALIZATION_MIN_PERCENTILE = 0.1;
+export declare const NORMALIZATION_MAX_PERCENTILE = 0.9;
+export declare const NORMALIZATION_LOGISTIC_K = 3;
+export declare const NORMALIZATION_ALPHA = 0.4;
+export declare const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+export declare const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
+export declare const WORKSPACE_PREFIX = "scene-sieve-";
+export declare const TEMP_BASE_DIR: string;
+export declare const FRAME_OUTPUT_EXTENSION = ".jpg";
+export declare const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+export declare const OPENCV_BATCH_SIZE = 10;
+export declare const MIN_IFRAME_COUNT = 3;
+export declare const DBSCAN_ALPHA = 0.03;
+export declare const DBSCAN_MIN_PTS = 4;
+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.25;
+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 const DEFAULT_MAX_SEGMENT_DURATION = 300;
+export declare const DEFAULT_SEGMENT_CONCURRENCY = 2;
+export declare function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/analyzer.d.ts

@@ -0,0 +1,62 @@
+import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } 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;
+    height: number;
+}>;
+export declare function computeIoU(a: BoundingBox, b: BoundingBox): number;
+export declare class IoUTracker {
+    private fps;
+    private iouThreshold;
+    private animationThreshold;
+    private regions;
+    private extractedAnimations;
+    constructor(fps?: number, iouThreshold?: number, animationThreshold?: number);
+    update(boxes: BoundingBox[], pairIndex: number): Set<number>;
+    private collectAnimation;
+    flushAndGetAnimations(): AnimationMetadata[];
+    getAnimationWeight(boxIndex: number, boxes: BoundingBox[]): number;
+}
+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)).
+ * 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
+ */
+export declare function analyzeFrames(ctx: ProcessContext): Promise<AnalysisResult>;
+export {};

package/dist/core/dbscan.d.ts

@@ -0,0 +1,10 @@
+import type { DBSCANResult } from '../types/index.js';
+export interface Point2D {
+    x: number;
+    y: number;
+}
+/**
+ * DBSCAN clustering with resolution-independent eps.
+ * eps = alpha * sqrt(width^2 + height^2)
+ */
+export declare function dbscan(points: Point2D[], imageWidth: number, imageHeight: number, alpha?: number, minPts?: number): DBSCANResult;

package/dist/core/extractor.d.ts

@@ -0,0 +1,30 @@
+import type { FrameNode, ProcessContext } from '../types/index.js';
+export interface FFprobeMetadata {
+    format?: {
+        format_name?: string;
+        duration?: string;
+    };
+    streams?: Array<{
+        codec_type?: string;
+    }>;
+}
+/**
+ * Extract frames from video/GIF using FFmpeg.
+ * Always uses FPS-based extraction. For long videos, FPS is automatically
+ * reduced to stay within maxFrames budget.
+ */
+export declare function extractFrames(ctx: ProcessContext): Promise<FrameNode[]>;
+export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMetadata>;
+/**
+ * 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
+ * @returns Array of FrameNode with segment-local timestamps (starting from 0)
+ */
+export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number): Promise<FrameNode[]>;

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+export { runPipeline } from './orchestrator.js';
+export { analyzeFrames, computeIoU, computeInformationGain, } from './analyzer.js';
+export { extractFrames } from './extractor.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';
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter.js';
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';

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

@@ -0,0 +1,13 @@
+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[].
+ *
+ * - '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[]
+ */
+export declare function resolveInput(options: SieveOptions, workspacePath: string): Promise<{
+    frames: FrameNode[];
+    resolvedInputPath?: string;
+}>;

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,2 @@
+import type { SieveOptions, SieveResult } from '../types/index.js';
+export declare function runPipeline(options: SieveOptions): Promise<SieveResult>;

package/dist/core/pipeline-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/pruner.d.ts

@@ -0,0 +1,61 @@
+import type { FrameNode, ScoreEdge } from '../types/index.js';
+/**
+ * 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.
+ */
+export declare function pruneTo(graph: ScoreEdge[], frames: FrameNode[], targetCount: number): Set<number>;
+/**
+ * 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)
+ */
+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>;
+/**
+ * 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.
+ */
+export declare function pruneByThresholdWithCap(graph: ScoreEdge[], frames: FrameNode[], threshold: number, maxCount: number): Set<number>;

package/dist/core/run-in-worker.d.ts

@@ -0,0 +1,9 @@
+import type { ProgressPhase, SieveInput, SieveOptionsBase, SieveResult } from '../types/index.js';
+export type SieveWorkerOptions = Omit<SieveOptionsBase, 'onProgress'> & SieveInput;
+/**
+ * Run the pipeline, choosing the best execution strategy:
+ *
+ * - Production (bundled .mjs): Worker thread — spinner never freezes
+ * - Dev mode (tsx .ts): Main thread — simpler, spinner may stutter during CPU work
+ */
+export declare function runPipelineInWorker(options: SieveWorkerOptions, onProgress: (phase: ProgressPhase, percent: number) => void): Promise<SieveResult>;

package/dist/core/segmenter.d.ts

@@ -0,0 +1,38 @@
+import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentPlan, SegmentResult, SieveOptions, SieveResult } from '../types/index.js';
+/**
+ * Determine whether segmentation should be used.
+ * Returns false for frames mode and GIF files.
+ * Actual duration check happens inside runSegmentedPipeline after metadata fetch.
+ */
+export declare function shouldSegment(resolvedOptions: ResolvedOptions, originalOptions: SieveOptions): boolean;
+/**
+ * Compute segment boundaries with overlap, frame allocation, and effectiveFps.
+ * Pure function — no I/O.
+ *
+ * - effectiveFps is uniform across all segments
+ * - Overlap: 1 frame at each internal boundary
+ * - allocatedFrames total <= maxFrames (last segment adjusted if needed)
+ */
+export declare function computeSegmentPlan(totalDuration: number, maxSegmentDuration: number, maxFrames: number, fps: number): SegmentPlan[];
+/**
+ * Merge multiple segment results into a single unified frame/edge/animation set.
+ * - Timestamps adjusted using extractStartTime (Section 18 note 1)
+ * - Overlap frames deduplicated by threshold 1/(effectiveFps*2) (Section 18 note 5)
+ * - Global IDs reassigned after dedup
+ * - Duplicate edges keep higher score
+ */
+export declare function mergeSegmentFrames(segmentResults: SegmentResult[]): {
+    frames: FrameNode[];
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+};
+/**
+ * Extract frames for a single segment and analyze them.
+ * Each segment uses an isolated workspace directory.
+ */
+export declare function processSegment(inputPath: string, segment: SegmentPlan, workspacePath: string, resolvedOptions: ResolvedOptions, onProgress: (percent: number) => void): Promise<SegmentResult>;
+/**
+ * Full segmented pipeline: metadata → plan → parallel extract+analyze → merge → prune → finalize.
+ * Called from runPipeline when shouldSegment() returns true.
+ */
+export declare function runSegmentedPipeline(options: SieveOptions, resolvedOptions: ResolvedOptions): Promise<SieveResult>;

package/dist/core/workspace.d.ts

@@ -0,0 +1,25 @@
+import type { FrameNode, ProcessContext } from '../types/index.js';
+export declare function createWorkspace(sessionId: string): Promise<string>;
+export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[]): Promise<string[]>;
+export declare function createSegmentWorkspace(parentWorkspacePath: string, segmentIndex: number): Promise<string>;
+export declare function cleanupWorkspace(workspacePath: string): Promise<void>;
+/**
+ * Remove stale workspace directories left by previous interrupted runs.
+ * Only deletes directories older than 1 hour to avoid removing active workspaces.
+ */
+export declare function cleanupStaleWorkspaces(): Promise<void>;
+/**
+ * Write a video buffer to a temp file in the workspace and return the path.
+ * Used by 'buffer' input mode.
+ */
+export declare function writeInputBuffer(buffer: Buffer, workspacePath: string): Promise<string>;
+/**
+ * Write an array of frame Buffers as JPG files and return FrameNode[].
+ * Used by 'frames' input mode.
+ */
+export declare function writeInputFrames(frames: Buffer[], workspacePath: string): Promise<FrameNode[]>;
+/**
+ * Read selected FrameNode files as Buffers with JPEG compression.
+ * Used to return output buffers in 'buffer' and 'frames' modes.
+ */
+export declare function readFramesAsBuffers(frameNodes: FrameNode[], quality: number): Promise<Buffer[]>;