fundus 0.0.3 → 0.1.0

package/dist/server/cli-commands.js

@@ -202,6 +202,7 @@ Subcommands:
   list      list assets (--manifest, --type, --warnings-only)
   show      one asset in detail
   ingest    copy a file into the raw dir as a typed asset
+  replace   replace an asset's raw file while preserving its metadata
   set       merge parameters and/or replace manifest membership
   rename    rename an asset id
   move      move an asset to a folder or root
@@ -285,6 +286,22 @@ Example:
   fundus asset ingest ./exports/navigation_panel@2x.png --type slice \\
     --manifests mainCatalog --json
 `;
+export const ASSET_REPLACE_HELP = `fundus asset replace — replace an asset's raw file
+
+Usage: fundus asset replace <id> <file> [--json]
+
+Replaces the stored raw file and content hash while preserving the asset's
+id, type, folder, parameters, references, and manifest memberships. The new
+file must have an extension accepted by the existing asset type. Runs the full
+autosave chain, so delivered assets are reprocessed and manifests regenerated.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json
+`;
 export const ASSET_SET_HELP = `fundus asset set — update an asset's parameters and/or memberships
 
 Usage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>] [--json]
@@ -368,6 +385,7 @@ const ASSET_SUBCOMMAND_HELP = {
     list: ASSET_LIST_HELP,
     show: ASSET_SHOW_HELP,
     ingest: ASSET_INGEST_HELP,
+    replace: ASSET_REPLACE_HELP,
     set: ASSET_SET_HELP,
     rename: ASSET_RENAME_HELP,
     move: ASSET_MOVE_HELP,
@@ -490,6 +508,27 @@ async function runAssetIngest(argumentList) {
     }
     printMutationResult(`Ingested "${fileName}" as ${type} asset "${id}".`, asset, state);
 }
+async function runAssetReplace(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset replace');
+    const [id, filePath] = requirePositionals(parsed, ['<id>', '<file>'], 'fundus asset replace');
+    const absolutePath = resolve(process.cwd(), filePath);
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(absolutePath));
+    }
+    catch {
+        throw new Error(`Cannot read file "${filePath}".`);
+    }
+    const fileName = basename(absolutePath);
+    const operations = await createOperations();
+    const state = await operations.replaceRawFile(id, { fileName, bytes });
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Replaced raw file for asset "${id}" with "${fileName}".`, asset, state);
+}
 async function runAssetSet(argumentList) {
     const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, parameters: { takesValue: true }, manifests: { takesValue: true } }, 'fundus asset set');
     const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset set');
@@ -554,7 +593,7 @@ export async function runAssetCommand(argumentList) {
     if (subcommand === undefined || subcommand === '--help') {
         console.log(ASSET_HELP);
         if (subcommand === undefined) {
-            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, set, rename, move, delete.');
+            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, replace, set, rename, move, delete.');
         }
         return;
     }
@@ -570,6 +609,8 @@ export async function runAssetCommand(argumentList) {
             return runAssetShow(rest);
         case 'ingest':
             return runAssetIngest(rest);
+        case 'replace':
+            return runAssetReplace(rest);
         case 'set':
             return runAssetSet(rest);
         case 'rename':

package/dist/server/cli-init.d.ts

@@ -1,3 +1,3 @@
 export declare const FUNDUS_CONFIG_TEMPLATE = "import { defineConfig } from 'fundus/config';\n\nexport default defineConfig({\n\trawDir: './assets/raw',\n\tproxyDir: './static/fundus',\n\tproxyBasePath: '/fundus/',\n\tlibrary: './assets/fundus.library.json',\n\tmanifestsDir: './src/lib/fundus'\n});\n";
-export declare const INIT_HELP = "fundus init \u2014 create a Fundus configuration file\n\nUsage: fundus init [--json]\n\nCreates a template fundus.config.ts in the current directory. The command\nrefuses to overwrite an existing configuration file.\n\nFlags:\n  --json   print {\"ok\": true, \"path\": \"fundus.config.ts\"} on stdout\n  --help   this help\n\nExample:\n  cd my-host-app && npx fundus init\n";
+export declare const INIT_HELP = "fundus init \u2014 create a Fundus configuration file\n\nUsage: fundus init [--json]\n\nCreates a template fundus.config.ts and a library with a default \"main\"\nmanifest in the current directory. The command refuses to initialize a project\nthat already has a Fundus configuration file.\n\nFlags:\n  --json   print {\"ok\": true, \"path\": \"fundus.config.ts\"} on stdout\n  --help   this help\n\nExample:\n  cd my-host-app && npx fundus init\n";
 export declare function runInitCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-init.js

@@ -1,5 +1,6 @@
-import { writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { mkdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createEmptyLibrary, serializeLibrary } from '../core/index.js';
 import { parseArguments, printJsonDocument, requirePositionals } from './cli-io.js';
 export const FUNDUS_CONFIG_TEMPLATE = `import { defineConfig } from 'fundus/config';
 
