fundus 0.0.2 → 0.0.3

package/dist/core/ingest.d.ts

@@ -0,0 +1,18 @@
+import type { AssetTypePluginDescriptor } from './plugins/contract.js';
+/** The built-in descriptors, in registration order (image before slice, video before chroma-key-video). */
+export declare const BUILT_IN_DESCRIPTORS: AssetTypePluginDescriptor<unknown, unknown>[];
+/** Unique HTML file-picker accept extensions derived from descriptor claims. */
+export declare function acceptedExtensions(descriptors?: AssetTypePluginDescriptor<unknown, unknown>[]): string[];
+/**
+ * Types an ingested file of this extension could become — derived from the
+ * descriptors' `accepts` claims. Raster images and video containers are
+ * ambiguous (image/slice, video/chroma-key-video) — the editor dialog prompts
+ * once, the CLI requires `--type`; audio is unambiguous.
+ */
+export declare function typesForFileName(fileName: string, descriptors?: AssetTypePluginDescriptor<unknown, unknown>[]): string[];
+/**
+ * Propose a camelCase asset id from a file name: split on non-alphanumeric
+ * runs and case boundaries, drop a `@2x`-style scale suffix, lowercase the
+ * first word, capitalize the rest, strip leading digits.
+ */
+export declare function proposeAssetId(fileName: string): string;

package/dist/core/ingest.js

@@ -0,0 +1,58 @@
+/**
+ * Ingestion helpers shared by every ingest surface: the editor's
+ * drag & drop dialog and the CLI's `asset ingest` command both resolve a
+ * dropped file name to its candidate asset types and propose an asset id the
+ * same way — one implementation, in core.
+ */
+import { audioPlugin } from './plugins/audio.js';
+import { chromaKeyVideoPlugin } from './plugins/chroma-key-video.js';
+import { imagePlugin } from './plugins/image.js';
+import { slicePlugin } from './plugins/slice.js';
+import { videoPlugin } from './plugins/video.js';
+/** The built-in descriptors, in registration order (image before slice, video before chroma-key-video). */
+export const BUILT_IN_DESCRIPTORS = [
+    imagePlugin,
+    slicePlugin,
+    videoPlugin,
+    chromaKeyVideoPlugin,
+    audioPlugin
+];
+/** Unique HTML file-picker accept extensions derived from descriptor claims. */
+export function acceptedExtensions(descriptors = BUILT_IN_DESCRIPTORS) {
+    return [...new Set(descriptors.flatMap((descriptor) => descriptor.accepts))]
+        .sort()
+        .map((extension) => `.${extension}`);
+}
+/**
+ * Types an ingested file of this extension could become — derived from the
+ * descriptors' `accepts` claims. Raster images and video containers are
+ * ambiguous (image/slice, video/chroma-key-video) — the editor dialog prompts
+ * once, the CLI requires `--type`; audio is unambiguous.
+ */
+export function typesForFileName(fileName, descriptors = BUILT_IN_DESCRIPTORS) {
+    const extension = fileName.slice(fileName.lastIndexOf('.') + 1).toLowerCase();
+    return descriptors
+        .filter((descriptor) => descriptor.accepts.includes(extension))
+        .map((descriptor) => descriptor.type);
+}
+/**
+ * Propose a camelCase asset id from a file name: split on non-alphanumeric
+ * runs and case boundaries, drop a `@2x`-style scale suffix, lowercase the
+ * first word, capitalize the rest, strip leading digits.
+ */
+export function proposeAssetId(fileName) {
+    const stem = fileName.replace(/\.[^.]+$/, '').replace(/(?:@|[-_])\dx$/i, '');
+    const words = stem
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean);
+    if (words.length === 0)
+        return 'asset';
+    const joined = words
+        .map((word, index) => index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join('');
+    const withoutLeadingDigits = joined.replace(/^[0-9]+/, '');
+    if (!withoutLeadingDigits)
+        return 'asset';
+    return withoutLeadingDigits.charAt(0).toLowerCase() + withoutLeadingDigits.slice(1);
+}

