fundus 0.0.2 → 0.0.3

package/dist/server/plugins/contract.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The server part of the type-plugin contract: everything the
+ * pipeline needs per asset type beyond the core descriptor — the plugin's
+ * config slice, preset resolution, the processing step (sharp/ffmpeg), proxy
+ * probing, and the manifest-entry builder for codegen. The orchestrators
+ * (processor, codegen, check, store, operations) are type-agnostic and consult
+ * only the registry (plugins.ts), so a new asset type is: a core descriptor +
+ * one `ServerAssetTypePlugin` + one registry entry — nothing else server-side.
+ */
+import type { AssetTypePluginDescriptor, ManifestEntryData } from '../../core/index.js';
+import type { ResolvedFundusConfig } from '../config-loader.js';
+/** Output metadata of one processed proxy file (absent fields don't apply). */
+export interface ProxyOutputInfo {
+    /** Intrinsic pixel dimensions; absent for audio proxies. */
+    width?: number;
+    height?: number;
+    /** Media duration; present for video and audio proxies. */
+    durationMs?: number;
+}
+/** One delivered asset's current proxy: file identity plus output metadata. */
+export interface AssetProxyInfo extends ProxyOutputInfo {
+    assetId: string;
+    /** Basename, stable across folder moves. */
+    fileName: string;
+    /** Path relative to proxyDir, mirroring the raw asset's folder. */
+    relativePath: string;
+    fileSize: number;
+}
+/** The inputs of one processing run: raw file → proxy file. */
+export interface ServerProcessingJob<TParameters, TPreset> {
+    /** Absolute path of the raw source file. */
+    sourcePath: string;
+    /** Absolute path the proxy file must be written to. */
+    targetPath: string;
+    /** The asset's validated parameters. */
+    parameters: TParameters;
+    /** The resolved preset the parameters name. */
+    preset: TPreset;
+    config: ResolvedFundusConfig;
+}
+/** The inputs of one manifest-entry build. */
+export interface ManifestEntryInput<TParameters> {
+    assetId: string;
+    /** The asset's validated parameters. */
+    parameters: TParameters;
+    /** The delivered proxy URL (`proxyBasePath` + proxy relative path). */
+    src: string;
+    proxy: AssetProxyInfo;
+}
+export interface ServerAssetTypePlugin<TParameters = unknown, TPreset = unknown> {
+    /** The environment-free half of the plugin (type key, ingestion, validation). */
+    descriptor: AssetTypePluginDescriptor<TParameters, unknown>;
+    /**
+     * The plugin's `plugins.<namespace>` config slice — handed to the
+     * descriptor's `defaultParameters` on ingest. Types may share a namespace
+     * (chroma-key-video uses the video slice).
+     */
+    pluginConfig(config: ResolvedFundusConfig): unknown;
+    /** The merged (built-in + host) named presets available to this type. */
+    presets(config: ResolvedFundusConfig): Record<string, TPreset>;
+    /**
+     * The resolved settings of the preset the validated parameters name —
+     * these feed the job hash (a preset edit under an unchanged name
+     * must rename the proxy). Throws (listing the known names) on a miss.
+     */
+    resolvePreset(parameters: TParameters, config: ResolvedFundusConfig): TPreset;
+    /** The proxy file extension a resolved preset's output carries. */
+    proxyExtension(preset: TPreset): string;
+    /**
+     * Optional ingest seeding, run right after the raw file is stored: derive
+     * better starting parameters than the schema defaults from the actual raw
+     * file — the slice plugin seeds insets from the image dimensions and a
+     * pixel ratio from a `@2x`-style file-name suffix. Returns the replacement
+     * parameters, or undefined to keep the defaults. Omitted = defaults stand.
+     */
+    seedIngestParameters?(context: {
+        /** Absolute path of the stored raw file. */
+        rawPath: string;
+        /** The stored raw file name (sanitized, unique). */
+        rawFileName: string;
+        /** The validated default parameters the record starts with. */
+        parameters: TParameters;
+        config: ResolvedFundusConfig;
+    }): Promise<TParameters | undefined>;
+    /** Run the processing job (sharp/ffmpeg): write the proxy, report its metadata. */
+    process(job: ServerProcessingJob<TParameters, TPreset>): Promise<ProxyOutputInfo>;
+    /** Probe an existing proxy file's output metadata (the up-to-date path). */
+    readProxyInfo(proxyPath: string, config: ResolvedFundusConfig): Promise<ProxyOutputInfo>;
+    /**
+     * Build the generated manifest entry. Reference fields stay
+     * `{ $asset }` markers — codegen's generic inline walk resolves them.
+     */
+    buildManifestEntry(input: ManifestEntryInput<TParameters>): ManifestEntryData;
+}
+/** The one server-side touch point for a new asset type: type key → plugin. */
+export type ServerPluginRegistry = Record<string, ServerAssetTypePlugin>;
+/** Resolve a named preset out of a plugin's merged preset map, or throw listing the known names. */
+export declare function resolveNamedPreset<TPreset>(label: string, presetName: string, presets: Record<string, TPreset>): TPreset;
+/** A proxy-info field a given entry kind cannot do without. */
+export declare function requireProxyField(proxy: AssetProxyInfo, field: 'width' | 'height' | 'durationMs'): number;

