@lumy-pack/scene-sieve 0.1.0 → 0.2.1

package/dist/constants/package-version.d.ts

@@ -0,0 +1,2 @@
+/** Runtime manifest version shared by CLI responses and metadata documents. */
+export declare const PACKAGE_VERSION: string;

package/dist/constants/pipeline-defaults.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Default values for scene-sieve pipeline options (frame count, threshold, extraction, segmentation).
+ */
+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 DEFAULT_MAX_SEGMENT_DURATION = 300;
+export declare const DEFAULT_SEGMENT_CONCURRENCY = 2;
+export declare const IOU_THRESHOLD = 0.9;
+export declare const ANIMATION_FRAME_THRESHOLD = 5;
+/** Default maximum contact sheet columns. */
+export declare const DEFAULT_SHEET_COLUMNS = 4;
+/** Default contact sheet tile width in pixels. */
+export declare const DEFAULT_SHEET_TILE_WIDTH = 320;
+/** Default maximum contact sheet tiles. */
+export declare const DEFAULT_SHEET_MAX_TILES = 40;
+/** Enable timestamp labels on contact sheet tiles by default. */
+export declare const DEFAULT_SHEET_LABEL = true;
+/** White contact sheet margin and gap in pixels. */
+export declare const SHEET_TILE_GAP = 4;
+/** Tile-height fraction used for label font size. */
+export declare const SHEET_LABEL_HEIGHT_RATIO = 0.07;
+/** Maximum distinct regions retained per selected-frame span. */
+export declare const CHANGE_REGION_LIMIT = 5;
+/** Metadata schema discriminator. */
+export declare const METADATA_VERSION = 2;
+/** Fixed contact sheet output name. */
+export declare const SHEET_FILE_NAME = "sheet.jpg";
+/** Fixed metadata document output name. */
+export declare const METADATA_FILE_NAME = ".metadata.json";

package/dist/core/{analyzer.d.ts → analyzer/analyzer.d.ts}

