fundus 0.0.2 → 0.0.3

package/dist/config.d.ts

@@ -1,2 +1,3 @@
-import { FundusConfig, defineConfig } from "#fundus/core";
-export { type FundusConfig, defineConfig };
+/** Node-safe configuration helpers for `fundus.config.ts`. */
+export { defineConfig } from './core/index.js';
+export type { FundusConfig } from './core/index.js';

package/dist/config.js

@@ -1,2 +1,2 @@
-import { defineConfig } from "#fundus/core";
-export { defineConfig };
+/** Node-safe configuration helpers for `fundus.config.ts`. */
+export { defineConfig } from './core/index.js';

package/dist/core/api-types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared derived-state and dev-server REST API types. They live in core so the
+ * editor stays typed without depending on the Node-only server package.
+ */
+import type { Library } from './library.js';
+/** One end of a reference edge: the parameter field and the asset across it. */
+export interface AssetReferenceLinkDto {
+    /** Dot-path of the referrer's parameter field holding the reference. */
+    field: string;
+    /** The asset on the other side: the target (outgoing) or the referrer (incoming). */
+    assetId: string;
+}
+/** An asset's reference edges in both directions. */
+export interface AssetReferencesDto {
+    outgoing: AssetReferenceLinkDto[];
+    incoming: AssetReferenceLinkDto[];
+}
+/**
+ * One derived passive membership of an asset: the manifest it
+ * is pulled into and the explicit-member roots whose reference closure pulls
+ * it in ("via characterGreenscreen" — the editor's attribution).
+ */
+export interface PassiveManifestMembershipDto {
+    manifest: string;
+    via: string[];
+}
+/** One passive member of a manifest, with explicit-root attribution. */
+export interface PassiveMemberDto {
+    assetId: string;
+    via: string[];
+}
+/** One manifest's membership picture for the manifests view. */
+export interface ManifestMembershipDto {
+    /** Members stored in the library — the manifest's typed API surface. */
+    explicitMemberIds: string[];
+    /** Members derived from the reference graph, with via-attribution. */
+    passiveMembers: PassiveMemberDto[];
+}
+/** One asset's derived, display-ready status alongside the raw library record. */
+export interface AssetStateDto {
+    id: string;
+    type: string;
+    /** Raw file name (relative to the raw dir). */
+    raw: string;
+    /** Explicit folder path, or the empty string for the implicit root. */
+    folder: string;
+    /** URL the Fundus server serves the raw file under (`/files/raw/<fileName>`). */
+    rawUrl: string;
+    rawHash: string;
+    parameters: unknown;
+    manifests: string[];
+    /** Derived passive memberships with attribution, sorted by manifest name. */
+    passiveManifests: PassiveManifestMembershipDto[];
+    /** Delivered proxy status; `null` while the asset is not delivered or unprocessed. */
+    proxy: ProxyStateDto | null;
+    /** Human-readable warnings: unreachable asset, stale proxy, validation problems. */
+    warnings: string[];
+    /** Reference edges in both directions (empty lists for reference-free types). */
+    references: AssetReferencesDto;
+}
+export interface ProxyStateDto {
+    /** Basename of the proxy file. */
+    fileName: string;
+    /** Path relative to proxyDir, including the mirrored asset folder. */
+    relativePath: string;
+    /** URL the Fundus server serves the proxy under (`/files/proxy/<fileName>`). */
+    url: string;
+    /** Whether the file named by the current job hash exists. */
+    upToDate: boolean;
+    /** Intrinsic pixel dimensions; absent for audio proxies. */
+    width?: number;
+    height?: number;
+    /** Media duration; present for video and audio proxies. */
+    durationMs?: number;
+    fileSize: number;
+}
+/** The full editor state payload returned by `GET /api/state` and every mutation. */
+export interface FundusStateDto {
+    library: Library;
+    assets: AssetStateDto[];
+    /** Library-level validation issues (per asset where attributable). */
+    issues: ValidationIssueDto[];
+    /** Available preset names per asset type (from the merged plugin config). */
+    presetNames: Record<string, string[]>;
+    /** Per manifest: explicit + passive member lists (the manifests view data). */
+    manifestMemberships: Record<string, ManifestMembershipDto>;
+    /**
+     * Delivered bytes per manifest over its full delivery set (explicit ∪
+     * passive members), deduplicated — the preload-budget number.
+     */
+    manifestDeliveredBytes: Record<string, number>;
+}
+export interface ValidationIssueDto {
+    assetId?: string;
+    message: string;
+}
+/** Body of `PATCH /api/assets/:id` — all fields optional, applied together. */
+export interface PatchAssetRequestDto {
+    parameters?: unknown;
+    manifests?: string[];
+    renameTo?: string;
+    /** Move the asset to this registered folder; empty string means root. */
+    folder?: string;
+}
+export interface CreateFolderRequestDto {
+    path: string;
+}
+export interface PatchFolderRequestDto {
+    /** Replacement name for the final path segment. */
+    name?: string;
+    /** Move the folder below this registered parent; empty string means root. */
+    parent?: string;
+}
+export interface MoveAssetsRequestDto {
+    assetIds: string[];
+    /** Registered destination folder; empty string means root. */
+    folder: string;
+}
+export interface DeleteAssetsRequestDto {
+    assetIds: string[];
+}
+/** Body of `POST /api/manifests`. */
+export interface CreateManifestRequestDto {
+    name: string;
+}
+/**
+ * Body of `PATCH /api/manifests/:name` — the manifest's editor appearance
+ * and/or a rename. A `null` clears that field; an omitted field is left
+ * unchanged.
+ */
+export interface PatchManifestRequestDto {
+    color?: string | null;
+    emoji?: string | null;
+    renameTo?: string;
+}
+/** Error payload for non-2xx API responses. */
+export interface ApiErrorDto {
+    error: {
+        message: string;
+    };
+}