package/dist/server/plugins/contract.js

@@ -0,0 +1,16 @@
+/** Resolve a named preset out of a plugin's merged preset map, or throw listing the known names. */
+export function resolveNamedPreset(label, presetName, presets) {
+    const preset = presets[presetName];
+    if (!preset) {
+        throw new Error(`Unknown ${label} preset "${presetName}" (known: ${Object.keys(presets).sort().join(', ')}).`);
+    }
+    return preset;
+}
+/** A proxy-info field a given entry kind cannot do without. */
+export function requireProxyField(proxy, field) {
+    const value = proxy[field];
+    if (value === undefined) {
+        throw new Error(`Proxy info of "${proxy.assetId}" is missing "${field}".`);
+    }
+    return value;
+}

package/dist/server/plugins/image.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Image plugin (server part): sharp scale + convert per preset.
+ */
+import { type ImageFormat, type ImageParameters, type ImagePreset } from '../../core/index.js';
+import { type ServerAssetTypePlugin } from './contract.js';
+/** The delivered file extension of an image-preset format. */
+export declare function extensionForImageFormat(format: ImageFormat): string;
+export declare const imageServerPlugin: ServerAssetTypePlugin<ImageParameters, ImagePreset>;

package/dist/server/plugins/image.js

@@ -0,0 +1,30 @@
+/**
+ * Image plugin (server part): sharp scale + convert per preset.
+ */
+import { imagePlugin } from '../../core/index.js';
+import { processImageFile, readImageDimensions } from '../processing/image-processing.js';
+import { requireProxyField, resolveNamedPreset } from './contract.js';
+/** The delivered file extension of an image-preset format. */
+export function extensionForImageFormat(format) {
+    return format === 'jpeg' ? 'jpg' : format;
+}
+export const imageServerPlugin = {
+    descriptor: imagePlugin,
+    pluginConfig: (config) => config.plugins.image,
+    presets: (config) => config.plugins.image.presets,
+    resolvePreset: (parameters, config) => resolveNamedPreset('image', parameters.preset, config.plugins.image.presets),
+    proxyExtension: (preset) => extensionForImageFormat(preset.format),
+    process: (job) => processImageFile({
+        sourcePath: job.sourcePath,
+        targetPath: job.targetPath,
+        preset: job.preset,
+        targetWidth: job.parameters.targetWidth
+    }),
+    readProxyInfo: (proxyPath) => readImageDimensions(proxyPath),
+    buildManifestEntry: ({ src, proxy }) => ({
+        kind: 'image',
+        src,
+        width: requireProxyField(proxy, 'width'),
+        height: requireProxyField(proxy, 'height')
+    })
+};

