@pixerate/flair 0.0.0-stage → 0.1.0

package/dist/clock-BhdXWH-n.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Time source for generative animations and playback.
+ * By default that is real time (animation frames and timers).
+ * A ManualClock instead moves only when told to, enabling frame-exact
+ * rendering, video recording, scrubbing, or fast simulation without waiting.
+ */
+interface Clock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Resolves on the next frame. */
+    frame(): Promise<void>;
+    /** Resolves after `ms` milliseconds of this clock's time. */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Whether the clock follows wall time. Live clocks stop when the tab is in
+     * the background (browsers pause animation frames there).
+     */
+    readonly live: boolean;
+}
+declare const pageHidden: () => boolean;
+declare const realClock: Clock;
+/**
+ * A clock that only moves when {@link advance} or {@link tick} is called.
+ * Each call fires the sleeps that fall due, in order, letting awaiting code
+ * run before the next sleep fires, then resolves pending frames.
+ */
+declare class ManualClock implements Clock {
+    readonly live = false;
+    private time;
+    private frames;
+    private sleepers;
+    private seq;
+    constructor(start?: number);
+    now(): number;
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    get pending(): boolean;
+    advance(ms: number): Promise<void>;
+    tick(fps?: number): Promise<void>;
+}
+/**
+ * A repeatable pseudo-random number in [0, 1) for a key and index.
+ * Useful for deterministic, reproducible animations.
+ */
+declare function jitter(key: string, n: number): number;
+
+export { type Clock as C, ManualClock as M, jitter as j, pageHidden as p, realClock as r };

