@pixerate/editor 0.27.0 → 0.29.0

package/dist/parameters/index.d.ts

@@ -0,0 +1,595 @@
+import { A as AnimationEasing } from '../easing-B6iAnJHk.js';
+import { J as JsonSchema } from '../schema-DYDGdYL9.js';
+import { H as HistoryManager } from '../HistoryManager-DWSLd6Tf.js';
+import { C as CommandSpec } from '../registry-DhVUZioj.js';
+import '../types-DsiXGmjo.js';
+
+/**
+ * Types for the schema-driven parameters editor: the control panel of an effect, shader,
+ * generator or component. A `ParameterSchema` lists fields (optionally in groups); a
+ * `ParametersController` holds their values with validation, undo, presets and keyframes.
+ */
+/** A parameter's value. `number` / `int`: a number; `boolean`; `choice`: an option value;
+ * `color`: `#rrggbb` (or `#rrggbbaa` with `alpha`); `vector`: 2–4 numbers; `image` / `text`: a string. */
+type ParameterValue = number | boolean | string | number[];
+/** Parameter id → value. */
+type ParameterValues = Record<string, ParameterValue>;
+type ParameterFieldType = 'number' | 'int' | 'boolean' | 'choice' | 'color' | 'vector' | 'image' | 'text';
+/**
+ * One test in a `showIf` condition: a literal (equal to), an array (one of), or an object
+ * whose keys must all hold.
+ */
+type ParameterConditionTest = string | number | boolean | readonly (string | number | boolean)[] | {
+    eq?: ParameterValue;
+    ne?: ParameterValue;
+    in?: readonly (string | number | boolean)[];
+    notIn?: readonly (string | number | boolean)[];
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    /** `true`: the value is truthy (non-zero, non-empty); `false`: falsy. */
+    truthy?: boolean;
+};
+/**
+ * When a field or group is shown. An object maps other parameter ids to tests, all of which
+ * must hold (`{ mode: 'advanced', count: { gte: 2 } }`); a function gets every value.
+ * Hidden fields keep their values.
+ */
+type ParameterCondition = {
+    readonly [id: string]: ParameterConditionTest;
+} | ((values: Readonly<ParameterValues>) => boolean);
+interface ParameterFieldBase<TValue extends ParameterValue> {
+    /** Unique id across the schema (also the key in `values`). */
+    id: string;
+    /** Display name (default: the id made readable, `flowSpeed` → "Flow speed"). */
+    label?: string;
+    /** Help text shown under the label and given to agents. */
+    description?: string;
+    default: TValue;
+    showIf?: ParameterCondition;
+    /** Include in `randomize()` (default `true`; image and text fields are never randomised). */
+    randomize?: boolean;
+    /** Shown but not editable from the panel (agents and code can still set it). */
+    readOnly?: boolean;
+}
+interface NumberParameterField extends ParameterFieldBase<number> {
+    type: 'number' | 'int';
+    min?: number;
+    max?: number;
+    /** Slider / spinner step (default: 1 for `int`, 1/100 of the range otherwise). */
+    step?: number;
+    /** Unit shown after the value (`px`, `%`, `°`, `ms`). */
+    unit?: string;
+    /** `slider` (slider plus number box; the default when `min` and `max` are set) or `input` (number box only). */
+    control?: 'slider' | 'input';
+    /** Decimal places shown (default: from `step`). */
+    decimals?: number;
+}
+interface BooleanParameterField extends ParameterFieldBase<boolean> {
+    type: 'boolean';
+}
+interface ParameterChoiceOption {
+    value: string | number;
+    label?: string;
+    description?: string;
+}
+interface ChoiceParameterField extends ParameterFieldBase<string | number> {
+    type: 'choice';
+    options: readonly (string | number | ParameterChoiceOption)[];
+    /** `select` (dropdown, the default) or `segmented` (buttons; best for 2–4 options). */
+    control?: 'select' | 'segmented';
+}
+interface ColorParameterField extends ParameterFieldBase<string> {
+    type: 'color';
+    /** Values carry alpha as `#rrggbbaa` (default `false`: `#rrggbb`). */
+    alpha?: boolean;
+    /** Colours offered as swatches. */
+    swatches?: readonly string[];
+}
+interface VectorParameterField extends ParameterFieldBase<number[]> {
+    type: 'vector';
+    /** Number of components, 2–4 (default: the default's length). */
+    size?: 2 | 3 | 4;
+    /** Bounds for every component, or one per component. */
+    min?: number | readonly number[];
+    max?: number | readonly number[];
+    step?: number;
+    unit?: string;
+    /** Component labels (default `x`, `y`, `z`, `w`). */
+    labels?: readonly string[];
+    decimals?: number;
+}
+interface ParameterImageOption {
+    url: string;
+    label?: string;
+}
+interface ImageParameterField extends ParameterFieldBase<string> {
+    type: 'image';
+    /** Suggested assets shown as thumbnails. */
+    options?: readonly ParameterImageOption[];
+    /** File types offered by the picker's file button, e.g. `image/*`. */
+    accept?: string;
+}
+interface TextParameterField extends ParameterFieldBase<string> {
+    type: 'text';
+    multiline?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    /** Regular expression (unicode) the whole value must match. */
+    pattern?: string;
+    placeholder?: string;
+}
+type ParameterField = NumberParameterField | BooleanParameterField | ChoiceParameterField | ColorParameterField | VectorParameterField | ImageParameterField | TextParameterField;
+/** A collapsible group of fields (groups may nest). */
+interface ParameterGroup {
+    type: 'group';
+    /** Unique id (used for its collapsed state). */
+    id: string;
+    label?: string;
+    description?: string;
+    /** Starts collapsed (default `false`). */
+    collapsed?: boolean;
+    showIf?: ParameterCondition;
+    fields: readonly ParameterSchemaItem[];
+}
+type ParameterSchemaItem = ParameterField | ParameterGroup;
+/** A named set of values. Fields a preset leaves out go back to their defaults when applied. */
+interface ParameterPreset {
+    name: string;
+    values: Partial<ParameterValues>;
+    description?: string;
+    /** Comes from the schema: cannot be overwritten or deleted. */
+    builtIn?: boolean;
+}
+interface ParameterSchema {
+    title?: string;
+    fields: readonly ParameterSchemaItem[];
+    /** Built-in presets. */
+    presets?: readonly ParameterPreset[];
+}
+/** One error, shaped like `validateJsonSchema`'s: `path` is `/<id>` (or `/<id>/<index>`). */
+interface ParameterError {
+    path: string;
+    /** The parameter's id. */
+    id: string;
+    /** A sentence naming the field, e.g. "Speed must be at most 4." */
+    message: string;
+}
+/** Easing of a keyframe segment (the `AnimationEasing` of `@pixerate/editor/animation`). */
+type ParameterEasing = AnimationEasing;
+/** One keyframe, shaped like `AnimationKeyframe` from `@pixerate/editor/animation`. */
+interface ParameterKeyframe<TValue = ParameterValue> {
+    /** Time in milliseconds. */
+    time: number;
+    value: TValue;
+    /** Easing of the segment leaving this keyframe. */
+    easing?: ParameterEasing;
+}
+/** A parameter's keyframes, shaped like `AnimationTrack` from `@pixerate/editor/animation` (which it accepts). */
+interface ParameterTrack<TValue = ParameterValue> {
+    keyframes: ParameterKeyframe<TValue>[];
+    enabled?: boolean;
+}
+/**
+ * Where a parameter's keyframes live: an effect document, a canvas node, or
+ * `createParameterKeyframeStore()`. The controller reads and writes whole tracks so a
+ * keyframe toggle is one undo step.
+ */
+interface ParameterKeyframes {
+    getTrack(id: string): ParameterTrack<any> | undefined;
+    /** Replaces a track; `undefined` (or no keyframes) removes it. */
+    setTrack(id: string, track: ParameterTrack<any> | undefined): void;
+    /** Called when tracks change from outside the controller. */
+    subscribe?(listener: () => void): () => void;
+}
+/** `keyed`: a keyframe sits at the current time; `animated`: keyframes elsewhere; `none`. */
+type ParameterKeyState = 'none' | 'animated' | 'keyed';
+
+/** `flowSpeed`, `flow_speed` or `uFlowSpeed` → "Flow speed". */
+declare function humanizeParameterId(id: string): string;
+/** The label shown for a field or group. */
+declare function parameterLabel(item: {
+    id: string;
+    label?: string;
+}): string;
+/**
+ * Normalises a hex colour to lower-case `#rrggbb`, or `#rrggbbaa` when `alpha` is true
+ * (opaque colours get `ff`). Accepts 3, 4, 6 and 8 digits with or without `#`; returns
+ * `null` for anything else. Without `alpha`, a colour's alpha is dropped.
+ */
+declare function normalizeHexColor(input: string, alpha?: boolean): string | null;
+/** `#77c16a` → `[0.467, 0.757, 0.416]` (0–1 components; four with `alpha`). `null` if not a colour. */
+declare function hexToRgba01(hex: string, alpha?: boolean): number[] | null;
+/** `[0.467, 0.757, 0.416]` → `#77c16a`; a fourth component becomes alpha when `alpha` is true. Clamped to 0–1. */
+declare function rgba01ToHex(components: readonly number[], alpha?: boolean): string;
+declare const isParameterGroup: (item: ParameterSchemaItem) => item is ParameterGroup;
+/** Every field in schema order, groups flattened. */
+declare function getParameterFields(schema: ParameterSchema | readonly ParameterSchemaItem[]): ParameterField[];
+/** Every group in schema order (nested groups after their parent). */
+declare function getParameterGroups(schema: ParameterSchema): ParameterGroup[];
+declare class ParameterSchemaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Checks a schema's structure: unique ids, known types, choice options, vector sizes and
+ * defaults that pass validation. Returns sentences; an empty array means the schema is fine.
+ */
+declare function checkParameterSchema(schema: ParameterSchema): string[];
+/** The defaults of every field (colours normalised to lower-case hex, `int`s rounded). */
+declare function getParameterDefaults(schema: ParameterSchema): ParameterValues;
+declare const cloneValue: <T extends ParameterValue>(value: T) => T;
+/** Value equality (vectors compare component-wise). */
+declare function parameterValuesEqual(a: ParameterValue | undefined, b: ParameterValue | undefined): boolean;
+/** Whether a `showIf` condition holds for `values` (no condition: `true`). */
+declare function evaluateParameterCondition(condition: ParameterCondition | undefined, values: Readonly<ParameterValues>): boolean;
+/**
+ * Field and group id → shown. An item is hidden when its own `showIf` fails or any
+ * enclosing group is hidden.
+ */
+declare function getParameterVisibility(schema: ParameterSchema, values: Readonly<ParameterValues>): Record<string, boolean>;
+/** A choice field's options as objects. */
+declare function getChoiceOptions(field: ChoiceParameterField): ParameterChoiceOption[];
+/** An option's label (default: the value made readable). */
+declare const choiceOptionLabel: (option: ParameterChoiceOption) => string;
+declare function vectorSize(field: VectorParameterField): number;
+/** A vector component as a number field (its bounds, step, unit and label). */
+declare function vectorComponentField(field: VectorParameterField, index: number): NumberParameterField;
+/** The step a number field moves by: `step`, else 1 for `int`, else 1/100 of the range (0.01 without one). */
+declare function parameterStep(field: NumberParameterField): number;
+/** Decimal places to show: `decimals`, else enough for the step (at most 4). */
+declare function parameterDecimals(field: NumberParameterField): number;
+/** Whether a number field renders a slider (`control`, else when it has both bounds). */
+declare const isSliderField: (field: NumberParameterField) => boolean;
+/** A number as shown for a field: fixed decimals, trailing zeros trimmed, plus the unit. */
+declare function formatParameterNumber(field: NumberParameterField, value: number): string;
+/** Clamps into the field's bounds, rounds `int`s and snaps float noise (for UI inputs). */
+declare function clampParameterNumber(field: NumberParameterField, value: number): number;
+/**
+ * Parses what someone typed into a number box ("2.5", "2.5x", "-1e2") and clamps it into
+ * the field's bounds. Returns `null` when it is not a number.
+ */
+declare function parseParameterNumberInput(field: NumberParameterField, text: string): number | null;
+/** A value as short display text (numbers formatted, vectors comma-separated, booleans On/Off). */
+declare function formatParameterValue(field: ParameterField, value: ParameterValue | undefined): string;
+/**
+ * Checks a value against a field. Returns `null` when it is valid, else one error whose
+ * message is a sentence naming the field ("Speed must be at most 4.").
+ */
+declare function validateParameterValue(field: ParameterField, value: unknown): ParameterError | null;
+type ParameterCoercion = {
+    ok: true;
+    value: ParameterValue;
+} | {
+    ok: false;
+    error: ParameterError;
+};
+/**
+ * Checks a value from outside (an agent's tool call, a URL, a form) and returns the value to
+ * store. Coercion is narrow: `int`s are rounded, colours normalised to lower-case hex.
+ */
+declare function coerceParameterValue(field: ParameterField, raw: unknown): ParameterCoercion;
+/** Every error for `values` (missing values are reported too). */
+declare function validateParameterValues(schema: ParameterSchema, values: Readonly<Partial<ParameterValues>>): ParameterError[];
+/** One field as JSON Schema (for agent tool parameters). */
+declare function parameterFieldToJsonSchema(field: ParameterField): JsonSchema;
+/** The schema's values as one object JSON Schema (every property optional). */
+declare function parameterSchemaToJsonSchema(schema: ParameterSchema): JsonSchema & {
+    type: 'object';
+};
+
+/** Keyframes closer than this (ms) to the playhead count as "at" it (default for the controller). */
+declare const PARAMETER_KEY_TOLERANCE = 0.5;
+/** Whether a track has a keyframe within `tolerance` ms of `time`. */
+declare function findParameterKeyframe(track: ParameterTrack<any> | undefined, time: number, tolerance?: number): number;
+/** `keyed` (a key at `time`), `animated` (keys elsewhere) or `none`. */
+declare function getParameterKeyState(track: ParameterTrack<any> | undefined, time: number, tolerance?: number): ParameterKeyState;
+/** A copy of `track` with a key at `time` holding `value` (replacing one already there). */
+declare function withParameterKeyframe<T>(track: ParameterTrack<T> | undefined, key: ParameterKeyframe<T>, tolerance?: number): ParameterTrack<T>;
+/** A copy of `track` without the key at `time`; `undefined` when no keys remain. */
+declare function withoutParameterKeyframe<T>(track: ParameterTrack<T> | undefined, time: number, tolerance?: number): ParameterTrack<T> | undefined;
+interface ParameterKeyframeStore extends ParameterKeyframes {
+    /** Every track (id → track). Stable between changes. */
+    getTracks(): Readonly<Record<string, ParameterTrack<any>>>;
+    /** Replaces every track (no notification when `silent`). */
+    setTracks(tracks: Record<string, ParameterTrack<any>>, silent?: boolean): void;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * An in-memory `ParameterKeyframes` adapter for apps that keep tracks next to their values
+ * (an effect document can implement the interface over its own storage instead).
+ */
+declare function createParameterKeyframeStore(initial?: Record<string, ParameterTrack<any>>): ParameterKeyframeStore;
+
+interface ParametersControllerOptions {
+    schema: ParameterSchema;
+    /** Starting values (missing or invalid ones use the default; invalid ones are reported in `errors`). */
+    values?: Partial<ParameterValues>;
+    /** User presets (the schema's presets are added as built-in). */
+    presets?: readonly ParameterPreset[];
+    /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
+    history?: HistoryManager;
+    /** Where keyframes live. Without it, keyframe methods do nothing. */
+    keyframes?: ParameterKeyframes;
+    /** Starting playhead time in ms (default 0). */
+    time?: number;
+    /** Keys within this many ms of the playhead count as "at" it (default 0.5). */
+    keyTolerance?: number;
+    /** Random source for `randomize` (default `Math.random`). */
+    random?: () => number;
+    /** Called after values change (set, undo, preset, load, …) with the ids that changed. */
+    onChange?: (values: Readonly<ParameterValues>, changed: readonly string[]) => void;
+}
+/** A snapshot of the controller. The same object is returned until something changes. */
+interface ParametersState {
+    schema: ParameterSchema;
+    /** Every field in schema order (groups flattened). */
+    fields: readonly ParameterField[];
+    values: Readonly<ParameterValues>;
+    defaults: Readonly<ParameterValues>;
+    /** Field and group id → shown (see `showIf`). */
+    visible: Readonly<Record<string, boolean>>;
+    /** Group id → collapsed. */
+    collapsed: Readonly<Record<string, boolean>>;
+    /** Field id → the last rejected value's error (cleared when the field is next set). */
+    errors: Readonly<Record<string, string>>;
+    /** Built-in presets first, then user presets. */
+    presets: readonly ParameterPreset[];
+    /** The first preset whose values match the current values, if any. */
+    activePreset: string | null;
+    /** Any value differs from its default. */
+    modified: boolean;
+    /** Playhead time in ms (for keyframes). */
+    time: number;
+    /** Whether a keyframes adapter is attached. */
+    keyframesEnabled: boolean;
+    /** Field id → keyframe state at `time`. */
+    keys: Readonly<Record<string, ParameterKeyState>>;
+    /** The gesture in progress (a field id), if any. */
+    gesture: string | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+type ParameterSetResult = {
+    ok: true;
+    value: ParameterValue;
+} | {
+    ok: false;
+    error: ParameterError;
+    message: string;
+};
+type ParameterSetValuesResult = {
+    ok: true;
+    values: Partial<ParameterValues>;
+    changed: string[];
+} | {
+    ok: false;
+    errors: ParameterError[];
+    message: string;
+};
+type ParameterActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+interface SetParameterOptions {
+    /** Undo step label (default "Change <label>"). */
+    label?: string;
+}
+interface RandomizeParametersOptions {
+    /** Only these fields (default: every visible field that allows it). */
+    ids?: readonly string[];
+    /** Seed for a repeatable result. */
+    seed?: number;
+    /** Random source (default: the controller's). */
+    random?: () => number;
+}
+interface ApplyPresetOptions {
+    /** Keep values the preset leaves out (default: they go back to their defaults). */
+    merge?: boolean;
+}
+/** What `toJSON` returns and `load` takes. */
+interface ParametersSnapshot {
+    values: Partial<ParameterValues>;
+    /** User presets. */
+    presets?: ParameterPreset[];
+}
+/** A repeatable random source (mulberry32). */
+declare function seededRandom(seed: number): () => number;
+/**
+ * Headless state for a parameters panel: values with validation, undo (slider drags merge
+ * into one step), reset, randomize, presets and optional keyframe hooks. `getState()` returns
+ * the same object until something changes, so it works with `useSyncExternalStore`.
+ */
+declare class ParametersController {
+    readonly history: HistoryManager;
+    private schema;
+    private fields;
+    private fieldMap;
+    private defaults;
+    private values;
+    private userPresets;
+    private collapsed;
+    private errors;
+    private time;
+    private keyframes?;
+    private readonly keyTolerance;
+    private readonly random;
+    private readonly onChange?;
+    private readonly listeners;
+    private readonly cleanups;
+    private gestureId;
+    private gestureCount;
+    private revision;
+    private applying;
+    private state;
+    constructor(options: ParametersControllerOptions);
+    private unwatchKeyframes?;
+    private watchKeyframes;
+    /** The current snapshot (stable until the next change). */
+    getState: () => ParametersState;
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe: (listener: (state: ParametersState) => void) => (() => void);
+    getSchema(): ParameterSchema;
+    getField(id: string): ParameterField | undefined;
+    getValue(id: string): ParameterValue | undefined;
+    getValues(): Readonly<ParameterValues>;
+    private indexSchema;
+    /** Values for every field: valid entries of `values`, else `fallback`. Invalid ones are reported. */
+    private adopt;
+    private allPresets;
+    private presetValues;
+    private computeState;
+    private notify;
+    private apply;
+    private command;
+    /** Track updates that keep keys at the playhead in step with new values. */
+    private keyUpdates;
+    private record;
+    private reject;
+    /** Only the entries of `values` that differ from the current values. */
+    private diff;
+    private clearErrors;
+    /**
+     * Sets one value after validating it (`int`s round, colours normalise). Invalid values are
+     * not stored; the error is returned and shown in `state.errors`. One undo step, or part of
+     * the current gesture (see `beginGesture`).
+     */
+    setValue(id: string, value: unknown, options?: SetParameterOptions): ParameterSetResult;
+    /**
+     * Sets several values as one undo step. All-or-nothing: if any id is unknown or any value
+     * invalid, nothing changes and every error is returned.
+     */
+    setValues(values: Partial<ParameterValues> | Record<string, unknown>, options?: SetParameterOptions): ParameterSetValuesResult;
+    /**
+     * Starts a continuous edit of `id` (a slider drag): every `setValue` until `endGesture()`
+     * merges into one undo step.
+     */
+    beginGesture(id: string): void;
+    /** Ends the current gesture; the next change is a new undo step. */
+    endGesture(): void;
+    /** Puts fields (default: all) back to their defaults as one undo step. */
+    reset(ids?: readonly string[]): ParameterActionResult;
+    /**
+     * Picks random values within each field's range, snapped to its step, as one undo step.
+     * Skips hidden fields, `randomize: false`, `readOnly`, image and text fields, and numbers
+     * without both `min` and `max`.
+     */
+    randomize(options?: RandomizeParametersOptions): ParameterSetValuesResult;
+    /** Applies a preset as one undo step. Fields it leaves out return to their defaults unless `merge`. */
+    applyPreset(name: string, options?: ApplyPresetOptions): ParameterActionResult;
+    /** Saves the current values (all fields) as a user preset, replacing one with the same name. Undoable. */
+    savePreset(name: string, options?: {
+        description?: string;
+    }): ParameterActionResult;
+    /** Deletes a user preset (built-in presets cannot be deleted). Undoable. */
+    deletePreset(name: string): ParameterActionResult;
+    private unknownPreset;
+    /** Moves the playhead. `values` (e.g. evaluated from the tracks) are shown without an undo step. */
+    setTime(time: number, values?: Partial<ParameterValues>): void;
+    /** `keyed`, `animated` or `none` for a field at `time` (default: the playhead). */
+    keyState(id: string, time?: number): ParameterKeyState;
+    /** Attaches (or with `undefined` detaches) a keyframes adapter. */
+    setKeyframes(keyframes: ParameterKeyframes | undefined): void;
+    /**
+     * Adds a keyframe with the field's current value at `time` (default: the playhead), or
+     * removes the one already there. One undo step.
+     */
+    toggleKeyframe(id: string, time?: number): {
+        ok: true;
+        keyed: boolean;
+    } | {
+        ok: false;
+        message: string;
+    };
+    /** Collapses or expands a group (view state; not an undo step). */
+    setCollapsed(groupId: string, collapsed: boolean): void;
+    toggleCollapsed(groupId: string): void;
+    /**
+     * Replaces the schema (e.g. after a shader recompiles). Values that still fit their field
+     * are kept; others reset to the new default. Not an undo step; throws a
+     * `ParameterSchemaError` for an invalid schema.
+     */
+    setSchema(schema: ParameterSchema): void;
+    /** Values and user presets, for saving. */
+    toJSON(): ParametersSnapshot;
+    /**
+     * Replaces values (and user presets, when given) without an undo step, e.g. when opening a
+     * document. Missing values use defaults; invalid ones use defaults and are reported in
+     * `state.errors`. Clears the history when `clearHistory` is true.
+     */
+    load(snapshot: ParametersSnapshot, options?: {
+        clearHistory?: boolean;
+    }): void;
+    undo(): boolean;
+    redo(): boolean;
+    /** Stops listening to the history and keyframes adapter. */
+    destroy(): void;
+}
+declare function createParametersController(options: ParametersControllerOptions): ParametersController;
+
+interface ParameterCommandOptions {
+    /** Id prefix (default `parameters.`); use one per panel when several are registered. */
+    prefix?: string;
+    /** Palette group (default `Parameters`, or the schema's title). */
+    group?: string;
+    /** Command scope. Omit for global commands. */
+    scope?: string;
+}
+/** A field as listed for agents: its JSON Schema plus current value and visibility. */
+interface ParameterListing {
+    id: string;
+    label: string;
+    type: ParameterField['type'];
+    description?: string;
+    value: ParameterValue;
+    default: ParameterValue;
+    visible: boolean;
+    keyframe?: 'none' | 'animated' | 'keyed';
+    schema: Record<string, unknown>;
+}
+/**
+ * Palette and agent commands for a parameters panel: list, set (validated, one undo step),
+ * reset, randomize, presets and keyframe toggles. Register them in a `CommandRegistry` and
+ * agents get them through `createCommandToolProvider`. Failures throw sentences, which the
+ * registry returns as `{ ok: false, code: 'failed', message }`.
+ */
+declare function createParameterCommands(controller: ParametersController, options?: ParameterCommandOptions): CommandSpec[];
+
+/** A shader uniform type that can be a control (Flair's `@control` uniforms). */
+type ShaderControlType = 'float' | 'int' | 'bool' | 'vec2' | 'vec3' | 'vec4' | 'sampler2D';
+/** A shader control value: a number, a boolean, vector components (colours are 0–1) or an image URL. */
+type ShaderControlValue = number | boolean | number[] | string;
+/**
+ * The shape of a parsed shader control, e.g. Flair's `ControlDef`
+ * (`uniform vec3 uTint; // @control color default=#77C16A`).
+ */
+interface ShaderControlLike {
+    name: string;
+    type: ShaderControlType;
+    label?: string;
+    /** A `vec3` / `vec4` shown as a colour picker. */
+    color?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    default: ShaderControlValue;
+    description?: string;
+}
+/** One shader control as a parameter field (colour vectors become hex `color` fields). */
+declare function parameterFieldFromShaderControl(control: ShaderControlLike): ParameterField;
+/** A parameter schema for a shader's controls, in source order. */
+declare function parameterSchemaFromShaderControls(controls: readonly ShaderControlLike[], options?: {
+    title?: string;
+}): ParameterSchema;
+/** A parameter value as the shader takes it: hex colours become 0–1 RGB(A) arrays. */
+declare function shaderControlValue(control: ShaderControlLike, value: ParameterValue): ShaderControlValue;
+/** A shader control value as a parameter value: colour arrays become hex. */
+declare function parameterValueFromShaderControl(control: ShaderControlLike, value: ShaderControlValue): ParameterValue;
+
+export { type ApplyPresetOptions, type BooleanParameterField, type ChoiceParameterField, type ColorParameterField, type ImageParameterField, type NumberParameterField, PARAMETER_KEY_TOLERANCE, type ParameterActionResult, type ParameterChoiceOption, type ParameterCoercion, type ParameterCommandOptions, type ParameterCondition, type ParameterConditionTest, type ParameterEasing, type ParameterError, type ParameterField, type ParameterFieldType, type ParameterGroup, type ParameterImageOption, type ParameterKeyState, type ParameterKeyframe, type ParameterKeyframeStore, type ParameterKeyframes, type ParameterListing, type ParameterPreset, type ParameterSchema, ParameterSchemaError, type ParameterSchemaItem, type ParameterSetResult, type ParameterSetValuesResult, type ParameterTrack, type ParameterValue, type ParameterValues, ParametersController, type ParametersControllerOptions, type ParametersSnapshot, type ParametersState, type RandomizeParametersOptions, type SetParameterOptions, type ShaderControlLike, type ShaderControlType, type ShaderControlValue, type TextParameterField, type VectorParameterField, checkParameterSchema, choiceOptionLabel, clampParameterNumber, cloneValue, coerceParameterValue, createParameterCommands, createParameterKeyframeStore, createParametersController, evaluateParameterCondition, findParameterKeyframe, formatParameterNumber, formatParameterValue, getChoiceOptions, getParameterDefaults, getParameterFields, getParameterGroups, getParameterKeyState, getParameterVisibility, hexToRgba01, humanizeParameterId, isParameterGroup, isSliderField, normalizeHexColor, parameterDecimals, parameterFieldFromShaderControl, parameterFieldToJsonSchema, parameterLabel, parameterSchemaFromShaderControls, parameterSchemaToJsonSchema, parameterStep, parameterValueFromShaderControl, parameterValuesEqual, parseParameterNumberInput, rgba01ToHex, seededRandom, shaderControlValue, validateParameterValue, validateParameterValues, vectorComponentField, vectorSize, withParameterKeyframe, withoutParameterKeyframe };