package/dist/server/plugins/slice.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Slice plugin (server part): the same sharp conversion as the image plugin,
+ * never resized — insets are authored in source pixels, so the delivered proxy
+ * keeps the source dimensions. The slicing data is entry-only.
+ */
+import { type ImagePreset, type SliceParameters } from '../../core/index.js';
+import { type ServerAssetTypePlugin } from './contract.js';
+/**
+ * Best-effort guess of the asset's export scale from a `@2x` / `@3x` suffix in
+ * the file name (also tolerates `-`/`_` separators, e.g. `dialog-3x.png`).
+ * Falls back to 1.
+ */
+export declare function detectPixelRatio(fileName: string): number;
+export declare const sliceServerPlugin: ServerAssetTypePlugin<SliceParameters, ImagePreset>;

package/dist/server/plugins/slice.js

@@ -0,0 +1,63 @@
+/**
+ * Slice plugin (server part): the same sharp conversion as the image plugin,
+ * never resized — insets are authored in source pixels, so the delivered proxy
+ * keeps the source dimensions. The slicing data is entry-only.
+ */
+import { defaultInsetsForSize, slicePlugin } from '../../core/index.js';
+import { processImageFile, readImageDimensions } from '../processing/image-processing.js';
+import { extensionForImageFormat } from './image.js';
+import { requireProxyField, resolveNamedPreset } from './contract.js';
+function hasAnySide(insets) {
+    if (!insets)
+        return false;
+    return insets.top > 0 || insets.right > 0 || insets.bottom > 0 || insets.left > 0;
+}
+/**
+ * Best-effort guess of the asset's export scale from a `@2x` / `@3x` suffix in
+ * the file name (also tolerates `-`/`_` separators, e.g. `dialog-3x.png`).
+ * Falls back to 1.
+ */
+export function detectPixelRatio(fileName) {
+    const match = fileName.match(/(?:@|[-_])(\d)x(?=\.[^.]*$|$)/i);
+    const ratio = match ? Number(match[1]) : 1;
+    return ratio >= 1 ? ratio : 1;
+}
+export const sliceServerPlugin = {
+    descriptor: slicePlugin,
+    pluginConfig: (config) => config.plugins.slice,
+    presets: (config) => config.plugins.slice.presets,
+    resolvePreset: (parameters, config) => resolveNamedPreset('slice', parameters.preset, config.plugins.slice.presets),
+    proxyExtension: (preset) => extensionForImageFormat(preset.format),
+    // Seed sensible insets from the actual image dimensions and a pixel ratio
+    // from the file name — the schema default can't know either.
+    seedIngestParameters: async ({ rawPath, rawFileName, parameters }) => {
+        const dimensions = await readImageDimensions(rawPath);
+        return {
+            ...parameters,
+            insets: defaultInsetsForSize(dimensions.width, dimensions.height),
+            pixelRatio: detectPixelRatio(rawFileName)
+        };
+    },
+    process: (job) => processImageFile({
+        sourcePath: job.sourcePath,
+        targetPath: job.targetPath,
+        preset: job.preset
+    }),
+    readProxyInfo: (proxyPath) => readImageDimensions(proxyPath),
+    buildManifestEntry: ({ parameters, src, proxy }) => {
+        const slicing = {
+            mode: parameters.mode,
+            insets: parameters.insets,
+            pixelRatio: parameters.pixelRatio,
+            // An all-zero overdraw is semantically "none" — keep the entry minimal.
+            ...(hasAnySide(parameters.overdraw) ? { overdraw: parameters.overdraw } : {})
+        };
+        return {
+            kind: 'slice',
+            src,
+            slicing,
+            sourceWidth: requireProxyField(proxy, 'width'),
+            sourceHeight: requireProxyField(proxy, 'height')
+        };
+    }
+};

package/dist/server/plugins/video.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Video plugin (server part): one ffmpeg transcode per preset.
+ */
+import { type VideoParameters, type VideoPreset } from '../../core/index.js';
+import { type ServerAssetTypePlugin } from './contract.js';
+export declare const videoServerPlugin: ServerAssetTypePlugin<VideoParameters, VideoPreset>;

package/dist/server/plugins/video.js