package/dist/core/api-types.js

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

package/dist/core/asset-id.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Asset ids are the SSOT keys and the generated property names on manifests
+ * are stable, human-readable camelCase slugs that must be valid JS
+ * identifiers and must not collide with `Manifest` class members.
+ */
+/**
+ * Names an asset id may never take: current and future members of the runtime
+ * `Manifest` class (entries become direct properties on it), plus inherited
+ * `Object.prototype` members that would shadow-collide, plus keys that are
+ * prototype-pollution hazards when used as record keys (`prototype`;
+ * `__proto__` already fails the camelCase pattern).
+ */
+export declare const RESERVED_ASSET_IDS: readonly string[];
+/**
+ * Whether `id` is a valid asset id: a camelCase JS identifier (lowercase
+ * letter, then letters/digits) that is not a reserved `Manifest` member name.
+ */
+export declare function isValidAssetId(id: string): boolean;
+/**
+ * Why an id is invalid, as a human-readable message — or `null` when valid.
+ * Lets the editor and the validator surface the precise reason.
+ */
+export declare function assetIdError(id: string): string | null;
+/**
+ * Manifest names deliberately share the asset-id grammar because each name
+ * becomes a generated JavaScript module export.
+ */
+export declare function manifestNameError(name: string): string | null;

package/dist/core/asset-id.js

@@ -0,0 +1,59 @@
+/**
+ * Asset ids are the SSOT keys and the generated property names on manifests
+ * are stable, human-readable camelCase slugs that must be valid JS
+ * identifiers and must not collide with `Manifest` class members.
+ */
+/**
+ * Names an asset id may never take: current and future members of the runtime
+ * `Manifest` class (entries become direct properties on it), plus inherited
+ * `Object.prototype` members that would shadow-collide, plus keys that are
+ * prototype-pollution hazards when used as record keys (`prototype`;
+ * `__proto__` already fails the camelCase pattern).
+ */
+export const RESERVED_ASSET_IDS = [
+    'preload',
+    'release',
+    'entries',
+    'constructor',
+    'prototype',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    'toLocaleString',
+    'toString',
+    'valueOf'
+];
+const ASSET_ID_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+/**
+ * Whether `id` is a valid asset id: a camelCase JS identifier (lowercase
+ * letter, then letters/digits) that is not a reserved `Manifest` member name.
+ */
+export function isValidAssetId(id) {
+    return ASSET_ID_PATTERN.test(id) && !RESERVED_ASSET_IDS.includes(id);
+}
+/**
+ * Why an id is invalid, as a human-readable message — or `null` when valid.
+ * Lets the editor and the validator surface the precise reason.
+ */
+export function assetIdError(id) {
+    if (!ASSET_ID_PATTERN.test(id)) {
+        return `"${id}" is not a valid asset id — use a camelCase identifier starting with a lowercase letter (e.g. "navigationPanel").`;
+    }
+    if (RESERVED_ASSET_IDS.includes(id)) {
+        return `"${id}" is reserved (it collides with a Manifest member name).`;
+    }
+    return null;
+}
+/**
+ * Manifest names deliberately share the asset-id grammar because each name
+ * becomes a generated JavaScript module export.
+ */
+export function manifestNameError(name) {
+    if (!ASSET_ID_PATTERN.test(name)) {
+        return `"${name}" is not a valid manifest name — use a camelCase identifier starting with a lowercase letter (e.g. "mainCatalog").`;
+    }
+    if (RESERVED_ASSET_IDS.includes(name)) {
+        return `"${name}" is reserved (it collides with a Manifest member name).`;
+    }
+    return null;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * The asset-reference schema primitive: a plugin parameter field may
+ * point at another asset, written as `{ "$asset": "<id>" }` in the library
+ * JSON. References keep type-specific composition out of the core — a plugin
+ * declares *which* of its fields are references (`collectReferences` on the
+ * plugin contract); the core only knows "this asset points at that asset".
+ */
+/** The in-library shape of a reference: `{ "$asset": "characterIdleMask" }`. */
+export interface AssetReference {
+    $asset: string;
+}
+/** Whether a value is a well-formed asset-reference marker. */
+export declare function isAssetReference(value: unknown): value is AssetReference;
+/**
+ * One reference a plugin found in an asset's parameters. `field` is the
+ * dot-path of the parameter field holding the reference (for messages);
+ * `expectedTypes` constrains the target's asset type (empty = any type).
+ */
+export interface CollectedReference {
+    field: string;
+    assetId: string;
+    expectedTypes: readonly string[];
+}

package/dist/core/asset-reference.js

@@ -0,0 +1,15 @@
+/**
+ * The asset-reference schema primitive: a plugin parameter field may
+ * point at another asset, written as `{ "$asset": "<id>" }` in the library
+ * JSON. References keep type-specific composition out of the core — a plugin
+ * declares *which* of its fields are references (`collectReferences` on the
+ * plugin contract); the core only knows "this asset points at that asset".
+ */
+/** Whether a value is a well-formed asset-reference marker. */
+export function isAssetReference(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.$asset === 'string' &&
+        value.$asset !== '');
+}

