@pixerate/flair 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pixerate/flair
 
+## 0.8.0
+
+### Minor Changes
+
+- a03bc70: Catalog: 35 new effects and two new categories.
+
+  - **overlay** (new category): rain on glass, snowfall, lens flare, vignette & grain, scanline sweep, spotlight, embers, shine sweep and frost creep shaders, plus a viewfinder vector effect. Overlay shaders have `transparent: true` (a new `ShaderEffect` field): render them with `{ alpha: true }` to lay them over other content.
+  - **image**: Ken Burns, ASCII art, shatter, melt, risograph, thermal / night vision, edge glow, tilt-shift, slit-scan, mosaic flip, chromatic lens and oil paint.
+  - **text** (new category): typewriter, scramble text, kinetic stagger, neon sign, stroke draw text, split reveal, highlighter, word cycle, liquid fill, glitch text and extruded text vector effects, and a `shader-text` shader that fills letters with plasma, fire, caustics or chrome. Drip text moves here from `icon`.
+  - `textImage(text, options)` in `/catalog`: any Unicode text as a transparent SVG `data:` URL, for image controls such as `shader-text`'s.
+  - Vector motion: `SvgAnimation.write` writes text letter by letter, with `scramble` (unwritten letters cycle through random characters) and `caret`; `writtenText` and `SCRAMBLE_MS` are exported from `/vector`.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -19,13 +19,13 @@ Flair gives products a library of good-looking, configurable visual effects (her
 
 ### Core Capabilities
 
-- 🎨 **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/).
+- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 98 effects, each with controls and presets. There are 68 WebGL2 shaders (gradients, organic textures, patterns, light, space, retro, image treatments, transparent overlays, text fills, transitions) and 30 animated SVG effects (loaders, status icons, animated 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`, with optional `{ alpha: true }` for transparent overlays) and many animated or hover-activated 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. Catalog vector effects declare their controls in the picture (`{{name: type …}}`), text included. It covers attribute tweens, draw-on strokes, motion along paths, counters (`animateCount` / `formatCount` for DOM elements too) and view zooms. Every frame is a pure function of time (`svgFrame`), and `SvgPlayer` plays it (with `scrollTrigger`, `hideWhenPaused`, and `reset()`).
+- ✒️ **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 (`animateCount` / `formatCount` for DOM elements too), text written letter by letter (`write`, with `scramble` and `caret`) and view zooms. Every frame is a pure function of time (`svgFrame`), and `SvgPlayer` plays it (with `scrollTrigger`, `hideWhenPaused`, and `reset()`).
 - 🎛️ **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.
@@ -41,7 +41,7 @@ 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`, `vectorControls`, GLSL helpers, sample images | None |
+| `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects`, `effectDefaults`, `renderVectorEffect`, `vectorControls`, GLSL helpers, sample images, `textImage` | None |
 | `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `animateCount`, `formatCount`, `svgMotionIssues` | None |
 | `@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 |
@@ -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: 63 effects + presets"]
+    Catalog["catalog: 98 effects + presets"]
     Shader["shader engine: controls, compile, render, GIF, HTML"]
     Vector["vector motion: SvgMotion, SvgPlayer"]
     Time["time: clocks, easing, keyframes, noise"]
@@ -100,7 +100,7 @@ npm install @pixerate/editor-react
 import { ShaderRenderer, SvgPlayer, ThumbnailPool, animateCount } from "@pixerate/flair";
 import { getEffect, effectDefaults, renderVectorEffect } from "@pixerate/flair/catalog";
 
-// A shader background (or pass { alpha: true } with uBackgroundAlpha: 0 for a transparent overlay)
+// A shader background (overlay effects have `transparent: true`: render them with { alpha: true })
 const aurora = getEffect("aurora")!;
 if (aurora.kind === "shader") {
   const preview = new ShaderRenderer(document.querySelector("#hero")!);
@@ -131,6 +131,8 @@ animateCount({
 
 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.
 
+Overlay shaders (`category: "overlay"`) have `transparent: true`: they write coverage to `fragColor.a` and draw nothing elsewhere, so render them with `new ShaderRenderer(host, { alpha: true })` (or `new ThumbnailPool({ alpha: true })`) and lay the canvas over a picture, video or page. `shader-text` fills letters from a text image: set its `uText` control to `textImage("Your title", { weight: 900 })`, a transparent SVG `data:` URL of any Unicode text.
+
 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
@@ -265,9 +267,11 @@ The exporters carry the camera too:
 | 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 |
+| image | ripple, glitch, duotone, halftone, pixel reveal, Ken Burns, ASCII art, shatter, melt, risograph, thermal, edge glow, tilt-shift, slit-scan, mosaic flip, chromatic lens, oil paint, CRT screen, film look |
+| overlay | rain on glass, snowfall, lens flare, vignette & grain, scanline sweep, spotlight, embers, shine sweep, frost creep, viewfinder |
+| text | shader text, drip text, typewriter, scramble text, kinetic stagger, neon sign, stroke draw text, split reveal, highlighter, word cycle, liquid fill, glitch text, extruded text |
 | 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, drip text, flow network |
+| loader / icon / data | spinner, bouncing dots, pulse ping, equalizer, progress ring, bar chart, line chart, stat counter, route, timeline track, success check, error cross, heartbeat, signature, confetti, 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,7 +1,7 @@
 import { a as ControlDef, C as ControlValue } from '../controls-Syr6drzO.js';
-import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-CfIFlnMY.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-CfIFlnMY.js';
-import '../motion-BwIlugh1.js';
+import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-CNPIrnTf.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-CNPIrnTf.js';
+import '../motion-Ce0lmzm3.js';
 
 /**
  * Sample pictures for the catalog's image effects: small SVGs as `data:` URLs,
@@ -15,6 +15,26 @@ declare const SAMPLE_IMAGES: {
     readonly city: string;
     readonly portrait: string;
 };
+interface TextImageOptions {
+    /** CSS font family (default a heavy system sans-serif). */
+    font?: string;
+    /** Font weight (default 900). */
+    weight?: number | string;
+    /** Font size in the picture's units; by default as large as fits. */
+    size?: number;
+    /** The picture's size (default 1024 × 256). */
+    width?: number;
+    height?: number;
+}
+/**
+ * A line of text, white on transparent, as an SVG `data:` URL for an image
+ * control (the shader text effects use its alpha as a letter mask). The text
+ * is centred and fitted to the picture (1024 × 256 by default): the font
+ * size comes from its length, and `textLength` stretches it to the width
+ * that size predicts, so any text fills about the same box in any font.
+ * Takes any Unicode text.
+ */
+declare function textImage(text: string, options?: TextImageOptions): string;
 
 /**
  * GLSL helpers the catalog's shaders are built from. Each effect's source
@@ -72,4 +92,4 @@ declare function effectDefaults(effect: EffectDefinition, options?: {
     values?: Record<string, ControlValue>;
 }): Record<string, ControlValue>;
 
-export { EFFECTS, EffectCategory, EffectDefinition, type EffectQuery, FBM, HASH, NOISE, OKLAB_MIX, PALETTE, ROTATE, SAMPLE_IMAGES, SHADER_EFFECTS, ShaderEffect, effectControls, effectDefaults, findEffects, getEffect, glsl, svgDataUrl };
+export { EFFECTS, EffectCategory, EffectDefinition, type EffectQuery, FBM, HASH, NOISE, OKLAB_MIX, PALETTE, ROTATE, SAMPLE_IMAGES, SHADER_EFFECTS, ShaderEffect, effectControls, effectDefaults, findEffects, getEffect, glsl, svgDataUrl, textImage };

package/dist/catalog/index.js

@@ -19,11 +19,12 @@ import {
   numberControl,
   renderVectorEffect,
   svgDataUrl,
+  textImage,
   vectorControlDef,
   vectorControlIssues,
   vectorControls,
   vectorEffectControls
-} from "../chunk-J2WIWT4J.js";
+} from "../chunk-FHXOMIQY.js";
 import "../chunk-EHDJ3CPJ.js";
 import "../chunk-WC3VADZC.js";
 export {
@@ -47,6 +48,7 @@ export {
   numberControl,
   renderVectorEffect,
   svgDataUrl,
+  textImage,
   vectorControlDef,
   vectorControlIssues,
   vectorControls,