@pixerate/flair 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @pixerate/flair
 
+## 0.24.0
+
+### Minor Changes
+
+- e909f4e: Catalog: a new **lighting** category, 10 effects that relight a picture or video rather than draw light as a background. The shaders read the picture's brightness as a height map (a Sobel of fine detail plus two broader scales from its mip levels) and shade the normals it gives.
+
+  - **relight**: a directional light with azimuth, elevation, colour, ambient and a soft specular.
+  - **point light**: a torch over a darkened picture, following the pointer while hovered and drifting otherwise.
+  - **studio lighting**: three-point lighting on a subject, warm key, cool fill and a rim along its silhouette (alpha, or the corner colour keyed out), on a studio backdrop.
+  - **time of day**: dawn, noon, golden hour, blue hour and night on an hour control or animated, with lights glowing from the brightest spots at night.
+  - **gobo projection**: window panes, foliage, stars, venetian slats or your own text (a gobo image) projected onto a picture, softly focused and drifting.
+  - **neon spill**, **candlelight**, **pool caustics** and **party lights** (beams, sweeping pools, mirror ball and strobe).
+  - **lamp switch** (vector, click): a pendant lamp whose pull cord switches a warm light cone on and off.
+
+## 0.23.0
+
+### Minor Changes
+
+- 69cdb60: `effectInputs(effect)` says what an effect takes and how it answers the pointer: what it `accepts` (image, video, svg, text, mask, path), its image controls and whether each wants a picture, a mask or text, its text controls (copy, font, path, glyphs), its video use, its `interactions` (hover, press, click, trail, pointer) and whether it is a transparent overlay. It is worked out from the effect's controls, source and fields, so it never drifts. `findEffects` and the `catalog.search` command filter on `accepts`, `interaction` and `transparent`, and the search lists each effect's inputs. `silhouette-morph` now says `video: "none"` (it takes silhouettes, not photos), and the fireworks, explosion and bullet-time effects are tagged `interactive`.
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ Flair gives products a library of good-looking, configurable visual effects (her
 
 ### Core Capabilities
 
-- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 287 effects, each with controls and presets. There are 205 WebGL2 shaders (gradients, organic textures and growth, patterns, light, space, retro and pixel art, image treatments, transparent overlays, text fills, image morphs, pointer interactions, pyrotechnics, time warps, melting, electricity, splatters, bubbles, stickers, pointer trails, particles, debris, impacts, comic looks, atmosphere, glows, shadows, distortions, transitions) and 82 animated SVG effects (loaders, status icons, animated titles, shape morphs, UI micro-interactions, pixel sprites, stickers, cartoon effects, glowing and lifting UI, charts, counters, node graphs). [Browse them live](https://pixerate.github.io/flair/).
+- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 297 effects, each with controls and presets. There are 214 WebGL2 shaders (gradients, organic textures and growth, patterns, light, lighting that relights pictures, space, retro and pixel art, image treatments, transparent overlays, text fills, image morphs, pointer interactions, pyrotechnics, time warps, melting, electricity, splatters, bubbles, stickers, pointer trails, particles, debris, impacts, comic looks, atmosphere, glows, shadows, distortions, transitions) and 83 animated SVG effects (loaders, status icons, animated titles, shape morphs, UI micro-interactions, pixel sprites, stickers, cartoon effects, glowing and lifting UI, a lamp switch, 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.
@@ -43,11 +43,12 @@ Flair gives products a library of good-looking, configurable visual effects (her
 | :--- | :--- | :--- |
 | `@pixerate/flair` | Shader engine, vector motion, time and easing, colour, blending, transitions, scenes, interchange exporters | None (browser-safe) |
 | `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects` (also by `video` use), `effectDefaults`, `renderVectorEffect`, `vectorControls`, GLSL helpers, sample images, `textImage` | None |
-| `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `svgFrameMarkup`, `svgViewBox`, `animateCount`, `formatCount`, `morphPaths`, `morphSequence`, `svgMotionIssues` | None |
-| `@pixerate/flair/react` | `<VectorEffect>`, `<SvgPlayerView>`: vector effects as React components, server-rendered as a still | `react` ≥ 18 (optional peer) |
-| `@pixerate/flair/svelte` | `vectorEffect` action, `vectorEffectStill`: vector effects in Svelte, server-rendered as a still | `svelte` ≥ 5 (optional peer; types only) |
+| `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `svgFrameMarkup`, `svgViewBox`, `animateCount`, `formatCount`, `morphPaths`, `morphSequence`, `svgAnimatedMarkup` (an animated `.svg` file), `svgMotionIssues` | None |
+| `@pixerate/flair/embed` | `mountEffect`, `subjectValues`: any catalog effect on a page, applied to a picture, video, SVG, words or a path; `recordEffect`: MP4, WebM, GIF or PNG frames in the browser | None |
+| `@pixerate/flair/react` | `<FlairEffect>`: any catalog effect applied to a subject; `<VectorEffect>`, `<SvgPlayerView>`: vector effects as React components, server-rendered as a still | `react` ≥ 18 (optional peer) |
+| `@pixerate/flair/svelte` | `flairEffect` action: any catalog effect applied to a subject; `vectorEffect` action, `vectorEffectStill`: vector effects in Svelte, server-rendered as a still | `svelte` ≥ 5 (optional peer; types only) |
 | `@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 |
+| `@pixerate/flair/node` | `exportEffect` and `exportMotionGraphic`: render a catalog effect (on a picture, video, SVG, words or a path) or a shader to MP4, WebM, MOV, GIF, PNG frames or animated SVG, through headless Chrome (and ffmpeg for video) | Node.js |
 
 The `flair` CLI inspects shaders, writes standalone pages and directs scenes (see [CLI](#-cli)).
 
@@ -58,7 +59,7 @@ The `flair` CLI inspects shaders, writes standalone pages and directs scenes (se
 ```mermaid
 graph TD
   subgraph Effects["Effects (no dependencies)"]
-    Catalog["catalog: 287 effects + presets"]
+    Catalog["catalog: 297 effects + presets"]
     Shader["shader engine: controls, compile, render, GIF, HTML"]
     Vector["vector motion: SvgMotion, SvgPlayer"]
     Time["time: clocks, easing, keyframes, noise"]
@@ -150,8 +151,90 @@ new SvgPlayer(host, motion, { loop: false });
 
 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.
 
+#### What an effect takes
+
+`effectInputs(effect)` says what you can give an effect and how it answers the pointer, worked out from the effect itself:
+
+```ts
+import { effectInputs, findEffects, getEffect, textImage } from "@pixerate/flair/catalog";
+
+effectInputs(getEffect("image-duotone")!);
+// { accepts: ["image", "video", "svg"], images: [{ name: "uImage", wants: "picture" }], video: "filter", interactions: [], transparent: false, … }
+effectInputs(getEffect("typewriter")!);
+// { accepts: ["text"], texts: [{ name: "text", holds: "copy" }, { name: "font", holds: "font" }], interactions: [], … }
+effectInputs(getEffect("click-ripple")!).interactions; // ["click"]
+
+findEffects({ accepts: ["video"] }); // effects that run on video
+findEffects({ accepts: ["text"], kind: "vector" }); // animated titles and labels
+findEffects({ accepts: ["image"], interaction: ["hover"] }); // pictures that react to hovering
+findEffects({ transparent: true }); // overlays to lay over a page, picture or video
+```
+
+- `accepts`: `image` (any picture URL), `video` (a live `<video>`, with `setLiveSource`), `svg` (an SVG URL, drawn with its transparency), `text` (words for a text control, or for a text mask through `textImage("…")`), `mask` (a shape with transparency whose silhouette the effect uses: an icon, a logo, a word), `path` (SVG path data for a shape control).
+- `images`: each image control's name, and whether it `wants` a `picture`, a `mask` or `text`.
+- `texts`: each text control's name, and whether it `holds` `copy`, a `font`, a `path` or `glyphs`.
+- `interactions`: `hover`, `press`, `click`, `trail` (follows where the pointer has been) or `pointer` (follows where it is), from the pointer built-ins a shader reads or a vector effect's `trigger`.
+- `transparent`, `video` and `trigger`, as on the effect.
+
+`findEffects` filters on `accepts` (all of them), `interaction` (any of them; `[]` for effects that don't answer the pointer) and `transparent`, and the `catalog.search` command takes the same filters and lists each effect's `accepts` and `interactions`. The `interactive` tag is kept in step with `interactions`.
+
+#### Put an effect on a page
+
+`@pixerate/flair/embed` pairs a catalog effect with what it takes and runs it, shader or vector, in one call. `mountEffect(host, effect, { subject })` takes a subject:
+- `{ image }`: a picture's URL.
+- `{ video }`: a playing `<video>`, shown live.
+- `{ svg }`: an SVG, as markup or a URL.
+- `{ text }`: words, typed into a vector effect, or drawn with `textImage` for a shader's text or mask.
+- `{ path }`: path data.
+
+It puts the subject in the right control (see `effectInputs`) and throws a sentence if the effect can't take it.
+
+```ts
+import { mountEffect } from "@pixerate/flair/embed";
+
+mountEffect(el, "image-duotone", { subject: { image: "/team.jpg" }, preset: "Spotify" });
+mountEffect(el, "crt", { subject: { video: document.querySelector("video")! } });
+mountEffect(el, "neon-outline", { subject: { svg: logoMarkup } });
+mountEffect(el, "typewriter", { subject: { text: "Hello there" } });
+mountEffect(el, "transition-wipe", { subject: [{ image: "/a.jpg" }, { image: "/b.jpg" }] });
+const m = mountEffect(el, "click-ripple"); // overlays get a transparent canvas, interactive effects answer the pointer
+m.setValues({ uSpeed: 2 });
+m.dispose();
+```
+
+`subjectValues(effect, subject)` gives the control values (and live sources) without mounting anything, for `ShaderRenderer`, `ShaderFrames` or `renderVectorEffect`.
+
+In React, `<FlairEffect effect="image-duotone" subject={{ image: "/team.jpg" }} style={{ aspectRatio: "16 / 9" }} />` (from `@pixerate/flair/react`) does the same. In Svelte, use `<div use:flairEffect={{ effect, subject }}></div>` (from `@pixerate/flair/svelte`). Either way the effect fills its element, so size it with CSS.
+
 Effects that show a picture (image, transition, morph, time-warp and the like) take transparent pictures too, such as SVG icons (Lucide and similar sets draw black `currentColor` strokes on a clear background). They lay the picture over a backdrop: `uBackdrop` (white by default) shows through its clear parts. Set `uBackdropAlpha` to 0 to keep the picture's alpha instead, and render with `{ alpha: true }` to lay the result over the page. `SAMPLE_IMAGES.icon` is a Lucide-style sample icon. SVGs are rasterised at 2048 px on the long edge, so icons stay sharp.
 
+#### Recording an effect
+
+`recordEffect(effect, options)` (from `@pixerate/flair/embed`) records a catalog effect, applied to a subject, to a file in the browser, with no server and no extra dependencies:
+
+```ts
+import { recordEffect } from "@pixerate/flair/embed";
+
+const mp4 = await recordEffect("image-duotone", { subject: { image: "/team.jpg" }, preset: "Spotify" });
+const webm = await recordEffect("crt", { subject: { video }, format: "webm", duration: 5 });
+const gif = await recordEffect("typewriter", { subject: { text: "Hello there" }, format: "gif", width: 640, height: 360, fps: 25 });
+const overlay = await recordEffect("click-ripple", {
+  format: "webm",
+  alpha: true,
+  pointer: { clicks: [{ x: 640, y: 360, time: 0.2 }] }, // or (t) => ({ pointer: [x, y, hover, press] })
+  onProgress: (f) => (bar.value = f),
+});
+download(mp4); // a Blob
+```
+
+- **Formats.** `mp4` (H.264) or `webm` (VP9, else VP8) are encoded with WebCodecs and written by small built-in muxers: a faststart MP4 (`moov` before `mdat`) and a WebM with no `Cues`. `gif` uses gifenc. `png` gives a ZIP of numbered frames (`frame-0001.png`, …), so every format is one `Blob`. The default is `mp4` where the browser encodes H.264, else `webm`. When the browser can't make a format, it rejects with a sentence that names the formats that would work.
+- **Exact frames.** Frame `i` is drawn at `start + i / fps` off screen, so the result is the same whatever the page is doing. Shaders render with `ShaderFrames`. A `<video>` subject is paused and sought to each frame's time, then put back. A canvas subject is drawn as it is, so draw it for each frame in `beforeFrame(time)`. Vector effects are drawn with `svgView` and rasterised.
+- **Defaults.** 1280 × 720 at 30 fps. The length is a shader's `loop`, or a vector effect's picture plus its `hold`, else 4 s. The bitrate is `width × height × fps × 0.15`. Video sizes round up to even numbers. `recordingPlan(effect, options)` tells you what a recording will be (format, size, frames, encoder) before any frame is drawn.
+- **Interaction.** Shaders that answer the pointer play their idle demo unless `pointer` scripts it, with the same `pointer`, `clicks` and `trail` that `ShaderFrames.render` takes. Click-triggered vector effects take `steps` (ms).
+- **Transparency.** `alpha` defaults to the effect's `transparent`. It is kept in `webm` (VP9/VP8 with an alpha channel, encoded as a second stream and stored as `BlockAdditions`, as Chrome does), in `png`, and in `gif` (one see-through colour, so edges are hard). An `mp4` has no alpha, so asking for both is refused. When alpha is off, transparent pixels are laid over `background` (black for shaders, white for vector effects).
+
+Limits: video needs WebCodecs (Chrome and Edge 94+, Safari 16.4+ for H.264, and Firefox 130+). Safari doesn't play alpha WebM, so use PNG frames there. Everything is held in memory until the end, so record long or 4K clips in parts. Vector effects are rasterised once per frame, which is slower than shaders. A picture from another site needs CORS, as on screen.
+
 #### Effects on video
 
 Image controls can show a playing `<video>` (or a canvas) instead of a picture. `setLiveSource(name, video)` puts it in the control named `name`. The video's current frame is uploaded each time it changes, and a paused preview still follows the video. The renderer never plays, seeks or loops the video itself. The control's value keeps its URL, so documents, presets and agents still see a plain string.
@@ -181,6 +264,24 @@ Overlay shaders (`category: "overlay"`) have `transparent: true`: they write cov
 
 To morph between any two SVG shapes, `morphPaths(from, to)` (from `@pixerate/flair/vector`) returns two paths with one structure, so `attrs: { d: [a, b] }` blends them point by point: curves and arcs are read, pieces are paired by position and size, and a piece with no partner grows from or shrinks to a point (draw them with `fill-rule="evenodd"`). `morphSequence` does the same for three or more shapes. `feature-morph` morphs two photos from five matching points, and `silhouette-morph` morphs any two silhouettes or logos (or words, through `textImage`).
 
+#### An animated SVG file
+
+`svgAnimatedMarkup(motion, options)` (from `@pixerate/flair/vector`) writes any `SvgMotion` as one self-contained `.svg` that plays and loops on its own, with no script and no player: put it in an `<img src>`, open it as a file, or inline it. The changes are written as SMIL, so it needs no DOM to make:
+
+```ts
+import { effectDefaults, getEffect, renderVectorEffect, type VectorEffect } from "@pixerate/flair/catalog";
+import { svgAnimatedMarkup } from "@pixerate/flair/vector";
+
+const effect = getEffect("stat-counter") as VectorEffect;
+const svg = svgAnimatedMarkup(renderVectorEffect(effect, effectDefaults(effect)), { hold: effect.hold })!;
+img.src = `data:image/svg+xml,${encodeURIComponent(svg)}`; // or save it as stat-counter.svg
+```
+
+- **Options**: `hold` (ms on the last frame, default 600), `duration` (the loop, default the picture's length plus `hold`), `loop: false` to play once and stay on the last frame, `steps` (ms) for click-triggered effects, `fps` (default 30) for what is sampled, and `idSuffix`.
+- **How it is written**: each attribute change is one `<animate>` (a `transform` is one `<animateTransform>` per function), and eases are exact `keySplines`. `draw` animates `stroke-dashoffset`, `along` becomes `<animateMotion>` on the path, `view` animates the `viewBox` (keeping `data-fixed` and `data-nonscaling` elements as the player does), and `solo` toggles `display`. Counts and written text are one `<tspan>` per text, shown in turn, sampled at `fps`. Every element starts on the first frame, so it still shows that where SMIL does not run.
+- **Limits**: a count that changes faster than `fps` can be up to half a sample out. A change cut short by the next one, or a `matrix` transform, is sampled. A `view` that frames an element by id (it needs layout) is left out, as in `svgFrameMarkup`. Attributes SMIL cannot blend change in steps. Ids the picture refers to (gradients, filters, paths followed) get a suffix, a hash of the motion by default, so two files inlined in one page don't clash. `#id` selectors in a `<style>` are not renamed. Interaction triggers (hover, press, click) cannot be written as SMIL, so a click-triggered effect plays its `steps` on a timer.
+- **Size**: catalog effects come out at 1 to 105 KB (`drip-text` is the largest).
+
 ### React
 
 `@pixerate/flair/react` wraps the player, so a page needs no ref, effect or dispose of its own. `<VectorEffect>` plays a catalog vector effect by id, `<SvgPlayerView>` any `SvgMotion`:
@@ -357,6 +458,7 @@ The exporters carry the camera too:
 | organic | liquid marble, smoke, lava lamp, plasma, caustics, flames, reaction diffusion, cell division, coral growth, veins, ferrofluid, jellyfish, fur, blob morph |
 | 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 |
+| lighting | relight, point light, studio lighting, time of day, gobo projection, neon spill, candlelight, pool caustics, party lights, lamp switch |
 | retro | synthwave, digital rain, dithered gradient, TV static, 8-bit, Game Boy screen, pixel fire, pixel landscape, OutRun road, palette cycle, raster bars, tape loading, pixel water, pixel text, coin spin, space invader, heart health bar, chomp loader |
 | 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 |
@@ -394,8 +496,51 @@ npx flair html ./effect.frag --out page.html --open
 npx flair scene validate ./scene.json        # layout, framing and timing checks
 npx flair scene review ./scene.json          # fast headless simulation + review
 npx flair scene lottie ./scene.json out.json # also: fcp7, edl, motn
+
+# Catalog effects to files
+npx flair effects --accepts video            # pick an effect: what each takes (--interaction click, --category image, --kind, --search, --json)
+npx flair render image-duotone --image team.jpg --preset Spotify -o team.mp4
+npx flair render crt --video clip.mp4 -o crt.mp4
+npx flair render click-ripple --alpha -o ripple.webm
+npx flair render shader-text --text "FLAIR" --set uSpeed=2 --size 1280x720 -o title.mov
+npx flair render typewriter --text "Hello" -o hello.gif
+npx flair render toggle-switch -o toggle.svg  # vector effects: an animated SVG, no browser needed
+npx flair render aurora --duration 4 -o frames/   # PNG frames (or -o out_%04d.png)
+
+# A shader file of your own
+npx flair export ./effect.frag -o out.mp4 -w 1280 -h 720 -d 5 --values '{"speed":2}'
 ```
 
+#### Rendering in Node
+
+`flair render` and `flair export` render in headless Chrome, so a shader draws exactly as `ShaderRenderer` draws it: the same GLSL wrapper and built-ins (`iPointer`, `iClicks`, `iTrail`), image controls (SVGs sized up first), `int` and `bool` controls. The output format comes from the extension:
+
+| Output | Notes |
+| --- | --- |
+| `.mp4` | H.264, yuv420p, BT.709. Always opaque (`--alpha` is refused). |
+| `.webm` | VP9; `--alpha` keeps transparency (yuva420p). |
+| `.mov` | ProRes 4444; `--alpha` keeps transparency. |
+| `.gif` | 256 colours a frame; `--alpha` gives one-bit transparency. No ffmpeg needed. |
+| `.png` | Frames: a folder (`-o frames/`) or a pattern (`-o out_%04d.png`). No ffmpeg needed. |
+| `.svg` | Vector effects only: one animated SVG (`svgAnimatedMarkup`), with no browser at all. |
+
+Subjects: `--image` (a file or URL), `--svg` (a file, URL or markup), `--text` (with `--font`, `--weight`), `--path` (path data) and `--video` (a file, decoded with ffmpeg to one frame per output frame, looping a short clip; the render lasts as long as the clip, up to 10 s, unless `--duration` says). Repeat a flag for effects that take two pictures, such as transitions. `--set name=value` sets a control (numbers, `true`/`false`, colours like `#ff0080`, or comma-separated vectors), over `--preset`.
+
+Without `--alpha`, overlays are drawn over `--background` (black for shaders, white for vector effects). Effects that answer the pointer get a scripted one that hovers, wanders and clicks (`--no-pointer` leaves it still); click-triggered vector effects are clicked through their steps, and hover or press ones play through and back.
+
+Chrome is found in the usual places, in Playwright's downloads, or at `CHROME_PATH`; ffmpeg on the `PATH` or at `FFMPEG_PATH`. The same from code:
+
+```ts
+import { exportEffect, exportMotionGraphic } from "@pixerate/flair/node";
+
+await exportEffect("image-duotone", { subject: { image: "team.jpg" }, preset: "Spotify", outputPath: "team.mp4" });
+await exportEffect("click-ripple", { alpha: true, outputPath: "ripple.webm" });
+await exportEffect("toggle-switch", { outputPath: "toggle.svg" });
+await exportMotionGraphic({ source, values: { speed: 2 }, outputPath: "out.gif", duration: 2 });
+```
+
+Limits: vector frames are drawn with `svgFrameMarkup`, so a change `along` a path and a `view` that frames an element by id stay where the markup puts them; GIF frame delays are whole hundredths of a second (30 fps plays at 33.3).
+
 ---
 
 ## 🧪 Interactive Browser Demo

package/dist/catalog/index.d.ts

@@ -1,7 +1,76 @@
 import { a as ControlDef, C as ControlValue } from '../controls-Ec6P0Vpy.js';
-import { E as EffectDefinition, a as EffectCategory, b as VideoUse, S as ShaderEffect } from '../types-Cy5EihZ8.js';
-export { C as CURRENT_COLOR, c as EFFECT_CATEGORIES, d as EffectPreset, e as VECTOR_CONTROL_TYPES, f as VIDEO_USES, g as VectorControl, V as VectorEffect, h as colorControl, i as isCurrentColor, n as numberControl, r as renderVectorEffect, v as vectorControlDef, j as vectorControlIssues, k as vectorControls, l as vectorEffectControls } from '../types-Cy5EihZ8.js';
-import '../svg-BEOJriIW.js';
+import { a as SvgTrigger } from '../svg-BhRboN9q.js';
+import { a as VideoUse, E as EffectDefinition, b as EffectCategory, S as ShaderEffect } from '../types-DUOMxZaq.js';
+export { C as CURRENT_COLOR, c as EFFECT_CATEGORIES, d as EffectPreset, e as VECTOR_CONTROL_TYPES, f as VIDEO_USES, g as VectorControl, V as VectorEffect, h as colorControl, i as isCurrentColor, n as numberControl, r as renderVectorEffect, v as vectorControlDef, j as vectorControlIssues, k as vectorControls, l as vectorEffectControls } from '../types-DUOMxZaq.js';
+
+/**
+ * What an effect takes and how it answers the pointer, worked out from the
+ * effect itself (its controls, its `video` use, the pointer built-ins its
+ * source reads, its `trigger`), so a consumer can pair a picture, a video,
+ * an SVG, a word or a path with effects that suit it.
+ */
+
+/**
+ * Something you can give an effect:
+ * - `image`: a photo or picture (any URL or `data:` image) for an image control.
+ * - `video`: a live `<video>` (or canvas) for an image control, with `setLiveSource`.
+ * - `svg`: an SVG file or `data:` URL for an image control (drawn as a picture, keeping its transparency).
+ * - `text`: words, for a text control, or for a text mask through `textImage`.
+ * - `mask`: a shape with transparency (an icon, a logo, `textImage`) whose silhouette the effect uses.
+ * - `path`: SVG path data (`d`), for a shape control.
+ */
+type EffectInput = "image" | "video" | "svg" | "text" | "mask" | "path";
+/** Every {@link EffectInput}. */
+declare const EFFECT_INPUTS: readonly EffectInput[];
+/**
+ * How an effect answers the pointer:
+ * - `hover`: changes while the pointer is over it.
+ * - `press`: changes while the pointer is held down (or dragged).
+ * - `click`: answers each click or tap.
+ * - `trail`: follows where the pointer has just been.
+ * - `pointer`: follows where the pointer is.
+ */
+type EffectInteraction = "hover" | "press" | "click" | "trail" | "pointer";
+/** Every {@link EffectInteraction}. */
+declare const EFFECT_INTERACTIONS: readonly EffectInteraction[];
+/** A shader's image control and what it wants. */
+interface ImageSlot {
+    /** The control's name (a `sampler2D` uniform): set it with `setValues` or `setLiveSource`. */
+    name: string;
+    label: string;
+    /**
+     * What it is for: `picture` (a photo, video or SVG shown as it is), `mask`
+     * (a shape whose transparency the effect uses: an icon, a logo, a
+     * silhouette), or `text` (a word drawn by `textImage`).
+     */
+    wants: "picture" | "mask" | "text";
+}
+/** A vector effect's text control and what it holds. */
+interface TextSlot {
+    /** The control's name: set it with `renderVectorEffect(effect, { [name]: … })`. */
+    name: string;
+    label: string;
+    /** `copy` (words shown), `font` (a CSS font family), `path` (SVG path data) or `glyphs` (characters to draw from). */
+    holds: "copy" | "font" | "path" | "glyphs";
+    default: string;
+}
+/** What an effect takes and how it answers the pointer (see {@link effectInputs}). */
+interface EffectInputs {
+    /** Everything it can be given, from its image and text controls. Empty: it makes its picture from nothing. */
+    accepts: EffectInput[];
+    /** Its image controls (shader effects). */
+    images: ImageSlot[];
+    /** Its text controls (vector effects). */
+    texts: TextSlot[];
+    /** How it suits video, for shaders with an image control (see `VideoUse`). */
+    video?: VideoUse;
+    /** How it answers the pointer; empty when it does not. */
+    interactions: EffectInteraction[];
+    /** A vector effect's trigger: what makes it play. */
+    trigger?: SvgTrigger;
+    /** Draws over other content (render it with `alpha: true`, over a page or picture). */
+    transparent: boolean;
+}
 
 /**
  * Sample pictures for the catalog's image effects: small SVGs as `data:` URLs,
@@ -71,6 +140,7 @@ declare function glsl(...parts: string[]): string;
  * - Video: shader effects with image controls say how they suit video
  *   (`video`, see `VideoUse`); `findEffects({ video: ["filter"] })` finds them.
  * - Controls: `effectControls`, `effectDefaults`.
+ * - Inputs: `effectInputs` (what an effect takes, how it answers the pointer).
  * - Vector effects: their pictures declare their controls (`vectorControls`),
  *   and `renderVectorEffect` fills them in.
  *
@@ -83,6 +153,17 @@ declare const SHADER_EFFECTS: readonly ShaderEffect[];
 declare const EFFECTS: readonly EffectDefinition[];
 /** The effect with this id, or undefined. */
 declare function getEffect(id: string): EffectDefinition | undefined;
+
+/**
+ * What an effect takes and how it answers the pointer: what you can give it
+ * (`accepts`: image, video, svg, text, mask, path), its image controls and
+ * whether each wants a picture, a mask or text, its text controls (copy,
+ * font, path, glyphs), how it suits video, how it answers the pointer
+ * (`interactions`: hover, press, click, trail, pointer) and whether it draws
+ * over other content. Worked out from the effect itself, so it always agrees
+ * with its controls and source.
+ */
+declare function effectInputs(effect: EffectDefinition): EffectInputs;
 interface EffectQuery {
     /** Words to look for in the name, description, tags and id (all must match). */
     text?: string;
@@ -92,6 +173,12 @@ interface EffectQuery {
     tags?: readonly string[];
     /** Effects that suit video in one of these ways (shader effects with image controls only). */
     video?: readonly VideoUse[];
+    /** Effects that can be given every one of these (see {@link effectInputs}): `["image"]`, `["text"]`, `["svg"]`… */
+    accepts?: readonly EffectInput[];
+    /** Effects that answer the pointer in at least one of these ways; `[]` for effects that don't answer it at all. */
+    interaction?: readonly EffectInteraction[];
+    /** Overlays (`true`), which draw over other content, or effects that fill their frame (`false`). */
+    transparent?: boolean;
 }
 /** Effects matching a query, in catalog order. */
 declare function findEffects(query?: EffectQuery): EffectDefinition[];
@@ -103,4 +190,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, VideoUse, effectControls, effectDefaults, findEffects, getEffect, glsl, svgDataUrl, textImage };
+export { EFFECTS, EFFECT_INPUTS, EFFECT_INTERACTIONS, EffectCategory, EffectDefinition, type EffectInput, type EffectInputs, type EffectInteraction, type EffectQuery, FBM, HASH, type ImageSlot, NOISE, OKLAB_MIX, PALETTE, ROTATE, SAMPLE_IMAGES, SHADER_EFFECTS, ShaderEffect, type TextSlot, VideoUse, effectControls, effectDefaults, effectInputs, findEffects, getEffect, glsl, svgDataUrl, textImage };

package/dist/catalog/index.js

@@ -2,6 +2,8 @@ import {
   CURRENT_COLOR,
   EFFECTS,
   EFFECT_CATEGORIES,
+  EFFECT_INPUTS,
+  EFFECT_INTERACTIONS,
   FBM,
   HASH,
   NOISE,
@@ -15,6 +17,7 @@ import {
   colorControl,
   effectControls,
   effectDefaults,
+  effectInputs,
   findEffects,
   getEffect,
   glsl,
@@ -27,7 +30,7 @@ import {
   vectorControlIssues,
   vectorControls,
   vectorEffectControls
-} from "../chunk-3RKDS64M.js";
+} from "../chunk-OQ4EWZ3B.js";
 import "../chunk-OHW7UG6D.js";
 import "../chunk-EHDJ3CPJ.js";
 import "../chunk-VYOMXE6I.js";
@@ -35,6 +38,8 @@ export {
   CURRENT_COLOR,
   EFFECTS,
   EFFECT_CATEGORIES,
+  EFFECT_INPUTS,
+  EFFECT_INTERACTIONS,
   FBM,
   HASH,
   NOISE,
@@ -48,6 +53,7 @@ export {
   colorControl,
   effectControls,
   effectDefaults,
+  effectInputs,
   findEffects,
   getEffect,
   glsl,