@pixerate/editor 0.147.0 → 0.148.0

package/dist/effects/types.d.cts

@@ -8,6 +8,7 @@
  */
 import type { JsonSchema } from '../tools/schema.cjs';
 import type { FlairSvgAnimation } from '../animation-editor/flair.cjs';
+import type { EffectAuthoringSession, EffectAuthoringSource } from './authoring.cjs';
 /** How an effect is drawn: a pixel shader, an animated vector picture, or motion applied to someone else's vector art. */
 export type EffectKind = 'shader' | 'vector' | 'motion';
 /**
@@ -166,8 +167,10 @@ export interface EffectProviderCapabilities {
     supportsVector: boolean;
     /** Largest width or height a renderer accepts (px). */
     maxSize?: number;
+    /** Implements `openAuthoring`: effects can be edited, not only used. */
+    supportsAuthoring?: boolean;
 }
-type MaybePromise<T> = T | Promise<T>;
+export type MaybePromise<T> = T | Promise<T>;
 /**
  * A source of effects. Implementations live outside this library (for example Flair's
  * `flairEffects()`); `createFakeEffectProvider` is a small reference implementation.
@@ -194,5 +197,9 @@ export interface EffectProvider {
      * effect cannot use with `EffectUnsupportedError`.
      */
     applyVectorEffect?(id: string, target: EffectVectorTarget, values?: EffectValues): MaybePromise<EffectVectorMotion>;
+    /**
+     * Opens an effect for editing. Present when `capabilities.supportsAuthoring`. Unknown ids throw
+     * `UnknownEffectError`; an effect the provider cannot edit throws `EffectUnsupportedError`.
+     */
+    openAuthoring?(from: EffectAuthoringSource): MaybePromise<EffectAuthoringSession>;
 }
-export {};

package/dist/effects/types.d.ts

@@ -8,6 +8,7 @@
  */
 import type { JsonSchema } from '../tools/schema.js';
 import type { FlairSvgAnimation } from '../animation-editor/flair.js';
+import type { EffectAuthoringSession, EffectAuthoringSource } from './authoring.js';
 /** How an effect is drawn: a pixel shader, an animated vector picture, or motion applied to someone else's vector art. */
 export type EffectKind = 'shader' | 'vector' | 'motion';
 /**
@@ -166,8 +167,10 @@ export interface EffectProviderCapabilities {
     supportsVector: boolean;
     /** Largest width or height a renderer accepts (px). */
     maxSize?: number;
+    /** Implements `openAuthoring`: effects can be edited, not only used. */
+    supportsAuthoring?: boolean;
 }
-type MaybePromise<T> = T | Promise<T>;
+export type MaybePromise<T> = T | Promise<T>;
 /**
  * A source of effects. Implementations live outside this library (for example Flair's
  * `flairEffects()`); `createFakeEffectProvider` is a small reference implementation.
@@ -194,5 +197,9 @@ export interface EffectProvider {
      * effect cannot use with `EffectUnsupportedError`.
      */
     applyVectorEffect?(id: string, target: EffectVectorTarget, values?: EffectValues): MaybePromise<EffectVectorMotion>;
+    /**
+     * Opens an effect for editing. Present when `capabilities.supportsAuthoring`. Unknown ids throw
+     * `UnknownEffectError`; an effect the provider cannot edit throws `EffectUnsupportedError`.
+     */
+    openAuthoring?(from: EffectAuthoringSource): MaybePromise<EffectAuthoringSession>;
 }
-export {};

package/dist/effects/ui.d.cts

@@ -23,6 +23,14 @@ export declare const effectFieldValue: (field: ParameterField, value: unknown) =
  * differ, for a transition's two sides).
  */
 export declare function effectSamplePicture(width: number, height: number, variant?: number): EffectPixels;
+/**
+ * Sample pictures for an effect's image inputs (`effectSamplePicture`; a transition's `to` gets
+ * the second variant), so previews of filters and transitions have something to change.
+ */
+export declare function effectSampleInputs(description: Pick<EffectDescription, 'inputs'>, size: {
+    width: number;
+    height: number;
+}): Record<string, EffectPixels>;
 /**
  * A small preview of an effect from the provider's own renderer: filters run on a sample picture,
  * transitions go half way between two, generators and overlays draw at `time` (default half

package/dist/effects/ui.d.ts

@@ -23,6 +23,14 @@ export declare const effectFieldValue: (field: ParameterField, value: unknown) =
  * differ, for a transition's two sides).
  */
 export declare function effectSamplePicture(width: number, height: number, variant?: number): EffectPixels;
