@lumy-pack/scene-sieve 0.0.10 → 0.0.11

package/dist/cli.d.ts

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

package/dist/cli.mjs

@@ -1297,18 +1297,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 +1330,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;

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[]>;

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const SieveErrorCode: {
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly PIPELINE_ERROR: "PIPELINE_ERROR";
+    readonly WORKER_ERROR: "WORKER_ERROR";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type SieveErrorCode = (typeof SieveErrorCode)[keyof typeof SieveErrorCode];
+export declare function classifyError(error: Error): SieveErrorCode;

package/dist/index.cjs

@@ -1241,18 +1241,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
+        });
       }
     }
   }
@@ -1262,10 +1274,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;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { BoundingBox, DBSCANResult, FrameNode, ProcessContext, ProgressPhase, ResolvedOptions, ScoreEdge, SieveInput, SieveOptions, SieveOptionsBase, SieveResult, } from './types/index.js';
+export { runPipeline as extractScenes } from './core/orchestrator.js';

package/dist/index.mjs

@@ -1201,18 +1201,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
+        });
       }
     }
   }
@@ -1222,10 +1234,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;

package/dist/pipeline-worker.mjs

@@ -1204,18 +1204,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
+        });
       }
     }
   }
@@ -1225,10 +1237,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;

package/dist/types/index.d.ts