package/dist/core/library.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The library file model — the single source of truth for all asset metadata
+ * and manifest membership. One JSON file in the host repo, committed,
+ * serialized deterministically (recursively sorted keys) to minimize merge
+ * conflicts.
+ */
+export type AssetId = string;
+export type ManifestName = string;
+export interface AssetRecord {
+    /** Asset type — which plugin owns this asset ('image' | 'slice' | …). */
+    type: string;
+    /** Raw file path, relative to the configured raw directory. */
+    raw: string;
+    /** Content hash (sha256 hex) of the raw file the parameters were authored against. */
+    rawHash: string;
+    /** Plugin-owned parameter blob, validated against the owning plugin's schema. */
+    parameters: unknown;
+    /** Empty + unreferenced = inert; referenced assets still deliver as passive members. */
+    manifests: ManifestName[];
+}
+/**
+ * Per-manifest data. A delivery unit needs no metadata to function, but may
+ * carry an optional editor appearance — a color and/or an emoji — so
+ * the editor can tag the manifest's label everywhere. Both are chosen from the
+ * fixed sets in `manifest-appearance.ts` and validated at every mutation entry
+ * point; parsing only enforces that they are strings when present.
+ */
+export interface ManifestRecord {
+    /** Optional color tag — a `#rrggbb` value from the fixed palette. */
+    color?: string;
+    /** Optional emoji tag — one of the fixed emoji set. */
+    emoji?: string;
+}
+export interface Library {
+    version: 1;
+    /** Persisted nested folder paths. The raw/proxy root is implicit. */
+    folders: string[];
+    assets: Record<AssetId, AssetRecord>;
+    manifests: Record<ManifestName, ManifestRecord>;
+}
+/** A fresh, empty library. */
+export declare function createEmptyLibrary(): Library;
+/**
+ * Parse and structurally validate a library file's JSON text. Throws with a
+ * clear message on any malformed part; plugin parameter validation is a
+ * separate, plugin-owned step.
+ */
+export declare function parseLibrary(json: string): Library;
+/**
+ * Serialize a library deterministically: recursively sorted keys, tab-indented,
+ * trailing newline. Same library → byte-identical file, whatever the in-memory
+ * insertion order was.
+ */
+export declare function serializeLibrary(library: Library): string;

package/dist/core/library.js

