@lumy-pack/scene-sieve 0.0.8 → 0.0.10

package/dist/core/pruner.d.ts

@@ -1,61 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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/workspace.d.ts

@@ -1,24 +0,0 @@
-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 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/index.d.ts

@@ -1,2 +0,0 @@
-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/types/index.d.ts

@@ -1,107 +0,0 @@
-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;
-}
-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;
-}
-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[];
-}

package/dist/utils/logger.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-/**
- * 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/paths.d.ts

@@ -1,18 +0,0 @@
-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;