@@ -0,0 +1,29 @@
+/**
+ * Video plugin (server part): one ffmpeg transcode per preset.
+ */
+import { videoPlugin } from '../../core/index.js';
+import { probeMedia } from '../processing/media-probe.js';
+import { processVideoFile } from '../processing/video-processing.js';
+import { requireProxyField, resolveNamedPreset } from './contract.js';
+export const videoServerPlugin = {
+    descriptor: videoPlugin,
+    pluginConfig: (config) => config.plugins.video,
+    presets: (config) => config.plugins.video.presets,
+    resolvePreset: (parameters, config) => resolveNamedPreset('video', parameters.preset, config.plugins.video.presets),
+    proxyExtension: (preset) => preset.container,
+    process: (job) => processVideoFile({
+        sourcePath: job.sourcePath,
+        targetPath: job.targetPath,
+        preset: job.preset,
+        maxWidth: job.parameters.maxWidth,
+        config: job.config
+    }),
+    readProxyInfo: (proxyPath, config) => probeMedia(proxyPath, config),
+    buildManifestEntry: ({ src, proxy }) => ({
+        kind: 'video',
+        src,
+        width: requireProxyField(proxy, 'width'),
+        height: requireProxyField(proxy, 'height'),
+        durationMs: requireProxyField(proxy, 'durationMs')
+    })
+};

package/dist/server/plugins.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The server-side plugin registry: the ONE map that binds an asset
+ * type to its server plugin (core descriptor + config slice + presets +
+ * processing + entry building — plugins/contract.ts). The pipeline
+ * orchestrators (processor, codegen, check, store, operations) are
+ * type-agnostic and take the registry as a parameter defaulting to this map,
+ * so a new asset type is a descriptor + one `ServerAssetTypePlugin` + one
+ * entry here — and tests can extend the registry without touching them.
+ */
+import type { AssetTypePluginDescriptor } from '../core/index.js';
+import type { ServerAssetTypePlugin, ServerPluginRegistry } from './plugins/contract.js';
+export declare const serverPluginsByType: ServerPluginRegistry;
+export declare function serverPluginForType(type: string, registry?: ServerPluginRegistry): ServerAssetTypePlugin;
+/** The core-descriptor view of a registry — what core's reference/graph helpers consume. */
+export declare function descriptorsByType(registry: ServerPluginRegistry): Record<string, AssetTypePluginDescriptor<unknown, unknown>>;
+/** The built-in registry's descriptor map (the common case; registry-aware code derives its own). */
+export declare const pluginsByType: Record<string, AssetTypePluginDescriptor<unknown, unknown>>;
+/**
+ * The job-hash parameter input for an asset: the plugin-declared
+ * processing-relevant subset when the plugin distinguishes one (chroma-key-
+ * video: keying + references are entry-only), else the full parameter value.
+ */
+export declare function processingParametersOf(plugin: AssetTypePluginDescriptor<unknown, unknown>, parameters: unknown): unknown;

package/dist/server/plugins.js

@@ -0,0 +1,33 @@
+import { audioServerPlugin } from './plugins/audio.js';
+import { chromaKeyVideoServerPlugin } from './plugins/chroma-key-video.js';
+import { imageServerPlugin } from './plugins/image.js';
+import { sliceServerPlugin } from './plugins/slice.js';
+import { videoServerPlugin } from './plugins/video.js';
+export const serverPluginsByType = {
+    [imageServerPlugin.descriptor.type]: imageServerPlugin,
+    [sliceServerPlugin.descriptor.type]: sliceServerPlugin,
+    [videoServerPlugin.descriptor.type]: videoServerPlugin,
+    [chromaKeyVideoServerPlugin.descriptor.type]: chromaKeyVideoServerPlugin,
+    [audioServerPlugin.descriptor.type]: audioServerPlugin
+};
+export function serverPluginForType(type, registry = serverPluginsByType) {
+    const plugin = registry[type];
+    if (!plugin) {
+        throw new Error(`Unknown asset type "${type}" (known: ${Object.keys(registry).sort().join(', ')}).`);
+    }
+    return plugin;
+}
+/** The core-descriptor view of a registry — what core's reference/graph helpers consume. */
+export function descriptorsByType(registry) {
+    return Object.fromEntries(Object.entries(registry).map(([type, plugin]) => [type, plugin.descriptor]));
+}
+/** The built-in registry's descriptor map (the common case; registry-aware code derives its own). */
+export const pluginsByType = descriptorsByType(serverPluginsByType);
+/**
+ * The job-hash parameter input for an asset: the plugin-declared
+ * processing-relevant subset when the plugin distinguishes one (chroma-key-
+ * video: keying + references are entry-only), else the full parameter value.
+ */
+export function processingParametersOf(plugin, parameters) {
+    return plugin.processingParameters ? plugin.processingParameters(parameters) : parameters;
+}