package/dist/controls-DdXMbovi.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Controls declared in a shader's source. A uniform becomes a control when
+ * its declaration carries an `@control` comment on the same line:
+ *
+ *   uniform float uSpeed;  // @control min=0 max=4 default=1 label="Speed"
+ *   uniform int uSteps;    // @control min=1 max=64 default=16
+ *   uniform bool uGrain;   // @control default=true label="Film grain"
+ *   uniform vec2 uCenter;  // @control min=-1 max=1 default=0,0
+ *   uniform vec3 uTint;    // @control color default=#77C16A label="Tint"
+ *   uniform sampler2D uPhoto; // @control filter=linear wrap=clamp label="Photo"
+ *
+ * The source is the single source of truth for which controls exist and
+ * their defaults; values someone picks are stored next to it.
+ */
+/** The uniform types a control can have. */
+type ControlType = "float" | "int" | "bool" | "vec2" | "vec3" | "vec4" | "sampler2D";
+/**
+ * A control's value: a number (`float`, `int`), a boolean (`bool`), the
+ * components of a vector, or an image URL (`sampler2D`; "" for none).
+ */
+type ControlValue = number | boolean | number[] | string;
+/** How an image is sampled: Shadertoy's channel settings. */
+interface TextureSettings {
+    /** `mipmap` (the default), `linear` or `nearest` (pixelated). */
+    filter: "mipmap" | "linear" | "nearest";
+    /** Outside 0–1: `repeat` (the default), `clamp` to the edge, or `mirror`. */
+    wrap: "repeat" | "clamp" | "mirror";
+}
+/** A control parsed from an annotated uniform. */
+interface ControlDef {
+    /** The uniform's name. */
+    name: string;
+    type: ControlType;
+    /** `label="…"`, or the name made readable ("uFlowSpeed" → "Flow speed"). */
+    label: string;
+    /** A `vec3` or `vec4` shown as a colour picker. */
+    color: boolean;
+    min: number;
+    /** Always greater than `min`. */
+    max: number;
+    step: number;
+    default: ControlValue;
+    /** 1-based line of the declaration. */
+    line: number;
+    /** Sampling settings, for `sampler2D` controls only. */
+    texture?: TextureSettings;
+}
+/** The number of components a control type has: 1 for scalars, `bool` and `sampler2D`, else the vector size. */
+declare function componentCount(type: ControlType): number;
+/** "uFlowSpeed" → "Flow speed". */
+declare function humanise(name: string): string;
+/** "#77C16A" (or "#7c6") → [0.467, 0.757, 0.416]; null when it is not a hex colour. */
+declare function hexToRgb(hex: string): number[] | null;
+/** [0.467, 0.757, 0.416] → "#77c16a". Components are clamped to 0–1; a fourth (alpha) is ignored. */
+declare function rgbToHex(rgb: number[]): string;
+/**
+ * The controls a source declares, in source order. A uniform declared twice
+ * counts once (the first wins). Unknown attributes are ignored, and missing
+ * or malformed ones fall back to defaults: `min=0`, `max=1` (10 for `int`),
+ * a step of 1/200 of the range (1 for `int`).
+ */
+declare function parseControls(source: string): ControlDef[];
+/** The value a control has: the stored one when it still fits the declaration, else the default. */
+declare function controlValue(control: ControlDef, values: Record<string, ControlValue> | undefined): ControlValue;
+/** What {@link checkControlValue} decides: the value to store, or a sentence saying what the control takes. */
+type ControlCheck = {
+    ok: true;
+    value: ControlValue;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Checks a value from outside (an agent's tool call, a URL, a form) against a
+ * control. Colours also accept "#RRGGBB"; `int` values are rounded. Images
+ * take a URL: `https:`, `http:`, `data:image/…`, `blob:` or a relative path
+ * ("" for none).
+ */
+declare function checkControlValue(control: ControlDef, raw: unknown): ControlCheck;
+/**
+ * {@link checkControlValue} for controls whose values are never strings:
+ * returns the value to store, or the message. An image control's value is a
+ * string too, so use `checkControlValue` where images can appear.
+ */
+declare function coerceControlValue(control: ControlDef, raw: unknown): ControlValue | string;
+/** Whether a string is a URL an image control can load: `http(s):`, `data:image/`, `blob:` or a relative path. */
+declare function isImageUrl(url: string): boolean;
+/** The image URLs the controls show with these values, without duplicates or empty ones. */
+declare function imageUrls(controls: ControlDef[], values: Record<string, ControlValue> | undefined): string[];
+/**
+ * A value as compact, JSON-friendly data: colours as hex, numbers to three
+ * decimals. A long `data:` URL is shortened to its type and size, which
+ * keeps it out of an agent's context but cannot be stored back.
+ */
+declare function describeValue(control: ControlDef, value: ControlValue): unknown;
+
+export { type ControlValue as C, type TextureSettings as T, type ControlDef as a, type ControlType as b, type ControlCheck as c, checkControlValue as d, coerceControlValue as e, componentCount as f, controlValue as g, describeValue as h, hexToRgb as i, humanise as j, imageUrls as k, isImageUrl as l, parseControls as p, rgbToHex as r };

package/dist/editor/index.d.ts

@@ -0,0 +1,413 @@
+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 { S as SvgMotion } from '../motion-D0TVv2CF.js';
+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 Clock } from '../clock-BhdXWH-n.js';
+import { AgentToolProvider, McpToolResult, McpToolDefinition } from '@pixerate/editor/generation';
+
+/**
+ * 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.
+ */
+
+/** 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;
+/** Every easing preset, in picker order. */
+declare const EASING_PRESETS: readonly EasingPreset[];
+interface Keyframe {
+    /** Ms from the start of the timeline. */
+    time: number;
+    value: ControlValue;
+    /** Easing of the segment from this keyframe to the next (default `linear`). */
+    easing?: Easing;
+}
+interface Track {
+    /** 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
+ * round, and booleans and images switch halfway.
+ */
+declare function interpolateControlValue(control: ControlDef | undefined, a: ControlValue, b: ControlValue, t: number): ControlValue;
+/** A track's value at `time` (ms), or undefined when it has no keyframes or is disabled. */
+declare function evaluateTrack(track: Track | undefined, time: number, control?: ControlDef): ControlValue | undefined;
+/** Keyframes sorted by time, one per time (the later of two at the same time wins). */
+declare function normalizeKeyframes(keyframes: readonly Keyframe[]): Keyframe[];
+/** The keyframe times across tracks, sorted and without duplicates. */
+declare function keyframeTimes(tracks: Record<string, Track>): number[];
+
+/**
+ * The document an effect editor edits: an effect (a shader's source, or a
+ * vector picture with its controls), the values picked for its controls,
+ * keyframed tracks, presets and a timeline. Plain JSON, so it can be saved,
+ * diffed, and written by an agent.
+ */
+
+/** What is being edited: a fragment shader, or an animated SVG with declared controls. */
+type EffectSource = {
+    kind: "shader";
+    source: string;
+} | {
+    kind: "vector";
+    motion: SvgMotion;
+    controls: VectorControl[];
+    hold?: number;
+};
+interface EffectDocument {
+    /** Format version (1). */
+    version: 1;
+    name: string;
+    /** The catalog effect it started from, if any. */
+    basedOn?: string;
+    effect: EffectSource;
+    /** Picked control values; controls without one use their default. */
+    values: Record<string, ControlValue>;
+    /** Keyframed controls, by control name. A track overrides the control's value. */
+    tracks: Record<string, Track>;
+    /** Timeline length in ms. */
+    duration: number;
+    loop: boolean;
+    presets: EffectPreset[];
+}
+/**
+ * A new document: blank (a small starter shader), from a catalog effect (by
+ * id or definition), or from a shader's source.
+ */
+declare function createEffectDocument(from?: string | EffectDefinition | {
+    source: string;
+    name?: string;
+}): EffectDocument;
+/** The document's controls. */
+declare function documentControls(doc: EffectDocument): ControlDef[];
+/** Every control's value at `time` (ms): its track if it has one, else the picked value, else its default. */
+declare function valuesAt(doc: EffectDocument, time: number, controls?: ControlDef[]): Record<string, ControlValue>;
+/** A vector document's picture with the values at `time` filled in; undefined for shaders. */
+declare function motionAt(doc: EffectDocument, time: number): SvgMotion | undefined;
+/**
+ * Problems with a document, as sentences: unknown controls in values, tracks
+ * or presets, values a control cannot take, bad keyframes, and (for vector
+ * effects) problems with the picture. Shader compile errors come from the
+ * GPU, not from here.
+ */
+declare function documentIssues(doc: EffectDocument): string[];
+/** Reads a document from JSON (or a parsed object), checking its shape. */
+declare function parseEffectDocument(input: string | unknown): {
+    ok: true;
+    document: EffectDocument;
+} | {
+    ok: false;
+    errors: string[];
+};
+
+/**
+ * A UI-agnostic effect editor: the document, its undo history, a playhead,
+ * and commands that menus, shortcuts, a palette and agents all run by id.
+ * Bring your own UI (any framework, or none) and your own renderer binding
+ * (see `bindShaderRenderer` and `bindSvgView`).
+ */
+
+/** What an edit did: `ok`, or why it was refused (in a sentence an agent can act on). */
+type EditResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/** The result of compiling the shader, as reported by a renderer (see `reportCompile`). */
+interface CompileReport {
+    ok: boolean;
+    errors: CompileError[];
+}
+interface EffectEditorState {
+    document: EffectDocument;
+    controls: ControlDef[];
+    /** Every control's value at the playhead. */
+    values: Record<string, ControlValue>;
+    /** Problems with the document (see `documentIssues`). */
+    issues: string[];
+    /** The latest compile report, or null before a renderer reported one (and for vector effects). */
+    compile: CompileReport | null;
+    /** Playhead, ms. */
+    time: number;
+    playing: boolean;
+    /** Whether changing a value keyframes it at the playhead. */
+    recording: boolean;
+    history: HistoryState;
+}
+interface EffectEditorOptions {
+    /** The document to edit, or what to start one from (see `createEffectDocument`). */
+    document?: EffectDocument;
+    from?: string | EffectDefinition | {
+        source: string;
+        name?: string;
+    };
+    /** Undo history to record into (default: a new one, 100 steps deep). */
+    history?: HistoryManager;
+    /** Time source for playback (default: animation frames). */
+    clock?: Clock;
+    /** Ms within which value changes to one control merge into one undo step (default 400). */
+    mergeWindowMs?: number;
+}
+/**
+ * Edits one effect. Every change to the document is an undo step (value
+ * changes in quick succession, like a slider drag, merge into one), and
+ * subscribers hear about every change to the state.
+ */
+declare class EffectEditor {
+    readonly history: HistoryManager;
+    /** Every editing action, by id: for menus, shortcuts, a command palette and agents. */
+    readonly commands: CommandRegistry<EffectEditor>;
+    private doc;
+    private controlsCache;
+    private compileReport;
+    private time;
+    private playing;
+    private recording;
+    private readonly clock;
+    private readonly mergeWindowMs;
+    private readonly listeners;
+    private state;
+    private readonly unsubscribeHistory;
+    private disposed;
+    constructor(options?: EffectEditorOptions);
+    get document(): EffectDocument;
+    /** The current state; the same object until something changes (safe for `useSyncExternalStore`). */
+    getState(): EffectEditorState;
+    /** Calls `listener` with the new state after every change; returns an unsubscribe function. */
+    subscribe(listener: (state: EffectEditorState) => void): () => void;
+    /** The document's controls. */
+    get controls(): ControlDef[];
+    /** The document as JSON. */
+    toJSON(): EffectDocument;
+    /** Replaces the document (one undo step). */
+    replaceDocument(next: EffectDocument, label?: string): EditResult;
+    /** Starts over from a catalog effect, a shader source, or blank (one undo step). */
+    load(from?: string | EffectDefinition | {
+        source: string;
+        name?: string;
+    }, preset?: string): EditResult;
+    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). */
+    setMotion(motion: SvgMotion, controls?: Extract<EffectDocument["effect"], {
+        kind: "vector";
+    }>["controls"]): EditResult;
+    /** Called by a renderer binding with the result of compiling the current source. */
+    reportCompile(report: CompileReport): void;
+    /**
+     * Sets a control's value. With a track on that control (or while
+     * recording) it sets a keyframe at the playhead instead. Quick successive
+     * changes to one control merge into one undo step.
+     */
+    setValue(name: string, value: unknown): EditResult;
+    /** Sets several values in one undo step; refuses them all if any is wrong. */
+    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. */
+    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. */
+    savePreset(name: string, names?: readonly string[]): EditResult;
+    deletePreset(name: string): EditResult;
+    /** Sets (or replaces) a keyframe; `value` defaults to the control's value at that time. */
+    setKeyframe(name: string, time: number, value?: unknown, easing?: Easing, mergeKey?: string): EditResult;
+    removeKeyframe(name: string, time: number): EditResult;
+    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;
+    setTiming(timing: {
+        duration?: number;
+        loop?: boolean;
+    }): EditResult;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Moves the playhead (clamped to the timeline). */
+    seek(time: number): void;
+    stop(): void;
+    /** While recording, changing a value keyframes it at the playhead. */
+    setRecording(recording: boolean): void;
+    undo(): boolean;
+    redo(): boolean;
+    dispose(): void;
+    private run;
+    private analysis;
+    private control;
+    private unknownControl;
+    private commit;
+    private changed;
+}
+/** A new {@link EffectEditor}. */
+declare function createEffectEditor(options?: EffectEditorOptions): EffectEditor;
+
+/** A summary of the editor's state for agents: the document, controls, values at the playhead, issues and compile errors. */
+declare function describeEditor(editor: EffectEditor): {
+    controls: {
+        default: ControlValue;
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+        color?: boolean | undefined;
+        name: string;
+        type: ControlType;
+        label: string;
+    }[];
+    values: Record<string, ControlValue>;
+    tracks: Record<string, Track>;
+    presets: string[];
+    timeline: {
+        duration: number;
+        loop: boolean;
+        time: number;
+        playing: boolean;
+        recording: boolean;
+    };
+    issues: string[];
+    compile: CompileReport | null;
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    source: string;
+    name: string;
+    basedOn: string | undefined;
+    kind: "shader" | "vector";
+} | {
+    controls: {
+        default: ControlValue;
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+        color?: boolean | undefined;
+        name: string;
+        type: ControlType;
+        label: string;
+    }[];
+    values: Record<string, ControlValue>;
+    tracks: Record<string, Track>;
+    presets: string[];
+    timeline: {
+        duration: number;
+        loop: boolean;
+        time: number;
+        playing: boolean;
+        recording: boolean;
+    };
+    issues: string[];
+    compile: CompileReport | null;
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    motion: SvgMotion;
+    vectorControls: VectorControl[];
+    name: string;
+    basedOn: string | undefined;
+    kind: "shader" | "vector";
+};
+/** The effect editor's commands (the registry adds `history.undo` / `history.redo`). */
+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).
+ */
+
+interface EffectToolProviderOptions {
+    /** Provider id (default `flair-effect`). */
+    id?: string;
+    /** Prefix every tool name with `<namespace>__`. */
+    namespace?: string;
+    /**
+     * Captures the preview as a data URL (PNG or JPEG), adding a `view_effect`
+     * tool so the agent can look at what it made. With `ShaderRenderer`:
+     * `() => renderer.capture({ type: "image/png" })`.
+     */
+    capture?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Commands agents may not see or run. */
+    exclude?: (id: string) => boolean;
+}
+/**
+ * The effect editor as agent tools (MCP-shaped, for `@pixerate/editor`'s
+ * `ToolRegistry` or any tool loop):
+ *
+ * - `list_commands`, `run_command`, `run_commands`: every editor command
+ *   (describe, search the catalog, load, set source, values, presets,
+ *   keyframes, timing, undo and redo).
+ * - `view_effect`, when `capture` is given: an image of the preview.
+ */
+declare function createEffectToolProvider(editor: EffectEditor, options?: EffectToolProviderOptions): AgentToolProvider;
+/** 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.
+ */
+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. */
+declare const EFFECT_AGENT_INSTRUCTIONS: string;
+
+/**
+ * Keeps a preview in step with an editor: the editor owns the playhead and
+ * the values; the preview draws what it is told.
+ */
+
+/** What {@link bindShaderRenderer} needs of a renderer (`ShaderRenderer` fits). */
+interface ShaderPreview {
+    setSource(source: string): CompileStatus;
+    setValues(values: Record<string, ControlValue> | undefined): void;
+    /** Seconds. */
+    seek(time: number): void;
+    pause(): void;
+}
+/**
+ * Drives a shader preview from the editor: the source (reporting compile
+ * results back), the values at the playhead, and the time. The renderer is
+ * paused so the editor's playhead is the only clock. Returns an unbind
+ * function.
+ */
+declare function bindShaderRenderer(editor: EffectEditor, renderer: ShaderPreview): () => void;
+/**
+ * Draws a vector effect into `container` from the editor: the picture with
+ * the values at the playhead, at the playhead's time. Returns an unbind
+ * function, which also removes the picture.
+ */
+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 };