cursedbelt-core 1.0.0

package/dist/core/media/ffmpeg.js

@@ -0,0 +1,126 @@
+// Pure ffmpeg/ffprobe argument builders + output parsers. No Bun.spawn, no I/O — the ONE
+// source of truth for ffmpeg argv construction, shared by the Bun server adapter
+// (`server/media-bun/video.ts` spawns these against native ffmpeg) and the browser editor
+// (`react/media` executes the same argv against ffmpeg.wasm). Unit tested without ffmpeg.
+const X264_CRF = { high: 18, medium: 23, low: 28 };
+const VP9_CRF = { high: 24, medium: 31, low: 37 };
+/**
+ * Resolve the codec plan for a trim. mp4 → H.264/AAC (universal playback) with
+ * `+faststart` so the moov atom is up front (web streaming); webm → VP9/Opus.
+ */
+export function videoCodecPlan(format = 'mp4', quality = 'medium') {
+    if (format === 'webm') {
+        return {
+            videoCodec: 'libvpx-vp9',
+            audioCodec: 'libopus',
+            crf: VP9_CRF[quality],
+            preset: 'good',
+            extraOutputArgs: ['-b:v', '0', '-row-mt', '1'],
+        };
+    }
+    return {
+        videoCodec: 'libx264',
+        audioCodec: 'aac',
+        crf: X264_CRF[quality],
+        preset: 'fast',
+        // yuv420p = broad decoder compatibility; faststart = progressive web playback.
+        extraOutputArgs: ['-pix_fmt', 'yuv420p', '-movflags', '+faststart'],
+    };
+}
+/**
+ * Build the ffmpeg argv (without the `ffmpeg` binary) for a re-encoding trim.
+ * Uses accurate input seeking (`-ss` before `-i`, accurate when transcoding) plus
+ * `-t duration` so the clip is exactly `end - start` long regardless of keyframes.
+ */
+export function buildTrimArgs(spec) {
+    const plan = videoCodecPlan(spec.format, spec.quality);
+    const duration = Math.max(0, spec.endSeconds - spec.startSeconds);
+    return [
+        '-hide_banner',
+        '-nostdin',
+        '-y',
+        '-ss',
+        String(spec.startSeconds),
+        '-i',
+        spec.inputPath,
+        '-t',
+        String(duration),
+        '-c:v',
+        plan.videoCodec,
+        '-preset',
+        plan.preset,
+        '-crf',
+        String(plan.crf),
+        '-c:a',
+        plan.audioCodec,
+        ...plan.extraOutputArgs,
+        spec.outputPath,
+    ];
+}
+/** ffprobe argv for `probeMedia` — quiet JSON with streams + format. */
+export function buildProbeArgs(inputPath) {
+    return ['-v', 'quiet', '-print_format', 'json', '-show_streams', '-show_format', inputPath];
+}
+/** ffmpeg argv to grab a single frame at `atSeconds` and write it to `output`. */
+export function buildThumbnailArgs(inputPath, atSeconds, output) {
+    return [
+        '-hide_banner',
+        '-nostdin',
+        '-y',
+        '-ss',
+        String(Math.max(0, atSeconds)),
+        '-i',
+        inputPath,
+        '-frames:v',
+        '1',
+        '-q:v',
+        '3',
+        output,
+    ];
+}
+/** Parse an ffmpeg `HH:MM:SS.ss` (or bare seconds) timestamp into seconds. */
+export function ffmpegTimeToSeconds(time) {
+    const t = time.trim();
+    if (t === 'N/A' || t === '')
+        return Number.NaN;
+    const parts = t.split(':');
+    if (parts.length === 1)
+        return Number.parseFloat(parts[0]);
+    let seconds = 0;
+    for (const part of parts)
+        seconds = seconds * 60 + Number.parseFloat(part);
+    return seconds;
+}
+const TIME_RE = /time=\s*([0-9:.]+)/;
+/**
+ * Parse one line/chunk of ffmpeg stderr into a progress event. ffmpeg emits
+ * `frame=… time=00:00:03.00 …` (carriage-return-updated). Returns an `encode`
+ * event with a clamped percent when `totalSeconds` is known, else just the phase;
+ * `null` when the line carries no timestamp.
+ */
+export function parseFfmpegProgress(line, totalSeconds) {
+    const m = TIME_RE.exec(line);
+    if (!m)
+        return null;
+    const elapsed = ffmpegTimeToSeconds(m[1]);
+    if (!Number.isFinite(elapsed))
+        return null;
+    if (totalSeconds && totalSeconds > 0) {
+        const pct = Math.min(100, Math.max(0, (elapsed / totalSeconds) * 100));
+        return { phase: 'encode', progressPercent: Math.round(pct) };
+    }
+    return { phase: 'encode' };
+}
+/** Extract width/height/duration/format from parsed ffprobe JSON. */
+export function parseFfprobe(json) {
+    const streams = json.streams ?? [];
+    const video = streams.find((s) => s.codec_type === 'video');
+    const durationStr = json.format?.duration ?? video?.duration ?? '';
+    const durationSeconds = durationStr ? Number.parseFloat(durationStr) : Number.NaN;
+    return {
+        width: video?.width ?? 0,
+        height: video?.height ?? 0,
+        durationSeconds: Number.isFinite(durationSeconds) ? durationSeconds : 0,
+        format: json.format?.format_name ?? '',
+    };
+}