package/dist/core/canonicalize.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable JSON for hash inputs: recursively sorted keys, no whitespace,
+ * `undefined` object values dropped. Two parameter objects that differ only in
+ * key order (or in explicitly-undefined optionals) canonicalize identically,
+ * so the derived job hash — and thus the proxy file name — stays stable.
+ */
+export declare function canonicalizeParameters(parameters: unknown): string;
+/** Deterministic UTF-16 code-unit ordering, independent of host locale. */
+export declare function compareCodeUnits(left: string, right: string): number;

package/dist/core/canonicalize.js

@@ -0,0 +1,36 @@
+/**
+ * Stable JSON for hash inputs: recursively sorted keys, no whitespace,
+ * `undefined` object values dropped. Two parameter objects that differ only in
+ * key order (or in explicitly-undefined optionals) canonicalize identically,
+ * so the derived job hash — and thus the proxy file name — stays stable.
+ */
+export function canonicalizeParameters(parameters) {
+    return stringify(parameters);
+}
+/** Deterministic UTF-16 code-unit ordering, independent of host locale. */
+export function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function stringify(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(stringify).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        const parts = [];
+        for (const key of Object.keys(record).sort()) {
+            if (record[key] === undefined)
+                continue;
+            parts.push(`${JSON.stringify(key)}:${stringify(record[key])}`);
+        }
+        return `{${parts.join(',')}}`;
+    }
+    throw new Error(`Cannot canonicalize a ${typeof value} value.`);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Chroma-key parameter data: the keying values the chroma-key-video plugin
+ * stores per asset and the runtime's WebGL renderer consumes. The parameter
+ * names and defaults follow the public UnityChromakey shader; this module is
+ * environment-free data only — the GL engine lives in the runtime directory.
+ */
+export interface ChromaKeyParameters {
+    /** RGB 0–1 each. The greenscreen color to key out. */
+    keyColor: [number, number, number];
+    /** Chroma distance below which a pixel is fully keyed. */
+    colorCutoff: number;
+    /** Chroma distance band over which the key fades out. */
+    colorFeathering: number;
+    /** Blend toward the 3×3-blurred mask, 0 = unfeathered. */
+    maskFeathering: number;
+    /** Lower smoothstep edge re-hardening the feathered mask. */
+    sharpening: number;
+    /** How strongly green spill is pulled toward the red/blue average. */
+    despill: number;
+    /** Luminance removed by the despill that is added back. */
+    despillLuminanceAdd: number;
+}
+/** The upstream shader's property defaults — a freshly ingested asset starts here. */
+export declare const DEFAULT_CHROMA_KEY_PARAMETERS: ChromaKeyParameters;
+/**
+ * Validate an unknown chroma-key blob: every field required, every channel and
+ * scalar a finite number. Values are clamped into 0–1 (slider float artifacts
+ * must not invalidate a library), non-numbers throw.
+ */
+export declare function validateChromaKeyParameters(value: unknown): ChromaKeyParameters;