@@ -1,5 +1,5 @@
-import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } from '../types/index.js';
-import type { Point2D } from './dbscan.js';
+import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } from '../../types/index.js';
+import type { Point2D } from './clustering/dbscan.js';
 type CvLib = typeof import('@techstark/opencv-js');
 export declare function preprocessFrame(framePath: string, scale: number): Promise<{
     data: Uint8Array;
@@ -19,10 +19,6 @@ export declare class IoUTracker {
     flushAndGetAnimations(): AnimationMetadata[];
     getAnimationWeight(boxIndex: number, boxes: BoundingBox[]): number;
 }
-export interface AKAZEResult {
-    sNew: Point2D[];
-    sLoss: Point2D[];
-}
 /**
  * Pixel-level difference fallback for AKAZE blind spots.
  *
@@ -37,6 +33,12 @@ export interface AKAZEResult {
  * 3. threshold → binary mask of significant changes
  * 4. findContours → bounding rects of changed regions
  * 5. Grid sampling within each bounding rect → Point2D[]
+ *
+ * @param cvLib - Initialized OpenCV runtime shared by the analyzer.
+ * @param frame1 - Previous grayscale frame, with the same dimensions as frame2.
+ * @param frame2 - Next grayscale frame, with the same dimensions as frame1.
+ * @returns Grid-sampled points from changed regions.
+ * @throws Propagates allocation or OpenCV errors after releasing acquired handles.
  */
 export declare function computePixelDiff(cvLib: CvLib, frame1: {
     data: Uint8Array;
@@ -57,6 +59,9 @@ export declare function computeInformationGain(clusters: BoundingBox[], clusterP
  * 2. DBSCAN Spatial Clustering
  * 3. Spatio-temporal IoU Tracking
  * 4. G(t) Information Gain Scoring
+ * @param ctx - Frames, analysis options, and the progress callback for this run.
+ * @returns Adjacent scores and tracked animations in analysis coordinates.
+ * @throws Propagates runtime errors and rejects total failure of two or more pairs after cleanup.
  */
 export declare function analyzeFrames(ctx: ProcessContext): Promise<AnalysisResult>;
 export {};

package/dist/core/{dbscan.d.ts → analyzer/clustering/dbscan.d.ts}

@@ -1,4 +1,4 @@
-import type { DBSCANResult } from '../types/index.js';
+import type { DBSCANResult } from '../../../types/index.js';
 export interface Point2D {
     x: number;
     y: number;

package/dist/core/analyzer/constants/vision-tuning.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tuning constants for the OpenCV-based vision analysis pipeline (DBSCAN, feature matching, pixel-diff fallback).
+ */
+export declare const OPENCV_BATCH_SIZE = 10;
+export declare const DBSCAN_ALPHA = 0.03;
+export declare const DBSCAN_MIN_PTS = 4;
+export declare const DECAY_LAMBDA = 0.95;
+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;

package/dist/core/analyzer/features/feature-diff.d.ts

@@ -0,0 +1,14 @@
+import type { Point2D } from '../clustering/dbscan.js';
+import type { FrameFeatures } from './frame-features.js';
+/** Initialized OpenCV runtime supplied by the analyzer. */
+type CvLib = typeof import('@techstark/opencv-js');
+/**
+ * Match prev to next with Hamming k=2, crossCheck=false and strict ratio 0.25.
+ * @param cvLib - Initialized OpenCV runtime.
+ * @param prev - Previous frame's live features, owned by the caller.
+ * @param next - Next frame's live features, owned by the caller.
+ * @returns Unmatched next-frame coordinates without changing input ownership.
+ * @throws Propagates matching errors after releasing temporary native handles.
+ */
+export declare function computeNewPoints(cvLib: CvLib, prev: FrameFeatures, next: FrameFeatures): Point2D[];
+export {};

package/dist/core/analyzer/features/frame-features.d.ts

@@ -0,0 +1,32 @@
+import type { AKAZE, KeyPointVector, Mat } from '@techstark/opencv-js';
+/** Initialized OpenCV runtime supplied by the analyzer. */
+type CvLib = typeof import('@techstark/opencv-js');
+/** Grayscale bytes whose length matches width times height. */
+type PreprocessedFrame = {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+/** Caller-owned AKAZE features for one frame; delete releases both handles once. */
+export interface FrameFeatures {
+    /** Width of the analyzed grayscale image. */
+    readonly width: number;
+    /** Height of the analyzed grayscale image. */
+    readonly height: number;
+    /** Keypoints in descriptor row order. */
+    readonly keypoints: KeyPointVector;
+    /** Descriptor rows equal keypoints.size(). */
+    readonly descriptors: Mat;
+    /** Release both native handles; repeated calls have no effect. */
+    delete(): void;
+}
+/**
+ * Detect one frame's features without retaining its image or mask.
+ * @param cvLib - Initialized OpenCV runtime.
+ * @param akaze - Detector owned and released by the caller.
+ * @param frame - Grayscale bytes with matching width and height.
+ * @returns Feature handles that the caller must delete.
+ * @throws Propagates native errors after releasing partial allocations.
+ */
+export declare function computeFrameFeatures(cvLib: CvLib, akaze: AKAZE, frame: PreprocessedFrame): FrameFeatures;
+export {};

package/dist/core/analyzer/index.d.ts

@@ -0,0 +1,3 @@
+export { analyzeFrames, computeIoU, computeInformationGain } from './analyzer.js';
+export { dbscan } from './clustering/dbscan.js';
+export type { Point2D } from './clustering/dbscan.js';

package/dist/core/constants/workspace-layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Temp workspace naming and frame file layout for pipeline runs.
+ */
+export declare const APP_NAME = "scene-sieve";
+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 function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/{extractor.d.ts → extractor/extractor.d.ts}

@@ -1,4 +1,4 @@
-import type { FrameNode, ProcessContext } from '../types/index.js';
+import type { FrameNode, ProcessContext } from '../../types/index.js';
 export interface FFprobeMetadata {
     format?: {
         format_name?: string;
@@ -10,8 +10,9 @@ export interface FFprobeMetadata {
 }
 /**
  * Extract frames from video/GIF using FFmpeg.
- * Always uses FPS-based extraction. For long videos, FPS is automatically
- * reduced to stay within maxFrames budget.
+ * @param ctx Pipeline context; records effectiveFps and sourceDurationSec for video input.
+ * @returns Extracted candidates, or the unchanged input array in frames mode.
+ * @throws When the input is missing, metadata has no video stream, or FFmpeg fails.
  */
 export declare function extractFrames(ctx: ProcessContext): Promise<FrameNode[]>;
 export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMetadata>;
@@ -25,6 +26,7 @@ export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMeta
  * @param scale - Height scale for vision analysis
  * @param startTime - Start time in seconds
  * @param duration - Duration in seconds to extract
+ * @param frameLimit - Positive output limit; defaults to the range's grid capacity
  * @returns Array of FrameNode with segment-local timestamps (starting from 0)
  */
-export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number): Promise<FrameNode[]>;
+export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number, frameLimit?: number): Promise<FrameNode[]>;

package/dist/core/extractor/index.d.ts

@@ -0,0 +1 @@
+export { extractFrames, extractFramesForRange, getVideoMetadata } from './extractor.js';

package/dist/core/index.d.ts

@@ -1,9 +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';
+export { runPipeline, runPipelineInWorker } from './orchestrator/index.js';
+export type { AnimationMetadata, VideoMetadata, FrameMetadata, FrameChange, ToolMetadata, ToolParams, SheetMetadata, SheetOptions, SieveMetadata, EdgeMetadata, EdgeChange, } from '../types/index.js';
+export { analyzeFrames, computeIoU, computeInformationGain, dbscan, } from './analyzer/index.js';
+export type { Point2D } from './analyzer/index.js';
+export { extractFrames } from './extractor/index.js';
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner/index.js';
+export { resolveInput, resolveOptions } from './input-resolver/index.js';
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter/index.js';
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, cleanupStaleWorkspaces, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace/index.js';

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

@@ -0,0 +1 @@
+export { resolveInput, resolveOptions } from './input-resolver.js';

package/dist/core/{input-resolver.d.ts → input-resolver/input-resolver.d.ts}

@@ -1,4 +1,10 @@
-import type { FrameNode, ResolvedOptions, SieveOptions } from '../types/index.js';
+import type { FrameNode, ResolvedOptions, SieveOptions } from '../../types/index.js';
+/**
+ * Validate supplied options and resolve defaults and paths for the pipeline.
+ * @param options - Mode-specific input and optional numeric settings.
+ * @returns Complete pipeline settings with absolute file input paths.
+ * @throws An input error if a supplied numeric setting is invalid.
+ */
 export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
 /**
  * Resolve the input source to a list of FrameNode[].
@@ -6,6 +12,10 @@ export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
  * - 'file'   mode: validate file exists and delegate to extractor (caller's responsibility)
  * - 'buffer' mode: write buffer as temp video file, return path via FrameNode trick (empty list)
  * - 'frames' mode: write frame buffers as JPGs, return FrameNode[]
+ * @param options - Input source; encoded frames must have matching dimensions.
+ * @param workspacePath - Workspace receiving temporary input files.
+ * @returns Frame nodes or a resolved video path for extraction.
+ * @throws Propagates metadata or write errors and rejects mismatched frame sizes.
  */
 export declare function resolveInput(options: SieveOptions, workspacePath: string): Promise<{
     frames: FrameNode[];

package/dist/core/input-resolver/validation/validate-options.d.ts

@@ -0,0 +1,8 @@
+import type { SieveOptions } from '../../../types/index.js';
+/**
+ * Reject invalid numeric options before defaults or pipeline effects are applied.
+ * @param options - Supplied options; omitted numeric fields use pipeline defaults.
+ * @returns Nothing when all supplied numeric fields satisfy their contracts.
+ * @throws An input error naming the invalid option and its received value.
+ */
+export declare function validateOptions(options: SieveOptions): void;

package/dist/core/orchestrator/index.d.ts

@@ -0,0 +1,3 @@
+export { runPipeline } from './orchestrator.js';
+export { runPipelineInWorker } from './worker/run-in-worker.js';
+export type { SieveWorkerOptions } from './worker/run-in-worker.js';

package/dist/core/orchestrator/orchestrator.d.ts

@@ -0,0 +1,8 @@
+import type { SieveOptions, SieveResult } from '../../types/index.js';
+/**
+ * Run the five pipeline stages, delegating segmented inputs to the segmenter.
+ * @param options - Mode-specific input and optional pipeline settings.
+ * @returns Selected outputs with v2 frame metadata and zero-based API animations.
+ * @throws Propagates stage failures after cleaning the workspace unless debug is enabled.
+ */
+export declare function runPipeline(options: SieveOptions): Promise<SieveResult>;

package/dist/core/{run-in-worker.d.ts → orchestrator/worker/run-in-worker.d.ts}

@@ -1,9 +1,13 @@
-import type { ProgressPhase, SieveInput, SieveOptionsBase, SieveResult } from '../types/index.js';
+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
+ * @param options - Serializable input and pipeline settings for this run.
+ * @param onProgress - Receives worker progress updates.
+ * @returns The pipeline result; settlement is unchanged by later exit events.
+ * @throws Rejects worker errors or any worker exit before a result is received.
  */
 export declare function runPipelineInWorker(options: SieveWorkerOptions, onProgress: (phase: ProgressPhase, percent: number) => void): Promise<SieveResult>;

package/dist/core/pruner/index.d.ts

@@ -0,0 +1 @@
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner.js';

package/dist/core/{pruner.d.ts → pruner/pruner.d.ts}

@@ -1,4 +1,4 @@
-import type { FrameNode, ScoreEdge } from '../types/index.js';
+import type { FrameNode, ScoreEdge } from '../../types/index.js';
 /**
  * Edge-aware greedy merge with re-linking — O(N log N).
  *
@@ -35,7 +35,7 @@ export declare function pruneTo(graph: ScoreEdge[], frames: FrameNode[], targetC
  */
 export declare function suppressConsecutiveRuns(graph: ScoreEdge[], passingIndices: number[], normalizedScores: number[]): Set<number>;
 /**
- * Threshold-based pruning with NMS -- O(N).
+ * Threshold-based pruning with NMS -- including normalization, O(N log N).
  *
  * 1. Scores are normalized to [0, 1] via percentile normalization.
  * 2. Edges with normalized score >= threshold are collected.

package/dist/{utils/math.d.ts → core/pruner/scoring/normalize-scores.d.ts}

@@ -1,3 +1,7 @@
+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;
 /**
  * Interface for objects that have a numeric score.
  */

package/dist/core/segmenter/index.d.ts

@@ -0,0 +1 @@
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter.js';

package/dist/core/{segmenter.d.ts → segmenter/segmenter.d.ts}

@@ -1,4 +1,4 @@
-import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentPlan, SegmentResult, SieveOptions, SieveResult } from '../types/index.js';
+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.
@@ -6,25 +6,25 @@ import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentP
  */
 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)
+ * Partition the global extraction grid into nonempty logical segments.
+ * @param totalDuration Positive source duration in seconds.
+ * @param maxSegmentDuration Positive logical segment width in seconds.
+ * @param maxFrames Candidate budget, defensively raised to at least two.
+ * @param fps Positive requested sampling frequency.
+ * @returns Contiguous plan indices with grid-aligned seeks and overlap-inclusive limits.
  */
 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
+ * @param segmentResults Local frames, edges and tracker entries with distinct segment indices.
+ * @returns Global timestamp-ordered frames, aliased edges and animations without self loops.
+ * Duplicate edges keep the higher score; duplicate animations keep the first tracker entry.
  */
 export declare function mergeSegmentFrames(segmentResults: SegmentResult[]): {
     frames: FrameNode[];
     edges: ScoreEdge[];
     animations: AnimationMetadata[];
+    analysisResolution: SegmentResult['analysisResolution'];
 };
 /**
  * Extract frames for a single segment and analyze them.

package/dist/core/utils/metadata/build-edge-metadata.d.ts

@@ -0,0 +1,11 @@
+import type { EdgeMetadata, ScoreEdge } from '../../../types/index.js';
+/**
+ * Serialize raw candidate edges in graph order.
+ * @param graph - Adjacent-pair edges, optionally carrying tracker partitions.
+ * @param analysisResolution - Analysis dimensions used for both area fractions.
+ * @returns One-based IDs with six-decimal scores and four-decimal clamped ratios.
+ */
+export declare function buildEdgeMetadata(graph: ScoreEdge[], analysisResolution: {
+    width: number;
+    height: number;
+}): EdgeMetadata[];

package/dist/core/utils/metadata/build-frame-metadata.d.ts

@@ -0,0 +1,20 @@
+import type { FrameMetadata, FrameNode, ScoreEdge } from '../../../types/index.js';
+/**
+ * Describe selected frames using candidate adjacency rather than synthetic pruning edges.
+ * @param input - Chronological candidates and selections, raw graph and output dimensions.
+ * @returns One-based frame summaries with rounded timestamps and nonnegative holds.
+ */
+export declare function buildFrameMetadata(input: {
+    frames: FrameNode[];
+    graph: ScoreEdge[];
+    selected: FrameNode[];
+    originalDurationMs: number;
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
+    outputResolution: {
+        width: number;
+        height: number;
+    };
+}): FrameMetadata[];

package/dist/core/utils/metadata/build-sieve-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, SheetMetadata, SieveMetadata, VideoMetadata } from '../../../types/index.js';
+/**
+ * Assemble the complete v2 document without I/O or mutation.
+ * @param input - Pipeline state, selections, output-space video and zero-based animations.
+ * @returns Contract-ordered metadata, omitting unrequested optional keys entirely.
+ */
+export declare function buildSieveMetadata(input: {
+    ctx: ProcessContext;
+    selected: FrameNode[];
+    video: VideoMetadata;
+    animations: AnimationMetadata[];
+    version: string;
+    sheet?: SheetMetadata;
+}): SieveMetadata;

package/dist/core/utils/metadata/build-tool-metadata.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedOptions, ToolMetadata } from '../../../types/index.js';
+/**
+ * Record the tool and the nine selection and encoding settings in contract order.
+ * @param options - Validated pipeline settings; operational options are excluded.
+ * @param version - Runtime package version supplied by the I/O boundary.
+ * @returns Deterministic tool provenance without paths or execution details.
+ */
+export declare function buildToolMetadata(options: ResolvedOptions, version: string): ToolMetadata;

package/dist/core/utils/metadata/build-video-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, VideoMetadata } from '../../../types/index.js';
+/**
+ * Read output dimensions and build consistent video and animation metadata.
+ * JPEG finalization does not resize, so the source dimensions match the output.
+ * @param ctx Pipeline state with source duration, effective FPS and analysis-space animations.
+ * @param selected Selected frames in output order; the first candidate is the fallback.
+ * @param analysisResolution Analysis dimensions; absent or zero dimensions imply no scaling.
+ * @returns Video metadata and new output-space animations, retaining zero-based frame IDs.
+ * @throws If sharp cannot read the selected or fallback image. Empty input performs no image I/O.
+ */
+export declare function buildVideoMetadata(ctx: ProcessContext, selected: FrameNode[], analysisResolution: ProcessContext['analysisResolution']): Promise<{
+    video: VideoMetadata;
+    animations: AnimationMetadata[];
+}>;

package/dist/core/utils/metadata/change/build-frame-change.d.ts

@@ -0,0 +1,20 @@
+import type { FrameChange, ScoreEdge } from '../../../../types/index.js';
+/**
+ * Aggregate adjacent-pair evidence across one selected-frame span.
+ * @param input - Ordered raw edges, one-based previous ID, skipped count and dimensions.
+ * @returns Rounded raw scores, analysis-space union ratio and output-space regions.
+ */
+export declare function buildFrameChange(input: {
+    spanEdges: ScoreEdge[];
+    fromFrameId: number;
+    skippedCandidates: number;
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
+    outputResolution: {
+        width: number;
+        height: number;
+    };
+    regionLimit: number;
+}): FrameChange;

package/dist/core/utils/metadata/change/select-regions.d.ts

@@ -0,0 +1,8 @@
+import type { BoundingBox } from '../../../../types/index.js';
+/**
+ * Select distinct positive-area boxes with deterministic area and coordinate ties.
+ * @param boxes - Already scaled output rectangles; the input is not mutated.
+ * @param limit - Nonnegative maximum number of regions.
+ * @returns Largest boxes ordered by area descending, then y, x and width ascending.
+ */
+export declare function selectRegions(boxes: BoundingBox[], limit: number): BoundingBox[];

package/dist/core/utils/metadata/change/union-area/y-coverage-tree.d.ts

@@ -0,0 +1,26 @@
+/** Internal sweep helper retaining cover counts and lengths between sorted y bounds. */
+export declare class YCoverageTree {
+    private readonly bounds;
+    /** Number of whole-node covering intervals, independent of descendants. */
+    private readonly counts;
+    /** Covered geometric length for each node, including partially covered children. */
+    private readonly lengths;
+    /**
+     * Allocate linear storage for the elementary intervals between coordinates.
+     * @param bounds - At least two sorted unique finite y endpoints.
+     */
+    constructor(bounds: number[]);
+    /** Total active covered y length, in the input coordinate system. */
+    get coveredLength(): number;
+    /**
+     * Adjust a nonempty half-open interval and refresh its ancestors' lengths.
+     * @param start - Inclusive endpoint index; 0 <= start < end.
+     * @param end - Exclusive endpoint index; end < bounds.length.
+     * @param delta - One on entry, minus one for the matching departure.
+     * @param node - Internal tree slot; callers use the root default.
+     * @param left - Inclusive endpoint index of this node.
+     * @param right - Exclusive endpoint index of this node.
+     * @returns Nothing; mutates this tree's coverage in O(log n).
+     */
+    update(start: number, end: number, delta: number, node?: number, left?: number, right?: number): void;
+}

package/dist/core/utils/metadata/change/union-area.d.ts

@@ -0,0 +1,7 @@
+import type { BoundingBox } from '../../../../types/index.js';
+/**
+ * Measure rectangle union with an x sweep in O(n log n) time and O(n) space.
+ * @param boxes - Finite rectangles; nonpositive dimensions are ignored.
+ * @returns Covered area in the input coordinate system, or zero for empty input.
+ */
+export declare function unionArea(boxes: BoundingBox[]): number;

package/dist/core/utils/metadata/scale-bounding-box.d.ts

@@ -0,0 +1,11 @@
+import type { BoundingBox } from '../../../types/index.js';
+/**
+ * Convert an analysis box to clamped integer output pixels.
+ * @param box - Analysis-space rectangle; the input remains unchanged.
+ * @param sx - Horizontal output-to-analysis scale.
+ * @param sy - Vertical output-to-analysis scale.
+ * @param width - Nonnegative output image width.
+ * @param height - Nonnegative output image height.
+ * @returns A rectangle contained within the output dimensions.
+ */
+export declare function scaleBoundingBox(box: BoundingBox, sx: number, sy: number, width: number, height: number): BoundingBox;

package/dist/core/utils/output/finalize-selection.d.ts

@@ -0,0 +1,15 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, SieveMetadata } from '../../../types/index.js';
+/**
+ * Read output dimensions once, render optional sheets and finalize the shared v2 document.
+ * @param ctx - Pipeline state owned by the orchestrator; this function does not mutate it.
+ * @param selected - Selected frames in temporal order.
+ * @returns Mode-specific output, the document and zero-based API animations.
+ * @throws Propagates image, rendering and output I/O errors to the orchestrator.
+ */
+export declare function finalizeSelection(ctx: ProcessContext, selected: FrameNode[]): Promise<{
+    outputFiles: string[];
+    outputBuffers?: Buffer[];
+    document: SieveMetadata;
+    animations: AnimationMetadata[];
+    sheetBuffer?: Buffer;
+}>;

package/dist/core/utils/sheet/build-tile-label-svg.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build a tile-sized SVG overlay with a translucent badge and an explicit text baseline.
+ * @param text - A formatTileLabel result containing only digits, #, spaces, colons and periods.
+ * @param tileWidth - Positive tile canvas width in pixels.
+ * @param tileHeight - Positive tile canvas height in pixels.
+ * @returns Encoded SVG bytes for a top-left sharp composite overlay.
+ */
+export declare function buildTileLabelSvg(text: string, tileWidth: number, tileHeight: number): Buffer;

package/dist/core/utils/sheet/format-tile-label.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Format a contact sheet label without rounding into the next tenth of a second.
+ * @param frameId - One-based candidate frame ID.
+ * @param timestampMs - Nonnegative candidate time in milliseconds.
+ * @returns A label in the form "#<id> mm:ss.s", allowing minutes beyond two digits.
+ */
+export declare function formatTileLabel(frameId: number, timestampMs: number): string;

package/dist/core/utils/sheet/render-contact-sheet.d.ts

@@ -0,0 +1,19 @@
+import type { FrameNode, SheetMetadata, SheetOptions } from '../../../types/index.js';
+/**
+ * Read selected frame images and render a row-major contact sheet.
+ * @param input - Nonempty ordered selections, positive dimensions and validated sheet settings.
+ * @returns JPEG bytes and the effective tile layout with one-based frame IDs.
+ * @throws Propagates sharp image reading, compositing or encoding errors.
+ */
+export declare function renderContactSheet(input: {
+    selected: FrameNode[];
+    resolution: {
+        width: number;
+        height: number;
+    };
+    options: Required<SheetOptions>;
+    quality: number;
+}): Promise<{
+    buffer: Buffer;
+    metadata: SheetMetadata;
+}>;

package/dist/core/utils/sheet/sample-tile-frames.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sample a sequence uniformly while always retaining both endpoints.
+ * @param items - Items in temporal order.
+ * @param maxTiles - Validated integer limit of at least two.
+ * @returns The original sequence when within the limit, otherwise evenly sampled items.
+ */
+export declare function sampleTileFrames<T>(items: T[], maxTiles: number): {
+    items: T[];
+    sampled: boolean;
+};

package/dist/core/workspace/index.d.ts

@@ -0,0 +1 @@
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, cleanupStaleWorkspaces, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';

package/dist/core/{workspace.d.ts → workspace/workspace.d.ts}

@@ -1,6 +1,15 @@
-import type { FrameNode, ProcessContext } from '../types/index.js';
+import type { FrameNode, ProcessContext, SieveMetadata } from '../../types/index.js';
 export declare function createWorkspace(sessionId: string): Promise<string>;
-export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[]): Promise<string[]>;
+/**
+ * Write selected JPEGs and the supplied document before replacing the output directory.
+ * @param ctx - Workspace, quality and destination settings.
+ * @param selectedFrames - Frames paired by position with document.frames.
+ * @param document - Complete metadata, including the output file names.
+ * @param sheetBuffer - Optional JPEG contact sheet bytes to persist unchanged.
+ * @returns Selected JPEG paths, optional sheet path and finally the metadata path.
+ * @throws Rejects mismatched frame counts and propagates image or filesystem errors.
+ */
+export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[], document: SieveMetadata, sheetBuffer?: Buffer): Promise<string[]>;
 export declare function createSegmentWorkspace(parentWorkspacePath: string, segmentIndex: number): Promise<string>;
 export declare function cleanupWorkspace(workspacePath: string): Promise<void>;
 /**