package/dist/server/processing/audio-processing.d.ts

@@ -0,0 +1,17 @@
+import type { AudioPreset } from '../../core/index.js';
+import type { ResolvedFundusConfig } from '../config-loader.js';
+/** The full ffmpeg argument list for one audio transcode (pure, testable). */
+export declare function buildAudioTranscodeArguments(options: {
+    sourcePath: string;
+    targetPath: string;
+    preset: AudioPreset;
+}): string[];
+export interface AudioProcessingOutput {
+    durationMs: number;
+}
+export declare function processAudioFile(options: {
+    sourcePath: string;
+    targetPath: string;
+    preset: AudioPreset;
+    config: ResolvedFundusConfig;
+}): Promise<AudioProcessingOutput>;

package/dist/server/processing/audio-processing.js

@@ -0,0 +1,46 @@
+/**
+ * The ffmpeg transcode step of the audio plugin: one audio-only proxy per
+ * preset (opus/webm or aac/m4a). Deterministic like the video step:
+ * metadata stripped, bitexact muxing.
+ */
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ffmpegBinaryPath, runToolchainBinary } from './ffmpeg.js';
+import { probeMedia } from './media-probe.js';
+const ENCODER_BY_CODEC = {
+    opus: 'libopus',
+    aac: 'aac'
+};
+/** The full ffmpeg argument list for one audio transcode (pure, testable). */
+export function buildAudioTranscodeArguments(options) {
+    return [
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-y',
+        '-i',
+        options.sourcePath,
+        '-vn',
+        '-c:a',
+        ENCODER_BY_CODEC[options.preset.codec],
+        '-b:a',
+        `${options.preset.bitrateKbps}k`,
+        '-map_metadata',
+        '-1',
+        '-fflags',
+        '+bitexact',
+        '-flags:a',
+        '+bitexact',
+        options.targetPath
+    ];
+}
+export async function processAudioFile(options) {
+    await mkdir(dirname(options.targetPath), { recursive: true });
+    await runToolchainBinary(ffmpegBinaryPath(options.config), buildAudioTranscodeArguments({
+        sourcePath: options.sourcePath,
+        targetPath: options.targetPath,
+        preset: options.preset
+    }));
+    const output = await probeMedia(options.targetPath, options.config);
+    return { durationMs: output.durationMs };
+}

package/dist/server/processing/ffmpeg.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedFundusConfig } from '../config-loader.js';
+export declare function ffmpegBinaryPath(config: ResolvedFundusConfig): string;
+export declare function ffprobeBinaryPath(config: ResolvedFundusConfig): string;
+/**
+ * Run a toolchain binary with an argument array (never a shell string) and
+ * return its stdout. A non-zero exit throws with the stderr tail — ffmpeg
+ * writes its diagnostics there.
+ */
+export declare function runToolchainBinary(binaryPath: string, commandArguments: string[]): Promise<string>;

package/dist/server/processing/ffmpeg.js