package/dist/core/chroma-key.js

@@ -0,0 +1,55 @@
+/**
+ * Chroma-key parameter data: the keying values the chroma-key-video plugin
+ * stores per asset and the runtime's WebGL renderer consumes. The parameter
+ * names and defaults follow the public UnityChromakey shader; this module is
+ * environment-free data only — the GL engine lives in the runtime directory.
+ */
+/** The upstream shader's property defaults — a freshly ingested asset starts here. */
+export const DEFAULT_CHROMA_KEY_PARAMETERS = {
+    keyColor: [0, 1, 0],
+    colorCutoff: 0.2,
+    colorFeathering: 0.33,
+    maskFeathering: 1,
+    sharpening: 0.5,
+    despill: 1,
+    despillLuminanceAdd: 0.2
+};
+const SCALAR_KEYS = [
+    'colorCutoff',
+    'colorFeathering',
+    'maskFeathering',
+    'sharpening',
+    'despill',
+    'despillLuminanceAdd'
+];
+function clampUnit(value) {
+    return Math.min(1, Math.max(0, value));
+}
+/**
+ * Validate an unknown chroma-key blob: every field required, every channel and
+ * scalar a finite number. Values are clamped into 0–1 (slider float artifacts
+ * must not invalidate a library), non-numbers throw.
+ */
+export function validateChromaKeyParameters(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('"chromaKey" must be an object.');
+    }
+    const record = value;
+    const keyColor = record.keyColor;
+    if (!Array.isArray(keyColor) ||
+        keyColor.length !== 3 ||
+        keyColor.some((channel) => typeof channel !== 'number' || !Number.isFinite(channel))) {
+        throw new Error('"chromaKey.keyColor" must be an array of three numbers (RGB, 0–1 each).');
+    }
+    const result = {
+        keyColor: [clampUnit(keyColor[0]), clampUnit(keyColor[1]), clampUnit(keyColor[2])]
+    };
+    for (const key of SCALAR_KEYS) {
+        const scalar = record[key];
+        if (typeof scalar !== 'number' || !Number.isFinite(scalar)) {
+            throw new Error(`"chromaKey.${key}" must be a number (0–1).`);
+        }
+        result[key] = clampUnit(scalar);
+    }
+    return result;
+}

package/dist/core/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Host configuration: `fundus.config.ts` in the host project root
+ * default-exports `defineConfig({ … })`. All paths are host-project-root
+ * relative; the server's config loader resolves them to absolute paths and
+ * merges built-in plugin preset defaults.
+ */
+import type { AudioPluginConfig } from './plugins/audio.js';
+import type { ImagePluginConfig } from './plugins/image.js';
+import type { SlicePluginConfig } from './plugins/slice.js';
+import type { VideoPluginConfig } from './plugins/video.js';
+export interface FundusConfig {
+    /** Directory holding the raw originals (never delivered). */
+    rawDir: string;
+    /** Directory processed proxies are written to (conventionally under `static/`). */
+    proxyDir: string;
+    /** URL prefix baked into generated proxy `src` values, e.g. '/fundus/'. */
+    proxyBasePath: string;
+    /** Path of the library JSON file (the SSOT). */
+    library: string;
+    /** Directory the generated manifest modules land in. */
+    manifestsDir: string;
+    /**
+     * Per-plugin configuration; each plugin owns its namespace and schema.
+     * chroma-key-video has no namespace — it shares the video plugin's presets
+     * (and ffmpeg/ffprobe path overrides) .
+     */
+    plugins?: {
+        image?: ImagePluginConfig;
+        slice?: SlicePluginConfig;
+        video?: VideoPluginConfig;
+        audio?: AudioPluginConfig;
+    };
+}
+/** Identity helper so the host config file gets full typing + completion. */
+export declare function defineConfig(config: FundusConfig): FundusConfig;

package/dist/core/config.js