package/dist/core/media/format.d.ts

@@ -0,0 +1,20 @@
+import type { ImageOutputFormat } from './types';
+export declare const IMAGE_OUTPUT_FORMATS: readonly ImageOutputFormat[];
+export declare function imageFormatToMime(format: ImageOutputFormat): string;
+export declare function imageFormatToExtension(format: ImageOutputFormat): string;
+/** Best-effort MIME → output format (e.g. `image/jpeg` → `jpeg`). */
+export declare function mimeToImageFormat(mime: string | undefined): ImageOutputFormat | undefined;
+/**
+ * Clamp an image quality to a sane 1–100 integer. A missing/NaN/out-of-range value
+ * falls back to `fallback` (default 80), so a malformed spec never yields a 0-quality
+ * (blank) or >100 (sharp-throwing) encode.
+ */
+export declare function clampQuality(quality: number | undefined, fallback?: number): number;
+/**
+ * The thumbnail encode format: webp by default (small + wide support); png when
+ * transparency must survive (the source already has alpha). Keeps thumbnail policy
+ * in one tested place rather than scattered across server handlers.
+ */
+export declare function pickThumbnailFormat(opts?: {
+    hasAlpha?: boolean;
+}): ImageOutputFormat;

package/dist/core/media/format.js

@@ -0,0 +1,54 @@
+// Pure format helpers — MIME/extension lookup, quality clamping, thumbnail-format
+// selection. No npm deps; shared by the server adapter, the React layer, and tests.
+export const IMAGE_OUTPUT_FORMATS = ['jpeg', 'png', 'webp', 'avif'];
+const IMAGE_MIME = {
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    webp: 'image/webp',
+    avif: 'image/avif',
+};
+const IMAGE_EXT = {
+    jpeg: 'jpg',
+    png: 'png',
+    webp: 'webp',
+    avif: 'avif',
+};
+export function imageFormatToMime(format) {
+    return IMAGE_MIME[format];
+}
+export function imageFormatToExtension(format) {
+    return IMAGE_EXT[format];
+}
+/** Best-effort MIME → output format (e.g. `image/jpeg` → `jpeg`). */
+export function mimeToImageFormat(mime) {
+    if (!mime)
+        return undefined;
+    const m = mime.toLowerCase();
+    if (m.includes('jpeg') || m.includes('jpg'))
+        return 'jpeg';
+    if (m.includes('png'))
+        return 'png';
+    if (m.includes('webp'))
+        return 'webp';
+    if (m.includes('avif'))
+        return 'avif';
+    return undefined;
+}
+/**
+ * Clamp an image quality to a sane 1–100 integer. A missing/NaN/out-of-range value
+ * falls back to `fallback` (default 80), so a malformed spec never yields a 0-quality
+ * (blank) or >100 (sharp-throwing) encode.
+ */
+export function clampQuality(quality, fallback = 80) {
+    if (quality == null || !Number.isFinite(quality))
+        return fallback;
+    return Math.min(100, Math.max(1, Math.round(quality)));
+}
+/**
+ * The thumbnail encode format: webp by default (small + wide support); png when
+ * transparency must survive (the source already has alpha). Keeps thumbnail policy
+ * in one tested place rather than scattered across server handlers.
+ */
+export function pickThumbnailFormat(opts) {
+    return opts?.hasAlpha ? 'png' : 'webp';
+}

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