@@ -0,0 +1,129 @@
+export type ProgressPhase = 'EXTRACTING' | 'ANALYZING' | 'PRUNING' | 'FINALIZING';
+export type SieveInput = {
+    mode: 'file';
+    inputPath: string;
+} | {
+    mode: 'buffer';
+    inputBuffer: Buffer;
+} | {
+    mode: 'frames';
+    inputFrames: Buffer[];
+};
+export interface SieveOptionsBase {
+    count?: number;
+    threshold?: number;
+    outputPath?: string;
+    fps?: number;
+    maxFrames?: number;
+    scale?: number;
+    quality?: number;
+    iouThreshold?: number;
+    animationThreshold?: number;
+    debug?: boolean;
+    onProgress?: (phase: ProgressPhase, percent: number) => void;
+    maxSegmentDuration?: number;
+    concurrency?: number;
+}
+export type SieveOptions = SieveOptionsBase & SieveInput;
+export interface ResolvedOptions {
+    mode: 'file' | 'buffer' | 'frames';
+    inputPath?: string;
+    count: number;
+    threshold: number;
+    pruneMode: 'threshold-with-cap';
+    outputPath: string;
+    fps: number;
+    maxFrames: number;
+    scale: number;
+    quality: number;
+    iouThreshold: number;
+    animationThreshold: number;
+    debug: boolean;
+    maxSegmentDuration: number;
+    concurrency: number;
+}
+export interface SieveResult {
+    success: boolean;
+    originalFramesCount: number;
+    prunedFramesCount: number;
+    outputFiles: string[];
+    outputBuffers?: Buffer[];
+    animations?: AnimationMetadata[];
+    video?: VideoMetadata;
+    executionTimeMs: number;
+}
+export interface AnimationMetadata {
+    type: string;
+    boundingBox: BoundingBox;
+    startFrameId: number;
+    endFrameId: number;
+    durationMs: number;
+}
+export interface VideoMetadata {
+    originalDurationMs: number;
+    fps: number;
+    resolution: {
+        width: number;
+        height: number;
+    };
+}
+export interface FrameNode {
+    id: number;
+    timestamp: number;
+    extractPath: string;
+}
+export interface ScoreEdge {
+    sourceId: number;
+    targetId: number;
+    /**
+     * Information gain score (G(t)) between adjacent frames.
+     * Higher values = greater visual change (state transition) = should be preserved.
+     * Lower values = similar frames (little change) = candidates for pruning.
+     *
+     * Pruner removes frames with the LOWEST scores first (greedy ascending).
+     * Maps directly to G(t) from the vision analysis pipeline.
+     */
+    score: number;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DBSCANResult {
+    labels: number[];
+    boundingBoxes: BoundingBox[];
+}
+export interface ProcessContext {
+    options: ResolvedOptions;
+    workspacePath: string;
+    frames: FrameNode[];
+    graph: ScoreEdge[];
+    animations?: AnimationMetadata[];
+    status: 'INIT' | ProgressPhase | 'SUCCESS' | 'FAILED';
+    emitProgress: (percent: number) => void;
+    error?: Error;
+}
+export interface AnalysisResult {
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+}
+export interface SegmentPlan {
+    index: number;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    allocatedFrames: number;
+    effectiveFps: number;
+    overlapBefore: number;
+    overlapAfter: number;
+    extractStartTime: number;
+    extractDuration: number;
+}
+export interface SegmentResult {
+    segment: SegmentPlan;
+    frames: FrameNode[];
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+}

package/dist/utils/command-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Central command registry for scene-sieve CLI.
+ * Single source of truth for command metadata, used by --describe and --help.
+ */
+export interface CommandOption {
+    flag: string;
+    description: string;
+    type?: 'boolean' | 'string' | 'number';
+    default?: string;
+}
+export interface CommandArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface CommandInfo {
+    name: string;
+    description: string;
+    usage: string;
+    arguments?: CommandArgument[];
+    options?: CommandOption[];
+    examples?: string[];
+}
+export declare const SIEVE_COMMAND: CommandInfo;

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Creates a concurrency limiter that runs at most `limit` tasks in parallel.
+ * Lightweight replacement for p-limit to avoid external dependency.
+ */
+export declare function concurrencyLimit(limit: number): <T>(fn: () => Promise<T>) => Promise<T>;

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare function setDebugMode(enabled: boolean): void;
+export declare const logger: {
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+};

package/dist/utils/math.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interface for objects that have a numeric score.
+ */
+export interface ScoredItem {
+    score: number;
+}
+/**
+ * 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)
+ */
+export declare function normalizeScores<T extends ScoredItem>(items: T[]): number[];

package/dist/utils/min-heap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generic binary min-heap.
+ *
+ * Elements are ordered by a numeric `score` field.
+ * push/pop: O(log N), size: O(1).
+ */
+export declare class MinHeap<T extends {
+    score: number;
+}> {
+    private readonly h;
+    get size(): number;
+    push(entry: T): void;
+    pop(): T | undefined;
+    private siftUp;
+    private siftDown;
+}

package/dist/utils/parse-options.d.ts

@@ -0,0 +1,21 @@
+import type { SieveOptionsBase } from '../types/index.js';
+/**
+ * Common pipeline options parsed from CLI opts (Commander string values → typed values).
+ * Does NOT include mode-specific fields (mode, inputPath, onProgress).
+ */
+export type ParsedPipelineOptions = Pick<Required<SieveOptionsBase>, 'fps' | 'maxFrames' | 'scale' | 'quality' | 'debug'> & Pick<SieveOptionsBase, 'count' | 'threshold' | 'outputPath' | 'iouThreshold' | 'animationThreshold' | 'maxSegmentDuration' | 'concurrency'>;
+export interface RawCliOptions {
+    count?: string;
+    threshold?: string;
+    output?: string;
+    fps: string;
+    maxFrames: string;
+    scale: string;
+    quality: string;
+    iouThreshold?: string;
+    animThreshold?: string;
+    maxSegmentDuration?: string;
+    concurrency?: string;
+    debug?: boolean;
+}
+export declare function parsePipelineOptions(opts: RawCliOptions): ParsedPipelineOptions;

package/dist/utils/paths.d.ts

@@ -0,0 +1,18 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function expandTilde(p: string): string;
+/**
+ * Resolve path to absolute. Expands ~ to homedir first so that the result
+ * does not depend on process.cwd().
+ */
+export declare function resolveAbsolute(p: string): string;
+/**
+ * Derive default output directory name from input file path.
+ * e.g., /path/to/video.mp4 -> /path/to/video_scenes
+ */
+export declare function deriveOutputPath(inputPath: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",
@@ -55,7 +55,6 @@
   },
   "dependencies": {
     "@ffprobe-installer/ffprobe": "^1.4.1",
-    "@lumy-pack/shared": "0.0.1",
     "@techstark/opencv-js": "4.12.0-release.1",
     "commander": "^12.1.0",
     "execa": "^9.5.0",
@@ -67,6 +66,7 @@
     "sharp": "^0.33.0"
   },
   "devDependencies": {
+    "@lumy-pack/shared": "0.0.1",
     "@types/node": "^20.11.0",
     "@types/react": "^18.0.0",
     "@vitest/coverage-v8": "^3.2.4"