fundus 0.0.2 → 0.0.4

package/dist/core/plugins/audio.js

@@ -0,0 +1,44 @@
+/** Built-in presets, always available; host config merges over them. */
+export const AUDIO_BUILT_IN_PRESETS = {
+    default: { codec: 'opus', bitrateKbps: 96, container: 'webm' }
+};
+/** Each codec's muxable container — a mismatch is a config error, not an ffmpeg one. */
+const CONTAINER_BY_CODEC = {
+    opus: 'webm',
+    aac: 'm4a'
+};
+export function validateAudioPreset(name, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Audio preset "${name}" must be an object.`);
+    }
+    const record = value;
+    if (record.codec !== 'opus' && record.codec !== 'aac') {
+        throw new Error(`Audio preset "${name}" needs a "codec" of 'opus' | 'aac'.`);
+    }
+    if (typeof record.bitrateKbps !== 'number' ||
+        !Number.isInteger(record.bitrateKbps) ||
+        record.bitrateKbps <= 0) {
+        throw new Error(`Audio preset "${name}" needs a positive integer "bitrateKbps".`);
+    }
+    const expectedContainer = CONTAINER_BY_CODEC[record.codec];
+    if (record.container !== expectedContainer) {
+        throw new Error(`Audio preset "${name}": codec '${record.codec}' requires container '${expectedContainer}'.`);
+    }
+    return { codec: record.codec, bitrateKbps: record.bitrateKbps, container: expectedContainer };
+}
+export const AUDIO_EXTENSIONS = ['mp3', 'wav', 'm4a', 'ogg', 'flac'];
+export const audioPlugin = {
+    type: 'audio',
+    accepts: [...AUDIO_EXTENSIONS],
+    defaultParameters: () => ({ preset: 'default' }),
+    validateParameters(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error('Audio parameters must be an object.');
+        }
+        const record = value;
+        if (typeof record.preset !== 'string' || record.preset.length === 0) {
+            throw new Error('Audio parameters need a non-empty string "preset".');
+        }
+        return { preset: record.preset };
+    }
+};

package/dist/core/plugins/chroma-key-video.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Chroma-key-video plugin (core part): a greenscreen video delivered through
+ * the video plugin's transcode pipeline, plus the keying data the runtime's
+ * WebGL renderer needs — chroma-key parameters and two optional image
+ * references: a grayscale shape `mask` multiplied onto the keyed
+ * alpha, and a static `fallback` image shown when WebGL2 is unavailable.
+ *
+ * The keying values and references are entry-only data: they travel into the
+ * generated manifest entry but never touch the ffmpeg job, so
+ * `processingParameters` narrows the job-hash input to the transcode inputs
+ * (preset + maxWidth) — retuning a slider must not re-transcode the proxy.
+ */
+import { type AssetReference } from '../asset-reference.js';
+import type { ChromaKeyParameters } from '../chroma-key.js';
+import type { AssetTypePluginDescriptor } from './contract.js';
+import type { VideoParameters, VideoPluginConfig } from './video.js';
+export interface ChromaKeyVideoParameters extends VideoParameters {
+    chromaKey: ChromaKeyParameters;
+    /** Grayscale shape mask multiplied onto the keyed alpha (an `image` asset). */
+    mask?: AssetReference;
+    /** Static image rendered when WebGL2 is unavailable (an `image` asset). */
+    fallback?: AssetReference;
+}
+/**
+ * Shares the video plugin's preset namespace (chroma-key-video builds
+ * on video's processing) — it has no config namespace of its own in M3.
+ */
+export type ChromaKeyVideoPluginConfig = VideoPluginConfig;
+export declare const chromaKeyVideoPlugin: AssetTypePluginDescriptor<ChromaKeyVideoParameters, ChromaKeyVideoPluginConfig>;

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

@@ -0,0 +1,69 @@
+/**
+ * Chroma-key-video plugin (core part): a greenscreen video delivered through
+ * the video plugin's transcode pipeline, plus the keying data the runtime's
+ * WebGL renderer needs — chroma-key parameters and two optional image
+ * references: a grayscale shape `mask` multiplied onto the keyed
+ * alpha, and a static `fallback` image shown when WebGL2 is unavailable.
+ *
+ * The keying values and references are entry-only data: they travel into the
+ * generated manifest entry but never touch the ffmpeg job, so
+ * `processingParameters` narrows the job-hash input to the transcode inputs
+ * (preset + maxWidth) — retuning a slider must not re-transcode the proxy.
+ */
+import { isAssetReference } from '../asset-reference.js';
+import { validateChromaKeyParameters, DEFAULT_CHROMA_KEY_PARAMETERS } from '../chroma-key.js';
+import { validateVideoParameters, VIDEO_EXTENSIONS } from './video.js';
+function validateOptionalReference(label, value) {
+    if (value === undefined)
+        return undefined;
+    if (!isAssetReference(value)) {
+        throw new Error(`"${label}" must be an asset reference ({ "$asset": "<id>" }).`);
+    }
+    return { $asset: value.$asset };
+}
+export const chromaKeyVideoPlugin = {
+    type: 'chroma-key-video',
+    accepts: [...VIDEO_EXTENSIONS],
+    defaultParameters: () => ({
+        preset: 'default',
+        chromaKey: {
+            ...DEFAULT_CHROMA_KEY_PARAMETERS,
+            keyColor: [...DEFAULT_CHROMA_KEY_PARAMETERS.keyColor]
+        }
+    }),
+    validateParameters(value) {
+        const videoParameters = validateVideoParameters('Chroma-key-video', value);
+        const record = value;
+        const chromaKey = validateChromaKeyParameters(record.chromaKey);
+        const mask = validateOptionalReference('mask', record.mask);
+        const fallback = validateOptionalReference('fallback', record.fallback);
+        return {
+            ...videoParameters,
+            chromaKey,
+            ...(mask !== undefined ? { mask } : {}),
+            ...(fallback !== undefined ? { fallback } : {})
+        };
+    },
+    collectReferences(parameters) {
+        const references = [];
+        if (parameters.mask) {
+            references.push({ field: 'mask', assetId: parameters.mask.$asset, expectedTypes: ['image'] });
+        }
+        if (parameters.fallback) {
+            references.push({
+                field: 'fallback',
+                assetId: parameters.fallback.$asset,
+                expectedTypes: ['image']
+            });
+        }
+        return references;
+    },
+    processingParameters(parameters) {
+        // Only what process() consumes: keying values and references are
+        // entry-only and must not force a re-transcode.
+        return {
+            preset: parameters.preset,
+            ...(parameters.maxWidth !== undefined ? { maxWidth: parameters.maxWidth } : {})
+        };
+    }
+};

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

@@ -0,0 +1,35 @@
+/**
+ * The core part of the type-plugin contract. A type plugin is a
+ * first-party module compiled into Fundus that fully defines one asset type;
+ * this descriptor is its environment-free part — ingestion claims, parameter
+ * defaults, and parameter validation. Server processing, editor panels, and
+ * runtime kind handlers complete the four-part contract.
+ */
+import type { CollectedReference } from '../asset-reference.js';
+export interface AssetTypePluginDescriptor<TParameters, TPluginConfig = unknown> {
+    /** Asset type key, e.g. 'image' | 'slice'. */
+    type: string;
+    /** Ingestion: lowercase file extensions (without dot) claimed by this type. */
+    accepts: string[];
+    /** Parameters a freshly ingested asset starts with. */
+    defaultParameters(pluginConfig: TPluginConfig): TParameters;
+    /** Validate an unknown parameter blob; returns the typed value or throws. */
+    validateParameters(value: unknown): TParameters;
+    /**
+     * Enumerate the asset references in a validated parameter value.
+     * A plugin that declares reference fields must list every one of them here —
+     * core and server never introspect parameter blobs to find references.
+     * Omitted = the type declares no references (image, slice).
+     */
+    collectReferences?(parameters: TParameters): CollectedReference[];
+    /**
+     * The subset of a validated parameter value the plugin's server-side
+     * `process()` actually consumes — the canonicalized form of this value feeds
+     * the job hash, so only these fields can force a reprocess.
+     * Entry-only parameters (chroma-key tuning, asset references) must be left
+     * out: they change the generated manifest entry, not the proxy bytes.
+     * Omitted = every parameter is processing-relevant (image, slice, video,
+     * audio).
+     */
+    processingParameters?(parameters: TParameters): unknown;
+}

package/dist/core/plugins/contract.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,30 @@
+/**
+ * Image plugin (core part): a raw raster image delivered as one optimized
+ * proxy. Parameters pick a named format preset (resolved against the plugin's
+ * config) and optionally a target width; omitted `targetWidth` keeps the
+ * source size (exactly one delivered variant per asset).
+ */
+import type { AssetTypePluginDescriptor } from './contract.js';
+declare const IMAGE_FORMATS: readonly ["webp", "png", "avif", "jpeg"];
+export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+export interface ImagePreset {
+    format: ImageFormat;
+    /** Encoder quality (format-dependent semantics); omitted = encoder default. */
+    quality?: number;
+}
+export interface ImagePluginConfig {
+    /** Named presets; merged over the built-in defaults. */
+    presets?: Record<string, ImagePreset>;
+}
+export interface ImageParameters {
+    /** Preset name, resolved against the plugin config's presets. */
+    preset: string;
+    /** Resize to this width (keeping aspect ratio); omitted = keep source size. */
+    targetWidth?: number;
+}
+/** Built-in presets, always available; host config merges over them. */
+export declare const IMAGE_BUILT_IN_PRESETS: Record<string, ImagePreset>;
+export declare function validateImagePreset(name: string, value: unknown): ImagePreset;
+export declare const RASTER_IMAGE_EXTENSIONS: readonly string[];
+export declare const imagePlugin: AssetTypePluginDescriptor<ImageParameters, ImagePluginConfig>;
+export {};

package/dist/core/plugins/image.js

@@ -0,0 +1,45 @@
+const IMAGE_FORMATS = ['webp', 'png', 'avif', 'jpeg'];
+/** Built-in presets, always available; host config merges over them. */
+export const IMAGE_BUILT_IN_PRESETS = {
+    default: { format: 'webp', quality: 82 }
+};
+export function validateImagePreset(name, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Image preset "${name}" must be an object.`);
+    }
+    const record = value;
+    if (typeof record.format !== 'string' ||
+        !IMAGE_FORMATS.includes(record.format)) {
+        throw new Error(`Image preset "${name}" needs a "format" of ${IMAGE_FORMATS.map((format) => `'${format}'`).join(' | ')}.`);
+    }
+    if (record.quality !== undefined && typeof record.quality !== 'number') {
+        throw new Error(`Image preset "${name}" has a non-number "quality".`);
+    }
+    return { format: record.format, quality: record.quality };
+}
+export const RASTER_IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'avif'];
+export const imagePlugin = {
+    type: 'image',
+    accepts: [...RASTER_IMAGE_EXTENSIONS],
+    defaultParameters: () => ({ preset: 'default' }),
+    validateParameters(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error('Image parameters must be an object.');
+        }
+        const record = value;
+        if (typeof record.preset !== 'string' || record.preset.length === 0) {
+            throw new Error('Image parameters need a non-empty string "preset".');
+        }
+        if (record.targetWidth !== undefined) {
+            if (typeof record.targetWidth !== 'number' ||
+                !Number.isInteger(record.targetWidth) ||
+                record.targetWidth <= 0) {
+                throw new Error('Image "targetWidth" must be a positive integer when set.');
+            }
+        }
+        return {
+            preset: record.preset,
+            ...(record.targetWidth !== undefined ? { targetWidth: record.targetWidth } : {})
+        };
+    }
+};