@@ -0,0 +1,12 @@
+export { type FloodFillBGOptions, floodFillBGS } from './bgRemoval';
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, ffmpegTimeToSeconds, type ProbeResult, parseFfmpegProgress, parseFfprobe, type VideoCodecPlan, videoCodecPlan, } from './ffmpeg';
+export { clampQuality, IMAGE_OUTPUT_FORMATS, imageFormatToExtension, imageFormatToMime, mimeToImageFormat, pickThumbnailFormat, } from './format';
+export { isAudioItem, isImageItem, isVideoItem, mediaItemAspect, mediaItemDimensions, } from './mediaItem';
+export { buildAtempoChain, buildTimelineRenderPlan, DEFAULT_NORMALIZE, type FfmpegCommand, type NormalizeSpec, type RenderPlanFile, speedFilters, type TimelineRenderOptions, type TimelineRenderPlan, } from './renderPlan';
+export { closeMask, createRegionSegmenter, DEFAULT_CLOSE_RADIUS, DEFAULT_TOLERANCE, dilateMask, downscaleRgba, erodeMask, fitWorkingSize, type ImageSegmenter, type SegmentOptions, type SegmentPrompt, type SegmentSource, sensitivityToTolerance, upscaleMask, } from './segment';
+export { formatBytes } from './size';
+export { type ClampTrimOptions, clampTrimRange, formatTimecode, type TrimRange, trimDurationSeconds, } from './trim';
+export type { GalleryMedia, GalleryPhoto, ImageOperation, ImageOutputFormat, ImagePipelineSpec, MediaItem, MediaKind, MediaKindFilter, PlayableVideo, ProcessingStatus, VideoFormat, VideoProgressEvent, VideoQuality, VideoTrimSpec, } from './types';
+export { DEFAULT_UPLOAD_CHUNK_SIZE, MAX_SINGLE_UPLOAD_BYTES } from './uploadLimits';
+export { assertValidImagePipelineSpec, assertValidVideoTrimSpec, type ValidationResult, validateImagePipelineSpec, validateVideoTrimSpec, } from './validate';
+export { cutListProblem, cutSeconds, cutTimecode, keptSeconds, keptSegments, MIN_CUT_SECONDS, normalizeCuts, type VideoCut, } from './videoCuts';

package/dist/core/media/index.js

@@ -0,0 +1,18 @@
+// cursedbelt-core/media — pure, dependency-free media contract + utilities shared by
+// the Bun server adapter (`src/server/media-bun`), the React components
+// (`cursedbelt/react/media`), and any consuming app/test. No React, no Bun, no npm
+// dep — the same module loads identically everywhere.
+export { floodFillBGS } from './bgRemoval';
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, ffmpegTimeToSeconds, parseFfmpegProgress, parseFfprobe, videoCodecPlan, } from './ffmpeg';
+export { clampQuality, IMAGE_OUTPUT_FORMATS, imageFormatToExtension, imageFormatToMime, mimeToImageFormat, pickThumbnailFormat, } from './format';
+export { isAudioItem, isImageItem, isVideoItem, mediaItemAspect, mediaItemDimensions, } from './mediaItem';
+export { buildAtempoChain, buildTimelineRenderPlan, DEFAULT_NORMALIZE, speedFilters, } from './renderPlan';
+export { closeMask, createRegionSegmenter, DEFAULT_CLOSE_RADIUS, DEFAULT_TOLERANCE, dilateMask, downscaleRgba, erodeMask, fitWorkingSize, sensitivityToTolerance, upscaleMask, } from './segment';
+export { formatBytes } from './size';
+export { clampTrimRange, formatTimecode, trimDurationSeconds, } from './trim';
+export { DEFAULT_UPLOAD_CHUNK_SIZE, MAX_SINGLE_UPLOAD_BYTES } from './uploadLimits';
+export { assertValidImagePipelineSpec, assertValidVideoTrimSpec, validateImagePipelineSpec, validateVideoTrimSpec, } from './validate';
+// Marking sections of a video to CUT OUT. Framework-free on purpose: the dialog
+// (`react/media/VideoCutEditor`), the app route that refuses an unexecutable list and the
+// binary-server job that runs it all read the same rules from here.
+export { cutListProblem, cutSeconds, cutTimecode, keptSeconds, keptSegments, MIN_CUT_SECONDS, normalizeCuts, } from './videoCuts';

