@pixerate/flair 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @pixerate/flair
 
+## 0.3.0
+
+### Minor Changes
+
+- 10f02b2: The 3D camera now reaches layout checks, motion blur direction and the exporters. `checkShot` judges framing, edges, text size and the title on screen, through the camera's angle (`screenBox`). A pan's motion blur streaks along its direction (`View.blurAngle`, `cameraBlur` for an SVG blur, `moveBlur`), and the standalone player draws it that way. `cameraTrack` and `cameraSamples` lay the camera out on a timeline, and the exporters use them: Lottie gets a camera rig (in 3D with an AE camera when angled), Apple Motion a keyframed camera group, FCP7 XML a keyframed Distort corner pin with Motion Blur, and EDL a `* CAMERA:` note.
+- 10f02b2: Scene cameras can turn in 3D and blur while they move. A shot's `camera` takes `tilt`, `turn` and `roll` (degrees), `perspective` and `motionBlur` alongside its framing, or on their own to change the angle in place, and angles carry over until a shot changes them. `playScene` passes views with the angle and a speed-based `blur`. New helpers: `cameraTransform` and `cameraFilter` (CSS for a board layer), `projectPoint`, `motionBlur`, `shotView`. `validateScene` checks the new fields, and the standalone scene player now plays camera moves (framing, angle and blur) and moves through shots when playing.
+- 10f02b2: Add two catalog effects: `flow-network`, an animated SVG node graph whose links draw on before a glowing critical path races through it to a pulsing hub (its label is a text control), and `light-ribbons`, a shader of thin iridescent light strands weaving across a dark frame.
+- 10f02b2: Add two catalog effects: `neon-circuit`, a shader of glowing neon traces routed up a circuit board with pulses running along them, and `drip-text`, an animated SVG title that pops in and oozes drips from its letters.
+- 10f02b2: Vector effects declare their controls in their picture: the first `{{name: type …}}` placeholder (`float`, `int`, `bool`, `color` or `text`, with `@control`'s attributes) declares a control, and `vectorControls` reads them, the way `parseControls` reads a shader's. Adds a `text` control type (shown as a text field in the parameters panel), so a picture's words can be changed; text is escaped when filled in. `drip-text` now takes any word, with its drips following it. Every catalog vector effect declares its controls inline, and a vector effect's `controls` list is now optional (still read, for effects written before). `renderVectorEffect` drops comments from the markup and falls back to defaults for values a control cannot take.
+
+## 0.2.0
+
+### Minor Changes
+
+- 6fb310a: Build the effect editor on `@pixerate/editor` 0.29's new subpaths (now the minimum version of the optional peer):
+
+  - Keyframes use `@pixerate/editor/animation`'s easing engine and track types. Flair's own copy is gone; its exports remain as aliases.
+  - Agent tools are typed by `@pixerate/editor/tools`. A new `createEffectToolRegistry(editor)` serves them through its `ToolRegistry`, with argument checking.
+  - New `parameterSchemaFor(controls)` and `bindEffectParameters(editor)` drive `@pixerate/editor/parameters`, including the React and Svelte `ParametersPanel`s, with every change and keyframe toggle going through the effect editor.
+  - New `EffectEditor.setTrack` and its `keyframe.setTrack` command replace a control's keyframes in one step.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -19,20 +19,20 @@ Flair gives products a library of good-looking, configurable visual effects (her
 
 ### Core Capabilities
 
-- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 59 effects, each with controls and presets. There are 44 WebGL2 shaders (gradients, organic textures, patterns, light, space, retro, image effects, transitions) and 15 animated SVG effects (loaders, status icons, charts, counters). [Browse them live](https://pixerate.github.io/flair/).
+- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 63 effects, each with controls and presets. There are 46 WebGL2 shaders (gradients, organic textures, patterns, light, space, retro, image effects, transitions) and 17 animated SVG effects (loaders, status icons, titles, charts, counters, node graphs). [Browse them live](https://pixerate.github.io/flair/).
 - ⚡ **Shader engine**:
   - Shadertoy-style GLSL ES 3.00 fragment shaders, with controls declared in the source (`// @control`), including image inputs.
   - Compile errors come back with line numbers that match the source.
   - Live previews (`ShaderRenderer`) and many animated thumbnails on one context (`ThumbnailPool`).
   - Frames at exact times (`ShaderFrames`), looping GIFs, and standalone HTML pages.
-- ✒️ **Vector motion (`@pixerate/flair/vector`)**: animated SVG described as data. It covers attribute tweens, draw-on strokes, motion along paths, counters and view zooms. Every frame is a pure function of time (`svgFrame`), and `SvgPlayer` plays it.
+- ✒️ **Vector motion (`@pixerate/flair/vector`)**: animated SVG described as data. Catalog vector effects declare their controls in the picture (`{{name: type …}}`), text included. It covers attribute tweens, draw-on strokes, motion along paths, counters and view zooms. Every frame is a pure function of time (`svgFrame`), and `SvgPlayer` plays it.
 - 🎛️ **Effect editor (`@pixerate/flair/editor`)**:
   - A headless editor for an effect's source, values, keyframes, presets and timeline.
   - Built on [`@pixerate/editor`](https://github.com/Pixerate/editor)'s undo history and command registry, with no UI framework assumed.
 - 🤖 **Agent-native, bring your own model**:
   - Every editing action is a command, and the commands are exposed as MCP-shaped tools.
   - Ships instructions for the model. The host supplies the model, keys and agent loop.
-- 🎬 **Directing and interchange**: multi-shot scenes with camera moves, procedural effects, validation and fast headless simulation. Also blend modes, Oklab colour and grading, retiming, timecode, and export to Lottie, Apple Motion, FCP7 XML and CMX 3600 EDL.
+- 🎬 **Directing and interchange**: multi-shot scenes with camera moves (3D tilt and motion blur included), procedural effects, validation and fast headless simulation. Also blend modes, Oklab colour and grading, retiming, timecode, and export to Lottie, Apple Motion, FCP7 XML and CMX 3600 EDL.
 
 ---
 
@@ -41,9 +41,9 @@ Flair gives products a library of good-looking, configurable visual effects (her
 | Import | What it provides | Runtime dependencies |
 | :--- | :--- | :--- |
 | `@pixerate/flair` | Shader engine, vector motion, time and easing, colour, blending, transitions, scenes, interchange exporters | None (browser-safe) |
-| `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects`, `effectDefaults`, `renderVectorEffect`, GLSL helpers, sample images | None |
+| `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects`, `effectDefaults`, `renderVectorEffect`, `vectorControls`, GLSL helpers, sample images | None |
 | `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `svgMotionIssues` | None |
-| `@pixerate/flair/editor` | `EffectEditor`, effect documents, keyframe tracks, renderer bindings, agent tools and instructions | `@pixerate/editor` (optional peer) |
+| `@pixerate/flair/editor` | `EffectEditor`, effect documents, keyframe tracks, renderer bindings, parameter-panel binding, agent tools and instructions | `@pixerate/editor` ≥ 0.29 (optional peer; only its dependency-free `/history`, `/commands`, `/tools`, `/animation` and `/parameters` subpaths) |
 | `@pixerate/flair/node` | `exportMotionGraphic`: renders a shader to GIF/MP4 through headless Chrome and ffmpeg | Node.js |
 
 The `flair` CLI inspects shaders, writes standalone pages and directs scenes (see [CLI](#-cli)).
@@ -55,7 +55,7 @@ The `flair` CLI inspects shaders, writes standalone pages and directs scenes (se
 ```mermaid
 graph TD
   subgraph Effects["Effects (no dependencies)"]
-    Catalog["catalog: 59 effects + presets"]
+    Catalog["catalog: 63 effects + presets"]
     Shader["shader engine: controls, compile, render, GIF, HTML"]
     Vector["vector motion: SvgMotion, SvgPlayer"]
     Time["time: clocks, easing, keyframes, noise"]
@@ -90,6 +90,8 @@ Flair stays free of LLM SDKs and UI frameworks. Your app owns the interface and
 npm install @pixerate/flair
 # For the editor:
 npm install @pixerate/flair @pixerate/editor
+# For the ready-made React (or Svelte) controls panel:
+npm install @pixerate/editor-react
 ```
 
 ### 1. Drop in a catalog effect
@@ -117,6 +119,15 @@ if (spinner.kind === "vector") {
 
 Find effects with `findEffects({ text: "glow", category: "light", kind: "shader" })`. Each effect has an `id`, `name`, `description`, `category`, `tags` and optional `presets`. Image effects default to built-in sample pictures, so they look right before you set `uImage` to your own URL.
 
+A vector effect declares its controls in its picture, the way a shader declares its uniforms: the first `{{name: type …}}` declares a control (`float`, `int`, `bool`, `color` or `text`, with `@control`'s attributes; quote values with spaces in single quotes), and every `{{name}}` is filled with its value. Declarations can sit in an XML comment, which is dropped when the picture is filled in, and text is escaped, so any words are safe:
+
+```ts
+const title = { motion: { svg: `<svg viewBox="0 0 200 60"><!-- {{title: text default='Hello' label='Title'}} {{ink: color default=#6366F1}} --><text x="10" y="40" fill="{{ink}}">{{title}}</text></svg>` } };
+vectorControls(title.motion); // [{ name: "title", type: "text", default: "Hello", … }, { name: "ink", type: "vec3", color: true, … }]
+renderVectorEffect(title, { title: "Fish & chips" }); // …<text …>Fish &amp; chips</text>…
+renderVectorEffect(getEffect("drip-text")!, { word: "UNSTOPPABLE" }); // drips follow the word
+```
+
 ### 2. Write your own shader
 
 ```glsl
@@ -163,12 +174,24 @@ editor.commands.execute("values.randomize");
 window.addEventListener("keydown", (e) => editor.commands.handleKeyDown(e)); // Space plays/pauses
 ```
 
-`getState()` returns the same object until something changes, so React's `useSyncExternalStore` works as is. Documents are plain JSON (`EffectDocument`), and keyframe tracks use `@pixerate/editor`'s keyframe shape and easing names.
+`getState()` returns the same object until something changes, so React's `useSyncExternalStore` works as is. Documents are plain JSON (`EffectDocument`). Keyframe tracks use `@pixerate/editor/animation`'s track shape and easing engine.
+
+For a ready-made controls panel, bind the effect to `@pixerate/editor`'s parameters editor. Every field, image pick and keyframe diamond goes through the effect editor and its undo history:
+
+```tsx
+import { bindEffectParameters } from "@pixerate/flair/editor";
+import { ParametersPanel } from "@pixerate/editor-react/parameters"; // or @pixerate/editor-svelte/parameters
+
+const { controller, dispose } = bindEffectParameters(editor);
+<ParametersPanel controller={controller} showToolbar={false} showPresets={false} showKeyframes />;
+```
+
+`parameterSchemaFor(controls)` gives you the schema alone, for a UI of your own.
 
 ### 4. Let an agent drive it
 
 ```ts
-import { createEffectToolProvider, toolDefinitions, callTool, EFFECT_AGENT_INSTRUCTIONS } from "@pixerate/flair/editor";
+import { createEffectToolProvider, createEffectToolRegistry, toolDefinitions, callTool, EFFECT_AGENT_INSTRUCTIONS } from "@pixerate/flair/editor";
 
 const tools = createEffectToolProvider(editor, {
   capture: () => renderer.capture({ type: "image/png" }), // adds a `view_effect` tool so the model can look
@@ -177,7 +200,8 @@ const tools = createEffectToolProvider(editor, {
 // Give your model EFFECT_AGENT_INSTRUCTIONS and toolDefinitions(tools), then for each tool call:
 const result = await callTool(tools, call.name, call.input); // MCP tools/call result
 
-// Or register the provider with @pixerate/editor's ToolRegistry, or bridge it to an MCP server.
+// Or serve them through @pixerate/editor/tools' ToolRegistry (MCP tools/list and tools/call):
+const registry = createEffectToolRegistry(editor); // registry.listTools(), registry.callTool(name, args)
 ```
 
 The tools are `list_commands`, `run_command` and `run_commands`, plus `view_effect` when you can capture the preview. The commands they run:
@@ -185,26 +209,53 @@ The tools are `list_commands`, `run_command` and `run_commands`, plus `view_effe
 - **Inspect and start:** `effect.describe`, `catalog.search`, `effect.load`.
 - **Edit the effect:** `effect.setSource`.
 - **Values and presets:** `values.set`, `values.reset`, `values.randomize`, `preset.apply` and `preset.save`.
-- **Keyframes:** `keyframe.set`, `keyframe.remove`, `keyframe.setEasing` and `keyframe.clear`.
-- **Timeline:** `timeline.setTiming`, `timeline.play` and `timeline.seek`.
+- **Keyframes:** `keyframe.set`, `keyframe.setTrack`, `keyframe.remove`, `keyframe.setEasing` and `keyframe.clear`.
+- **Timeline:** `timeline.setTiming`, `timeline.play`, `timeline.pause` and `timeline.seek`.
 - **History:** `history.undo` and `history.redo`.
 
 Every change is one undo step, and refusals come back as messages the model can act on.
 
 ---
 
+## 🎬 Camera moves
+
+A shot's `camera` frames a box (`{ x, y, width, height }`) or elements (`{ frame: ["card"] }`), and can turn in 3D and blur while it moves, like the product-video swoop onto a tilted screen:
+
+```json
+{ "camera": { "frame": ["dashboard"], "tilt": 35, "turn": -15, "motionBlur": 1.5 } }
+```
+
+- `tilt` leans the board back (top away, like a desk seen from above), `turn` swings it round its vertical axis (left side nearer when positive), `roll` rolls it clockwise. Tilt and turn go up to ±75°.
+- `perspective` is the lens distance as a multiple of the stage width (1.2 by default). Lower values look more dramatic.
+- `motionBlur` (0 to 3, with 1 as natural) blurs the move in proportion to its speed, so the blur peaks mid-move and clears when the camera settles. A pan streaks along its direction (`View.blurAngle`), while a zoom or turn blurs in every direction.
+- Angles carry over to later shots until a shot changes them. `{ "camera": { "tilt": 0, "turn": 0 } }` flattens the board in place.
+
+`playScene` hands boards views with these fields (`View.tilt`, `View.blur`, `View.blurAngle`, …). For renderers:
+- `cameraTransform(view, stage, width)` gives the CSS `transform` for a board layer.
+- `cameraBlur(...)` gives the `stdDeviation` for an SVG `feGaussianBlur` that streaks, and `cameraFilter(...)` gives a CSS `blur()`.
+- `projectPoint` gives where a scene point lands on screen.
+- `cameraTrack` and `cameraSamples` lay the camera out on a timeline.
+
+The standalone player (`flair scene html`) plays all of it. Layout checks (framing, edges, text size, the title) are judged on screen, where the angle puts each element.
+
+The exporters carry the camera too:
+- **Lottie:** a "Camera" null layer that the element layers hang off. When the camera is angled, it is a 3D layer with an AE camera (lottie-web draws it with its `html` renderer).
+- **Apple Motion:** a keyframed "Camera" group around the shots.
+- **FCP7 XML:** a keyframed Distort corner pin on each shot's clip, plus Motion Blur.
+- **EDL:** a `* CAMERA:` note, since CMX 3600 has no transforms.
+
 ## 🎨 The catalog
 
 | Category | Effects |
 | :--- | :--- |
 | gradient | mesh gradient, aurora, gradient flow, conic sweep, silk |
 | organic | liquid marble, smoke, lava lamp, plasma, caustics, flames, blob morph |
-| pattern | dot wave, Truchet flow, hex pulse, living cells, moiré rings, kaleidoscope, stripes |
-| light / space | bokeh, god rays, sparkles, neon ripple, warp starfield, nebula, event horizon |
+| pattern | dot wave, Truchet flow, hex pulse, living cells, moiré rings, kaleidoscope, stripes, neon circuit |
+| light / space | bokeh, god rays, sparkles, neon ripple, light ribbons, warp starfield, nebula, event horizon |
 | retro | synthwave, digital rain, dithered gradient, TV static |
 | image | ripple, glitch, duotone, halftone, pixel reveal, CRT screen, film look |
 | transition | wipe, iris, block dissolve, grid wipe, glass wipe, twister, light leak, cross zoom |
-| loader / icon / data | spinner, bouncing dots, pulse ping, equalizer, progress ring, bar chart, line chart, stat counter, route, success check, error cross, heartbeat, signature, confetti |
+| loader / icon / data | spinner, bouncing dots, pulse ping, equalizer, progress ring, bar chart, line chart, stat counter, route, success check, error cross, heartbeat, signature, confetti, drip text, flow network |
 
 Every shader is self-contained and compiles on WebGL2. Open [`#check`](https://pixerate.github.io/flair/#check) on the demo to compile the catalog on your own GPU.
 

package/dist/catalog/index.d.ts

@@ -1,6 +1,6 @@
-import { a as ControlDef, C as ControlValue } from '../controls-DdXMbovi.js';
-import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-CkKkavvB.js';
-export { b as EFFECT_CATEGORIES, c as EffectPreset, V as VectorControl, d as VectorEffect, e as colorControl, n as numberControl, r as renderVectorEffect, v as vectorControlDef } from '../types-CkKkavvB.js';
+import { a as ControlDef, C as ControlValue } from '../controls-Syr6drzO.js';
+import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-CsFUZZIv.js';
+export { b as EFFECT_CATEGORIES, c as EffectPreset, V as VECTOR_CONTROL_TYPES, d as VectorControl, e as VectorEffect, f as colorControl, n as numberControl, r as renderVectorEffect, v as vectorControlDef, g as vectorControlIssues, h as vectorControls, i as vectorEffectControls } from '../types-CsFUZZIv.js';
 import '../motion-D0TVv2CF.js';
 
 /**
@@ -42,7 +42,8 @@ declare function glsl(...parts: string[]): string;
  *
  * - Browsing: `EFFECTS`, `getEffect`, `findEffects`, `EFFECT_CATEGORIES`.
  * - Controls: `effectControls`, `effectDefaults`.
- * - Vector effects: `renderVectorEffect` fills in their controls.
+ * - Vector effects: their pictures declare their controls (`vectorControls`),
+ *   and `renderVectorEffect` fills them in.
  *
  * @packageDocumentation
  */

package/dist/catalog/index.js

@@ -9,6 +9,7 @@ import {
   ROTATE,
   SAMPLE_IMAGES,
   SHADER_EFFECTS,
+  VECTOR_CONTROL_TYPES,
   colorControl,
   effectControls,
   effectDefaults,
@@ -18,10 +19,13 @@ import {
   numberControl,
   renderVectorEffect,
   svgDataUrl,
-  vectorControlDef
-} from "../chunk-MWVTQFV5.js";
+  vectorControlDef,
+  vectorControlIssues,
+  vectorControls,
+  vectorEffectControls
+} from "../chunk-IWKM5FJK.js";
 import "../chunk-EHDJ3CPJ.js";
-import "../chunk-J55UBNAT.js";
+import "../chunk-WC3VADZC.js";
 export {
   EFFECTS,
   EFFECT_CATEGORIES,
@@ -33,6 +37,7 @@ export {
   ROTATE,
   SAMPLE_IMAGES,
   SHADER_EFFECTS,
+  VECTOR_CONTROL_TYPES,
   colorControl,
   effectControls,
   effectDefaults,
@@ -42,6 +47,9 @@ export {
   numberControl,
   renderVectorEffect,
   svgDataUrl,
-  vectorControlDef
+  vectorControlDef,
+  vectorControlIssues,
+  vectorControls,
+  vectorEffectControls
 };
 //# sourceMappingURL=index.js.map