package/dist/core/plugins/registry.d.ts

@@ -0,0 +1,16 @@
+import type { AssetTypePluginDescriptor } from './contract.js';
+export type RegisteredPlugin = AssetTypePluginDescriptor<unknown, unknown>;
+export declare class PluginRegistry {
+    #private;
+    register(plugin: RegisteredPlugin): void;
+    has(type: string): boolean;
+    values(): RegisteredPlugin[];
+    types(): string[];
+    /**
+     * Select the environment-specific implementation for every registered
+     * plugin. Unregistered catalogue entries remain dormant; a registered
+     * plugin without the requested facet fails immediately during startup.
+     */
+    project<T>(catalogue: Readonly<Record<string, T>>, facet: string): Record<string, T>;
+}
+export declare const plugins: PluginRegistry;

package/dist/core/plugins/registry.js

@@ -0,0 +1,52 @@
+/**
+ * The composition root for Fundus asset-type plugins.
+ *
+ * A plugin is registered exactly once here. Environment-specific surfaces
+ * (server processing, editor panels, runtime handlers) keep their imports on
+ * the correct side of SvelteKit's browser/server boundary and project this
+ * registered set onto their local implementation catalogues.
+ */
+import { audioPlugin } from './audio.js';
+import { chromaKeyVideoPlugin } from './chroma-key-video.js';
+import { imagePlugin } from './image.js';
+import { slicePlugin } from './slice.js';
+import { videoPlugin } from './video.js';
+export class PluginRegistry {
+    #byType = new Map();
+    register(plugin) {
+        if (this.#byType.has(plugin.type)) {
+            throw new Error(`Plugin type "${plugin.type}" is already registered.`);
+        }
+        this.#byType.set(plugin.type, plugin);
+    }
+    has(type) {
+        return this.#byType.has(type);
+    }
+    values() {
+        return [...this.#byType.values()];
+    }
+    types() {
+        return [...this.#byType.keys()];
+    }
+    /**
+     * Select the environment-specific implementation for every registered
+     * plugin. Unregistered catalogue entries remain dormant; a registered
+     * plugin without the requested facet fails immediately during startup.
+     */
+    project(catalogue, facet) {
+        const projected = Object.create(null);
+        for (const type of this.#byType.keys()) {
+            if (!Object.hasOwn(catalogue, type)) {
+                throw new Error(`Registered plugin "${type}" has no ${facet}.`);
+            }
+            projected[type] = catalogue[type];
+        }
+        return projected;
+    }
+}
+export const plugins = new PluginRegistry();
+plugins.register(imagePlugin);
+plugins.register(slicePlugin);
+plugins.register(videoPlugin);
+plugins.register(chromaKeyVideoPlugin);
+plugins.register(audioPlugin);

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

@@ -0,0 +1,22 @@
+/**
+ * Slice plugin (core part): an image plus 9-/3-/1-slice data. Parameters carry the full slicing
+ * model (mode, insets, overdraw, pixelRatio) plus the same image output
+ * options (a format preset). No `targetWidth`: insets are authored in source
+ * pixels, so the delivered proxy keeps the source dimensions.
+ */
+import type { AssetTypePluginDescriptor } from './contract.js';
+import type { SliceInsets, SliceMode } from '../slice-data.js';
+import type { ImagePluginConfig, ImagePreset } from './image.js';
+export interface SliceParameters {
+    mode: SliceMode;
+    insets: SliceInsets;
+    pixelRatio: number;
+    overdraw?: SliceInsets;
+    /** Output format preset name, resolved against the slice plugin config's presets. */
+    preset: string;
+}
+/** Same shape as the image plugin's config: named output-format presets. */
+export type SlicePluginConfig = ImagePluginConfig;
+/** Built-in presets, always available; host config merges over them. */
+export declare const SLICE_BUILT_IN_PRESETS: Record<string, ImagePreset>;
+export declare const slicePlugin: AssetTypePluginDescriptor<SliceParameters, SlicePluginConfig>;

package/dist/core/plugins/slice.js

@@ -0,0 +1,60 @@
+import { createZeroInsets, SLICE_MODES } from '../slice-data.js';
+import { RASTER_IMAGE_EXTENSIONS } from './image.js';
+/** Built-in presets, always available; host config merges over them. */
+// Deliberately separate from image presets: each namespace feeds its own job hash.
+export const SLICE_BUILT_IN_PRESETS = {
+    default: { format: 'webp', quality: 82 }
+};
+function validateInsets(label, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Slice ${label} must be an object with top/right/bottom/left.`);
+    }
+    const record = value;
+    const sides = ['top', 'right', 'bottom', 'left'];
+    const result = createZeroInsets();
+    for (const side of sides) {
+        const sideValue = record[side];
+        if (typeof sideValue !== 'number' || !Number.isInteger(sideValue) || sideValue < 0) {
+            throw new Error(`Slice ${label}.${side} must be a non-negative integer.`);
+        }
+        result[side] = sideValue;
+    }
+    return result;
+}
+export const slicePlugin = {
+    type: 'slice',
+    accepts: [...RASTER_IMAGE_EXTENSIONS],
+    defaultParameters: () => ({
+        mode: 'nine',
+        insets: createZeroInsets(),
+        pixelRatio: 1,
+        preset: 'default'
+    }),
+    validateParameters(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error('Slice parameters must be an object.');
+        }
+        const record = value;
+        if (typeof record.mode !== 'string' ||
+            !SLICE_MODES.includes(record.mode)) {
+            throw new Error(`Slice "mode" must be one of ${SLICE_MODES.map((mode) => `'${mode}'`).join(' | ')}.`);
+        }
+        const insets = validateInsets('insets', record.insets);
+        if (typeof record.pixelRatio !== 'number' ||
+            !Number.isInteger(record.pixelRatio) ||
+            record.pixelRatio < 1) {
+            throw new Error('Slice "pixelRatio" must be an integer ≥ 1.');
+        }
+        const overdraw = record.overdraw === undefined ? undefined : validateInsets('overdraw', record.overdraw);
+        if (typeof record.preset !== 'string' || record.preset.length === 0) {
+            throw new Error('Slice parameters need a non-empty string "preset".');
+        }
+        return {
+            mode: record.mode,
+            insets,
+            pixelRatio: record.pixelRatio,
+            ...(overdraw !== undefined ? { overdraw } : {}),
+            preset: record.preset
+        };
+    }
+};

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

@@ -0,0 +1,45 @@
+/**
+ * Video plugin (core part): a raw video delivered as one universally playable
+ * H.264 MP4 proxy (one variant per asset, with no per-platform splits in
+ * v1). Parameters pick a named encoding preset (resolved against the plugin's
+ * config) and optionally a downscale-only width cap; omitted `maxWidth` keeps
+ * the source resolution.
+ */
+import type { AssetTypePluginDescriptor } from './contract.js';
+export interface VideoPreset {
+    codec: 'h264';
+    /** x264 constant rate factor (quality; lower = better/larger). */
+    crf: number;
+    /** x264 speed/efficiency preset (`-preset`), e.g. 'slow'. */
+    encoderPreset: string;
+    /** x264 content tuning (`-tune`), e.g. 'animation'; omitted = none. */
+    tune?: string;
+    /** Output pixel format (`-pix_fmt`), e.g. 'yuv420p'. */
+    pixelFormat: string;
+    container: 'mp4';
+}
+export interface VideoPluginConfig {
+    /** Named presets; merged over the built-in defaults. */
+    presets?: Record<string, VideoPreset>;
+    /** Absolute path of a system ffmpeg binary; omitted = the bundled `ffmpeg-static`. */
+    ffmpegPath?: string;
+    /** Absolute path of a system ffprobe binary; omitted = the bundled `ffprobe-static`. */
+    ffprobePath?: string;
+}
+export interface VideoParameters {
+    /** Preset name, resolved against the video plugin config's presets. */
+    preset: string;
+    /** Downscale-only width cap (keeping aspect ratio); omitted = source resolution. */
+    maxWidth?: number;
+}
+/**
+ * Built-in presets, always available; host config merges over them. The
+ * default is the proven committed-video formula: H.264, slow preset, animation
+ * tune, CRF 28, yuv420p, faststart MP4.
+ */
+export declare const VIDEO_BUILT_IN_PRESETS: Record<string, VideoPreset>;
+export declare function validateVideoPreset(name: string, value: unknown): VideoPreset;
+export declare const VIDEO_EXTENSIONS: readonly string[];
+/** Shared by the video and chroma-key-video plugins (identical transcode inputs). */
+export declare function validateVideoParameters(label: string, value: unknown): VideoParameters;
+export declare const videoPlugin: AssetTypePluginDescriptor<VideoParameters, VideoPluginConfig>;

package/dist/core/plugins/video.js

@@ -0,0 +1,77 @@
+/**
+ * Built-in presets, always available; host config merges over them. The
+ * default is the proven committed-video formula: H.264, slow preset, animation
+ * tune, CRF 28, yuv420p, faststart MP4.
+ */
+export const VIDEO_BUILT_IN_PRESETS = {
+    default: {
+        codec: 'h264',
+        crf: 28,
+        encoderPreset: 'slow',
+        tune: 'animation',
+        pixelFormat: 'yuv420p',
+        container: 'mp4'
+    }
+};
+export function validateVideoPreset(name, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Video preset "${name}" must be an object.`);
+    }
+    const record = value;
+    if (record.codec !== 'h264') {
+        throw new Error(`Video preset "${name}" needs a "codec" of 'h264'.`);
+    }
+    if (typeof record.crf !== 'number' || !Number.isInteger(record.crf) || record.crf < 0) {
+        throw new Error(`Video preset "${name}" needs an integer "crf" ≥ 0.`);
+    }
+    if (typeof record.encoderPreset !== 'string' || record.encoderPreset.length === 0) {
+        throw new Error(`Video preset "${name}" needs a non-empty string "encoderPreset".`);
+    }
+    if (record.tune !== undefined && (typeof record.tune !== 'string' || record.tune.length === 0)) {
+        throw new Error(`Video preset "${name}" has a non-string "tune".`);
+    }
+    if (typeof record.pixelFormat !== 'string' || record.pixelFormat.length === 0) {
+        throw new Error(`Video preset "${name}" needs a non-empty string "pixelFormat".`);
+    }
+    if (record.container !== 'mp4') {
+        throw new Error(`Video preset "${name}" needs a "container" of 'mp4'.`);
+    }
+    return {
+        codec: 'h264',
+        crf: record.crf,
+        encoderPreset: record.encoderPreset,
+        ...(record.tune !== undefined ? { tune: record.tune } : {}),
+        pixelFormat: record.pixelFormat,
+        container: 'mp4'
+    };
+}
+export const VIDEO_EXTENSIONS = ['mp4', 'mov', 'webm', 'm4v'];
+/** Shared by the video and chroma-key-video plugins (identical transcode inputs). */
+export function validateVideoParameters(label, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${label} parameters must be an object.`);
+    }
+    const record = value;
+    if (typeof record.preset !== 'string' || record.preset.length === 0) {
+        throw new Error(`${label} parameters need a non-empty string "preset".`);
+    }
+    if (record.maxWidth !== undefined) {
+        if (typeof record.maxWidth !== 'number' ||
+            !Number.isInteger(record.maxWidth) ||
+            record.maxWidth <= 0) {
+            throw new Error(`${label} "maxWidth" must be a positive integer when set.`);
+        }
+    }
+    return {
+        preset: record.preset,
+        ...(record.maxWidth !== undefined ? { maxWidth: record.maxWidth } : {})
+    };
+}
+export const videoPlugin = {
+    type: 'video',
+    accepts: [...VIDEO_EXTENSIONS],
+    defaultParameters: () => ({ preset: 'default' }),
+    validateParameters(value) {
+        return validateVideoParameters('Video', value);
+    }
+};

package/dist/core/reference-graph.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure functions over the reference graph: references form a
+ * directed acyclic graph — cycles, dangling targets, and type mismatches are
+ * validation *errors*; a closure that leaks out of a manifest is simply
+ * passive membership (`manifest-membership.ts`), not a problem. Everything
+ * here operates on a `Library` plus the per-asset references the plugins
+ * enumerated (`collectAllReferences`) — no fs, no plugin introspection.
+ */
+import type { CollectedReference } from './asset-reference.js';
+import type { AssetId, Library } from './library.js';
+import type { ValidationIssueDto } from './api-types.js';
+import type { AssetTypePluginDescriptor } from './plugins/contract.js';
+/** The plugin registry shape shared by server and tests: type → descriptor. */
+export type PluginDescriptorRegistry = Record<string, AssetTypePluginDescriptor<unknown, unknown>>;
+/** Per-asset outgoing references, keyed by asset id (every asset gets a key). */
+export type ReferencesByAsset = Record<AssetId, CollectedReference[]>;
+/**
+ * Ask each asset's owning plugin for the references in its parameters. Assets
+ * whose type is unknown or whose parameters do not validate contribute no
+ * references — those problems are reported by the regular validation pass.
+ */
+export declare function collectAllReferences(library: Library, plugins: PluginDescriptorRegistry): ReferencesByAsset;
+/**
+ * Reference *errors* (they block build/codegen): a reference to an unknown
+ * asset, a target whose type is not among the field's expected types, and
+ * cycles (composition is acyclic by nature).
+ */
+export declare function referenceErrors(library: Library, referencesByAsset: ReferencesByAsset): ValidationIssueDto[];
+/**
+ * The transitive reference closure of a set of assets, including the starting
+ * set — the assets that must be delivered so the starting set renders as
+ * authored. Tolerates cycles and ignores dangling targets (both are reported
+ * as errors by `referenceErrors`).
+ */
+export declare function referenceClosure(assetIds: Iterable<AssetId>, referencesByAsset: ReferencesByAsset): Set<AssetId>;
+/**
+ * A dependencies-first order over `assetIds` and everything they transitively
+ * reference — the build order that lets each entry inline its references from
+ * already-built entries. Throws on a cycle (with the cycle path).
+ */
+export declare function topologicalReferenceOrder(assetIds: Iterable<AssetId>, referencesByAsset: ReferencesByAsset): AssetId[];