package/dist/core/media/mediaItem.d.ts

@@ -0,0 +1,15 @@
+import type { MediaItem } from './types';
+export declare const isImageItem: (item: MediaItem) => boolean;
+export declare const isVideoItem: (item: MediaItem) => boolean;
+export declare const isAudioItem: (item: MediaItem) => boolean;
+/**
+ * Resolve renderable dimensions for an item. Real `width`/`height` win; otherwise a
+ * per-kind default (4:3 image, 16:9 video, 1:1 audio) keeps the justified/masonry
+ * layout from collapsing a dimensionless item to zero height.
+ */
+export declare function mediaItemDimensions(item: MediaItem): {
+    width: number;
+    height: number;
+};
+/** width / height (clamped to a sane range), falling back to `fallback` (default 1). */
+export declare function mediaItemAspect(item: MediaItem, fallback?: number): number;

package/dist/core/media/mediaItem.js

@@ -0,0 +1,34 @@
+// Pure MediaItem helpers — kind predicates + dimension/aspect resolution. The React
+// catalogue maps items to layout photos through these, so the "what size is this
+// thumbnail" logic is tested here, not buried in a component.
+export const isImageItem = (item) => item.type === 'image';
+export const isVideoItem = (item) => item.type === 'video';
+export const isAudioItem = (item) => item.type === 'audio';
+/** Default cell shape when an item carries no intrinsic dimensions. */
+const FALLBACK_DIMS = {
+    image: { width: 4, height: 3 },
+    video: { width: 16, height: 9 },
+    audio: { width: 1, height: 1 },
+};
+/**
+ * Resolve renderable dimensions for an item. Real `width`/`height` win; otherwise a
+ * per-kind default (4:3 image, 16:9 video, 1:1 audio) keeps the justified/masonry
+ * layout from collapsing a dimensionless item to zero height.
+ */
+export function mediaItemDimensions(item) {
+    if (isPositive(item.width) && isPositive(item.height)) {
+        return { width: item.width, height: item.height };
+    }
+    return FALLBACK_DIMS[item.type];
+}
+/** width / height (clamped to a sane range), falling back to `fallback` (default 1). */
+export function mediaItemAspect(item, fallback = 1) {
+    const { width, height } = mediaItemDimensions(item);
+    if (!isPositive(width) || !isPositive(height))
+        return fallback;
+    const ratio = width / height;
+    return Number.isFinite(ratio) && ratio > 0 ? ratio : fallback;
+}
+function isPositive(n) {
+    return typeof n === 'number' && Number.isFinite(n) && n > 0;
+}

package/dist/core/media/renderPlan.d.ts