+/**
+ * Sample pictures for an effect's image inputs (`effectSamplePicture`; a transition's `to` gets
+ * the second variant), so previews of filters and transitions have something to change.
+ */
+export declare function effectSampleInputs(description: Pick<EffectDescription, 'inputs'>, size: {
+    width: number;
+    height: number;
+}): Record<string, EffectPixels>;
 /**
  * A small preview of an effect from the provider's own renderer: filters run on a sample picture,
  * transitions go half way between two, generators and overlays draw at `time` (default half

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.147.0",
+  "version": "0.148.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -20,6 +20,7 @@ that uses the tools can load the matching skill.
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
 | [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
+| [`pixerate-effect-authoring`](pixerate-effect-authoring/SKILL.md) | Authoring shaders and procedural effects: inspecting parameters and source code, setting values and presets, keyframing animation tracks, playback timing, and previewing. |
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 
 ## Using them

package/skills/pixerate-effect-authoring/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pixerate-effect-authoring
+description: How to author and edit procedural effects, shaders, and filters through the effect authoring agent tools - inspecting effect schemas and current control values, reading and compiling shader source code, adjusting parameters with all-or-nothing validation, applying and saving presets, keyframing animation tracks with easing, configuring timeline playback duration and looping, scrubbing the playhead, and capturing visual previews. Use when asked to author, modify, or debug shaders or procedural effects, animate effect parameters over time, or when effect_authoring tools are available.
+---
+
+# Pixerate effect authoring
+
+An effect authoring session hosts an active effect definition (shader or procedural filter) and
+exposes its controls, animated tracks, compile status, playback timing, and visual preview.
+Control values can be static or animated via keyframes along a timeline. Each edit creates a
+single undoable history step.
+
+When an effect session is opened, tools allow inspecting the control schema, updating control
+values, modifying shader code (for code-backed effects), saving and loading presets, managing
+keyframe animation tracks with interpolation easing, seeking the playhead, and capturing rendered
+preview frames.
+
+For general error reporting and undo conventions, see `pixerate-agent-tools`.
+
+## Working method
+
+1. **Inspect first.** Run `effect_authoring_describe` to inspect the effect name, kind, source
+   language (`glsl`, `svg`, or null when the effect has no source to edit), control parameter schemas, current
+   values, existing tracks, and compile issues.
+2. **Read or update source code.** If `sourceLanguage` is non-null, use `effect_authoring_get_source`
+   to read the shader or script code. Use `effect_authoring_set_source` to recompile with new code
+   and immediately inspect any reported syntax or compilation issues with line numbers.
+3. **Adjust parameters.** Use `effect_authoring_set_values` to set one or more controls at once.
+   This runs all-or-nothing validation: any invalid control name or out-of-range value cancels the
+   change and returns a helpful error.
+4. **Animate with keyframes.** For controls that change over time, set keyframes using
+   `effect_authoring_set_keyframe` specifying `control`, `time` (ms), optional `value`, and `easing` (a preset name such as `ease-in-out`, or a `cubic-bezier`, `spring` or `elastic` curve object).
+   Use `effect_authoring_seek` to move the playhead across the timeline and check resolved values.
+   Use `effect_authoring_remove_keyframe` to delete specific points, or `effect_authoring_clear_track`
+   to revert a parameter to static behavior (both refuse a control that has no keyframes, and say which controls are animated).
+5. **Tune timing.** Use `effect_authoring_set_timing` to configure total `duration` in ms and
+   whether playback loops.
+6. **Save presets.** When an interesting look is achieved, save it with `effect_authoring_save_preset`
+   or restore known presets with `effect_authoring_apply_preset`.
+7. **Verify visually.** When `effect_authoring_view` is available, capture rendered preview frames
+   at specific times to visually confirm effect appearance.
+
+## Best practices
+
+- **Batch parameter changes.** Set all related control values in a single `effect_authoring_set_values`
+  call so they apply cleanly in a single undo step.
+- **Check compile issues.** When editing source code via `effect_authoring_set_source`, always verify
+  the returned `issues` array. Fix errors before attempting to preview or set controls.
+- **Keyframe animation tracks.** Controls with active keyframes calculate their values dynamically
+  based on the playhead time. Setting a value on an animated control at the current playhead updates
+  or adds a keyframe at that time.
+- **Safe exploration.** Use `effect_authoring_save_preset` before major shader or parameter
+  refactoring, and use `effect_authoring_undo` / `effect_authoring_redo` to step through changes.
+
+## Tools
+
+| Tool | Description and usage |
+| --- | --- |
+| `effect_authoring_describe` | Reads the currently open effect session: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, duration, loop, and compile issues. |
+| `effect_authoring_get_source` | Retrieves shader or script source code and language for code-backed effects. Refused if `sourceLanguage` is null. |
+| `effect_authoring_set_source` | Recompiles the effect with new shader or script source code. Returns compiler issues with line numbers and messages. Available only when supported by the session. |
+| `effect_authoring_set_values` | Sets one or more control values at the current playhead time as a single undo step. Rejects all changes if any control name or value is invalid. |
+| `effect_authoring_reset_values` | Resets specified controls (or all controls if omitted) back to their schema defaults in a single undo step. |
+| `effect_authoring_apply_preset` | Applies a built-in or user-saved preset by name, updating current control values in one undo step. |
+| `effect_authoring_save_preset` | Saves the current control values as a user preset under the given name. Replaces an existing preset with the same name. |
+| `effect_authoring_set_keyframe` | Adds or replaces a keyframe on a control track at a specific time in milliseconds, with optional value and easing curve. |
+| `effect_authoring_remove_keyframe` | Deletes a keyframe at the exact millisecond timestamp from a control animation track. |
+| `effect_authoring_clear_track` | Removes all keyframes from an animated control track. The control's value at the playhead becomes its static value. |
+| `effect_authoring_set_timing` | Configures the effect's timeline duration in milliseconds and whether playback loops. |
+| `effect_authoring_seek` | Moves the preview playhead to a specific timeline position in milliseconds (clamped to 0..duration) and returns values at that time. |
+| `effect_authoring_undo` | Undoes the most recent edit in the authoring session. |
+| `effect_authoring_redo` | Redoes the most recently undone edit in the authoring session. |
+| `effect_authoring_view` | Captures a preview image of the effect at the current playhead or a specified timestamp. Available when preview capture is supported. |
+
+## Pitfalls
+
+- Calling authoring tools when no authoring session is open returns an error explaining that a session must be opened first.
+- Animated controls calculate their values dynamically from keyframes; clearing a track reverts the parameter to static behavior.
+- Compiling invalid shader code produces issues in `effect_authoring_set_source`; inspect the line numbers and messages to correct syntax.
+- Control values must match their schema types and bounds; colours must be `#rrggbb` (or `#rrggbbaa`), and numbers must fall within `[min, max]`.