@@ -15,8 +16,9 @@ export const INIT_HELP = `fundus init — create a Fundus configuration file
 
 Usage: fundus init [--json]
 
-Creates a template fundus.config.ts in the current directory. The command
-refuses to overwrite an existing configuration file.
+Creates a template fundus.config.ts and a library with a default "main"
+manifest in the current directory. The command refuses to initialize a project
+that already has a Fundus configuration file.
 
 Flags:
   --json   print {"ok": true, "path": "fundus.config.ts"} on stdout
@@ -45,9 +47,25 @@ export async function runInitCommand(argumentList) {
         }
         throw new Error(`Cannot create fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
+    const libraryPath = resolve(process.cwd(), 'assets/fundus.library.json');
+    const library = createEmptyLibrary();
+    library.manifests.main = {};
+    try {
+        await mkdir(dirname(libraryPath), { recursive: true });
+        await writeFile(libraryPath, serializeLibrary(library), { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (cause) {
+        // The config was created by this invocation. Remove it so a failed
+        // library scaffold does not make the project look initialized.
+        await unlink(configPath).catch(() => { });
+        if (cause.code === 'EEXIST') {
+            throw new Error(`assets/fundus.library.json already exists in ${process.cwd()}.`);
+        }
+        throw new Error(`Cannot create assets/fundus.library.json: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
     if (parsed.flags.json) {
         printJsonDocument({ ok: true, path: 'fundus.config.ts' });
         return;
     }
-    console.log('Created fundus.config.ts.');
+    console.log('Created fundus.config.ts and default "main" manifest.');
 }

package/dist/server/config-loader.d.ts

@@ -1,4 +1,5 @@
-import { type AudioPreset, type ImagePreset, type VideoPreset } from '../core/index.js';
+import type { AudioPreset, ImagePreset, VideoPreset } from '../core/index.js';
+import type { ServerPluginRegistry } from './plugins/contract.js';
 export interface ResolvedPresetPluginConfig {
     presets: Record<string, ImagePreset>;
 }
@@ -29,6 +30,6 @@ export interface ResolvedFundusConfig {
     };
 }
 /** Pure resolution step (testable without a config file on disk). */
-export declare function resolveConfig(projectRoot: string, value: unknown): ResolvedFundusConfig;
+export declare function resolveConfig(projectRoot: string, value: unknown, registry?: ServerPluginRegistry): ResolvedFundusConfig;
 /** Load `fundus.config.ts` from the host project root. */
 export declare function loadConfig(projectRoot: string): Promise<ResolvedFundusConfig>;

package/dist/server/config-loader.js

@@ -4,12 +4,10 @@
  * absolute, and merges the built-in plugin preset defaults under the host's.
  */
 import { existsSync } from 'node:fs';
-import { isAbsolute, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { createJiti } from 'jiti';
-import { AUDIO_BUILT_IN_PRESETS, IMAGE_BUILT_IN_PRESETS, SLICE_BUILT_IN_PRESETS, VIDEO_BUILT_IN_PRESETS, validateAudioPreset, validateImagePreset, validateVideoPreset } from '../core/index.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import { serverPluginsByType } from './plugins.js';
+import { isRecord } from './plugins/config.js';
 function requiredString(config, key) {
     const value = config[key];
     if (typeof value !== 'string' || value.length === 0) {
@@ -18,37 +16,23 @@ function requiredString(config, key) {
     return value;
 }
 function resolvePath(projectRoot, value) {
-    return isAbsolute(value) ? value : resolve(projectRoot, value);
-}
-function mergePresets(label, builtIn, pluginConfig, validatePreset) {
-    const merged = { ...builtIn };
-    if (pluginConfig === undefined)
-        return merged;
-    if (!isRecord(pluginConfig)) {
-        throw new Error(`fundus.config: "plugins.${label}" must be an object.`);
-    }
-    if (pluginConfig.presets === undefined)
-        return merged;
-    if (!isRecord(pluginConfig.presets)) {
-        throw new Error(`fundus.config: "plugins.${label}.presets" must be an object.`);
-    }
-    for (const [name, preset] of Object.entries(pluginConfig.presets)) {
-        merged[name] = validatePreset(name, preset);
-    }
-    return merged;
+    return resolve(projectRoot, value);
 }
-/** `plugins.video.ffmpegPath` / `ffprobePath`: optional system-binary overrides. */
-function binaryPathOverride(projectRoot, pluginConfig, key) {
-    if (!isRecord(pluginConfig) || pluginConfig[key] === undefined)
-        return null;
-    const value = pluginConfig[key];
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new Error(`fundus.config: "plugins.video.${key}" must be a non-empty string.`);
+function configDefinitionsFor(registry) {
+    const byNamespace = new Map();
+    for (const plugin of Object.values(registry)) {
+        for (const definition of plugin.configDefinitions) {
+            const existing = byNamespace.get(definition.namespace);
+            if (existing && existing !== definition) {
+                throw new Error(`Plugins provide conflicting config definitions for "plugins.${definition.namespace}".`);
+            }
+            byNamespace.set(definition.namespace, definition);
+        }
     }
-    return resolvePath(projectRoot, value);
+    return [...byNamespace.values()];
 }
 /** Pure resolution step (testable without a config file on disk). */
-export function resolveConfig(projectRoot, value) {
+export function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
     if (!isRecord(value)) {
         throw new Error('fundus.config must default-export a configuration object.');
     }
@@ -60,28 +44,20 @@ export function resolveConfig(projectRoot, value) {
     if (!isRecord(plugins)) {
         throw new Error('fundus.config: "plugins" must be an object.');
     }
+    const resolvedPlugins = {};
+    for (const definition of configDefinitionsFor(registry)) {
+        resolvedPlugins[definition.namespace] = definition.resolve({
+            projectRoot,
+            value: plugins[definition.namespace]
+        });
+    }
     return {
         rawDir: resolvePath(projectRoot, requiredString(value, 'rawDir')),
         proxyDir: resolvePath(projectRoot, requiredString(value, 'proxyDir')),
         library: resolvePath(projectRoot, requiredString(value, 'library')),
         manifestsDir: resolvePath(projectRoot, requiredString(value, 'manifestsDir')),
         proxyBasePath,
-        plugins: {
-            image: {
-                presets: mergePresets('image', IMAGE_BUILT_IN_PRESETS, plugins.image, validateImagePreset)
-            },
-            slice: {
-                presets: mergePresets('slice', SLICE_BUILT_IN_PRESETS, plugins.slice, validateImagePreset)
-            },
-            video: {
-                presets: mergePresets('video', VIDEO_BUILT_IN_PRESETS, plugins.video, validateVideoPreset),
-                ffmpegPath: binaryPathOverride(projectRoot, plugins.video, 'ffmpegPath'),
-                ffprobePath: binaryPathOverride(projectRoot, plugins.video, 'ffprobePath')
-            },
-            audio: {
-                presets: mergePresets('audio', AUDIO_BUILT_IN_PRESETS, plugins.audio, validateAudioPreset)
-            }
-        }
+        plugins: resolvedPlugins
     };
 }
 /** Load `fundus.config.ts` from the host project root. */

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
 export type { ResolvedFundusConfig, ResolvedPresetPluginConfig, ResolvedVideoPluginConfig, ResolvedAudioPluginConfig } from './config-loader.js';
 export { loadConfig, resolveConfig } from './config-loader.js';
 export { LibraryStore } from './library-store.js';
-export type { IngestOptions } from './library-store.js';
+export type { IngestOptions, ReplaceRawFileOptions } from './library-store.js';
 export type { AssetProxyInfo, ProxyOutputInfo, ProcessingReport } from './processing/processor.js';
 export { processAssets, expectedProxyFileName, expectedProxyRelativePath, deliveredAssetIds, isProxyFileName, readProxyOutputInfo } from './processing/processor.js';
 export { ffmpegBinaryPath, runToolchainBinary } from './processing/ffmpeg.js';
@@ -13,4 +13,5 @@ export type { CheckFinding, CheckReport } from './check.js';
 export { formatCheckFinding, runCheck } from './check.js';
 export type { AssetChangeOptions } from './operations.js';
 export { FundusOperations } from './operations.js';
+export type { RunStartOptions } from './start.js';
 export { runStart } from './start.js';

package/dist/server/library-store.d.ts

@@ -23,6 +23,11 @@ export interface IngestOptions {
     /** Registered destination folder; empty string means the implicit root. */
     folder?: string;
 }
+export interface ReplaceRawFileOptions {
+    /** Original file name of the replacement (sanitized before storing). */
+    fileName: string;
+    bytes: Uint8Array;
+}
 export declare class LibraryStore {
     #private;
     constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry);
@@ -37,6 +42,12 @@ export declare class LibraryStore {
      * the owning plugin's default parameters. Returns the updated library.
      */
     ingest(options: IngestOptions): Promise<Library>;
+    /**
+     * Replace one asset's raw file while preserving its identity and authored
+     * metadata. The replacement stays in the current folder, receives a safe
+     * non-colliding name, and must be accepted by the asset's existing type.
+     */
+    replaceRawFile(id: string, options: ReplaceRawFileOptions): Promise<Library>;
     /** Replace an asset's parameters (validated by the owning plugin). */
     updateParameters(id: string, parameters: unknown): Promise<Library>;
     /** Replace an asset's manifest membership (every name must exist). */

package/dist/server/library-store.js

@@ -136,6 +136,63 @@ export class LibraryStore {
         await this.write(library);
         return library;
     }
+    /**
+     * Replace one asset's raw file while preserving its identity and authored
+     * metadata. The replacement stays in the current folder, receives a safe
+     * non-colliding name, and must be accepted by the asset's existing type.
+     */
+    async replaceRawFile(id, options) {
+        return this.#enqueue(() => this.#replaceRawFile(id, options));
+    }
+    async #replaceRawFile(id, options) {
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        const sanitizedName = sanitizeFileName(options.fileName);
+        const extension = extname(sanitizedName).slice(1).toLowerCase();
+        const plugin = serverPluginForType(record.type, this.#registry);
+        if (!plugin.descriptor.accepts.includes(extension)) {
+            throw new Error(`The ${record.type} type does not accept ".${extension}" files (accepts: ${plugin.descriptor.accepts.join(', ')}).`);
+        }
+        const previousRaw = record.raw;
+        const previousHash = record.rawHash;
+        const folder = folderOfRawPath(previousRaw);
+        const previousName = rawFileNameOfPath(previousRaw);
+        const storedName = sanitizedName === previousName ? previousName : this.#uniqueRawName(sanitizedName, folder);
+        const nextRaw = folder === '' ? storedName : `${folder}/${storedName}`;
+        const previousPath = join(this.#config.rawDir, previousRaw);
+        const nextPath = join(this.#config.rawDir, nextRaw);
+        const token = crypto.randomUUID();
+        const temporaryPath = join(this.#config.rawDir, folder, `.fundus-replace-${token}.tmp`);
+        const backupPath = `${previousPath}.fundus-replace-${token}`;
+        let previousStaged = false;
+        let replacementInstalled = false;
+        await mkdir(dirname(temporaryPath), { recursive: true });
+        try {
+            await writeFile(temporaryPath, options.bytes);
+            if (existsSync(previousPath)) {
+                await rename(previousPath, backupPath);
+                previousStaged = true;
+            }
+            await rename(temporaryPath, nextPath);
+            replacementInstalled = true;
+            record.raw = nextRaw;
+            record.rawHash = sha256Hex(options.bytes);
+            await this.write(library);
+        }
+        catch (cause) {
+            record.raw = previousRaw;
+            record.rawHash = previousHash;
+            if (replacementInstalled)
+                await unlink(nextPath).catch(() => { });
+            if (previousStaged)
+                await rename(backupPath, previousPath);
+            await unlink(temporaryPath).catch(() => { });
+            throw cause;
+        }
+        if (previousStaged)
+            await unlink(backupPath).catch(() => { });
+        return library;
+    }
     /** Replace an asset's parameters (validated by the owning plugin). */
     async updateParameters(id, parameters) {
         return this.#enqueue(() => this.#updateParameters(id, parameters));

package/dist/server/operations.d.ts

@@ -1,6 +1,6 @@
 import { type FundusStateDto, type PatchAssetRequestDto, type PatchManifestRequestDto } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
-import { LibraryStore, type IngestOptions } from './library-store.js';
+import { LibraryStore, type IngestOptions, type ReplaceRawFileOptions } from './library-store.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 /**
  * The CLI's `--parameters` merge semantics (M7): a SHALLOW merge at the top
@@ -37,6 +37,8 @@ export declare class FundusOperations {
     /** Apply a PATCH body: parameters and/or manifests and/or a rename — in that order. */
     patchAsset(id: string, body: PatchAssetRequestDto): Promise<FundusStateDto>;
     moveAsset(id: string, folder: string): Promise<FundusStateDto>;
+    /** Replace the raw bytes/name and run the normal processing + codegen tail. */
+    replaceRawFile(id: string, options: ReplaceRawFileOptions): Promise<FundusStateDto>;
     /** Move a selected asset set as one editor action and roll back on any failure. */
     moveAssets(assetIds: string[], folder: string): Promise<FundusStateDto>;
     createFolder(path: string): Promise<FundusStateDto>;

package/dist/server/operations.js

@@ -125,6 +125,10 @@ export class FundusOperations {
     async moveAsset(id, folder) {
         return this.#afterMutation(await this.#store.moveAsset(id, folder));
     }
+    /** Replace the raw bytes/name and run the normal processing + codegen tail. */
+    async replaceRawFile(id, options) {
+        return this.#afterMutation(await this.#store.replaceRawFile(id, options));
+    }
     /** Move a selected asset set as one editor action and roll back on any failure. */
     async moveAssets(assetIds, folder) {
         const uniqueIds = [...new Set(assetIds)];
@@ -334,7 +338,7 @@ export class FundusOperations {
                 type: record.type,
                 raw: record.raw,
                 folder: folderOfRawPath(record.raw),
-                rawUrl: `/files/raw/${encodeRelativePathForUrl(record.raw)}`,
+                rawUrl: `/files/raw/${encodeRelativePathForUrl(record.raw)}?v=${record.rawHash.slice(0, 12)}`,
                 rawHash: record.rawHash,
                 parameters: record.parameters,
                 manifests: record.manifests,

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

@@ -3,5 +3,6 @@
  * No dimensions — the proxy's only output metadata is its duration.
  */
 import { type AudioParameters, type AudioPreset } from '../../core/index.js';
-import { type ServerAssetTypePlugin } from './contract.js';
+import { type ServerAssetTypePlugin, type ServerPluginConfigDefinition } from './contract.js';
+export declare const audioConfigDefinition: ServerPluginConfigDefinition;
 export declare const audioServerPlugin: ServerAssetTypePlugin<AudioParameters, AudioPreset>;

package/dist/server/plugins/audio.js

@@ -2,12 +2,26 @@
  * Audio plugin (server part): one ffmpeg transcode per preset.
  * No dimensions — the proxy's only output metadata is its duration.
  */
-import { audioPlugin } from '../../core/index.js';
+import { AUDIO_BUILT_IN_PRESETS, audioPlugin, validateAudioPreset } from '../../core/index.js';
 import { processAudioFile } from '../processing/audio-processing.js';
 import { probeMedia } from '../processing/media-probe.js';
+import { mergePresets } from './config.js';
 import { requireProxyField, resolveNamedPreset } from './contract.js';
+import { videoConfigDefinition } from './video.js';
+export const audioConfigDefinition = {
+    namespace: 'audio',
+    resolve: ({ value }) => ({
+        presets: mergePresets({
+            label: 'audio',
+            builtIn: AUDIO_BUILT_IN_PRESETS,
+            pluginConfig: value,
+            validatePreset: validateAudioPreset
+        })
+    })
+};
 export const audioServerPlugin = {
     descriptor: audioPlugin,
+    configDefinitions: [audioConfigDefinition, videoConfigDefinition],
     pluginConfig: (config) => config.plugins.audio,
     presets: (config) => config.plugins.audio.presets,
     resolvePreset: (parameters, config) => resolveNamedPreset('audio', parameters.preset, config.plugins.audio.presets),

package/dist/server/plugins/chroma-key-video.js

@@ -8,8 +8,10 @@ import { chromaKeyVideoPlugin } from '../../core/index.js';
 import { probeMedia } from '../processing/media-probe.js';
 import { processVideoFile } from '../processing/video-processing.js';
 import { requireProxyField, resolveNamedPreset } from './contract.js';
+import { videoConfigDefinition } from './video.js';
 export const chromaKeyVideoServerPlugin = {
     descriptor: chromaKeyVideoPlugin,
+    configDefinitions: [videoConfigDefinition],
     // One preset namespace with the video plugin — the config slice,
     // the preset map, and the resolution label are video's.
     pluginConfig: (config) => config.plugins.video,

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

@@ -0,0 +1,13 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function mergePresets<TPreset>(options: {
+    label: string;
+    builtIn: Record<string, TPreset>;
+    pluginConfig: unknown;
+    validatePreset: (name: string, value: unknown) => TPreset;
+}): Record<string, TPreset>;
+export declare function binaryPathOverride(options: {
+    projectRoot: string;
+    pluginConfig: unknown;
+    label: string;
+    key: string;
+}): string | null;

package/dist/server/plugins/config.js

@@ -0,0 +1,32 @@
+import { isAbsolute, resolve } from 'node:path';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function mergePresets(options) {
+    const { label, builtIn, pluginConfig, validatePreset } = options;
+    const merged = { ...builtIn };
+    if (pluginConfig === undefined)
+        return merged;
+    if (!isRecord(pluginConfig)) {
+        throw new Error(`fundus.config: "plugins.${label}" must be an object.`);
+    }
+    if (pluginConfig.presets === undefined)
+        return merged;
+    if (!isRecord(pluginConfig.presets)) {
+        throw new Error(`fundus.config: "plugins.${label}.presets" must be an object.`);
+    }
+    for (const [name, preset] of Object.entries(pluginConfig.presets)) {
+        merged[name] = validatePreset(name, preset);
+    }
+    return merged;
+}
+export function binaryPathOverride(options) {
+    const { projectRoot, pluginConfig, label, key } = options;
+    if (!isRecord(pluginConfig) || pluginConfig[key] === undefined)
+        return null;
+    const value = pluginConfig[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`fundus.config: "plugins.${label}.${key}" must be a non-empty string.`);
+    }
+    return isAbsolute(value) ? value : resolve(projectRoot, value);
+}

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

@@ -4,8 +4,7 @@
  * 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.
+ * only the projected server registry (plugins.ts).
  */
 import type { AssetTypePluginDescriptor, ManifestEntryData } from '../../core/index.js';
 import type { ResolvedFundusConfig } from '../config-loader.js';
@@ -47,9 +46,24 @@ export interface ManifestEntryInput<TParameters> {
     src: string;
     proxy: AssetProxyInfo;
 }
+/** One host-config namespace required by a server plugin. */
+export interface ServerPluginConfigDefinition {
+    /** Key below `plugins` in fundus.config.ts. */
+    namespace: string;
+    /** Validate and resolve that namespace's host value. */
+    resolve(context: {
+        projectRoot: string;
+        value: unknown;
+    }): unknown;
+}
 export interface ServerAssetTypePlugin<TParameters = unknown, TPreset = unknown> {
     /** The environment-free half of the plugin (type key, ingestion, validation). */
     descriptor: AssetTypePluginDescriptor<TParameters, unknown>;
+    /**
+     * Config namespaces this plugin needs. Shared definitions are deduplicated
+     * by identity (video, chroma-key-video, and audio share the video toolchain).
+     */
+    configDefinitions: readonly ServerPluginConfigDefinition[];
     /**
      * The plugin's `plugins.<namespace>` config slice — handed to the
      * descriptor's `defaultParameters` on ingest. Types may share a namespace
@@ -92,7 +106,7 @@ export interface ServerAssetTypePlugin<TParameters = unknown, TPreset = unknown>
      */
     buildManifestEntry(input: ManifestEntryInput<TParameters>): ManifestEntryData;
 }
-/** The one server-side touch point for a new asset type: type key → plugin. */
+/** The server projection consumed by type-agnostic orchestrators and tests. */
 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;

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

@@ -2,7 +2,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';
+import { type ServerAssetTypePlugin, type ServerPluginConfigDefinition } from './contract.js';
+export declare const imageConfigDefinition: ServerPluginConfigDefinition;
 /** 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

@@ -1,15 +1,28 @@
 /**
  * Image plugin (server part): sharp scale + convert per preset.
  */
-import { imagePlugin } from '../../core/index.js';
+import { IMAGE_BUILT_IN_PRESETS, imagePlugin, validateImagePreset } from '../../core/index.js';
 import { processImageFile, readImageDimensions } from '../processing/image-processing.js';
+import { mergePresets } from './config.js';
 import { requireProxyField, resolveNamedPreset } from './contract.js';
+export const imageConfigDefinition = {
+    namespace: 'image',
+    resolve: ({ value }) => ({
+        presets: mergePresets({
+            label: 'image',
+            builtIn: IMAGE_BUILT_IN_PRESETS,
+            pluginConfig: value,
+            validatePreset: validateImagePreset
+        })
+    })
+};
 /** The delivered file extension of an image-preset format. */
 export function extensionForImageFormat(format) {
     return format === 'jpeg' ? 'jpg' : format;
 }
 export const imageServerPlugin = {
     descriptor: imagePlugin,
+    configDefinitions: [imageConfigDefinition],
     pluginConfig: (config) => config.plugins.image,
     presets: (config) => config.plugins.image.presets,
     resolvePreset: (parameters, config) => resolveNamedPreset('image', parameters.preset, config.plugins.image.presets),

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

@@ -4,7 +4,8 @@
  * 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';
+import { type ServerAssetTypePlugin, type ServerPluginConfigDefinition } from './contract.js';
+export declare const sliceConfigDefinition: ServerPluginConfigDefinition;
 /**
  * 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`).

package/dist/server/plugins/slice.js

@@ -3,10 +3,22 @@
  * 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 { SLICE_BUILT_IN_PRESETS, defaultInsetsForSize, slicePlugin, validateImagePreset } from '../../core/index.js';
 import { processImageFile, readImageDimensions } from '../processing/image-processing.js';
 import { extensionForImageFormat } from './image.js';
+import { mergePresets } from './config.js';
 import { requireProxyField, resolveNamedPreset } from './contract.js';
+export const sliceConfigDefinition = {
+    namespace: 'slice',
+    resolve: ({ value }) => ({
+        presets: mergePresets({
+            label: 'slice',
+            builtIn: SLICE_BUILT_IN_PRESETS,
+            pluginConfig: value,
+            validatePreset: validateImagePreset
+        })
+    })
+};
 function hasAnySide(insets) {
     if (!insets)
         return false;
@@ -24,6 +36,7 @@ export function detectPixelRatio(fileName) {
 }
 export const sliceServerPlugin = {
     descriptor: slicePlugin,
+    configDefinitions: [sliceConfigDefinition],
     pluginConfig: (config) => config.plugins.slice,
     presets: (config) => config.plugins.slice.presets,
     resolvePreset: (parameters, config) => resolveNamedPreset('slice', parameters.preset, config.plugins.slice.presets),

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

@@ -2,5 +2,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';
+import { type ServerAssetTypePlugin, type ServerPluginConfigDefinition } from './contract.js';
+export declare const videoConfigDefinition: ServerPluginConfigDefinition;
 export declare const videoServerPlugin: ServerAssetTypePlugin<VideoParameters, VideoPreset>;