@@ -0,0 +1,63 @@
+import { type TimelineTrack } from 'cwip/timeline';
+import type { VideoFormat, VideoQuality } from './types';
+/** An auxiliary text file the executor writes before running the commands. */
+export interface RenderPlanFile {
+    name: string;
+    text: string;
+}
+/** One ffmpeg invocation (argv without the binary). */
+export interface FfmpegCommand {
+    args: string[];
+    /** The file this command produces. */
+    outputName: string;
+    /** Output seconds this command encodes — weight for progress reporting
+     * (0 for stream-copy steps, which are ~instant). */
+    encodeSeconds: number;
+    label: string;
+}
+export interface TimelineRenderPlan {
+    files: RenderPlanFile[];
+    commands: FfmpegCommand[];
+    outputName: string;
+    /** Intermediates to delete after the export (NOT the inputs or the output). */
+    intermediateNames: string[];
+    totalEncodeSeconds: number;
+    /** Asset ids the executor must materialize under their mapped file names. */
+    requiredAssetIds: string[];
+}
+export interface NormalizeSpec {
+    width: number;
+    height: number;
+    fps: number;
+    audioRate: number;
+}
+/** 720p30 keeps in-browser (wasm) export times tolerable; hosts can raise it. */
+export declare const DEFAULT_NORMALIZE: NormalizeSpec;
+export interface TimelineRenderOptions {
+    /** assetId → file name in the executor's filesystem. */
+    assetFileNames: Record<string, string>;
+    /** assetId → whether the file HAS an audio stream (default true). Sources
+     * without one get a silent bed so every chunk concats consistently. */
+    assetHasAudio?: Record<string, boolean>;
+    outputName?: string;
+    format?: VideoFormat;
+    quality?: VideoQuality;
+    normalize?: NormalizeSpec;
+    /** Prefix for every intermediate file (default "csrp_"). */
+    intermediatePrefix?: string;
+}
+/**
+ * ffmpeg's `atempo` only accepts 0.5–2.0 — chain filters for anything beyond
+ * (4× → `atempo=2.0,atempo=2.0`).
+ */
+export declare const buildAtempoChain: (speed: number) => string;
+/** Video/audio speed filter fragments for a clip (null at speed 1). */
+export declare const speedFilters: (speed: number) => {
+    video: string;
+    audio: string;
+} | null;
+/**
+ * Compile the timeline into an ordered command list. Throws when the first
+ * video track has no clips (nothing to render) or an asset is unmapped.
+ */
+export declare const buildTimelineRenderPlan: (tracks: TimelineTrack[], options: TimelineRenderOptions) => TimelineRenderPlan;

package/dist/core/media/renderPlan.js