@@ -0,0 +1,4 @@
+/** Identity helper so the host config file gets full typing + completion. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/core/folder-path.d.ts

@@ -0,0 +1,19 @@
+/** The implicit raw/proxy root. Explicit folders are always non-empty paths. */
+export declare const ROOT_FOLDER = "";
+/** Fundus-owned file that preserves explicit empty folders in source control. */
+export declare const FOLDER_SENTINEL = ".gitkeep";
+/** Validate one human-facing folder name (a single path segment). */
+export declare function folderNameError(name: string): string | null;
+/** Normalize a validated, portable relative folder path to NFC + POSIX separators. */
+export declare function normalizeFolderPath(path: string): string;
+/** Validate a non-root, POSIX-relative folder path. */
+export declare function folderPathError(path: string): string | null;
+/** Case-insensitive, Unicode-normalized key used to prevent portable path collisions. */
+export declare function portableFolderPathKey(path: string): string;
+export declare function parentFolderPath(path: string): string;
+export declare function folderNameOf(path: string): string;
+export declare function joinFolderPath(parent: string, name: string): string;
+export declare function folderOfRawPath(rawPath: string): string;
+export declare function rawFileNameOfPath(rawPath: string): string;
+export declare function isFolderOrDescendant(path: string, ancestor: string): boolean;
+export declare function replaceFolderPrefix(path: string, from: string, to: string): string;

package/dist/core/folder-path.js

@@ -0,0 +1,86 @@
+/** The implicit raw/proxy root. Explicit folders are always non-empty paths. */
+export const ROOT_FOLDER = '';
+/** Fundus-owned file that preserves explicit empty folders in source control. */
+export const FOLDER_SENTINEL = '.gitkeep';
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+const WINDOWS_FORBIDDEN_CHARACTERS = /[<>:"|?*]/;
+const WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+/** Validate one human-facing folder name (a single path segment). */
+export function folderNameError(name) {
+    if (name.length === 0)
+        return 'Folder names must not be empty.';
+    if (name !== name.trim())
+        return 'Folder names must not start or end with whitespace.';
+    if (name === '.' || name === '..')
+        return `"${name}" is not a valid folder name.`;
+    if (name.includes('/') || name.includes('\\')) {
+        return 'Folder names must not contain path separators.';
+    }
+    if (CONTROL_CHARACTERS.test(name))
+        return 'Folder names must not contain control characters.';
+    if (WINDOWS_FORBIDDEN_CHARACTERS.test(name)) {
+        return 'Folder names must not contain Windows-reserved characters (: * ? " < > |).';
+    }
+    if (name.endsWith('.'))
+        return 'Folder names must not end with a dot.';
+    if (name.toLocaleLowerCase('en-US') === 'root') {
+        return `"${name}" is reserved for the implicit Fundus root folder.`;
+    }
+    if (name.toLocaleLowerCase('en-US') === FOLDER_SENTINEL) {
+        return `"${name}" is reserved for Fundus folder management.`;
+    }
+    if (WINDOWS_RESERVED_NAME.test(name)) {
+        return `"${name}" is a reserved filesystem name.`;
+    }
+    return null;
+}
+/** Normalize a validated, portable relative folder path to NFC + POSIX separators. */
+export function normalizeFolderPath(path) {
+    return path
+        .split('/')
+        .map((segment) => segment.normalize('NFC'))
+        .join('/');
+}
+/** Validate a non-root, POSIX-relative folder path. */
+export function folderPathError(path) {
+    if (path.length === 0)
+        return 'The root is implicit and cannot be registered as a folder.';
+    if (path.startsWith('/') || path.endsWith('/')) {
+        return 'Folder paths must be relative and must not start or end with a slash.';
+    }
+    for (const segment of path.split('/')) {
+        const problem = folderNameError(segment);
+        if (problem)
+            return `Invalid folder path "${path}": ${problem}`;
+    }
+    return null;
+}
+/** Case-insensitive, Unicode-normalized key used to prevent portable path collisions. */
+export function portableFolderPathKey(path) {
+    return normalizeFolderPath(path).toLocaleLowerCase('en-US');
+}
+export function parentFolderPath(path) {
+    const separator = path.lastIndexOf('/');
+    return separator === -1 ? ROOT_FOLDER : path.slice(0, separator);
+}
+export function folderNameOf(path) {
+    const separator = path.lastIndexOf('/');
+    return separator === -1 ? path : path.slice(separator + 1);
+}
+export function joinFolderPath(parent, name) {
+    return parent === ROOT_FOLDER ? name : `${parent}/${name}`;
+}
+export function folderOfRawPath(rawPath) {
+    return parentFolderPath(rawPath);
+}
+export function rawFileNameOfPath(rawPath) {
+    return folderNameOf(rawPath);
+}
+export function isFolderOrDescendant(path, ancestor) {
+    return path === ancestor || path.startsWith(`${ancestor}/`);
+}
+export function replaceFolderPrefix(path, from, to) {
+    if (path === from)
+        return to;
+    return `${to}${path.slice(from.length)}`;
+}