@@ -0,0 +1,138 @@
+import { folderPathError } from './folder-path.js';
+/** A fresh, empty library. */
+export function createEmptyLibrary() {
+    return { version: 1, folders: [], assets: {}, manifests: {} };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Keys that are prototype-pollution hazards as record keys: assigning
+ * `assets["__proto__"] = …` on a plain object replaces its prototype instead
+ * of adding an entry. Rejected outright at parse time — id *validity* beyond
+ * this is a validator concern (reported as issues, not parse failures).
+ */
+const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'];
+function assertSafeKey(kind, key) {
+    if (DANGEROUS_KEYS.includes(key)) {
+        throw new Error(`Library ${kind} key "${key}" is not allowed.`);
+    }
+}
+function parseAssetRecord(id, value) {
+    if (!isRecord(value)) {
+        throw new Error(`Library asset "${id}" must be an object.`);
+    }
+    if (typeof value.type !== 'string' || value.type.length === 0) {
+        throw new Error(`Library asset "${id}" is missing a string "type".`);
+    }
+    if (typeof value.raw !== 'string' || value.raw.length === 0) {
+        throw new Error(`Library asset "${id}" is missing a string "raw" file name.`);
+    }
+    if (typeof value.rawHash !== 'string' || value.rawHash.length === 0) {
+        throw new Error(`Library asset "${id}" is missing a string "rawHash".`);
+    }
+    if (!('parameters' in value)) {
+        throw new Error(`Library asset "${id}" is missing "parameters".`);
+    }
+    if (!Array.isArray(value.manifests) ||
+        value.manifests.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`Library asset "${id}" must have a "manifests" array of strings.`);
+    }
+    return {
+        type: value.type,
+        raw: value.raw,
+        rawHash: value.rawHash,
+        parameters: value.parameters,
+        manifests: value.manifests
+    };
+}
+function parseManifestRecord(name, value) {
+    const record = {};
+    if ('color' in value && value.color !== undefined) {
+        if (typeof value.color !== 'string') {
+            throw new Error(`Library manifest "${name}" has a non-string "color".`);
+        }
+        record.color = value.color;
+    }
+    if ('emoji' in value && value.emoji !== undefined) {
+        if (typeof value.emoji !== 'string') {
+            throw new Error(`Library manifest "${name}" has a non-string "emoji".`);
+        }
+        record.emoji = value.emoji;
+    }
+    return record;
+}
+/**
+ * Parse and structurally validate a library file's JSON text. Throws with a
+ * clear message on any malformed part; plugin parameter validation is a
+ * separate, plugin-owned step.
+ */
+export function parseLibrary(json) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch (cause) {
+        throw new Error(`Library file is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (!isRecord(value)) {
+        throw new Error('Library file must contain a JSON object.');
+    }
+    if (value.version !== 1) {
+        throw new Error(`Unsupported library version ${JSON.stringify(value.version)} (expected 1).`);
+    }
+    if (!isRecord(value.assets)) {
+        throw new Error('Library "assets" must be an object.');
+    }
+    if (!isRecord(value.manifests)) {
+        throw new Error('Library "manifests" must be an object.');
+    }
+    if (value.folders !== undefined &&
+        (!Array.isArray(value.folders) || value.folders.some((entry) => typeof entry !== 'string'))) {
+        throw new Error('Library "folders" must be an array of strings.');
+    }
+    const folders = value.folders === undefined ? [] : value.folders;
+    for (const folder of folders) {
+        const problem = folderPathError(folder);
+        if (problem)
+            throw new Error(`Invalid library folder: ${problem}`);
+    }
+    const assets = {};
+    for (const [id, record] of Object.entries(value.assets)) {
+        assertSafeKey('asset', id);
+        assets[id] = parseAssetRecord(id, record);
+    }
+    const manifests = {};
+    for (const [name, record] of Object.entries(value.manifests)) {
+        assertSafeKey('manifest', name);
+        if (!isRecord(record)) {
+            throw new Error(`Library manifest "${name}" must be an object.`);
+        }
+        manifests[name] = parseManifestRecord(name, record);
+    }
+    return { version: 1, folders, assets, manifests };
+}
+/** Recursively sort object keys so serialization is order-independent. */
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (typeof value === 'object' && value !== null) {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            const entry = value[key];
+            if (entry !== undefined)
+                sorted[key] = sortValue(entry);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Serialize a library deterministically: recursively sorted keys, tab-indented,
+ * trailing newline. Same library → byte-identical file, whatever the in-memory
+ * insertion order was.
+ */
+export function serializeLibrary(library) {
+    return `${JSON.stringify(sortValue({ ...library, folders: [...library.folders].sort() }), null, '\t')}\n`;
+}

package/dist/core/manifest-appearance.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Manifest appearance: each manifest may carry a color and an emoji,
+ * chosen from these fixed sets, so the editor can tag its label everywhere and
+ * make asset↔manifest membership visually scannable. The sets are the closed
+ * palette both the editor pickers and the CLI validate against — storing a
+ * value outside them is rejected at every mutation entry point.
+ */
+/** One selectable manifest color: a stable display name and its hex value. */
+export interface ManifestColor {
+    /** Human-readable palette name (used by the CLI's `--color <name|hex>`). */
+    name: string;
+    /** The stored value — a lowercase `#rrggbb` hex string. */
+    value: string;
+}
+/**
+ * The fixed color palette. Values are the SSOT stored in the library; names are
+ * an ergonomic CLI alias. A Figma-like spread of distinct, saturated hues.
+ */
+export declare const MANIFEST_COLORS: readonly ManifestColor[];
+/** The fixed emoji set — 63 visually distinct choices (an 8×8 picker grid with a clear cell). */
+export declare const MANIFEST_EMOJIS: readonly string[];
+/** Whether `value` is one of the fixed color values (`#rrggbb`, lowercased). */
+export declare function isManifestColor(value: string): boolean;
+/** Whether `emoji` is one of the fixed emojis. */
+export declare function isManifestEmoji(emoji: string): boolean;
+/**
+ * Resolve a CLI-supplied color token (either a palette name like `blue` or a
+ * hex value like `#3b82f6`, case-insensitively) to its stored hex value, or
+ * `null` when it matches no palette entry.
+ */
+export declare function resolveManifestColor(token: string): string | null;
+/** Why a color value is invalid, as a human-readable message — or `null` when valid. */
+export declare function manifestColorError(value: string): string | null;
+/** Why an emoji is invalid, as a human-readable message — or `null` when valid. */
+export declare function manifestEmojiError(emoji: string): string | null;

package/dist/core/manifest-appearance.js

@@ -0,0 +1,123 @@
+/**
+ * Manifest appearance: each manifest may carry a color and an emoji,
+ * chosen from these fixed sets, so the editor can tag its label everywhere and
+ * make asset↔manifest membership visually scannable. The sets are the closed
+ * palette both the editor pickers and the CLI validate against — storing a
+ * value outside them is rejected at every mutation entry point.
+ */
+/**
+ * The fixed color palette. Values are the SSOT stored in the library; names are
+ * an ergonomic CLI alias. A Figma-like spread of distinct, saturated hues.
+ */
+export const MANIFEST_COLORS = [
+    { name: 'slate', value: '#64748b' },
+    { name: 'red', value: '#ef4444' },
+    { name: 'orange', value: '#f97316' },
+    { name: 'amber', value: '#f59e0b' },
+    { name: 'yellow', value: '#eab308' },
+    { name: 'lime', value: '#84cc16' },
+    { name: 'green', value: '#22c55e' },
+    { name: 'teal', value: '#14b8a6' },
+    { name: 'cyan', value: '#06b6d4' },
+    { name: 'blue', value: '#3b82f6' },
+    { name: 'indigo', value: '#6366f1' },
+    { name: 'violet', value: '#8b5cf6' },
+    { name: 'pink', value: '#ec4899' }
+];
+/** The fixed emoji set — 63 visually distinct choices (an 8×8 picker grid with a clear cell). */
+export const MANIFEST_EMOJIS = [
+    '🗂️',
+    '🏠',
+    '🎯',
+    '⭐',
+    '🔥',
+    '💎',
+    '🎨',
+    '🧩',
+    '🚀',
+    '🎵',
+    '🏆',
+    '⚡',
+    '🌟',
+    '🍀',
+    '🎁',
+    '📦',
+    '🗺️',
+    '🔑',
+    '🛒',
+    '❤️',
+    '🐙',
+    '🎲',
+    '🌈',
+    '🧪',
+    '🎪',
+    '🎭',
+    '🎬',
+    '🎤',
+    '🎧',
+    '🎸',
+    '🥁',
+    '🔔',
+    '💡',
+    '🔮',
+    '🧭',
+    '⏰',
+    '📸',
+    '🖼️',
+    '📚',
+    '✏️',
+    '🖌️',
+    '🧲',
+    '⚙️',
+    '🛠️',
+    '🔧',
+    '🧰',
+    '🔌',
+    '🔋',
+    '🌍',
+    '🌙',
+    '☀️',
+    '❄️',
+    '🌊',
+    '🍄',
+    '🌵',
+    '🌸',
+    '🍎',
+    '🍕',
+    '🍩',
+    '☕',
+    '🐳',
+    '🦄',
+    '🐝'
+];
+/** Whether `value` is one of the fixed color values (`#rrggbb`, lowercased). */
+export function isManifestColor(value) {
+    return MANIFEST_COLORS.some((color) => color.value === value);
+}
+/** Whether `emoji` is one of the fixed emojis. */
+export function isManifestEmoji(emoji) {
+    return MANIFEST_EMOJIS.includes(emoji);
+}
+/**
+ * Resolve a CLI-supplied color token (either a palette name like `blue` or a
+ * hex value like `#3b82f6`, case-insensitively) to its stored hex value, or
+ * `null` when it matches no palette entry.
+ */
+export function resolveManifestColor(token) {
+    const normalized = token.trim().toLowerCase();
+    const match = MANIFEST_COLORS.find((color) => color.value === normalized || color.name === normalized);
+    return match ? match.value : null;
+}
+/** Why a color value is invalid, as a human-readable message — or `null` when valid. */
+export function manifestColorError(value) {
+    if (isManifestColor(value))
+        return null;
+    return (`"${value}" is not a selectable manifest color — choose one of: ` +
+        `${MANIFEST_COLORS.map((color) => `${color.name} (${color.value})`).join(', ')}.`);
+}
+/** Why an emoji is invalid, as a human-readable message — or `null` when valid. */
+export function manifestEmojiError(emoji) {
+    if (isManifestEmoji(emoji))
+        return null;
+    return `"${emoji}" is not a selectable manifest emoji — choose one of: ${MANIFEST_EMOJIS.join(' ')}.`;
+}

package/dist/core/manifest-entry.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The generated-entry data types shared by codegen (server) and the runtime:
+ * exactly what a generated manifest module passes to `createManifest` per
+ * asset. Data only — behavior lives in the runtime directory.
+ */
+import type { ChromaKeyParameters } from './chroma-key.js';
+import type { Slicing } from './slice-data.js';
+/**
+ * Pre-inline manifest-entry data. Reference fields may still contain
+ * `{ $asset }` markers; codegen narrows this to `ManifestEntry` after inlining.
+ */
+export type ManifestEntryData = {
+    kind: string;
+    src: string;
+} & Record<string, unknown>;
+export interface ImageManifestEntry {
+    kind: 'image';
+    /** Delivered proxy URL (`proxyBasePath` + proxy file name). */
+    src: string;
+    /** Intrinsic pixel dimensions of the delivered proxy. */
+    width: number;
+    height: number;
+}
+export interface SliceManifestEntry {
+    kind: 'slice';
+    /** Delivered proxy URL (`proxyBasePath` + proxy file name). */
+    src: string;
+    slicing: Slicing;
+    /** Pixel dimensions of the delivered image the insets are measured in. */
+    sourceWidth: number;
+    sourceHeight: number;
+}
+export interface VideoManifestEntry {
+    kind: 'video';
+    /** Delivered proxy URL (`proxyBasePath` + proxy file name). */
+    src: string;
+    /** Intrinsic pixel dimensions of the delivered proxy. */
+    width: number;
+    height: number;
+    durationMs: number;
+}
+export interface ChromaKeyVideoManifestEntry {
+    kind: 'chroma-key-video';
+    /** Delivered proxy URL (`proxyBasePath` + proxy file name). */
+    src: string;
+    /** Intrinsic pixel dimensions of the delivered proxy. */
+    width: number;
+    height: number;
+    durationMs: number;
+    chromaKey: ChromaKeyParameters;
+    /** Grayscale shape mask — the referenced image's entry, inlined by codegen. */
+    mask?: ImageManifestEntry;
+    /** WebGL2-unavailable fallback — the referenced image's entry, inlined by codegen. */
+    fallback?: ImageManifestEntry;
+}
+export interface AudioManifestEntry {
+    kind: 'audio';
+    /** Delivered proxy URL (`proxyBasePath` + proxy file name). */
+    src: string;
+    durationMs: number;
+}
+export type ManifestEntry = ImageManifestEntry | SliceManifestEntry | VideoManifestEntry | ChromaKeyVideoManifestEntry | AudioManifestEntry;
+/** Preload options of the image kind: decode the fetched file up front. */
+export interface ImagePreloadOptions {
+    /** Decode via an HTMLImageElement after fetching (default true). */
+    decode?: boolean;
+}
+/**
+ * Preload options of the slice kind. A slice is image-backed, so it carries
+ * the same decode switch — typed per kind (not shared), so kinds can diverge.
+ */
+export interface SlicePreloadOptions {
+    /** Decode via an HTMLImageElement after fetching (default true). */
+    decode?: boolean;
+}
+/**
+ * Preload options of the video kind. Retention (full fetch + object URL) is
+ * always on  — no options yet; the namespaced slot is the API.
+ */
+export interface VideoPreloadOptions {
+}
+/**
+ * Preload options of the chroma-key-video kind. No options yet; the
+ * namespaced slot is the API.
+ */
+export interface ChromaKeyVideoPreloadOptions {
+}
+/** Preload options of the audio kind. Retention is always on — no options yet. */
+export interface AudioPreloadOptions {
+}
+/**
+ * Options for `Manifest.preload()`, namespaced per asset kind exactly like
+ * plugin configuration lives under `plugins.<type>` in `fundus.config.ts`
+ *; each kind that has preload options declares its own type here,
+ * and adding a kind is purely additive. An option applies to every entry of
+ * that kind, including entries reached via the inlined reference closure.
+ */
+export interface PreloadOptions {
+    image?: ImagePreloadOptions;
+    slice?: SlicePreloadOptions;
+    video?: VideoPreloadOptions;
+    chromaKeyVideo?: ChromaKeyVideoPreloadOptions;
+    audio?: AudioPreloadOptions;
+}

package/dist/core/manifest-entry.js

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

package/dist/core/manifest-membership.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Automatic closure membership: a referenced asset is a
+ * *passive member* of every manifest its referrer is in — derived from the
+ * reference graph, never stored in the library (explicit membership stays the
+ * only persisted fact). This is the single place the membership and delivery
+ * picture is computed; server processing, codegen, delivered-size accounting,
+ * and the editor state payload all consume it — no parallel closure walks.
+ */
+import type { AssetId, Library, ManifestName } from './library.js';
+import { type ReferencesByAsset } from './reference-graph.js';
+/** One derived passive membership, with the attribution that explains it. */
+export interface PassiveMember {
+    assetId: AssetId;
+    /**
+     * The explicit members of the manifest whose reference closure contains
+     * this asset — the answer to "why is this here". Attribution is to the
+     * explicit-member *roots*, so a chain `a → b → c` attributes both `b` and
+     * `c` to `a` (sorted, at least one entry).
+     */
+    via: AssetId[];
+}
+/** One manifest's full membership picture: explicit (stored) + passive (derived). */
+export interface ManifestMembership {
+    /** Members stored in the library — the manifest's typed API surface (sorted). */
+    explicitMemberIds: AssetId[];
+    /**
+     * Members derived from the reference graph: in the explicit members'
+     * reference closure without being explicit themselves. Delivered and
+     * preloaded with the manifest, but inlined-only in the generated module —
+     * never a top-level typed property. Sorted by asset id. An asset that is
+     * both explicit and referenced is an explicit member, full stop.
+     */
+    passiveMembers: PassiveMember[];
+    /** The delivery set: explicit ∪ passive. */
+    deliveredAssetIds: Set<AssetId>;
+}
+/**
+ * Membership per manifest name. Covers every name in `library.manifests` plus
+ * any name an asset record points at — a record referencing an unknown
+ * manifest is a validation error, but delivery semantics must not silently
+ * flip on a hand-edited library, so such names still deliver here.
+ */
+export type LibraryMembership = Record<ManifestName, ManifestMembership>;
+/**
+ * Compute the full membership picture from a library and its collected
+ * references: for each manifest the explicit members, the passive members
+ * (`referenceClosure(explicit) − explicit`) with their via-attribution, and
+ * the resulting delivery set.
+ */
+export declare function computeLibraryMembership(library: Library, referencesByAsset: ReferencesByAsset): LibraryMembership;
+/**
+ * Every asset delivered by at least one manifest, explicitly or passively —
+ * the processing set (assets outside it are inert). An asset is
+ * *unreachable* (nothing delivers it) exactly when it is missing here.
+ */
+export declare function allDeliveredAssetIds(membership: LibraryMembership): Set<AssetId>;

package/dist/core/manifest-membership.js

@@ -0,0 +1,54 @@
+import { compareCodeUnits } from './canonicalize.js';
+import { referenceClosure } from './reference-graph.js';
+/**
+ * Compute the full membership picture from a library and its collected
+ * references: for each manifest the explicit members, the passive members
+ * (`referenceClosure(explicit) − explicit`) with their via-attribution, and
+ * the resulting delivery set.
+ */
+export function computeLibraryMembership(library, referencesByAsset) {
+    const manifestNames = new Set(Object.keys(library.manifests));
+    for (const record of Object.values(library.assets)) {
+        for (const manifestName of record.manifests)
+            manifestNames.add(manifestName);
+    }
+    const membership = {};
+    for (const manifestName of [...manifestNames].sort(compareCodeUnits)) {
+        const explicitMemberIds = Object.entries(library.assets)
+            .filter(([, record]) => record.manifests.includes(manifestName))
+            .map(([assetId]) => assetId)
+            .sort(compareCodeUnits);
+        const explicitMemberSet = new Set(explicitMemberIds);
+        const deliveredAssetIds = new Set(explicitMemberIds);
+        const viaByPassiveAssetId = new Map();
+        for (const explicitMemberId of explicitMemberIds) {
+            for (const reachedAssetId of referenceClosure([explicitMemberId], referencesByAsset)) {
+                deliveredAssetIds.add(reachedAssetId);
+                if (explicitMemberSet.has(reachedAssetId))
+                    continue;
+                const via = viaByPassiveAssetId.get(reachedAssetId) ?? [];
+                // Explicit members iterate sorted, so `via` stays sorted for free.
+                via.push(explicitMemberId);
+                viaByPassiveAssetId.set(reachedAssetId, via);
+            }
+        }
+        const passiveMembers = [...viaByPassiveAssetId.entries()]
+            .map(([assetId, via]) => ({ assetId, via }))
+            .sort((a, b) => compareCodeUnits(a.assetId, b.assetId));
+        membership[manifestName] = { explicitMemberIds, passiveMembers, deliveredAssetIds };
+    }
+    return membership;
+}
+/**
+ * Every asset delivered by at least one manifest, explicitly or passively —
+ * the processing set (assets outside it are inert). An asset is
+ * *unreachable* (nothing delivers it) exactly when it is missing here.
+ */
+export function allDeliveredAssetIds(membership) {
+    const delivered = new Set();
+    for (const manifestMembership of Object.values(membership)) {
+        for (const assetId of manifestMembership.deliveredAssetIds)
+            delivered.add(assetId);
+    }
+    return delivered;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Audio plugin (core part): a raw audio file delivered as one transcoded
+ * proxy. Fundus delivers URLs + metadata only — playback belongs to the host's
+ * audio engine, so there is no runtime component; the typed handle
+ * is the `AudioManifestEntry` itself.
+ */
+import type { AssetTypePluginDescriptor } from './contract.js';
+export interface AudioPreset {
+    codec: 'opus' | 'aac';
+    /** Target bitrate in kilobits per second (`-b:a`). */
+    bitrateKbps: number;
+    container: 'webm' | 'm4a';
+}
+export interface AudioPluginConfig {
+    /** Named presets; merged over the built-in defaults. */
+    presets?: Record<string, AudioPreset>;
+}
+export interface AudioParameters {
+    /** Preset name, resolved against the audio plugin config's presets. */
+    preset: string;
+}
+/** Built-in presets, always available; host config merges over them. */
+export declare const AUDIO_BUILT_IN_PRESETS: Record<string, AudioPreset>;
+export declare function validateAudioPreset(name: string, value: unknown): AudioPreset;
+export declare const AUDIO_EXTENSIONS: readonly string[];
+export declare const audioPlugin: AssetTypePluginDescriptor<AudioParameters, AudioPluginConfig>;