@@ -0,0 +1,232 @@
+// Timeline → ffmpeg render plan. Pure compiler from a cwip/timeline document to
+// an ordered list of ffmpeg argv commands + auxiliary files — executor-agnostic:
+// the browser runs the SAME plan on ffmpeg.wasm (`react/media/ffmpeg-wasm`) and a
+// server can spawn native ffmpeg against it. Nothing here touches an FS.
+//
+// Pipeline shape (the two-pass normalize+concat that survives mixed sources):
+//   1. per video clip  — extract the source window, apply speed (setpts/atempo),
+//      volume, and NORMALIZE to one spec (scale+pad+fps, resampled audio, a
+//      silent bed when the source has no audio) → chunk_i
+//   2. concat          — all chunks share codec/fps/resolution, so `-c copy`
+//   3. audio mix       — audio-track clips are extracted the same way and
+//      `adelay`ed to their timeline offsets, then `amix`ed under the video lane
+//
+// v1 model notes: ONE video lane (the first video track) — clips are laid
+// end-to-end in timeline order, so close gaps before exporting if you want cuts
+// where the gaps were. Audio clip offsets are their absolute `timelineStart`.
+import { clipDuration, roundSeconds } from 'cwip/timeline';
+import { videoCodecPlan } from './ffmpeg';
+/** 720p30 keeps in-browser (wasm) export times tolerable; hosts can raise it. */
+export const DEFAULT_NORMALIZE = {
+    width: 1280,
+    height: 720,
+    fps: 30,
+    audioRate: 44100,
+};
+/**
+ * ffmpeg's `atempo` only accepts 0.5–2.0 — chain filters for anything beyond
+ * (4× → `atempo=2.0,atempo=2.0`).
+ */
+export const buildAtempoChain = (speed) => {
+    const filters = [];
+    let remaining = speed;
+    while (remaining > 2) {
+        filters.push('atempo=2.0');
+        remaining /= 2;
+    }
+    while (remaining < 0.5) {
+        filters.push('atempo=0.5');
+        remaining /= 0.5;
+    }
+    filters.push(`atempo=${remaining.toFixed(4)}`);
+    return filters.join(',');
+};
+/** Video/audio speed filter fragments for a clip (null at speed 1). */
+export const speedFilters = (speed) => speed === 1
+    ? null
+    : { video: `setpts=${(1 / speed).toFixed(6)}*PTS`, audio: buildAtempoChain(speed) };
+const scalePad = (n) => `scale=${n.width}:${n.height}:force_original_aspect_ratio=decrease,` +
+    `pad=${n.width}:${n.height}:(ow-iw)/2:(oh-ih)/2,fps=${n.fps}`;
+/** The `-vf` chain for one clip: reset timestamps, speed, then normalize.
+ * `setpts=PTS-STARTPTS` rebases the extracted window to t=0 — without it a
+ * source whose first frame carries a non-zero PTS (common for screen/live
+ * recordings) makes the `fps` filter emit a BLACK frame to fill the gap before
+ * the real first frame, so the export opens on black instead of the picture. */
+const videoFilter = (clip, normalize) => {
+    const speed = speedFilters(clip.speed);
+    return ['setpts=PTS-STARTPTS', speed?.video, scalePad(normalize)].filter(Boolean).join(',');
+};
+/** The audio chain for one clip: reset timestamps, speed, volume, resample.
+ * `asetpts=PTS-STARTPTS` mirrors the video rebase so audio stays aligned. */
+const audioFilter = (clip, normalize) => {
+    const speed = speedFilters(clip.speed);
+    const volume = clip.volume !== 1 ? `volume=${clip.volume.toFixed(3)}` : null;
+    return ['asetpts=PTS-STARTPTS', speed?.audio, volume, `aresample=${normalize.audioRate}`]
+        .filter(Boolean)
+        .join(',');
+};
+const BASE_ARGS = ['-hide_banner', '-nostdin', '-y'];
+const sourceFileOf = (ctx, clip) => {
+    const file = ctx.options.assetFileNames[clip.sourceAssetId];
+    if (!file) {
+        throw new Error(`[renderPlan] no file name mapped for asset "${clip.sourceAssetId}" (clip "${clip.name}") — add it to assetFileNames`);
+    }
+    return file;
+};
+const hasAudio = (ctx, clip) => ctx.options.assetHasAudio?.[clip.sourceAssetId] ?? true;
+/** Extract + normalize one VIDEO clip into a self-contained chunk. */
+const videoChunkCommand = (ctx, clip, index) => {
+    const plan = videoCodecPlan(ctx.options.format, ctx.options.quality);
+    const outputName = `${ctx.prefix}v${index}.${ctx.options.format === 'webm' ? 'webm' : 'mp4'}`;
+    const silent = !hasAudio(ctx, clip);
+    const args = [
+        ...BASE_ARGS,
+        '-ss',
+        String(clip.trackIn),
+        '-to',
+        String(clip.trackOut),
+        '-i',
+        sourceFileOf(ctx, clip),
+        // A silent stereo bed when the source has no audio track, so EVERY chunk
+        // carries an audio stream and the concat/copy step stays consistent.
+        ...(silent
+            ? [
+                '-f',
+                'lavfi',
+                '-t',
+                String(clipDuration(clip)),
+                '-i',
+                `anullsrc=channel_layout=stereo:sample_rate=${ctx.normalize.audioRate}`,
+            ]
+            : []),
+        '-vf',
+        videoFilter(clip, ctx.normalize),
+        ...(silent ? ['-map', '0:v:0', '-map', '1:a:0'] : ['-af', audioFilter(clip, ctx.normalize)]),
+        '-c:v',
+        plan.videoCodec,
+        '-preset',
+        plan.preset,
+        '-crf',
+        String(plan.crf),
+        '-c:a',
+        plan.audioCodec,
+        ...plan.extraOutputArgs,
+        outputName,
+    ];
+    return {
+        args,
+        outputName,
+        encodeSeconds: clipDuration(clip),
+        label: `video clip ${index + 1} (${clip.name})`,
+    };
+};
+/** Extract one AUDIO-track clip as a lone audio chunk (m4a). */
+const audioChunkCommand = (ctx, clip, index) => {
+    const outputName = `${ctx.prefix}a${index}.m4a`;
+    const args = [
+        ...BASE_ARGS,
+        '-ss',
+        String(clip.trackIn),
+        '-to',
+        String(clip.trackOut),
+        '-i',
+        sourceFileOf(ctx, clip),
+        '-vn',
+        '-af',
+        audioFilter(clip, ctx.normalize),
+        '-c:a',
+        'aac',
+        outputName,
+    ];
+    return {
+        args,
+        outputName,
+        encodeSeconds: clipDuration(clip),
+        label: `audio clip ${index + 1} (${clip.name})`,
+    };
+};
+/**
+ * Compile the timeline into an ordered command list. Throws when the first
+ * video track has no clips (nothing to render) or an asset is unmapped.
+ */
+export const buildTimelineRenderPlan = (tracks, options) => {
+    const normalize = options.normalize ?? DEFAULT_NORMALIZE;
+    const prefix = options.intermediatePrefix ?? 'csrp_';
+    const outputName = options.outputName ?? 'output.mp4';
+    const ctx = { options: options, normalize, prefix };
+    const videoTrack = tracks.find((t) => t.type === 'video');
+    const videoClips = [...(videoTrack?.clips ?? [])].sort((a, b) => a.timelineStart - b.timelineStart);
+    if (videoClips.length === 0) {
+        throw new Error('[renderPlan] the timeline has no video clips — nothing to render');
+    }
+    const audioClips = tracks
+        .filter((t) => t.type === 'audio')
+        .flatMap((t) => t.clips)
+        .sort((a, b) => a.timelineStart - b.timelineStart);
+    const commands = [];
+    const files = [];
+    const intermediateNames = [];
+    // 1. video chunks
+    const videoChunks = videoClips.map((clip, i) => videoChunkCommand(ctx, clip, i));
+    commands.push(...videoChunks);
+    intermediateNames.push(...videoChunks.map((c) => c.outputName));
+    // 2. concat (stream copy — chunks are normalized to one spec)
+    const listName = `${prefix}concat.txt`;
+    files.push({ name: listName, text: videoChunks.map((c) => `file '${c.outputName}'`).join('\n') });
+    intermediateNames.push(listName);
+    const needsMix = audioClips.length > 0;
+    const videoLaneName = needsMix ? `${prefix}lane.mp4` : outputName;
+    commands.push({
+        args: [...BASE_ARGS, '-f', 'concat', '-safe', '0', '-i', listName, '-c', 'copy', videoLaneName],
+        outputName: videoLaneName,
+        encodeSeconds: 0,
+        label: 'concat video lane',
+    });
+    // 3. audio mix under the lane
+    if (needsMix) {
+        intermediateNames.push(videoLaneName);
+        const audioChunks = audioClips.map((clip, i) => audioChunkCommand(ctx, clip, i));
+        commands.push(...audioChunks);
+        intermediateNames.push(...audioChunks.map((c) => c.outputName));
+        const inputs = [videoLaneName, ...audioChunks.map((c) => c.outputName)];
+        const delays = audioClips.map((clip, i) => {
+            const ms = Math.max(0, Math.round(clip.timelineStart * 1000));
+            return `[${i + 1}:a]adelay=${ms}|${ms}[d${i}]`;
+        });
+        const mixInputs = ['[0:a]', ...audioClips.map((_, i) => `[d${i}]`)].join('');
+        const filterComplex = [
+            ...delays,
+            `${mixInputs}amix=inputs=${audioClips.length + 1}:duration=first:normalize=0[aout]`,
+        ].join(';');
+        commands.push({
+            args: [
+                ...BASE_ARGS,
+                ...inputs.flatMap((name) => ['-i', name]),
+                '-filter_complex',
+                filterComplex,
+                '-map',
+                '0:v',
+                '-map',
+                '[aout]',
+                '-c:v',
+                'copy',
+                '-c:a',
+                'aac',
+                outputName,
+            ],
+            outputName,
+            // re-encodes the full audio lane under a copied video stream — cheap but
+            // not instant; weight it by the lane length.
+            encodeSeconds: roundSeconds(videoClips.reduce((sum, c) => sum + clipDuration(c), 0)),
+            label: 'mix audio tracks',
+        });
+    }
+    return {
+        files,
+        commands,
+        outputName,
+        intermediateNames,
+        totalEncodeSeconds: roundSeconds(commands.reduce((sum, c) => sum + c.encodeSeconds, 0)),
+        requiredAssetIds: [...new Set([...videoClips, ...audioClips].map((c) => c.sourceAssetId))],
+    };
+};

