@pixerate/flair 0.1.1 → 0.3.0

package/dist/editor/index.d.ts

@@ -1,60 +1,47 @@
-import { V as VectorControl, c as EffectPreset, E as EffectDefinition } from '../types-CkKkavvB.js';
-import { C as ControlValue, a as ControlDef, b as ControlType } from '../controls-DdXMbovi.js';
+import { d as VectorControl, c as EffectPreset, E as EffectDefinition } from '../types-CsFUZZIv.js';
+import { C as ControlValue, a as ControlDef, b as ControlType } from '../controls-Syr6drzO.js';
 import { S as SvgMotion } from '../motion-D0TVv2CF.js';
+import { AnimationEasingPreset, AnimationEasing, AnimationTrack, AnimationKeyframe, cubicBezierAt as cubicBezierAt$1, evaluateEasing as evaluateEasing$1 } from '@pixerate/editor/animation';
+export { CubicBezierEasing, SpringEasing } from '@pixerate/editor/animation';
 import { CommandRegistry, CommandSpec } from '@pixerate/editor/commands';
 import { HistoryManager, HistoryState } from '@pixerate/editor/history';
-import { C as CompileError, a as CompileStatus } from '../renderer-Oyynz-fs.js';
+import { C as CompileError, a as CompileStatus } from '../renderer-mzvhKzKa.js';
 import { C as Clock } from '../clock-BhdXWH-n.js';
-import { AgentToolProvider, McpToolResult, McpToolDefinition } from '@pixerate/editor/generation';
+import { AgentToolProvider, McpToolResult, ToolRegistryOptions, ToolRegistry, McpToolDefinition } from '@pixerate/editor/tools';
+import { ParameterImageOption, ParametersController, ParameterField, ParameterSchema, ParameterValue, ParameterValues } from '@pixerate/editor/parameters';
 
 /**
  * Keyframed control values. A track holds keyframes `{ time (ms), value,
  * easing }` for one control; the easing governs the segment leaving its
- * keyframe. The shapes and easing names match `@pixerate/editor`'s keyframe
- * animation (`AnimationTrack`, `AnimationEasing`), so timelines move between
- * the two unchanged.
+ * keyframe. Easing comes from `@pixerate/editor/animation`, and tracks keep
+ * its `AnimationTrack` shape; Flair adds what control values need beyond
+ * numbers and colours (vectors, booleans, images, ints).
  */
 
 /** Named easings (CSS keywords plus back and spring curves). */
-type EasingPreset = "linear" | "hold" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | "ease-in-back" | "ease-out-back" | "spring";
-interface CubicBezierEasing {
-    type: "cubic-bezier";
-    x1: number;
-    y1: number;
-    x2: number;
-    y2: number;
-}
-interface SpringEasing {
-    type: "spring";
-    /** Default 170. */
-    stiffness?: number;
-    /** Default 26. */
-    damping?: number;
-    /** Default 1. */
-    mass?: number;
-}
-type Easing = EasingPreset | CubicBezierEasing | SpringEasing;
+type EasingPreset = AnimationEasingPreset;
+type Easing = AnimationEasing;
+
 /** Every easing preset, in picker order. */
 declare const EASING_PRESETS: readonly EasingPreset[];
