@jini-ai/cms 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.5.2 — 2026-10-06
+
+- Video previews (`@jini-ai/cms/media`): `planVideoFrames` / `planVideoContactSheets` / `getVideoFrameEdge` / `parseVideoProbe` plus the `VideoFrameExtractor` port and an ffmpeg adapter (`createFfmpegVideoFrameExtractor`, `findVideoBinaries`, `runLowPriorityVideoProcess`). Default 16 frames, up to 64 (frames past 16 shrink to bound image tokens), `every`/`start` spacing, explicit `at` times, or up to 4 contact sheets of ≤16 tiles with a timestamp map.
+- Bounded by design: ≤64 MiB input, ≤512 KiB per frame, ≤2 MiB per sheet, ≤8 MiB total; ffmpeg runs `nice -n 19`, `-threads 1`, ≤8 source decoders per process in serial batches, one extraction at a time, 60 s shared deadline. Uses `-fps_mode passthrough` (ffmpeg ≥ 5.1; `-vsync` is gone in ffmpeg 9).
+
 # Changelog
 
 ## 0.5.1 — 2026-10-06

package/dist/media/index.d.ts

@@ -48,4 +48,6 @@ export type { RegisterTransformRequired, GetLatestTransformDefinitionRequired, I
 export type { IsBlobUnreferencedRequired, TombstoneBlobRequired, RunBlobGcDeletePassRequired, RunBlobGcUnlinkPassRequired, RunBlobGcCycleRequired } from "./blob-gc.js";
 export { rollbackUploadedMedia } from "./media-service.js";
 export type { MediaRowCleanupDeps } from "./media-service.js";
+export { VIDEO_DEFAULT_FRAMES, VIDEO_MAX_FRAMES, VIDEO_MAX_EDGE_PX, VIDEO_MAX_INPUT_BYTES, VIDEO_MAX_FRAME_BYTES, VIDEO_MAX_OUTPUT_BYTES, VIDEO_MAX_SHEET_BYTES, VIDEO_MAX_SHEETS, VIDEO_EXTRACTION_TIMEOUT_MS, planVideoFrames, parseVideoProbe, getVideoFrameEdge, planVideoContactSheets, type VideoMetadata, type VideoFrame, type VideoFrameOptions, type VideoFrameResult, type VideoFrameExtractor, type VideoSheetTile, type VideoSheetLayout, type VideoContactSheet, } from './video-frames.js';
+export { createFfmpegVideoFrameExtractor, findVideoBinaries, runLowPriorityVideoProcess, type VideoBinaries, type VideoBinaryFinder, type VideoProcessRunner, } from './video-frames.ffmpeg.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/media/index.js

@@ -31,4 +31,7 @@ export { mediaAgentToolCatalog, } from "./agent-tools.js";
  */
 export { buildMediaRegistrations, mediaDerivedRisk, } from "./tool-registrations.js";
 export { rollbackUploadedMedia } from "./media-service.js";
+// Video previews: policy/port plus a bounded optional-host codec adapter.
+export { VIDEO_DEFAULT_FRAMES, VIDEO_MAX_FRAMES, VIDEO_MAX_EDGE_PX, VIDEO_MAX_INPUT_BYTES, VIDEO_MAX_FRAME_BYTES, VIDEO_MAX_OUTPUT_BYTES, VIDEO_MAX_SHEET_BYTES, VIDEO_MAX_SHEETS, VIDEO_EXTRACTION_TIMEOUT_MS, planVideoFrames, parseVideoProbe, getVideoFrameEdge, planVideoContactSheets, } from './video-frames.js';
+export { createFfmpegVideoFrameExtractor, findVideoBinaries, runLowPriorityVideoProcess, } from './video-frames.ffmpeg.js';
 //# sourceMappingURL=index.js.map

package/dist/media/video-frames.d.ts

@@ -0,0 +1,94 @@
+/** Video preview contract and sampling policy, independent of a host, codec or AI provider. */
+export declare const VIDEO_MAX_FRAMES = 64;
+export declare const VIDEO_DEFAULT_FRAMES = 16;
+export declare const VIDEO_MAX_EDGE_PX = 768;
+export declare const VIDEO_MAX_INPUT_BYTES: number;
+export declare const VIDEO_MAX_FRAME_BYTES: number;
+/** Aggregate raw JPEG payload budget; base64 expands this to about 10.67 MiB plus metadata. */
+export declare const VIDEO_MAX_OUTPUT_BYTES: number;
+export declare const VIDEO_MAX_SHEET_BYTES: number;
+export declare const VIDEO_MAX_SHEETS = 4;
+export declare const VIDEO_EXTRACTION_TIMEOUT_MS = 60000;
+export interface VideoMetadata {
+    readonly duration: number;
+    readonly width: number;
+    readonly height: number;
+    readonly codec: string;
+    readonly container: string;
+    readonly sizeBytes: number;
+    readonly hasAudio: boolean;
+}
+export interface VideoFrame {
+    readonly at: number;
+    readonly mimeType: 'image/jpeg';
+    readonly bytes: Uint8Array;
+}
+export interface VideoSheetTile {
+    readonly index: number;
+    readonly row: number;
+    readonly column: number;
+    readonly at: number;
+}
+export interface VideoSheetLayout {
+    readonly columns: number;
+    readonly rows: number;
+    readonly tileEdgePx: number;
+    /** One-based row-major positions; timestamp order and repetitions are preserved. */
+    readonly tiles: readonly VideoSheetTile[];
+}
+export interface VideoContactSheet extends VideoSheetLayout {
+    readonly mimeType: 'image/jpeg';
+    readonly bytes: Uint8Array;
+}
+export interface VideoFrameOptions {
+    readonly layout?: 'frames' | 'sheet';
+    readonly frames?: number;
+    readonly at?: readonly number[];
+    readonly every?: number;
+    readonly start?: number;
+    readonly signal?: AbortSignal;
+}
+export type VideoFrameResult = {
+    readonly ok: true;
+    readonly metadata: VideoMetadata;
+    readonly frames: readonly VideoFrame[];
+    readonly sheets?: readonly VideoContactSheet[];
+} | {
+    readonly ok: false;
+    readonly reason: 'unavailable' | 'busy' | 'too-large' | 'timeout' | 'canceled' | 'invalid';
+    readonly message: string;
+};
+/** Implementations return <=64 sampled frames: separate JPEGs <=512KiB or <=4 sheets <=2MiB.
+ * The count-dependent pixel policy and <=8MiB aggregate budget apply in both modes.
+ * Sheet mode returns frames: [] plus sheets; separate mode omits sheets. Overflow fails in full.
+ * Inputs are authorized bytes, never caller paths. No provider or CMS-owner concepts live here. */
+export interface VideoFrameExtractor {
+    extract(required: {
+        bytes: Uint8Array;
+    }, optional: VideoFrameOptions): Promise<VideoFrameResult>;
+}
+/** Keep sixteen square 768px images worth of pixels (about 12.6k tokens at pixels/750).
+ * Even pixel sizes are codec-friendly; flooring never increases the budget. */
+export declare function getVideoFrameEdge({ frameCount }: {
+    frameCount: number;
+}, _optional?: Record<string, never>): number;
+/** Grid pixels, including black unused cells, share the separate-frame pixel budget.
+ * Metadata provides labels without requiring a host font or ffmpeg drawtext support. */
+export declare function planVideoContactSheets({ times }: {
+    times: readonly number[];
+}, _optional?: Record<string, never>): VideoSheetLayout[];
+/** Avoid seeking to exact EOF, which commonly has no decodable frame. Preserve explicit order,
+ * including repeated timestamps, so image positions continue to match the requested positions.
+ * With every and no count, stop when the next timestamp cannot fit (always emit the first clamped
+ * position). An explicit count preserves the requested count, clamping positions beyond the clip.
+ * start only affects every; at overrides count/start, but at + every is invalid. */
+export declare function planVideoFrames({ duration }: {
+    duration: number;
+}, { frames, at, every, start }?: Pick<VideoFrameOptions, 'frames' | 'at' | 'every' | 'start'>): number[];
+/** Parse only the ffprobe fields requested by the adapter. File size is measured from authorized
+ * input bytes, never from a possibly stale container header. Cover art is not a video stream. */
+export declare function parseVideoProbe({ output, sizeBytes }: {
+    output: string;
+    sizeBytes: number;
+}, _optional?: Record<string, never>): VideoMetadata;
+//# sourceMappingURL=video-frames.d.ts.map

package/dist/media/video-frames.ffmpeg.d.ts

@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import { type VideoFrameExtractor } from './video-frames.js';
+export interface VideoBinaries {
+    readonly nice: string;
+    readonly ffmpeg: string;
+    readonly ffprobe: string;
+}
+export type VideoBinaryFinder = (required: Record<string, never>, optional: Record<string, never>) => Promise<VideoBinaries | undefined>;
+export type VideoProcessRunner = (required: {
+    command: string;
+    args: readonly string[];
+}, optional: {
+    timeoutMs: number;
+    maxOutputBytes: number;
+    signal?: AbortSignal;
+}) => Promise<Uint8Array>;
+/** Discovery never executes a version/probe command. Configured paths are host configuration,
+ * never tool arguments, and all subprocesses (including ffprobe) still go through nice. */
+export declare const findVideoBinaries: VideoBinaryFinder;
+/** detached creates a group including nice and its eventual executable; killing the group prevents
+ * a wrapper from leaving a decoder alive. Waiting for close keeps the extraction lock until exit. */
+export declare const runLowPriorityVideoProcess: ({ command, args, spawnProcess, killGroup }: {
+    command: string;
+    args: readonly string[];
+    spawnProcess?: typeof spawn;
+    killGroup?: (required: {
+        pid: number;
+    }, optional: Record<string, never>) => void;
+}, { timeoutMs, maxOutputBytes, signal }: {
+    timeoutMs: number;
+    maxOutputBytes: number;
+    signal?: AbortSignal;
+}) => Promise<Uint8Array>;
+export declare function createFfmpegVideoFrameExtractor({ findBinaries, runProcess, nowMs }: {
+    findBinaries?: VideoBinaryFinder;
+    runProcess?: VideoProcessRunner;
+    nowMs?: (required: Record<string, never>, optional: Record<string, never>) => number;
+}, _optional?: Record<string, never>): VideoFrameExtractor;
+//# sourceMappingURL=video-frames.ffmpeg.d.ts.map

package/dist/media/video-frames.ffmpeg.js

@@ -0,0 +1,261 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { performance } from 'node:perf_hooks';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { sniffContentType } from './content-type-sniffer.js';
+import { getVideoFrameEdge, parseVideoProbe, planVideoFrames, planVideoContactSheets, VIDEO_EXTRACTION_TIMEOUT_MS, VIDEO_MAX_SHEET_BYTES, VIDEO_MAX_FRAME_BYTES, VIDEO_MAX_INPUT_BYTES, VIDEO_MAX_OUTPUT_BYTES } from './video-frames.js';
+class VideoProcessError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+async function executable(required, { configured } = {}) {
+    const candidates = configured ? [configured] : [
+        ...(process.env['PATH'] ?? '').split(delimiter).filter(isAbsolute).map(directory => join(directory, required.name)),
+        join('/opt/homebrew/bin', required.name), join('/usr/local/bin', required.name), join('/usr/bin', required.name),
+    ];
+    for (const candidate of candidates) {
+        if (!isAbsolute(candidate))
+            continue;
+        try {
+            await access(candidate, constants.X_OK);
+            if ((await stat(candidate)).isFile())
+                return candidate;
+        }
+        catch { /* Try the next host executable. */ }
+    }
+    return undefined;
+}
+/** Discovery never executes a version/probe command. Configured paths are host configuration,
+ * never tool arguments, and all subprocesses (including ffprobe) still go through nice. */
+export const findVideoBinaries = async (_required, _optional) => {
+    if (process.platform === 'win32')
+        return undefined; // Never silently omit the low-priority guarantee.
+    const nice = await executable({ name: 'nice' }, {});
+    const ffmpeg = await executable({ name: 'ffmpeg' }, { configured: process.env['FFMPEG_PATH'] });
+    const ffprobe = await executable({ name: 'ffprobe' }, { configured: process.env['FFPROBE_PATH'] });
+    return nice && ffmpeg && ffprobe ? { nice, ffmpeg, ffprobe } : undefined;
+};
+/** detached creates a group including nice and its eventual executable; killing the group prevents
+ * a wrapper from leaving a decoder alive. Waiting for close keeps the extraction lock until exit. */
+export const runLowPriorityVideoProcess = async ({ command, args, spawnProcess = spawn, killGroup = ({ pid }) => { process.kill(-pid, 'SIGKILL'); } }, { timeoutMs, maxOutputBytes, signal }) => {
+    if (signal?.aborted)
+        throw new VideoProcessError('canceled', 'Video preview canceled.');
+    if (timeoutMs <= 0)
+        throw new VideoProcessError('timeout', 'Video preview timed out.');
+    return new Promise((resolve, reject) => {
+        const child = spawnProcess(command, [...args], { detached: true, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const chunks = [];
+        let bytes = 0;
+        let stopped;
+        let settled = false;
+        const stop = (error) => {
+            if (stopped || settled)
+                return;
+            stopped = error;
+            try {
+                if (child.pid === undefined)
+                    child.kill('SIGKILL');
+                else
+                    killGroup({ pid: child.pid }, {});
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        };
+        const timer = setTimeout(() => stop(new VideoProcessError('timeout', 'Video preview timed out.')), timeoutMs);
+        const abort = () => stop(new VideoProcessError('canceled', 'Video preview canceled.'));
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve(Buffer.concat(chunks));
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (stopped)
+                return;
+            bytes += chunk.length;
+            if (bytes > maxOutputBytes) {
+                stop(new VideoProcessError('invalid', 'Video preview exceeded its output limit.'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        // Drain diagnostics but do not retain unbounded stderr or expose host paths to the model.
+        child.stderr?.resume();
+        child.once('error', (error) => finish(new VideoProcessError(error.code === 'ENOENT' || error.code === 'EACCES' ? 'unavailable' : 'invalid', 'Video preview process could not start.')));
+        child.once('close', (code) => finish(stopped ?? (code === 0 ? undefined : new VideoProcessError('invalid', 'Video preview could not decode this clip.'))));
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+    });
+};
+// Shared across ALL adapter instances: a second catalog/tenant cannot run a second ffmpeg in this
+// process. Fail busy instead of holding arbitrary numbers of uploaded videos in a pending queue.
+let extracting = false;
+const UNAVAILABLE = 'video preview unavailable on this host (nice, ffmpeg and ffprobe are required).';
+// Eight amortizes process/seek overhead while bounding expensive source decoders to
+// one eighth of the 64-frame maximum. Thread caps alone do not bound decoder memory.
+// This is a decoder-count limit, not a measured host RSS guarantee.
+const SOURCE_BATCH_SIZE = 8;
+const localInputFlags = ['-threads', '1', '-protocol_whitelist', 'file', '-format_whitelist', 'mov,matroska,webm'];
+export function createFfmpegVideoFrameExtractor({ findBinaries = findVideoBinaries, runProcess = runLowPriorityVideoProcess, nowMs = () => performance.now() }, _optional = {}) {
+    return { extract: async ({ bytes }, options) => {
+            if (bytes.byteLength > VIDEO_MAX_INPUT_BYTES)
+                return { ok: false, reason: 'too-large', message: `Video preview input exceeds ${VIDEO_MAX_INPUT_BYTES} bytes.` };
+            const type = sniffContentType({ bytes });
+            if (type !== 'video/mp4' && type !== 'video/webm')
+                return { ok: false, reason: 'invalid', message: 'Video preview requires stored MP4 or WebM bytes.' };
+            if (extracting)
+                return { ok: false, reason: 'busy', message: 'Video preview is busy. Try again after the current extraction finishes.' };
+            extracting = true;
+            const deadline = nowMs({}, {}) + VIDEO_EXTRACTION_TIMEOUT_MS;
+            let directory;
+            try {
+                if (options.signal?.aborted)
+                    throw new VideoProcessError('canceled', 'Video preview canceled.');
+                if (options.layout !== undefined && options.layout !== 'frames' && options.layout !== 'sheet')
+                    throw new VideoProcessError('invalid', 'Video layout must be frames or sheet.');
+                const binaries = await findBinaries({}, {});
+                if (!binaries)
+                    return { ok: false, reason: 'unavailable', message: UNAVAILABLE };
+                directory = await mkdtemp(join(tmpdir(), 'video-preview-'));
+                const input = join(directory, 'input');
+                await writeFile(input, bytes, { mode: 0o600, flag: 'wx' });
+                const checkDeadline = () => {
+                    if (options.signal?.aborted)
+                        throw new VideoProcessError('canceled', 'Video preview canceled.');
+                    if (nowMs({}, {}) >= deadline)
+                        throw new VideoProcessError('timeout', 'Video preview timed out.');
+                };
+                const run = (required, optional) => {
+                    checkDeadline();
+                    const timeoutMs = deadline - nowMs({}, {});
+                    if (timeoutMs <= 0)
+                        throw new VideoProcessError('timeout', 'Video preview timed out.');
+                    return runProcess({ command: binaries.nice, args: ['-n', '19', required.binary, ...required.args] }, { timeoutMs, maxOutputBytes: optional.maxOutputBytes, ...(options.signal ? { signal: options.signal } : {}) });
+                };
+                const probe = await run({ binary: binaries.ffprobe, args: ['-v', 'error', ...localInputFlags, '-show_entries', 'format=duration,format_name:stream=codec_type,codec_name,width,height,duration:stream_disposition=attached_pic', '-of', 'json', '-i', input] }, { maxOutputBytes: 64 * 1024 });
+                const metadata = parseVideoProbe({ output: Buffer.from(probe).toString('utf8'), sizeBytes: bytes.byteLength }, {});
+                const times = planVideoFrames({ duration: metadata.duration }, options);
+                const sheetLayouts = options.layout === 'sheet' ? planVideoContactSheets({ times }, {}) : undefined;
+                const edge = sheetLayouts?.[0]?.tileEdgePx ?? getVideoFrameEdge({ frameCount: times.length }, {});
+                const imageCount = sheetLayouts?.length ?? times.length;
+                const perImageLimit = sheetLayouts ? VIDEO_MAX_SHEET_BYTES : VIDEO_MAX_FRAME_BYTES;
+                // Preallocate a fair share for each output, so all file limits together fit the total budget.
+                const fileLimit = Math.min(perImageLimit, Math.floor(VIDEO_MAX_OUTPUT_BYTES / imageCount));
+                const paths = Array.from({ length: imageCount }, (_, index) => join(directory, `image-${index}.jpg`));
+                const tilePaths = sheetLayouts ? times.map((_, index) => join(directory, `tile-${index}.jpg`)) : paths;
+                // Intermediates have their own bounded allocation; never spend a sheet's 2 MiB per tile.
+                const tileLimit = sheetLayouts ? Math.min(VIDEO_MAX_FRAME_BYTES, Math.floor(VIDEO_MAX_OUTPUT_BYTES / times.length)) : fileLimit;
+                const ffmpegArgs = () => ['-hide_banner', '-loglevel', 'error', '-nostdin', '-filter_threads', '1', '-filter_complex_threads', '1'];
+                // Framerate mode is per output (ffmpeg >=5.1); preserve each selected frame
+                // for both source extraction and contact-sheet assembly without resync.
+                const appendOutput = ({ args, label, path, limit }) => args.push('-map', label, '-an', '-sn', '-dn', '-frames:v', '1', '-c:v', 'mjpeg', '-threads', '1', '-q:v', '5', '-fs', String(limit), '-f', 'mjpeg', '-fps_mode', 'passthrough', path);
+                const readImage = async ({ path, perImageLimit, fileLimit }) => {
+                    checkDeadline();
+                    // -fs is packet-granular: check size before allocating and refuse overshoot.
+                    const size = (await stat(path)).size;
+                    checkDeadline();
+                    if (size > perImageLimit)
+                        throw new VideoProcessError('invalid', 'Video preview exceeded its output limit.');
+                    if (size > fileLimit)
+                        throw new VideoProcessError('invalid', 'Video preview exceeded its total output limit (8 MiB).');
+                    const image = await readFile(path);
+                    checkDeadline();
+                    if (image.length < 4 || image[0] !== 255 || image[1] !== 216 || image[image.length - 2] !== 255 || image[image.length - 1] !== 217) {
+                        throw new VideoProcessError('invalid', 'Video preview returned no JPEG frame.');
+                    }
+                    return image;
+                };
+                const scale = `scale=w='min(${edge},iw)':h='min(${edge},ih)':force_original_aspect_ratio=decrease`;
+                const images = [];
+                let tileBytes = 0;
+                // Await exit and validate this batch before starting another: <=8 source contexts alive.
+                for (let offset = 0; offset < times.length; offset += SOURCE_BATCH_SIZE) {
+                    checkDeadline();
+                    const batch = times.slice(offset, offset + SOURCE_BATCH_SIZE);
+                    const args = ffmpegArgs();
+                    // Seek each source input before opening it; no full-clip select/decode scan.
+                    for (const at of batch)
+                        args.push(...localInputFlags, '-ss', String(at), '-i', input);
+                    const filters = batch.map((_, index) => `[${index}:V:0]trim=end_frame=1,setpts=PTS-STARTPTS,${scale},setsar=1${sheetLayouts ? `,pad=${edge}:${edge}:(ow-iw)/2:(oh-ih)/2:color=black` : ''}[tile${index}]`);
+                    args.push('-filter_complex', filters.join(';'));
+                    for (let index = 0; index < batch.length; index++)
+                        appendOutput({ args, label: `[tile${index}]`, path: tilePaths[offset + index], limit: tileLimit });
+                    // Raw MJPEG with one frame writes one JPEG through the file muxer (-fs applies).
+                    await run({ binary: binaries.ffmpeg, args }, { maxOutputBytes: 64 * 1024 });
+                    checkDeadline();
+                    for (let index = 0; index < batch.length; index++) {
+                        const image = await readImage({ path: tilePaths[offset + index], perImageLimit: VIDEO_MAX_FRAME_BYTES, fileLimit: tileLimit });
+                        tileBytes += image.byteLength;
+                        if (tileBytes > VIDEO_MAX_OUTPUT_BYTES)
+                            throw new VideoProcessError('invalid', 'Video preview exceeded its total output limit (8 MiB).');
+                        if (!sheetLayouts)
+                            images.push(image); // Sheet tiles remain on disk, not retained in memory.
+                    }
+                }
+                if (sheetLayouts) {
+                    let offset = 0;
+                    let outputBytes = 0;
+                    for (const [index, sheet] of sheetLayouts.entries()) {
+                        checkDeadline();
+                        const inputs = tilePaths.slice(offset, offset + sheet.tiles.length);
+                        const args = ffmpegArgs();
+                        // These decoders see only small, validated JPEGs, never the source video.
+                        for (const path of inputs)
+                            args.push('-threads', '1', '-protocol_whitelist', 'file', '-format_whitelist', 'mjpeg', '-f', 'mjpeg', '-i', path);
+                        const filters = inputs.map((_, tile) => `[${tile}:v:0]trim=end_frame=1,setpts=PTS-STARTPTS[tile${tile}]`);
+                        const labels = inputs.map((_, tile) => `[tile${tile}]`).join('');
+                        const positions = sheet.tiles.map(tile => `${(tile.column - 1) * edge}_${(tile.row - 1) * edge}`).join('|');
+                        // Pad the grid if unused bottom-right cells do not establish the full extent.
+                        filters.push(`${labels}${inputs.length === 1 ? 'null' : `xstack=inputs=${inputs.length}:layout=${positions}:fill=black:shortest=1`},pad=${sheet.columns * edge}:${sheet.rows * edge}:0:0:color=black[sheet]`);
+                        args.push('-filter_complex', filters.join(';'));
+                        appendOutput({ args, label: '[sheet]', path: paths[index], limit: fileLimit });
+                        await run({ binary: binaries.ffmpeg, args }, { maxOutputBytes: 64 * 1024 });
+                        const image = await readImage({ path: paths[index], perImageLimit, fileLimit });
+                        outputBytes += image.byteLength;
+                        if (outputBytes > VIDEO_MAX_OUTPUT_BYTES)
+                            throw new VideoProcessError('invalid', 'Video preview exceeded its total output limit (8 MiB).');
+                        images.push(image);
+                        // Retire tiles as soon as their sheet is verified; finally still cleans on any failure.
+                        for (const path of inputs) {
+                            checkDeadline();
+                            await rm(path);
+                        }
+                        offset += inputs.length;
+                    }
+                }
+                checkDeadline();
+                if (sheetLayouts)
+                    return { ok: true, metadata, frames: [], sheets: sheetLayouts.map((sheet, index) => ({ ...sheet, mimeType: 'image/jpeg', bytes: images[index] })) };
+                return { ok: true, metadata, frames: times.map((at, index) => ({ at, mimeType: 'image/jpeg', bytes: images[index] })) };
+            }
+            catch (error) {
+                const reason = error instanceof VideoProcessError ? error.reason : 'invalid';
+                return { ok: false, reason, message: reason === 'unavailable' ? UNAVAILABLE : error instanceof VideoProcessError ? error.message : 'Video preview could not read or decode this clip.' };
+            }
+            finally {
+                try {
+                    if (directory)
+                        await rm(directory, { recursive: true, force: true });
+                }
+                catch {
+                    return { ok: false, reason: 'invalid', message: 'Video preview temporary files could not be removed.' };
+                }
+                finally {
+                    extracting = false;
+                }
+            }
+        } };
+}
+//# sourceMappingURL=video-frames.ffmpeg.js.map

package/dist/media/video-frames.js

@@ -0,0 +1,97 @@
+/** Video preview contract and sampling policy, independent of a host, codec or AI provider. */
+export const VIDEO_MAX_FRAMES = 64;
+export const VIDEO_DEFAULT_FRAMES = 16;
+export const VIDEO_MAX_EDGE_PX = 768;
+export const VIDEO_MAX_INPUT_BYTES = 64 * 1024 * 1024;
+export const VIDEO_MAX_FRAME_BYTES = 512 * 1024;
+/** Aggregate raw JPEG payload budget; base64 expands this to about 10.67 MiB plus metadata. */
+export const VIDEO_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+export const VIDEO_MAX_SHEET_BYTES = 2 * 1024 * 1024;
+export const VIDEO_MAX_SHEETS = 4;
+// One shared deadline: serial source batches and JPEG sheet assembly need launch/seek
+// headroom at nice 19. This remains a hard bound, not a per-process allowance.
+export const VIDEO_EXTRACTION_TIMEOUT_MS = 60_000;
+/** Keep sixteen square 768px images worth of pixels (about 12.6k tokens at pixels/750).
+ * Even pixel sizes are codec-friendly; flooring never increases the budget. */
+export function getVideoFrameEdge({ frameCount }, _optional = {}) {
+    if (!Number.isInteger(frameCount) || frameCount < 1 || frameCount > VIDEO_MAX_FRAMES)
+        throw new Error('Frame count must be an integer from 1 to 64.');
+    return 2 * Math.floor(VIDEO_MAX_EDGE_PX * Math.min(1, Math.sqrt(VIDEO_DEFAULT_FRAMES / frameCount)) / 2);
+}
+/** Grid pixels, including black unused cells, share the separate-frame pixel budget.
+ * Metadata provides labels without requiring a host font or ffmpeg drawtext support. */
+export function planVideoContactSheets({ times }, _optional = {}) {
+    if (!Array.isArray(times) || times.length < 1 || times.length > VIDEO_MAX_FRAMES || times.some(time => typeof time !== 'number' || !Number.isFinite(time) || time < 0)) {
+        throw new Error('Sheets require 1 to 64 finite nonnegative timestamps.');
+    }
+    const groups = [];
+    for (let offset = 0; offset < times.length; offset += 16) {
+        const group = times.slice(offset, offset + 16);
+        const columns = Math.min(4, Math.ceil(Math.sqrt(group.length)));
+        const rows = Math.ceil(group.length / columns);
+        groups.push({ columns, rows, tileEdgePx: 0, tiles: group.map((at, index) => ({ index: index + 1, row: Math.floor(index / columns) + 1, column: index % columns + 1, at })) });
+    }
+    const frameCount = groups.reduce((sum, group) => sum + group.columns * group.rows, 0);
+    const tileEdgePx = getVideoFrameEdge({ frameCount }, {});
+    return groups.map(group => ({ ...group, tileEdgePx }));
+}
+/** Avoid seeking to exact EOF, which commonly has no decodable frame. Preserve explicit order,
+ * including repeated timestamps, so image positions continue to match the requested positions.
+ * With every and no count, stop when the next timestamp cannot fit (always emit the first clamped
+ * position). An explicit count preserves the requested count, clamping positions beyond the clip.
+ * start only affects every; at overrides count/start, but at + every is invalid. */
+export function planVideoFrames({ duration }, { frames, at, every, start = 0 } = {}) {
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new Error('Video duration must be positive and finite.');
+    if (frames !== undefined && (typeof frames !== 'number' || !Number.isFinite(frames)))
+        throw new Error('Frame count must be finite.');
+    if (frames !== undefined && frames < 0)
+        throw new Error('Frame count must be nonnegative.');
+    if (at !== undefined && (!Array.isArray(at) || !at.length || at.some(time => typeof time !== 'number' || !Number.isFinite(time)))) {
+        throw new Error('at must contain finite timestamps in seconds.');
+    }
+    if (at?.some(time => time < 0))
+        throw new Error('at timestamps must be nonnegative.');
+    if (every !== undefined && (typeof every !== 'number' || !Number.isFinite(every) || every <= 0))
+        throw new Error('every must be a positive finite number of seconds.');
+    if (typeof start !== 'number' || !Number.isFinite(start) || start < 0)
+        throw new Error('start must be a nonnegative finite number of seconds.');
+    if (at !== undefined && every !== undefined)
+        throw new Error('every cannot be combined with at.');
+    const inset = Math.min(0.1, duration / 10);
+    const end = duration - inset;
+    if (at !== undefined) {
+        return at.slice(0, VIDEO_MAX_FRAMES).map(time => Math.max(0, Math.min(end, time)));
+    }
+    const count = Math.max(1, Math.min(VIDEO_MAX_FRAMES, Math.floor(frames ?? (every !== undefined ? VIDEO_MAX_FRAMES : VIDEO_DEFAULT_FRAMES))));
+    if (every !== undefined) {
+        const times = [];
+        for (let index = 0; index < count; index++) {
+            const time = start + index * every;
+            // Multiplication can round a fitting boundary just above end. Only tolerate arithmetic
+            // roundoff; a materially later timestamp must not add an EOF sample when count is omitted.
+            const tolerance = Number.EPSILON * Math.max(end, Math.abs(time)) * 4;
+            if (frames === undefined && index > 0 && (!Number.isFinite(time) || time - end > tolerance))
+                break;
+            times.push(Math.min(end, time));
+        }
+        return times;
+    }
+    if (count === 1)
+        return [duration / 2];
+    return Array.from({ length: count }, (_, index) => inset + (end - inset) * index / (count - 1));
+}
+/** Parse only the ffprobe fields requested by the adapter. File size is measured from authorized
+ * input bytes, never from a possibly stale container header. Cover art is not a video stream. */
+export function parseVideoProbe({ output, sizeBytes }, _optional = {}) {
+    const raw = JSON.parse(output);
+    const streams = Array.isArray(raw?.streams) ? raw.streams : [];
+    const video = streams.find(stream => stream.codec_type === 'video' && stream.disposition?.attached_pic !== 1);
+    const formatDuration = Number(raw?.format?.duration);
+    const duration = Number.isFinite(formatDuration) && formatDuration > 0 ? formatDuration : Number(video?.duration);
+    if (!video || !Number.isFinite(duration) || duration <= 0 || !Number.isInteger(video.width) || !Number.isInteger(video.height) || video.width <= 0 || video.height <= 0) {
+        throw new Error('Video metadata is missing or invalid.');
+    }
+    return { duration, width: video.width, height: video.height, codec: video.codec_name ?? 'unknown', container: raw.format?.format_name ?? 'unknown', sizeBytes, hasAudio: streams.some(stream => stream.codec_type === 'audio') };
+}
+//# sourceMappingURL=video-frames.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Content-model capability for Jini-hosted products: framework-free contracts, ports, and domain services in `/core` and per-domain subpaths; Node-bound adapters in domain-specific subpaths.",
   "license": "Apache-2.0",
   "repository": {