@@ -0,0 +1,50 @@
+/**
+ * The ffmpeg/ffprobe toolchain layer: binary resolution (bundled `-static`
+ * packages by default, with host-config overrides) and a spawn helper.
+ * Since proxies are committed, this toolchain is only needed where
+ * assets are authored/processed — host builds and CI never invoke it.
+ */
+import ffmpegStaticPath from 'ffmpeg-static';
+import { path as ffprobeStaticPath } from 'ffprobe-static';
+import { basename } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+export function ffmpegBinaryPath(config) {
+    if (config.plugins.video.ffmpegPath)
+        return config.plugins.video.ffmpegPath;
+    if (!ffmpegStaticPath) {
+        throw new Error('ffmpeg-static provides no binary for this platform — set "plugins.video.ffmpegPath" in fundus.config.ts.');
+    }
+    return ffmpegStaticPath;
+}
+export function ffprobeBinaryPath(config) {
+    if (config.plugins.video.ffprobePath)
+        return config.plugins.video.ffprobePath;
+    if (!ffprobeStaticPath) {
+        throw new Error('ffprobe-static provides no binary for this platform — set "plugins.video.ffprobePath" in fundus.config.ts.');
+    }
+    return ffprobeStaticPath;
+}
+/**
+ * Run a toolchain binary with an argument array (never a shell string) and
+ * return its stdout. A non-zero exit throws with the stderr tail — ffmpeg
+ * writes its diagnostics there.
+ */
+export async function runToolchainBinary(binaryPath, commandArguments) {
+    try {
+        const { stdout } = await promisify(execFile)(binaryPath, commandArguments, {
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024
+        });
+        return stdout;
+    }
+    catch (cause) {
+        const failure = cause;
+        const diagnostics = (failure.stderr ?? failure.message)
+            .trim()
+            .split('\n')
+            .slice(-12)
+            .join('\n');
+        throw new Error(`${basename(binaryPath)} exited with code ${failure.code ?? 'unknown'}:\n${diagnostics}`);
+    }
+}

package/dist/server/processing/image-processing.d.ts

@@ -0,0 +1,16 @@
+import type { ImagePreset } from '../../core/index.js';
+export interface ImageProcessingOutput {
+    width: number;
+    height: number;
+}
+export declare function processImageFile(options: {
+    sourcePath: string;
+    targetPath: string;
+    preset: ImagePreset;
+    targetWidth?: number;
+}): Promise<ImageProcessingOutput>;
+/** Pixel dimensions of an existing image file (for already-fresh proxies). */
+export declare function readImageDimensions(filePath: string): Promise<{
+    width: number;
+    height: number;
+}>;

package/dist/server/processing/image-processing.js

@@ -0,0 +1,26 @@
+/**
+ * The sharp step shared by the image and slice plugins: optional resize to a
+ * target width, format conversion per preset, write the proxy file. Returns
+ * the delivered (post-resize) dimensions.
+ */
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import sharp from 'sharp';
+export async function processImageFile(options) {
+    await mkdir(dirname(options.targetPath), { recursive: true });
+    let pipeline = sharp(options.sourcePath);
+    if (options.targetWidth !== undefined) {
+        pipeline = pipeline.resize({ width: options.targetWidth });
+    }
+    pipeline = pipeline.toFormat(options.preset.format, options.preset.quality !== undefined ? { quality: options.preset.quality } : {});
+    const info = await pipeline.toFile(options.targetPath);
+    return { width: info.width, height: info.height };
+}
+/** Pixel dimensions of an existing image file (for already-fresh proxies). */
+export async function readImageDimensions(filePath) {
+    const metadata = await sharp(filePath).metadata();
+    if (typeof metadata.width !== 'number' || typeof metadata.height !== 'number') {
+        throw new Error(`Could not read image dimensions of ${filePath}.`);
+    }
+    return { width: metadata.width, height: metadata.height };
+}

package/dist/server/processing/media-probe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ffprobe wrapper: intrinsic dimensions (video streams) and duration of a
+ * media file — the metadata the manifest entries and the editor's output info
+ * carry (`VideoManifestEntry.width/height/durationMs`, `AudioManifestEntry.durationMs`).
+ */
+import type { ResolvedFundusConfig } from '../config-loader.js';
+export interface MediaProbeResult {
+    /** Present when the file has a video stream. */
+    width?: number;
+    height?: number;
+    durationMs: number;
+}
+/** Parse ffprobe's JSON output (pure, testable without a binary). */
+export declare function parseProbeOutput(json: string, filePath: string): MediaProbeResult;
+export declare function probeMedia(filePath: string, config: ResolvedFundusConfig): Promise<MediaProbeResult>;

package/dist/server/processing/media-probe.js

