@lumy-pack/scene-sieve 0.2.0 → 0.2.1

package/dist/pipeline-worker.mjs

@@ -4,12 +4,13 @@ import { randomUUID } from "node:crypto";
 import { filter, map } from "@winglet/common-utils";
 import pc from "picocolors";
 import sharp from "sharp";
+import { existsSync } from "node:fs";
 import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
+import { homedir, tmpdir } from "node:os";
 import { path } from "@ffprobe-installer/ffprobe";
 import { execa } from "execa";
 import ffmpegPath from "ffmpeg-static";
-import { homedir, tmpdir } from "node:os";
 
 //#region src/logging/logger.ts
 let debugMode = false;
@@ -36,8 +37,10 @@ const logger = {
 		console.error(`${pc.red("error")} ${message}`);
 	},
 	debug(message) {
-		if (debugMode) if (jsonMode) process.stderr.write(`${pc.gray(`[${timestamp()}] debug`)} ${message}\n`);
-		else console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+		if (debugMode) {
+			if (jsonMode) process.stderr.write(`${pc.gray(`[${timestamp()}] debug`)} ${message}\n`);
+			else console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+		}
 	}
 };
 
@@ -45,6 +48,12 @@ const logger = {
 //#region src/constants/pipeline-defaults.ts
 const DEFAULT_THRESHOLD = .5;
 const IOU_THRESHOLD = .9;
+/** Tile-height fraction used for label font size. */
+const SHEET_LABEL_HEIGHT_RATIO = .07;
+/** Fixed contact sheet output name. */
+const SHEET_FILE_NAME = "sheet.jpg";
+/** Fixed metadata document output name. */
+const METADATA_FILE_NAME = ".metadata.json";
 
 //#endregion
 //#region src/core/analyzer/constants/vision-tuning.ts
@@ -467,7 +476,8 @@ async function analyzeBatch(cvLib, akaze, frames, carry, scale, tracker, pairOff
 			try {
 				prev ??= computeFrameFeatures(cvLib, akaze, preprocessed[i]);
 				next = computeFrameFeatures(cvLib, akaze, preprocessed[i + 1]);
-				let dbscanResult = dbscan(computeNewPoints(cvLib, prev, next), imageWidth, imageHeight);
+				const sNew = computeNewPoints(cvLib, prev, next);
+				let dbscanResult = dbscan(sNew, imageWidth, imageHeight);
 				let clusters = dbscanResult.boundingBoxes;
 				if (clusters.length === 0) {
 					const pixelDiffPoints = computePixelDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
@@ -480,13 +490,18 @@ async function analyzeBatch(cvLib, akaze, frames, carry, scale, tracker, pairOff
 				const clusterPointCounts = new Array(clusters.length).fill(0);
 				for (const label of dbscanResult.labels) if (label >= 0) clusterPointCounts[label]++;
 				const animationIndices = tracker.update(clusters, pairIndex);
+				const change = {
+					regions: filter(clusters, (_, ci) => !animationIndices.has(ci)),
+					animatedRegions: filter(clusters, (_, ci) => animationIndices.has(ci))
+				};
 				const animationWeights = map(clusters, (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0);
 				const score = computeInformationGain(clusters, clusterPointCounts, imageArea, animationIndices, animationWeights);
 				logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
 				edges.push({
 					sourceId: frames[i].id,
 					targetId: frames[i + 1].id,
-					score
+					score,
+					change
 				});
 			} catch (err) {
 				logger.warn(`Frame pair analysis failed: ${String(err)}`);
@@ -584,50 +599,11 @@ async function analyzeFrames(ctx) {
 }
 
 //#endregion
-//#region src/core/utils/metadata/build-video-metadata.ts
-/**
-* 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.
-*/
-async function buildVideoMetadata(ctx, selected, analysisResolution) {
-	const firstFrame = selected[0] ?? ctx.frames[0];
-	const dimensions = firstFrame ? await sharp(firstFrame.extractPath).metadata() : void 0;
-	const width = dimensions?.width ?? 0;
-	const height = dimensions?.height ?? 0;
-	const sx = analysisResolution?.width ? width / analysisResolution.width : 1;
-	const sy = analysisResolution?.height ? height / analysisResolution.height : 1;
-	const lastTimestamp = ctx.frames[ctx.frames.length - 1]?.timestamp ?? 0;
-	const duration = ctx.options.mode === "frames" ? lastTimestamp : ctx.sourceDurationSec ?? lastTimestamp;
-	return {
-		video: {
-			originalDurationMs: Math.round(duration * 1e3),
-			fps: ctx.options.mode === "frames" ? 1 : ctx.effectiveFps ?? ctx.options.fps,
-			resolution: {
-				width,
-				height
-			}
-		},
-		animations: (ctx.animations ?? []).map((animation) => {
-			const box = animation.boundingBox;
-			const x = Math.max(0, Math.min(width, Math.round(box.x * sx)));
-			const y = Math.max(0, Math.min(height, Math.round(box.y * sy)));
-			return {
-				...animation,
-				boundingBox: {
-					x,
-					y,
-					width: Math.max(0, Math.min(width - x, Math.round(box.width * sx))),
-					height: Math.max(0, Math.min(height - y, Math.round(box.height * sy)))
-				}
-			};
-		})
-	};
-}
+//#region src/constants/package-version.ts
+/** Source constants are two levels below the manifest; runtime bundles are one level below. */
+const manifestPath = existsSync(new URL("../package.json", import.meta.url)) ? "../package.json" : "../../package.json";
+/** Runtime manifest version shared by CLI responses and metadata documents. */
+const PACKAGE_VERSION = createRequire(import.meta.url)(manifestPath).version;
 
 //#endregion
 //#region src/core/constants/workspace-layout.ts
@@ -678,7 +654,564 @@ function resolveAbsolute(p) {
 * e.g., /path/to/video.mp4 -> /path/to/video_scenes
 */
 function deriveOutputPath(inputPath) {
-	return resolve(resolve(inputPath, ".."), `${basename(inputPath, extname(inputPath))}_scenes`);
+	const dir = resolve(inputPath, "..");
+	const name = basename(inputPath, extname(inputPath));
+	return resolve(dir, `${name}_scenes`);
+}
+
+//#endregion
+//#region src/core/workspace/workspace.ts
+async function createWorkspace(sessionId) {
+	const workspacePath = getTempWorkspaceDir(sessionId);
+	await ensureDir(join(workspacePath, "frames"));
+	await ensureDir(join(workspacePath, "output"));
+	return workspacePath;
+}
+/**
+* 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.
+*/
+async function finalizeOutput(ctx, selectedFrames, document, sheetBuffer) {
+	if (document.frames.length !== selectedFrames.length) throw new Error("metadata frame count must match selected frame count");
+	const stagingDir = join(ctx.workspacePath, "output");
+	const outputPath = ctx.options.outputPath;
+	const quality = ctx.options.quality;
+	const outputFiles = [];
+	for (let i = 0; i < selectedFrames.length; i++) {
+		const frame = selectedFrames[i];
+		const fileName = document.frames[i].fileName;
+		const destPath = join(stagingDir, fileName);
+		await sharp(frame.extractPath).jpeg({
+			quality,
+			mozjpeg: true
+		}).toFile(destPath);
+		outputFiles.push(join(outputPath, fileName));
+	}
+	if (sheetBuffer) {
+		await writeFile(join(stagingDir, SHEET_FILE_NAME), sheetBuffer);
+		outputFiles.push(join(outputPath, SHEET_FILE_NAME));
+	}
+	const metadataPath = join(stagingDir, METADATA_FILE_NAME);
+	await writeFile(metadataPath, JSON.stringify(document, null, 2));
+	outputFiles.push(join(outputPath, METADATA_FILE_NAME));
+	await ensureDir(join(outputPath, ".."));
+	await rm(outputPath, {
+		recursive: true,
+		force: true
+	});
+	await rename(stagingDir, outputPath);
+	return outputFiles;
+}
+async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
+	const segmentPath = join(parentWorkspacePath, "segments", String(segmentIndex));
+	await ensureDir(join(segmentPath, "frames"));
+	return segmentPath;
+}
+async function cleanupWorkspace(workspacePath) {
+	if (!workspacePath) return;
+	try {
+		await rm(workspacePath, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+/**
+* Write a video buffer to a temp file in the workspace and return the path.
+* Used by 'buffer' input mode.
+*/
+async function writeInputBuffer(buffer, workspacePath) {
+	const inputDir = join(workspacePath, "input");
+	await ensureDir(inputDir);
+	const tempPath = join(inputDir, "input.mp4");
+	await writeFile(tempPath, buffer);
+	return tempPath;
+}
+/**
+* Write an array of frame Buffers as JPG files and return FrameNode[].
+* Used by 'frames' input mode.
+*/
+async function writeInputFrames(frames, workspacePath) {
+	const framesDir = join(workspacePath, "frames");
+	await ensureDir(framesDir);
+	const frameNodes = [];
+	for (let i = 0; i < frames.length; i++) {
+		const filename = `frame_${String(i).padStart(6, "0")}${FRAME_OUTPUT_EXTENSION}`;
+		const extractPath = join(framesDir, filename);
+		await writeFile(extractPath, frames[i]);
+		frameNodes.push({
+			id: i,
+			timestamp: i,
+			extractPath
+		});
+	}
+	return frameNodes;
+}
+/**
+* Read selected FrameNode files as Buffers with JPEG compression.
+* Used to return output buffers in 'buffer' and 'frames' modes.
+*/
+async function readFramesAsBuffers(frameNodes, quality) {
+	return Promise.all(map(frameNodes, (f) => sharp(f.extractPath).jpeg({
+		quality,
+		mozjpeg: true
+	}).toBuffer()));
+}
+
+//#endregion
+//#region src/core/utils/metadata/change/union-area/y-coverage-tree.ts
+/** Internal sweep helper retaining cover counts and lengths between sorted y bounds. */
+var YCoverageTree = class {
+	bounds;
+	/** Number of whole-node covering intervals, independent of descendants. */
+	counts;
+	/** Covered geometric length for each node, including partially covered children. */
+	lengths;
+	/**
+	* Allocate linear storage for the elementary intervals between coordinates.
+	* @param bounds - At least two sorted unique finite y endpoints.
+	*/
+	constructor(bounds) {
+		this.bounds = bounds;
+		this.counts = Array(4 * bounds.length).fill(0);
+		this.lengths = Array(4 * bounds.length).fill(0);
+	}
+	/** Total active covered y length, in the input coordinate system. */
+	get coveredLength() {
+		return this.lengths[1];
+	}
+	/**
+	* 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, end, delta, node = 1, left = 0, right = this.bounds.length - 1) {
+		if (start <= left && right <= end) this.counts[node] += delta;
+		else {
+			const middle = Math.floor((left + right) / 2);
+			if (start < middle) this.update(start, end, delta, node * 2, left, middle);
+			if (end > middle) this.update(start, end, delta, node * 2 + 1, middle, right);
+		}
+		this.lengths[node] = this.counts[node] > 0 ? this.bounds[right] - this.bounds[left] : right - left === 1 ? 0 : this.lengths[node * 2] + this.lengths[node * 2 + 1];
+	}
+};
+
+//#endregion
+//#region src/core/utils/metadata/change/union-area.ts
+/**
+* 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.
+*/
+function unionArea(boxes) {
+	const events = [];
+	const endpoints = [];
+	for (const box of boxes) {
+		if (!(box.width > 0 && box.height > 0)) continue;
+		const end = box.y + box.height;
+		if (end === box.y) continue;
+		events.push({
+			x: box.x,
+			start: box.y,
+			end,
+			delta: 1
+		});
+		events.push({
+			x: box.x + box.width,
+			start: box.y,
+			end,
+			delta: -1
+		});
+		endpoints.push(box.y, end);
+	}
+	if (events.length === 0) return 0;
+	events.sort((a, b) => a.x - b.x);
+	endpoints.sort((a, b) => a - b);
+	const bounds = endpoints.filter((value, index) => index === 0 || value !== endpoints[index - 1]);
+	const indices = new Map(bounds.map((value, index) => [value, index]));
+	const coverage = new YCoverageTree(bounds);
+	let area = 0;
+	let previousX = events[0].x;
+	for (const event of events) {
+		area += (event.x - previousX) * coverage.coveredLength;
+		coverage.update(indices.get(event.start), indices.get(event.end), event.delta);
+		previousX = event.x;
+	}
+	return area;
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-edge-metadata.ts
+/**
+* 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.
+*/
+function buildEdgeMetadata(graph, analysisResolution) {
+	const area = analysisResolution.width * analysisResolution.height;
+	return map(graph, (edge) => ({
+		sourceFrameId: edge.sourceId + 1,
+		targetFrameId: edge.targetId + 1,
+		score: Math.round(edge.score * 1e6) / 1e6,
+		areaRatio: area > 0 ? Math.round(Math.max(0, Math.min(1, unionArea(edge.change?.regions ?? []) / area)) * 1e4) / 1e4 : 0,
+		animatedAreaRatio: area > 0 ? Math.round(Math.max(0, Math.min(1, unionArea(edge.change?.animatedRegions ?? []) / area)) * 1e4) / 1e4 : 0
+	}));
+}
+
+//#endregion
+//#region src/core/utils/metadata/scale-bounding-box.ts
+/**
+* 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.
+*/
+function scaleBoundingBox(box, sx, sy, width, height) {
+	const x = Math.max(0, Math.min(width, Math.round(box.x * sx)));
+	const y = Math.max(0, Math.min(height, Math.round(box.y * sy)));
+	return {
+		x,
+		y,
+		width: Math.max(0, Math.min(width - x, Math.round(box.width * sx))),
+		height: Math.max(0, Math.min(height - y, Math.round(box.height * sy)))
+	};
+}
+
+//#endregion
+//#region src/core/utils/metadata/change/select-regions.ts
+/**
+* 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.
+*/
+function selectRegions(boxes, limit) {
+	return filter(boxes, (box, index) => box.width > 0 && box.height > 0 && boxes.findIndex((other) => other.x === box.x && other.y === box.y && other.width === box.width && other.height === box.height) === index).sort((a, b) => b.width * b.height - a.width * a.height || a.y - b.y || a.x - b.x || a.width - b.width).slice(0, limit);
+}
+
+//#endregion
+//#region src/core/utils/metadata/change/build-frame-change.ts
+/**
+* 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.
+*/
+function buildFrameChange(input) {
+	const { spanEdges, fromFrameId, skippedCandidates, analysisResolution, outputResolution, regionLimit } = input;
+	const boxes = spanEdges.flatMap((edge) => edge.change?.regions ?? []);
+	const area = analysisResolution.width * analysisResolution.height;
+	const peakScore = spanEdges.reduce((peak, edge) => Math.max(peak, edge.score), 0);
+	const sumScore = spanEdges.reduce((sum, edge) => sum + edge.score, 0);
+	const areaRatio = area > 0 ? Math.max(0, Math.min(1, unionArea(boxes) / area)) : 0;
+	const regions = area > 0 ? selectRegions(map(boxes, (box) => scaleBoundingBox(box, outputResolution.width / analysisResolution.width, outputResolution.height / analysisResolution.height, outputResolution.width, outputResolution.height)), regionLimit) : [];
+	return {
+		fromFrameId,
+		skippedCandidates,
+		peakScore: Math.round(peakScore * 1e6) / 1e6,
+		sumScore: Math.round(sumScore * 1e6) / 1e6,
+		areaRatio: Math.round(areaRatio * 1e4) / 1e4,
+		regions
+	};
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-frame-metadata.ts
+/**
+* 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.
+*/
+function buildFrameMetadata(input) {
+	const { frames, graph, selected, originalDurationMs, analysisResolution, outputResolution } = input;
+	const edgesByPair = new Map(map(graph, (edge) => [`${edge.sourceId}:${edge.targetId}`, edge]));
+	const candidateIndices = new Map(map(frames, (frame, index) => [frame.id, index]));
+	const padding = Math.max(4, String(frames.length).length);
+	return map(selected, (frame, index) => {
+		const timestampMs = Math.round(frame.timestamp * 1e3);
+		const nextTimestampMs = index + 1 < selected.length ? Math.round(selected[index + 1].timestamp * 1e3) : originalDurationMs;
+		const previous = selected[index - 1];
+		const previousIndex = previous ? candidateIndices.get(previous.id) : 0;
+		const currentIndex = candidateIndices.get(frame.id);
+		const spanEdges = [];
+		if (previous) for (let i = previousIndex; i < currentIndex; i++) {
+			const edge = edgesByPair.get(`${frames[i].id}:${frames[i + 1].id}`);
+			if (edge) spanEdges.push(edge);
+		}
+		return {
+			step: index + 1,
+			fileName: `frame_${String(frame.id + 1).padStart(padding, "0")}.jpg`,
+			frameId: frame.id + 1,
+			timestampMs,
+			holdsMs: Math.max(0, nextTimestampMs - timestampMs),
+			change: previous ? buildFrameChange({
+				spanEdges,
+				fromFrameId: previous.id + 1,
+				skippedCandidates: currentIndex - previousIndex - 1,
+				analysisResolution,
+				outputResolution,
+				regionLimit: 5
+			}) : null
+		};
+	});
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-tool-metadata.ts
+/**
+* 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.
+*/
+function buildToolMetadata(options, version) {
+	return {
+		name: "@lumy-pack/scene-sieve",
+		version,
+		params: {
+			fps: options.fps,
+			count: options.count,
+			threshold: options.threshold,
+			scale: options.scale,
+			quality: options.quality,
+			maxFrames: options.maxFrames,
+			iouThreshold: options.iouThreshold,
+			animationThreshold: options.animationThreshold,
+			maxSegmentDuration: options.maxSegmentDuration
+		}
+	};
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-sieve-metadata.ts
+/**
+* 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.
+*/
+function buildSieveMetadata(input) {
+	const { ctx, selected, video, animations, version, sheet } = input;
+	const analysisResolution = ctx.analysisResolution ?? {
+		width: 0,
+		height: 0
+	};
+	return {
+		metadataVersion: 2,
+		tool: buildToolMetadata(ctx.options, version),
+		video,
+		frames: buildFrameMetadata({
+			frames: ctx.frames,
+			graph: ctx.graph,
+			selected,
+			originalDurationMs: video.originalDurationMs,
+			analysisResolution,
+			outputResolution: video.resolution
+		}),
+		animations: map(animations, (animation) => ({
+			...animation,
+			startFrameId: animation.startFrameId + 1,
+			endFrameId: animation.endFrameId + 1,
+			durationMs: Math.round(animation.durationMs)
+		})),
+		...sheet ? { sheet } : {},
+		...ctx.options.includeEdges ? { edges: buildEdgeMetadata(ctx.graph, analysisResolution) } : {}
+	};
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-video-metadata.ts
+/**
+* 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.
+*/
+async function buildVideoMetadata(ctx, selected, analysisResolution) {
+	const firstFrame = selected[0] ?? ctx.frames[0];
+	const dimensions = firstFrame ? await sharp(firstFrame.extractPath).metadata() : void 0;
+	const width = dimensions?.width ?? 0;
+	const height = dimensions?.height ?? 0;
+	const sx = analysisResolution?.width ? width / analysisResolution.width : 1;
+	const sy = analysisResolution?.height ? height / analysisResolution.height : 1;
+	const lastTimestamp = ctx.frames[ctx.frames.length - 1]?.timestamp ?? 0;
+	const duration = ctx.options.mode === "frames" ? lastTimestamp : ctx.sourceDurationSec ?? lastTimestamp;
+	return {
+		video: {
+			originalDurationMs: Math.round(duration * 1e3),
+			fps: ctx.options.mode === "frames" ? 1 : ctx.effectiveFps ?? ctx.options.fps,
+			resolution: {
+				width,
+				height
+			},
+			candidatesCount: ctx.frames.length,
+			selectedCount: selected.length,
+			source: {
+				fileName: ctx.options.mode === "file" && ctx.options.inputPath ? basename(ctx.options.inputPath) : null,
+				mode: ctx.options.mode
+			}
+		},
+		animations: (ctx.animations ?? []).map((animation) => ({
+			...animation,
+			boundingBox: scaleBoundingBox(animation.boundingBox, sx, sy, width, height)
+		}))
+	};
+}
+
+//#endregion
+//#region src/core/utils/sheet/build-tile-label-svg.ts
+/**
+* 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.
+*/
+function buildTileLabelSvg(text, tileWidth, tileHeight) {
+	const fontSize = Math.max(8, Math.round(tileHeight * SHEET_LABEL_HEIGHT_RATIO));
+	const padX = Math.round(fontSize * .4);
+	const padY = Math.round(fontSize * .2);
+	const badgeWidth = Math.min(tileWidth, Math.ceil(text.length * fontSize * .6) + 2 * padX);
+	return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${tileWidth}" height="${tileHeight}"><rect x="0" y="0" width="${badgeWidth}" height="${fontSize + 2 * padY}" fill="black" fill-opacity="0.5"/><text x="${padX}" y="${padY + Math.round(fontSize * .8)}" font-family="sans-serif" font-size="${fontSize}" fill="white">${text}</text></svg>`);
+}
+
+//#endregion
+//#region src/core/utils/sheet/format-tile-label.ts
+/**
+* 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.
+*/
+function formatTileLabel(frameId, timestampMs) {
+	const tenths = Math.floor(timestampMs / 100);
+	return `#${frameId} ${String(Math.floor(tenths / 600)).padStart(2, "0")}:${String(Math.floor(tenths / 10) % 60).padStart(2, "0")}.${tenths % 10}`;
+}
+
+//#endregion
+//#region src/core/utils/sheet/sample-tile-frames.ts
+/**
+* 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.
+*/
+function sampleTileFrames(items, maxTiles) {
+	if (items.length <= maxTiles) return {
+		items,
+		sampled: false
+	};
+	return {
+		items: Array.from({ length: maxTiles }, (_, i) => items[Math.round(i * (items.length - 1) / (maxTiles - 1))]),
+		sampled: true
+	};
+}
+
+//#endregion
+//#region src/core/utils/sheet/render-contact-sheet.ts
+/**
+* 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.
+*/
+async function renderContactSheet(input) {
+	const { selected, resolution, options, quality } = input;
+	const { items, sampled } = sampleTileFrames(selected, options.maxTiles);
+	const columns = Math.min(options.columns, items.length);
+	const rows = Math.ceil(items.length / columns);
+	const tileWidth = options.tileWidth;
+	const tileHeight = Math.max(1, Math.round(tileWidth * resolution.height / resolution.width));
+	const gap = 4;
+	const tiles = await Promise.all(map(items, async (frame, index) => {
+		const tile = sharp(frame.extractPath).resize(tileWidth, tileHeight, { fit: "fill" });
+		if (options.label) {
+			const text = formatTileLabel(frame.id + 1, Math.round(frame.timestamp * 1e3));
+			tile.composite([{
+				input: buildTileLabelSvg(text, tileWidth, tileHeight),
+				top: 0,
+				left: 0
+			}]);
+		}
+		return {
+			input: await tile.png().toBuffer(),
+			top: gap + Math.floor(index / columns) * (tileHeight + gap),
+			left: gap + index % columns * (tileWidth + gap)
+		};
+	}));
+	return {
+		buffer: await sharp({ create: {
+			width: columns * tileWidth + (columns + 1) * gap,
+			height: rows * tileHeight + (rows + 1) * gap,
+			channels: 3,
+			background: "white"
+		} }).composite(tiles).jpeg({
+			quality,
+			mozjpeg: true
+		}).toBuffer(),
+		metadata: {
+			fileName: SHEET_FILE_NAME,
+			columns,
+			tileWidth,
+			tileHeight,
+			frameIds: map(items, (frame) => frame.id + 1),
+			sampled
+		}
+	};
+}
+
+//#endregion
+//#region src/core/utils/output/finalize-selection.ts
+/**
+* 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.
+*/
+async function finalizeSelection(ctx, selected) {
+	const { video, animations } = await buildVideoMetadata(ctx, selected, ctx.analysisResolution);
+	const sheet = ctx.options.sheet && selected.length > 0 && video.resolution.width > 0 && video.resolution.height > 0 ? await renderContactSheet({
+		selected,
+		resolution: video.resolution,
+		options: ctx.options.sheet,
+		quality: ctx.options.quality
+	}) : void 0;
+	const document = buildSieveMetadata({
+		ctx,
+		selected,
+		video,
+		animations,
+		version: PACKAGE_VERSION,
+		...sheet ? { sheet: sheet.metadata } : {}
+	});
+	if (ctx.options.mode === "file") return {
+		outputFiles: await finalizeOutput(ctx, selected, document, sheet?.buffer),
+		document,
+		animations
+	};
+	return {
+		outputFiles: [],
+		outputBuffers: await readFramesAsBuffers(selected, ctx.options.quality),
+		document,
+		animations,
+		...sheet ? { sheetBuffer: sheet.buffer } : {}
+	};
 }
 
 //#endregion
@@ -765,7 +1298,8 @@ async function getVideoMetadata(inputPath) {
 * @returns Zero-based candidates without a segment seek offset.
 */
 async function buildFrameList(framesDir, effectiveFps) {
-	const jpgFiles = filter(await readdir(framesDir), (f) => f.endsWith(".jpg")).sort();
+	const files = await readdir(framesDir);
+	const jpgFiles = filter(files, (f) => f.endsWith(".jpg")).sort();
 	if (jpgFiles.length === 0) return [];
 	return map(jpgFiles, (file, index) => ({
 		id: index,
@@ -901,114 +1435,19 @@ function validateOptions(options) {
 		if (value === void 0) continue;
 		if (!Number.isFinite(value) || integer && !Number.isInteger(value) || (exclusiveMin ? value <= min : value < min) || value > max) throw new Error(`${name} must be ${requirement}, received: ${value}`);
 	}
-}
-
-//#endregion
-//#region src/core/workspace/workspace.ts
-async function createWorkspace(sessionId) {
-	const workspacePath = getTempWorkspaceDir(sessionId);
-	await ensureDir(join(workspacePath, "frames"));
-	await ensureDir(join(workspacePath, "output"));
-	return workspacePath;
-}
-async function finalizeOutput(ctx, selectedFrames) {
-	const stagingDir = join(ctx.workspacePath, "output");
-	const outputPath = ctx.options.outputPath;
-	const quality = ctx.options.quality;
-	const outputFiles = [];
-	const framesMetadata = [];
-	const totalFramesCount = ctx.frames.length;
-	const padding = Math.max(4, String(totalFramesCount).length);
-	for (let i = 0; i < selectedFrames.length; i++) {
-		const frame = selectedFrames[i];
-		const fileName = `frame_${String(frame.id + 1).padStart(padding, "0")}.jpg`;
-		const destPath = join(stagingDir, fileName);
-		await sharp(frame.extractPath).jpeg({
-			quality,
-			mozjpeg: true
-		}).toFile(destPath);
-		outputFiles.push(join(outputPath, fileName));
-		framesMetadata.push({
-			step: i + 1,
-			fileName,
-			frameId: frame.id + 1,
-			timestampMs: Math.round(frame.timestamp * 1e3)
-		});
-	}
-	const { video, animations } = await buildVideoMetadata(ctx, selectedFrames, ctx.analysisResolution);
-	const metadata = {
-		video,
-		frames: framesMetadata,
-		animations: map(animations, (anim) => ({
-			...anim,
-			startFrameId: anim.startFrameId + 1,
-			endFrameId: anim.endFrameId + 1,
-			durationMs: Math.round(anim.durationMs)
-		}))
-	};
-	await writeFile(join(stagingDir, ".metadata.json"), JSON.stringify(metadata, null, 2));
-	outputFiles.push(join(outputPath, ".metadata.json"));
-	await ensureDir(join(outputPath, ".."));
-	await rm(outputPath, {
-		recursive: true,
-		force: true
-	});
-	await rename(stagingDir, outputPath);
-	return outputFiles;
-}
-async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
-	const segmentPath = join(parentWorkspacePath, "segments", String(segmentIndex));
-	await ensureDir(join(segmentPath, "frames"));
-	return segmentPath;
-}
-async function cleanupWorkspace(workspacePath) {
-	if (!workspacePath) return;
-	try {
-		await rm(workspacePath, {
-			recursive: true,
-			force: true
-		});
-	} catch {}
-}
-/**
-* Write a video buffer to a temp file in the workspace and return the path.
-* Used by 'buffer' input mode.
-*/
-async function writeInputBuffer(buffer, workspacePath) {
-	const inputDir = join(workspacePath, "input");
-	await ensureDir(inputDir);
-	const tempPath = join(inputDir, "input.mp4");
-	await writeFile(tempPath, buffer);
-	return tempPath;
-}
-/**
-* Write an array of frame Buffers as JPG files and return FrameNode[].
-* Used by 'frames' input mode.
-*/
-async function writeInputFrames(frames, workspacePath) {
-	const framesDir = join(workspacePath, "frames");
-	await ensureDir(framesDir);
-	const frameNodes = [];
-	for (let i = 0; i < frames.length; i++) {
-		const extractPath = join(framesDir, `frame_${String(i).padStart(6, "0")}${FRAME_OUTPUT_EXTENSION}`);
-		await writeFile(extractPath, frames[i]);
-		frameNodes.push({
-			id: i,
-			timestamp: i,
-			extractPath
-		});
+	const sheet = options.sheet;
+	if (sheet === void 0 || typeof sheet === "boolean") return;
+	if (sheet === null || typeof sheet !== "object" || Array.isArray(sheet)) throw new Error(`sheet must be a boolean or an object, received: ${Array.isArray(sheet) ? "array" : String(sheet)}`);
+	for (const [name, min] of [
+		["columns", 1],
+		["tileWidth", 16],
+		["maxTiles", 2]
+	]) {
+		const value = sheet[name];
+		if (value === void 0) continue;
+		if (!Number.isInteger(value) || value < min) throw new Error(`sheet.${name} must be an integer >= ${min}, received: ${value}`);
 	}
-	return frameNodes;
-}
-/**
-* Read selected FrameNode files as Buffers with JPEG compression.
-* Used to return output buffers in 'buffer' and 'frames' modes.
-*/
-async function readFramesAsBuffers(frameNodes, quality) {
-	return Promise.all(map(frameNodes, (f) => sharp(f.extractPath).jpeg({
-		quality,
-		mozjpeg: true
-	}).toBuffer()));
+	if (sheet.label !== void 0 && typeof sheet.label !== "boolean") throw new Error(`sheet.label must be a boolean, received: ${sheet.label}`);
 }
 
 //#endregion
@@ -1025,12 +1464,14 @@ function resolveOptions(options) {
 	const inputPath = mode === "file" ? resolveAbsolute(options.inputPath) : void 0;
 	const outputPath = options.outputPath ?? (inputPath ? deriveOutputPath(inputPath) : join(process.cwd(), "scene-sieve-output"));
 	const threshold = options.threshold ?? .5;
+	const pruneMode = "threshold-with-cap";
+	const sheet = typeof options.sheet === "object" ? options.sheet : {};
 	return {
 		mode,
 		inputPath,
 		count: options.count ?? 20,
 		threshold,
-		pruneMode: "threshold-with-cap",
+		pruneMode,
 		outputPath,
 		fps: options.fps ?? 5,
 		maxFrames: options.maxFrames ?? 300,
@@ -1040,7 +1481,14 @@ function resolveOptions(options) {
 		animationThreshold: options.animationThreshold ?? 5,
 		debug: options.debug ?? false,
 		maxSegmentDuration: options.maxSegmentDuration ?? 300,
-		concurrency: options.concurrency ?? 2
+		concurrency: options.concurrency ?? 2,
+		sheet: options.sheet ? {
+			columns: sheet.columns ?? 4,
+			tileWidth: sheet.tileWidth ?? 320,
+			maxTiles: sheet.maxTiles ?? 40,
+			label: sheet.label ?? true
+		} : null,
+		includeEdges: options.includeEdges ?? false
 	};
 }
 /**
@@ -1145,7 +1593,7 @@ function normalizeScores(items) {
 		if (s <= 0) return 0;
 		return lowerBound(sorted, s) / sorted.length;
 	});
-	return map(logisticZ, (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA);
+	return map(logisticZ, (z, i) => z * .6 + cdf[i] * NORMALIZATION_ALPHA);
 }
 
 //#endregion
@@ -1554,16 +2002,16 @@ function remapEdges(segmentResults, globalIdMap) {
 		const existingIdx = edgeMap.get(edgeKey);
 		if (existingIdx !== void 0) {
 			if (edges[existingIdx].score < edge.score) edges[existingIdx] = {
+				...edge,
 				sourceId: newSourceId,
-				targetId: newTargetId,
-				score: edge.score
+				targetId: newTargetId
 			};
 		} else {
 			edgeMap.set(edgeKey, edges.length);
 			edges.push({
+				...edge,
 				sourceId: newSourceId,
-				targetId: newTargetId,
-				score: edge.score
+				targetId: newTargetId
 			});
 		}
 	}
@@ -1638,7 +2086,8 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 * Each segment uses an isolated workspace directory.
 */
 async function processSegment(inputPath, segment, workspacePath, resolvedOptions, onProgress) {
-	const frames = await extractFramesForRange(inputPath, join(workspacePath, "frames"), segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration, segment.allocatedFrames);
+	const framesDir = join(workspacePath, "frames");
+	const frames = await extractFramesForRange(inputPath, framesDir, segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration, segment.allocatedFrames);
 	if (frames.length < 2) return {
 		segment,
 		frames,
@@ -1649,7 +2098,8 @@ async function processSegment(inputPath, segment, workspacePath, resolvedOptions
 			height: 0
 		}
 	};
-	const { edges, animations, analysisResolution } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
+	const ctx = buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress);
+	const { edges, animations, analysisResolution } = await analyzeFrames(ctx);
 	return {
 		segment,
 		frames,
@@ -1714,20 +2164,20 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 			status: "FINALIZING",
 			emitProgress: (percent) => options.onProgress?.("FINALIZING", percent)
 		};
-		let outputFiles = [];
-		let outputBuffers;
-		if (resolvedOptions.mode === "buffer" || resolvedOptions.mode === "frames") outputBuffers = await readFramesAsBuffers(prunedFrames, resolvedOptions.quality);
-		else outputFiles = await finalizeOutput(ctx, prunedFrames);
+		const finalized = await finalizeSelection(ctx, prunedFrames);
 		options.onProgress?.("FINALIZING", 100);
 		logger.success(`Segmented pipeline: ${prunedFrames.length} scenes from ${frames.length} frames (${segments.length} segments)`);
-		const outputMetadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		return {
 			success: true,
 			originalFramesCount: frames.length,
 			prunedFramesCount: prunedFrames.length,
-			outputFiles,
-			outputBuffers,
-			...outputMetadata,
+			outputFiles: finalized.outputFiles,
+			outputBuffers: finalized.outputBuffers,
+			video: finalized.document.video,
+			animations: finalized.animations,
+			frames: finalized.document.frames,
+			...finalized.document.sheet ? { sheet: finalized.document.sheet } : {},
+			...finalized.sheetBuffer ? { sheetBuffer: finalized.sheetBuffer } : {},
 			executionTimeMs: Date.now() - pipelineStart
 		};
 	} catch (error) {
@@ -1742,6 +2192,12 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 
 //#endregion
 //#region src/core/orchestrator/orchestrator.ts
+/**
+* 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.
+*/
 async function runPipeline(options) {
 	setDebugMode(options.debug ?? false);
 	const resolvedOptions = resolveOptions(options);
@@ -1789,25 +2245,21 @@ async function runPipeline(options) {
 		const prunedFrames = filter(ctx.frames, (f) => survivingIds.has(f.id));
 		ctx.emitProgress(100);
 		ctx.status = "FINALIZING";
-		let outputFiles = [];
-		let outputBuffers;
-		if (resolvedOptions.mode === "buffer" || resolvedOptions.mode === "frames") {
-			outputBuffers = await readFramesAsBuffers(prunedFrames, resolvedOptions.quality);
-			ctx.emitProgress(100);
-		} else {
-			outputFiles = await finalizeOutput(ctx, prunedFrames);
-			ctx.emitProgress(100);
-		}
+		const finalized = await finalizeSelection(ctx, prunedFrames);
+		ctx.emitProgress(100);
 		ctx.status = "SUCCESS";
 		logger.success(`Extracted ${prunedFrames.length} scenes from ${ctx.frames.length} frames`);
-		const metadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		return {
 			success: true,
 			originalFramesCount: ctx.frames.length,
 			prunedFramesCount: prunedFrames.length,
-			outputFiles,
-			outputBuffers,
-			...metadata,
+			outputFiles: finalized.outputFiles,
+			outputBuffers: finalized.outputBuffers,
+			video: finalized.document.video,
+			animations: finalized.animations,
+			frames: finalized.document.frames,
+			...finalized.document.sheet ? { sheet: finalized.document.sheet } : {},
+			...finalized.sheetBuffer ? { sheetBuffer: finalized.sheetBuffer } : {},
 			executionTimeMs: Date.now() - startTime
 		};
 	} catch (error) {