@pixerate/flair 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pixerate/flair
 
+## 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

@@ -150,6 +150,33 @@ 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`.
+
 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.
 
 #### Effects on video

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-DLkbOX8d.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-DLkbOX8d.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-4F4KL4KU.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,

package/dist/{chunk-3RKDS64M.js → chunk-4F4KL4KU.js}

@@ -14,6 +14,68 @@ import {
   rgbToHex
 } from "./chunk-VYOMXE6I.js";
 
+// src/catalog/inputs.ts
+var EFFECT_INPUTS = ["image", "video", "svg", "text", "mask", "path"];
+var EFFECT_INTERACTIONS = ["hover", "press", "click", "trail", "pointer"];
+function isTextImage(url) {
+  if (!url.startsWith("data:image/svg+xml;charset=utf-8,")) return false;
+  try {
+    return decodeURIComponent(url.slice(url.indexOf(",") + 1)).includes("<text");
+  } catch {
+    return false;
+  }
+}
+var PATH_DATA = /^\s*[Mm]\s*[-+.\d]/;
+function textSlot(control) {
+  const value = String(control.default);
+  const holds2 = control.name === "font" || /\bfont\b/i.test(control.label) ? "font" : PATH_DATA.test(value) ? "path" : control.name === "glyphs" ? "glyphs" : "copy";
+  return { name: control.name, label: control.label, holds: holds2, default: value };
+}
+function shaderInteractions(source) {
+  const code = source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "");
+  const found = /* @__PURE__ */ new Set();
+  if (/\biClicks\b/.test(code)) found.add("click");
+  if (/\biTrail\b/.test(code)) found.add("trail");
+  if (/\biPointer\s*\.\s*z\b/.test(code)) found.add("hover");
+  if (/\biPointer\s*\.\s*w\b/.test(code) || /\biMouse\s*\.\s*z\b/.test(code)) found.add("press");
+  if (/\biPointer\s*\.\s*xy?\b/.test(code) || /\biMouse\s*\.\s*xy?\b/.test(code)) found.add("pointer");
+  return EFFECT_INTERACTIONS.filter((i) => found.has(i));
+}
+function inputsOf(effect, controls) {
+  const accepts = /* @__PURE__ */ new Set();
+  const images = [];
+  const texts = [];
+  for (const control of controls) {
+    if (control.type === "sampler2D") {
+      const value = String(control.default);
+      const video = effect.kind === "shader" ? effect.video : void 0;
+      const wants = isTextImage(value) ? "text" : video === "none" ? "mask" : "picture";
+      images.push({ name: control.name, label: control.label, wants });
+      if (wants === "picture") {
+        accepts.add("image").add("svg");
+        if (video && video !== "none") accepts.add("video");
+      } else {
+        accepts.add("mask").add("svg").add("text").add("image");
+      }
+    } else if (control.type === "text") {
+      const slot = textSlot(control);
+      texts.push(slot);
+      if (slot.holds === "copy") accepts.add("text");
+      if (slot.holds === "path") accepts.add("path");
+    }
+  }
+  const interactions = effect.kind === "vector" ? effect.trigger ? [effect.trigger] : [] : shaderInteractions(effect.source);
+  return {
+    accepts: EFFECT_INPUTS.filter((i) => accepts.has(i)),
+    images,
+    texts,
+    ...effect.kind === "shader" && effect.video ? { video: effect.video } : {},
+    interactions,
+    ...effect.kind === "vector" && effect.trigger ? { trigger: effect.trigger } : {},
+    transparent: effect.kind === "shader" ? Boolean(effect.transparent) : false
+  };
+}
+
 // src/catalog/glsl.ts
 var HASH = `
 float hash12(vec2 p) {
@@ -10242,7 +10304,7 @@ var fireworks = {
   name: "Fireworks",
   description: "Shells rising on faint trails and bursting into peonies, chrysanthemums, gold willows and rings that droop and twinkle out; clicks fire more.",
   category: "pyrotechnics",
-  tags: ["pyro", "overlay", "fireworks", "celebration", "festive", "night", "click"],
+  tags: ["pyro", "overlay", "fireworks", "celebration", "festive", "night", "click", "interactive"],
   transparent: true,
   source: glsl(
     `// Fireworks: staggered shells rising and bursting into peony, chrysanthemum, willow and ring patterns.
@@ -10461,7 +10523,7 @@ var explosion = {
   name: "Explosion",
   description: "A fireball cooling from white-hot to orange to rolling dark smoke, with a shockwave ring and flying debris; it loops and also goes off at each click.",
   category: "pyrotechnics",
-  tags: ["pyro", "overlay", "explosion", "fire", "smoke", "action", "click"],
+  tags: ["pyro", "overlay", "explosion", "fire", "smoke", "action", "click", "interactive"],
   transparent: true,
   loop: 3,
   source: glsl(
@@ -11308,7 +11370,7 @@ var bulletTime = {
   description: "A shockwave sweeping out from the centre or a click, freezing the picture grey and zoomed behind it while the rest moves on.",
   category: "timewarp",
   video: "stills",
-  tags: ["time", "image", "freeze", "shockwave", "click", "cinematic"],
+  tags: ["time", "image", "freeze", "shockwave", "click", "cinematic", "interactive"],
   loop: 8,
   source: glsl(
     `// Bullet time: every 4 s (or on a click) a wave freezes the picture behind it, then lets go.
@@ -11659,7 +11721,7 @@ var silhouetteMorph = {
   name: "Silhouette morph",
   description: "One silhouette or logo flowing into another as a gooey blob, its colour blending from the first shape's to the second's.",
   category: "morph",
-  video: "stills",
+  video: "none",
   tags: ["morph", "shape", "logo", "goo", "blob", "text"],
   loop: 4,
   source: glsl(
@@ -20128,6 +20190,12 @@ var byId = new Map(EFFECTS.map((e) => [e.id, e]));
 function getEffect(id) {
   return byId.get(id);
 }
+var inputsCache = /* @__PURE__ */ new WeakMap();
+function effectInputs(effect) {
+  let inputs = inputsCache.get(effect);
+  if (!inputs) inputsCache.set(effect, inputs = inputsOf(effect, effectControls(effect)));
+  return inputs;
+}
 function findEffects(query = {}) {
   const words = (query.text ?? "").toLowerCase().split(/\s+/).filter(Boolean);
   return EFFECTS.filter((e) => {
@@ -20135,6 +20203,15 @@ function findEffects(query = {}) {
     if (query.kind && e.kind !== query.kind) return false;
     if (query.tags && !query.tags.every((t) => e.tags.includes(t))) return false;
     if (query.video && !(e.kind === "shader" && e.video && query.video.includes(e.video))) return false;
+    if (query.accepts || query.interaction || query.transparent !== void 0) {
+      const inputs = effectInputs(e);
+      if (query.accepts && !query.accepts.every((i) => inputs.accepts.includes(i))) return false;
+      if (query.interaction) {
+        const answers = query.interaction.length === 0 ? inputs.interactions.length === 0 : query.interaction.some((i) => inputs.interactions.includes(i));
+        if (!answers) return false;
+      }
+      if (query.transparent !== void 0 && inputs.transparent !== query.transparent) return false;
+    }
     const haystack = [e.id, e.name, e.description, e.category, ...e.tags].join(" ").toLowerCase();
     return words.every((w) => haystack.includes(w));
   });
@@ -20150,6 +20227,8 @@ function effectDefaults(effect, options = {}) {
 }
 
 export {
+  EFFECT_INPUTS,
+  EFFECT_INTERACTIONS,
   HASH,
   NOISE,
   FBM,
@@ -20175,8 +20254,9 @@ export {
   SHADER_EFFECTS,
   EFFECTS,
   getEffect,
+  effectInputs,
   findEffects,
   effectControls,
   effectDefaults
 };
-//# sourceMappingURL=chunk-3RKDS64M.js.map
+//# sourceMappingURL=chunk-4F4KL4KU.js.map