package/dist/core/media/segment.d.ts

@@ -0,0 +1,79 @@
+/** A source image as raw RGBA pixels at its working dimensions. */
+export interface SegmentSource {
+    /** RGBA pixels, length `width * height * 4`. */
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * What to select. `point` = magic-wand from a clicked pixel; `box` = the dominant object
+ * inside a dragged rectangle. Coordinates are in the SOURCE pixel space passed in `source`
+ * (the painter downscales both the image and the prompt together for large images).
+ */
+export type SegmentPrompt = {
+    readonly type: 'point';
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly type: 'box';
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+};
+export interface SegmentOptions {
+    /**
+     * Color-distance tolerance (RGB euclidean, 0–441) for region growth: a neighbor joins
+     * the region when it is within this distance of the seed color. Higher = looser (selects
+     * more, leaks across gradients sooner). Default {@link DEFAULT_TOLERANCE}. The painter maps
+     * a 0–100 "sensitivity" slider onto this via {@link sensitivityToTolerance}.
+     */
+    readonly tolerance?: number;
+    /**
+     * Morphological close radius (px) applied after growth to fill speckle + small holes and
+     * smooth the edge. 0 disables it. Default {@link DEFAULT_CLOSE_RADIUS}.
+     */
+    readonly closeRadius?: number;
+}
+/**
+ * A promptable image segmenter: `(source, prompt) → binary alpha plane (0/255)` at the
+ * source's dimensions, white where selected. `segment` may be sync (the pure region grower)
+ * or async (a model-backed engine); the painter always awaits it. `dispose` releases any
+ * held resources (e.g. an ONNX session) and is optional.
+ */
+export interface ImageSegmenter {
+    /** Stable identifier for diagnostics / telemetry (e.g. `'region-grow'`, `'mobile-sam'`). */
+    readonly id: string;
+    segment(source: SegmentSource, prompt: SegmentPrompt, options?: SegmentOptions): Uint8ClampedArray | Promise<Uint8ClampedArray>;
+    dispose?(): void;
+}
+export declare const DEFAULT_TOLERANCE = 28;
+export declare const DEFAULT_CLOSE_RADIUS = 2;
+/** Map a 0–100 "sensitivity" slider to a growth tolerance. 0 → tight (exact color), 100 →
+ *  loose. A gentle quadratic keeps the low end fine-grained where most clicks land. */
+export declare function sensitivityToTolerance(sensitivity: number): number;
+/** 4-connected binary dilate (grow by 1px). */
+export declare function dilateMask(mask: Uint8ClampedArray, width: number, height: number): Uint8ClampedArray;
+/** 4-connected binary erode (shrink by 1px). */
+export declare function erodeMask(mask: Uint8ClampedArray, width: number, height: number): Uint8ClampedArray;
+/** Morphological close (dilate×r then erode×r): fills holes/gaps ≤ ~2·radius and smooths
+ *  the edge without changing the overall area. */
+export declare function closeMask(mask: Uint8ClampedArray, width: number, height: number, radius: number): Uint8ClampedArray;
+/** Working size that fits within `maxPixels` while preserving aspect (never upsizes). */
+export declare function fitWorkingSize(width: number, height: number, maxPixels: number): {
+    width: number;
+    height: number;
+    scale: number;
+};
+/** Area-average downscale of an RGBA buffer (stable colors → cleaner growth than nearest). */
+export declare function downscaleRgba(data: Uint8ClampedArray, sw: number, sh: number, dw: number, dh: number): Uint8ClampedArray;
+/** Nearest-neighbor upscale of a 0/255 mask back to the source's natural dimensions. */
+export declare function upscaleMask(mask: Uint8ClampedArray, sw: number, sh: number, dw: number, dh: number): Uint8ClampedArray;
+/**
+ * The default, pure region-growing segmenter — no model, no download, instant + offline.
+ * `point` grows a magic-wand selection from the clicked pixel; `box` selects the dominant
+ * object inside the rectangle by growing from a spread of interior seeds, clipped to the
+ * box so it can't leak into the surrounding scene. Always returns a binary alpha plane at
+ * the source dimensions; the painter lands it as an editable region for accept/refine.
+ */
+export declare function createRegionSegmenter(defaults?: SegmentOptions): ImageSegmenter;