-interface Keyframe {
-    /** Ms from the start of the timeline. */
-    time: number;
+/** Eased progress at `u` (0–1) through a segment `durationMs` long (`@pixerate/editor`'s easing engine). */
+declare const evaluateEasing: typeof evaluateEasing$1;
+/** CSS `cubic-bezier(x1, y1, x2, y2)` solved for y at progress x. */
+declare const cubicBezierAt: typeof cubicBezierAt$1;
+/**
+ * Whether `value` is an easing (a preset name, a cubic bezier or a spring),
+ * with a spring's stiffness, damping and mass above 0 when given.
+ */
+declare function isEasing(value: unknown): value is Easing;
+/** A keyframe of a control: like `AnimationKeyframe`, with any control value (vectors and booleans too). */
+interface Keyframe extends Omit<AnimationKeyframe, "value"> {
     value: ControlValue;
-    /** Easing of the segment from this keyframe to the next (default `linear`). */
-    easing?: Easing;
 }
-interface Track {
+/** A control's keyframes: `AnimationTrack`'s shape, with control values. */
+interface Track extends Omit<AnimationTrack, "keyframes"> {
     /** Sorted by time, at most one per time. */
     keyframes: Keyframe[];
-    /** Disabled tracks keep their keyframes but do not animate (default `true`). */
-    enabled?: boolean;
 }
-/** Whether `value` is an easing this module understands. */
-declare function isEasing(value: unknown): value is Easing;
-/** CSS `cubic-bezier(x1, y1, x2, y2)` solved for y at progress x. */
-declare function cubicBezierAt(x1: number, y1: number, x2: number, y2: number, x: number): number;
-/** Eased progress at `u` (0–1) through a segment `durationMs` long. */
-declare function evaluateEasing(easing: Easing | undefined, u: number, durationMs?: number): number;
 /**
  * A control value `t` of the way from `a` to `b`: numbers and vectors blend
  * (overshooting with back and spring easings), colours blend in Oklab, `int`s
@@ -75,14 +62,18 @@ declare function keyframeTimes(tracks: Record<string, Track>): number[];
  * diffed, and written by an agent.
  */
 
-/** What is being edited: a fragment shader, or an animated SVG with declared controls. */
+/**
+ * What is being edited: a fragment shader, or an animated SVG. Both declare
+ * their controls in themselves (`// @control`, `{{name: type …}}`); a vector
+ * effect's optional `controls` list is for pictures written before that.
+ */
 type EffectSource = {
     kind: "shader";
     source: string;
 } | {
     kind: "vector";
     motion: SvgMotion;
-    controls: VectorControl[];
+    controls?: VectorControl[];
     hold?: number;
 };
 interface EffectDocument {
@@ -221,7 +212,7 @@ declare class EffectEditor {
     rename(name: string): EditResult;
     /** Replaces a shader's source. Compile errors arrive later, from the renderer (see `reportCompile`). */
     setSource(source: string): EditResult;
-    /** Replaces a vector effect's picture (and optionally its controls). */
+    /** Replaces a vector effect's picture, whose `{{name: type …}}` placeholders declare its controls (and optionally a `controls` list). */
     setMotion(motion: SvgMotion, controls?: Extract<EffectDocument["effect"], {
         kind: "vector";
     }>["controls"]): EditResult;
@@ -237,7 +228,7 @@ declare class EffectEditor {
     setValues(values: Record<string, unknown>): EditResult;
     /** Back to defaults: the named controls, or all of them (values only; tracks stay). */
     resetValues(names?: readonly string[]): EditResult;
-    /** Random values in each control's range (colours anywhere), for exploring. */
+    /** Random values in each control's range (colours anywhere), for exploring. Images and text keep theirs. */
     randomize(names?: readonly string[], random?: () => number): EditResult;
     applyPreset(name: string): EditResult;
     /** Saves the current values (all, or the named ones) as a preset, replacing one of the same name. */
@@ -249,6 +240,19 @@ declare class EffectEditor {
     setKeyframeEasing(name: string, time: number, easing: Easing): EditResult;
     /** Removes a control's track; it keeps the value it had at the playhead. */
     clearTrack(name: string): EditResult;
+    /**
+     * Replaces a control's whole track (or removes it with `undefined`), one
+     * undo step. Every keyframe is checked like `setKeyframe`; values may be
+     * any form the control accepts (colours as "#RRGGBB" too).
+     */
+    setTrack(name: string, track: {
+        keyframes: readonly {
+            time: number;
+            value: unknown;
+            easing?: unknown;
+        }[];
+        enabled?: boolean;
+    } | undefined): EditResult;
     setTiming(timing: {
         duration?: number;
         loop?: boolean;
@@ -333,8 +337,8 @@ declare function describeEditor(editor: EffectEditor): {
         canUndo: boolean;
         canRedo: boolean;
     };
+    vectorControls?: VectorControl[] | undefined;
     motion: SvgMotion;
-    vectorControls: VectorControl[];
     name: string;
     basedOn: string | undefined;
     kind: "shader" | "vector";
@@ -345,7 +349,8 @@ declare function effectCommands(): CommandSpec<EffectEditor>[];
 /**
  * Agents edit effects through the editor's commands. Flair ships the tools
  * and the instructions; the model, its credentials and the agent loop are
- * the host's (bridge the provider into an MCP server or any tool-calling LLM).
+ * the host's. Serve the tools with `@pixerate/editor/tools`' `ToolRegistry`
+ * (MCP `tools/list` and `tools/call`), or call them directly with `callTool`.
  */
 
 interface EffectToolProviderOptions {
@@ -372,12 +377,21 @@ interface EffectToolProviderOptions {
  * - `view_effect`, when `capture` is given: an image of the preview.
  */
 declare function createEffectToolProvider(editor: EffectEditor, options?: EffectToolProviderOptions): AgentToolProvider;
+/**
+ * A `ToolRegistry` (from `@pixerate/editor/tools`) serving the effect editor's
+ * tools: `listTools()` and `callTool(name, args)` are MCP's `tools/list` and
+ * `tools/call`, with arguments checked against each tool's schema. Register
+ * more providers on it to give the agent other tools too.
+ */
+declare function createEffectToolRegistry(editor: EffectEditor, options?: EffectToolProviderOptions & {
+    registry?: ToolRegistryOptions;
+}): ToolRegistry;
 /** A provider's tool definitions without their handlers, to send to a model. */
 declare function toolDefinitions(provider: AgentToolProvider): McpToolDefinition[];
 /**
- * Runs one of a provider's tools by name, for hosts without a `ToolRegistry`:
- * the handler's result comes back as an MCP `tools/call` result, and a
- * thrown error as an `isError` result.
+ * Runs one of a provider's tools by name without a registry: the handler's
+ * result comes back as an MCP `tools/call` result, and a thrown error as an
+ * `isError` result. (A `ToolRegistry` also checks the arguments first.)
  */
 declare function callTool(provider: AgentToolProvider, name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
 /** A system prompt for agents that author effects with these tools. Add your product's own guidance to it. */
@@ -410,4 +424,42 @@ declare function bindShaderRenderer(editor: EffectEditor, renderer: ShaderPrevie
  */
 declare function bindSvgView(editor: EffectEditor, container: HTMLElement): () => void;
 
-export { type CompileReport, type CubicBezierEasing, EASING_PRESETS, EFFECT_AGENT_INSTRUCTIONS, type Easing, type EasingPreset, type EditResult, type EffectDocument, EffectEditor, type EffectEditorOptions, type EffectEditorState, type EffectSource, type EffectToolProviderOptions, type Keyframe, type ShaderPreview, type SpringEasing, type Track, bindShaderRenderer, bindSvgView, callTool, createEffectDocument, createEffectEditor, createEffectToolProvider, cubicBezierAt, describeEditor, documentControls, documentIssues, effectCommands, evaluateEasing, evaluateTrack, interpolateControlValue, isEasing, keyframeTimes, motionAt, normalizeKeyframes, parseEffectDocument, toolDefinitions, valuesAt };
+/**
+ * An effect's controls as a `@pixerate/editor/parameters` schema, and a
+ * parameters controller kept in step with an `EffectEditor`. With them, any
+ * parameters UI (the ready-made React and Svelte panels, or your own) edits
+ * an effect: values, image picks and keyframe diamonds go through the effect
+ * editor, so its undo history and agent tools see every change.
+ */
+
+interface EffectParameterOptions {
+    /** Pictures image controls offer to pick from (any URL still works). */
+    images?: readonly ParameterImageOption[];
+    /** Schema title (default: none). */
+    title?: string;
+}
+/** One control as a parameter field. */
+declare function parameterFieldFor(control: ControlDef, options?: EffectParameterOptions): ParameterField;
+/** An effect's controls as a parameters schema. */
+declare function parameterSchemaFor(controls: readonly ControlDef[], options?: EffectParameterOptions): ParameterSchema;
+/** A control value as a parameter value: colours become `#rrggbb` (`#rrggbbaa` for `vec4`). */
+declare function toParameterValue(control: ControlDef, value: ControlValue): ParameterValue;
+/** Control values as parameter values (see {@link toParameterValue}). */
+declare function toParameterValues(controls: readonly ControlDef[], values: Record<string, ControlValue>): ParameterValues;
+interface EffectParametersBinding {
+    /** Drive a parameters UI with it (e.g. `<ParametersPanel controller={…} />`). */
+    readonly controller: ParametersController;
+    /** Stops following the editor. */
+    dispose(): void;
+}
+/**
+ * A `ParametersController` for the effect in `editor`, kept in step with it:
+ * the schema follows the effect's controls (a recompiled shader updates it),
+ * values and the playhead follow the editor, and changes made through the
+ * controller (fields, keyframe diamonds, reset, randomize) are applied to the
+ * editor, which records the undo steps. Use the editor's undo, not the
+ * controller's, and its presets (the controller's own presets are not saved).
+ */
+declare function bindEffectParameters(editor: EffectEditor, options?: EffectParameterOptions): EffectParametersBinding;
+
+export { type CompileReport, EASING_PRESETS, EFFECT_AGENT_INSTRUCTIONS, type Easing, type EasingPreset, type EditResult, type EffectDocument, EffectEditor, type EffectEditorOptions, type EffectEditorState, type EffectParameterOptions, type EffectParametersBinding, type EffectSource, type EffectToolProviderOptions, type Keyframe, type ShaderPreview, type Track, bindEffectParameters, bindShaderRenderer, bindSvgView, callTool, createEffectDocument, createEffectEditor, createEffectToolProvider, createEffectToolRegistry, cubicBezierAt, describeEditor, documentControls, documentIssues, effectCommands, evaluateEasing, evaluateTrack, interpolateControlValue, isEasing, keyframeTimes, motionAt, normalizeKeyframes, parameterFieldFor, parameterSchemaFor, parseEffectDocument, toParameterValue, toParameterValues, toolDefinitions, valuesAt };