@@ -0,0 +1,27 @@
+import { ffprobeBinaryPath, runToolchainBinary } from './ffmpeg.js';
+/** Parse ffprobe's JSON output (pure, testable without a binary). */
+export function parseProbeOutput(json, filePath) {
+    const output = JSON.parse(json);
+    const videoStream = output.streams?.find((stream) => stream.codec_type === 'video' && stream.width && stream.height);
+    // Container duration first; some formats only report it per stream.
+    const durationSeconds = Number(output.format?.duration ?? output.streams?.find((stream) => stream.duration)?.duration);
+    if (!Number.isFinite(durationSeconds)) {
+        throw new Error(`Could not read the media duration of ${filePath}.`);
+    }
+    return {
+        ...(videoStream ? { width: videoStream.width, height: videoStream.height } : {}),
+        durationMs: Math.round(durationSeconds * 1000)
+    };
+}
+export async function probeMedia(filePath, config) {
+    const json = await runToolchainBinary(ffprobeBinaryPath(config), [
+        '-v',
+        'error',
+        '-show_entries',
+        'stream=codec_type,width,height,duration:format=duration',
+        '-of',
+        'json',
+        filePath
+    ]);
+    return parseProbeOutput(json, filePath);
+}

package/dist/server/processing/processor.d.ts

@@ -0,0 +1,50 @@
+import { type AssetId, type AssetRecord, type Library } from '../../core/index.js';
+import type { ResolvedFundusConfig } from '../config-loader.js';
+import type { AssetProxyInfo, ProxyOutputInfo, ServerPluginRegistry } from '../plugins/contract.js';
+export type { AssetProxyInfo, ProxyOutputInfo } from '../plugins/contract.js';
+/** Whether a file name in the proxy directory is (shaped like) a fundus proxy. */
+export declare function isProxyFileName(fileName: string): boolean;
+/** Whether a shaped proxy file belongs to one specific asset id. */
+export declare function isProxyFileNameFor(assetId: string, fileName: string): boolean;
+export interface ProcessingReport {
+    /** Asset ids whose proxy was (re)generated in this run. */
+    processed: string[];
+    /** Asset ids whose proxy was already current (name check hit). */
+    reused: string[];
+    /** Orphaned proxy file names removed from the proxy directory. */
+    pruned: string[];
+    /** Per delivered asset: the current proxy and its output metadata. */
+    proxies: Record<string, AssetProxyInfo>;
+}
+/**
+ * The proxy file name an asset's current raw content + parameters demand.
+ * Throws when the parameters are invalid or reference an unknown preset.
+ *
+ * The hash input is the *effective* processing input: the asset's
+ * processing-relevant parameters (the plugin-declared subset — entry-only data
+ * like chroma-key tuning and references must not rename the proxy)
+ * plus the preset's **resolved settings** — parameters only carry the preset
+ * *name*, so hashing them alone would keep serving stale proxy bytes after a
+ * preset's quality/format is edited in the host config.
+ */
+export declare function expectedProxyFileName(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): string;
+/** Expected proxy path relative to proxyDir, mirroring the raw asset folder. */
+export declare function expectedProxyRelativePath(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): string;
+/**
+ * Output metadata of an existing proxy file, probed per the owning plugin's
+ * strategy: image-backed proxies via sharp, media proxies via ffprobe.
+ */
+export declare function readProxyOutputInfo(type: string, proxyPath: string, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): Promise<ProxyOutputInfo>;
+/** Read one asset's current proxy projection, or null when its expected file is absent. */
+export declare function readCurrentProxy(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): Promise<AssetProxyInfo | null>;
+/**
+ * The delivered set: every explicit or passive member of ≥ 1 manifest —
+ * derived by the shared membership computation. Assets outside
+ * it are inert.
+ */
+export declare function deliveredAssetIds(library: Library, registry?: ServerPluginRegistry): Set<AssetId>;
+/**
+ * Ensure every delivered asset's proxy exists (processing stale/missing ones)
+ * and prune orphans. Assets outside the delivered set are skipped entirely.
+ */
+export declare function processAssets(config: ResolvedFundusConfig, library: Library, registry?: ServerPluginRegistry): Promise<ProcessingReport>;