@pixerate/editor 0.172.0 → 0.174.0

package/dist/animation-editor/index.cjs

@@ -48,7 +48,7 @@ require('../chunk-NM3G4VQT.cjs');
 
 
 
-var _chunkRUZQMYXHcjs = require('../chunk-RUZQMYXH.cjs');
+var _chunkA3A5TI6Rcjs = require('../chunk-A3A5TI6R.cjs');
 require('../chunk-WOFXZ3XU.cjs');
 require('../chunk-EBDCRTZI.cjs');
 require('../chunk-YQGCPL5X.cjs');
@@ -3827,7 +3827,7 @@ var AnimationEditorController = (_class = class {
   
   
   /** The effects provider slot (see `setEffectsProvider`). */
-  __init() {this.effects = new (0, _chunkRUZQMYXHcjs.EffectsSlot)()}
+  __init() {this.effects = new (0, _chunkA3A5TI6Rcjs.EffectsSlot)()}
   
   
   __init2() {this.selection = null}
@@ -4012,7 +4012,7 @@ var AnimationEditorController = (_class = class {
     try {
       plan = await work();
     } catch (error) {
-      if (_chunkRUZQMYXHcjs.isEffectError.call(void 0, error) || error instanceof Error) return this.refuse(error.message);
+      if (_chunkA3A5TI6Rcjs.isEffectError.call(void 0, error) || error instanceof Error) return this.refuse(error.message);
       throw error;
     }
     const r = this.apply({ op: "replace_scene", scene: plan.scene }, plan.label, { merge });
@@ -4023,11 +4023,11 @@ var AnimationEditorController = (_class = class {
   }
   async describeFor(effect, kinds) {
     const provider = this.effects.require();
-    if (!provider.applyVectorEffect) throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(`${provider.name} has no vector or motion effects.`);
+    if (!provider.applyVectorEffect) throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`${provider.name} has no vector or motion effects.`);
     const d = await provider.describe(effect);
     if (!kinds.includes(d.kind)) {
       const hint = d.kind === "motion" ? "apply it to nodes with apply_effect" : d.kind === "vector" ? "add it with add_vector_effect" : "it draws pixels, which scenes cannot hold";
-      throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.kind} effect: ${hint}.`, d.id);
+      throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.kind} effect: ${hint}.`, d.id);
     }
     return d;
   }
@@ -4048,7 +4048,7 @@ var AnimationEditorController = (_class = class {
     return this.effectEdit(async () => {
       this.knownNodes(targets);
       const d = await this.describeFor(effect, ["motion"]);
-      const values = _chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, d, options.values);
+      const values = _chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, d, options.values);
       const instance = _nullishCoalesce(options.instance, () => ( nextMotionEffectInstance(this.scene)));
       const motion = await this.effects.require().applyVectorEffect(d.id, { svg: motionArtworkSvg(this.scene.artwork), nodeIds: [...targets] }, values);
       const source = { instance, effect: d.id, provider: this.effects.require().id, name: d.name, values };
@@ -4070,7 +4070,7 @@ var AnimationEditorController = (_class = class {
   addVectorEffect(effect, options = {}) {
     return this.effectEdit(async () => {
       const d = await this.describeFor(effect, ["vector"]);
-      const values = _chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, d, options.values);
+      const values = _chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, d, options.values);
       const instance = _nullishCoalesce(options.instance, () => ( nextMotionEffectInstance(this.scene)));
       const motion = await this.effects.require().applyVectorEffect(d.id, motionArtworkSvg(this.scene.artwork), values);
       const source = { instance, effect: d.id, provider: this.effects.require().id, name: d.name, values };
@@ -4094,7 +4094,7 @@ var AnimationEditorController = (_class = class {
         else if (k in d.controls.properties) base[k] = d.defaults[k];
         else throw new Error(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
       }
-      const merged = { ...base, ..._chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
+      const merged = { ...base, ..._chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
       const { scene: bare, place } = withoutMotionEffect(this.scene, instance);
       const provider = this.effects.require();
       const source = { instance, effect: d.id, provider: provider.id, name: d.name, values: merged };
@@ -5867,7 +5867,7 @@ function createAnimationEffectsToolProvider(controller, options = {}) {
     if (!r.ok) throw new Error(r.error);
     return { target, effect: info(r.effect), effects: controller.appliedEffects().filter((e) => e.targets.includes(target)).map(info), ...r.notes.length ? { notes: r.notes } : {} };
   };
-  return withAnimationPlayback(_chunkRUZQMYXHcjs.createEffectToolProvider.call(void 0, {
+  return withAnimationPlayback(_chunkA3A5TI6Rcjs.createEffectToolProvider.call(void 0, {
     id: _nullishCoalesce(options.id, () => ( "animation-effects")),
     namespace: options.namespace,
     title: "Animation effects",

package/dist/animation-editor/index.js

@@ -48,7 +48,7 @@ import {
   createEffectToolProvider,
   isEffectError,
   resolveEffectValues
-} from "../chunk-7KWJEYIK.js";
+} from "../chunk-6G2NLMVK.js";
 import "../chunk-V2ZCJRDM.js";
 import "../chunk-2N2QPO3H.js";
 import "../chunk-ODBT55Q7.js";

package/dist/canvas/index.cjs

@@ -209,7 +209,7 @@ var _chunkNM3G4VQTcjs = require('../chunk-NM3G4VQT.cjs');
 
 
 
-var _chunkRUZQMYXHcjs = require('../chunk-RUZQMYXH.cjs');
+var _chunkA3A5TI6Rcjs = require('../chunk-A3A5TI6R.cjs');
 require('../chunk-WOFXZ3XU.cjs');
 
 
@@ -11396,14 +11396,14 @@ function canvasNodeEffect(node) {
   return _chunkNM3G4VQTcjs.isShapeDescription.call(void 0, shape) ? shape.effect : void 0;
 }
 function createCanvasEffectsController(options) {
-  const slot = new (0, _chunkRUZQMYXHcjs.EffectsSlot)();
+  const slot = new (0, _chunkA3A5TI6Rcjs.EffectsSlot)();
   if (options.effects) slot.set(options.effects);
   const describe = async (effect, place2) => {
     const d = await slot.require().describe(effect);
     const allowed = CANVAS_EFFECT_PLACES[place2];
     if (d.kind === "motion" || !d.uses.some((u) => allowed.includes(u))) {
       const where = place2 === "transition" ? "a scene transition" : place2 === "fill" ? "a fill" : "an overlay";
-      throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.uses.join(" / ")} effect and cannot be ${where}, which takes ${allowed.join(" or ")} effects; search_effects with use "${allowed[0]}" lists ones that fit.`, d.id);
+      throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.uses.join(" / ")} effect and cannot be ${where}, which takes ${allowed.join(" or ")} effects; search_effects with use "${allowed[0]}" lists ones that fit.`, d.id);
     }
     return d;
   };
@@ -11434,7 +11434,7 @@ function createCanvasEffectsController(options) {
       else if (k in d.controls.properties) base[k] = d.defaults[k];
       else throw new Error(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
     }
-    return { ...base, ..._chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
+    return { ...base, ..._chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
   };
   return {
     /** The provider slot. */
@@ -11464,7 +11464,7 @@ function createCanvasEffectsController(options) {
       const mode = _nullishCoalesce(opts.mode, () => ( "fill"));
       const d = await describe(effect, mode);
       if (opts.opacity !== void 0 && !(opts.opacity >= 0 && opts.opacity <= 1)) throw new Error("opacity must be from 0 to 1.");
-      const next = { effect: d.id, provider: slot.require().id, name: d.name, values: _chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, d, opts.values), mode, ...opts.opacity !== void 0 && opts.opacity !== 1 ? { opacity: opts.opacity } : {} };
+      const next = { effect: d.id, provider: slot.require().id, name: d.name, values: _chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, d, opts.values), mode, ...opts.opacity !== void 0 && opts.opacity !== 1 ? { opacity: opts.opacity } : {} };
       commit(`Add effect ${d.name}`, withEffect(nodeId, next));
       return next;
     },
@@ -11521,7 +11521,7 @@ function createCanvasEffectsController(options) {
       const d = await describe(effect, "transition");
       const duration = _nullishCoalesce(_nullishCoalesce(opts.duration, () => ( d.duration)), () => ( 600));
       if (!(duration > 0)) throw new Error("duration must be a number of ms above 0.");
-      const transition = { effect: d.id, provider: slot.require().id, name: d.name, values: _chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, d, opts.values), duration };
+      const transition = { effect: d.id, provider: slot.require().id, name: d.name, values: _chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, d, opts.values), duration };
       scenes2.update(sceneId, { transition });
       return transition;
     }
@@ -11665,7 +11665,7 @@ function createCanvasEffectsToolProvider(controller, options = {}) {
   const once = (instance) => {
     if (instance !== "effect") throw new Error('A shape node has one effect, "effect".');
   };
-  return _chunkRUZQMYXHcjs.createEffectToolProvider.call(void 0, {
+  return _chunkA3A5TI6Rcjs.createEffectToolProvider.call(void 0, {
     id: _nullishCoalesce(options.id, () => ( "canvas-effects")),
     namespace: options.namespace,
     title: "Canvas effects",

package/dist/canvas/index.js

@@ -209,7 +209,7 @@ import {
   EffectsSlot,
   createEffectToolProvider,
   resolveEffectValues
-} from "../chunk-7KWJEYIK.js";
+} from "../chunk-6G2NLMVK.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   brushstrokeScaleBucket

package/dist/{chunk-CYKWYP6D.cjs → chunk-6DUEV36F.cjs}

@@ -3,7 +3,7 @@
 
 
 
-var _chunkRUZQMYXHcjs = require('./chunk-RUZQMYXH.cjs');
+var _chunkA3A5TI6Rcjs = require('./chunk-A3A5TI6R.cjs');
 
 
 var _chunkFJ2MSI43cjs = require('./chunk-FJ2MSI43.cjs');
@@ -26,7 +26,7 @@ function documentErrors(doc, description) {
   const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
   if (doc.values !== void 0) {
     if (!isRecord(doc.values)) errors.push({ path: "/values", message: "must be an object of control values" });
-    else errors.push(..._chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, doc.values).map((e) => ({ ...e, path: `/values${e.path}` })));
+    else errors.push(..._chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, doc.values).map((e) => ({ ...e, path: `/values${e.path}` })));
   }
   if (doc.tracks !== void 0) {
     if (!isRecord(doc.tracks)) errors.push({ path: "/tracks", message: "must be an object of keyframe lists" });
@@ -39,7 +39,7 @@ function documentErrors(doc, description) {
           kfs.forEach((kf, i) => {
             if (!isRecord(kf)) return errors.push({ path: `${at}/${i}`, message: "must be a keyframe object" });
             if (typeof kf.time !== "number" || !Number.isFinite(kf.time) || kf.time < 0) errors.push({ path: `${at}/${i}/time`, message: "must be a finite number of ms >= 0" });
-            errors.push(..._chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, { [control]: kf.value }).map((e) => ({ ...e, path: `${at}/${i}/value` })));
+            errors.push(..._chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, { [control]: kf.value }).map((e) => ({ ...e, path: `${at}/${i}/value` })));
             if (kf.easing !== void 0 && !_chunkDWJJI6RTcjs.isAnimationEasing.call(void 0, kf.easing)) errors.push({ path: `${at}/${i}/easing`, message: "is not a valid easing" });
           });
       }
@@ -49,7 +49,7 @@ function documentErrors(doc, description) {
     else
       doc.presets.forEach((p, i) => {
         if (!isRecord(p) || typeof p.name !== "string" || !p.name) return errors.push({ path: `/presets/${i}`, message: "must have a name" });
-        errors.push(..._chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, p.values).map((e) => ({ ...e, path: `/presets/${i}/values${e.path}` })));
+        errors.push(..._chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, p.values).map((e) => ({ ...e, path: `/presets/${i}/values${e.path}` })));
       });
   }
   if (doc.duration !== void 0 && (typeof doc.duration !== "number" || !Number.isFinite(doc.duration) || !(doc.duration > 0))) {
@@ -170,7 +170,7 @@ async function createEffectAuthoringSession(source, options) {
   if (isDocumentSource(source)) {
     const doc = source.document;
     if (doc.version !== 1 || !doc.effectId) {
-      throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)("Invalid effect authoring document: version 1 required");
+      throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)("Invalid effect authoring document: version 1 required");
     }
     effectId = doc.effectId;
     initialDoc = doc;
@@ -178,15 +178,15 @@ async function createEffectAuthoringSession(source, options) {
     effectId = source.effectId;
     requestedPreset = source.preset;
   } else {
-    throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)("Invalid effect authoring source");
+    throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)("Invalid effect authoring source");
   }
   const description = await provider.describe(effectId);
   if (initialDoc) {
     const problems = documentErrors(initialDoc, description);
-    if (problems.length) throw new (0, _chunkRUZQMYXHcjs.EffectControlError)(effectId, problems);
+    if (problems.length) throw new (0, _chunkA3A5TI6Rcjs.EffectControlError)(effectId, problems);
   }
   if (description.kind === "motion") {
-    throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)("Motion effects cannot be authored as pixel effects", effectId);
+    throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)("Motion effects cannot be authored as pixel effects", effectId);
   }
   let disposed = false;
   let playing = false;
@@ -207,7 +207,7 @@ async function createEffectAuthoringSession(source, options) {
     const found = description.presets.find((p) => p.name === requestedPreset);
     if (!found) {
       const validNames = description.presets.map((p) => `"${p.name}"`).join(", ");
-      throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(
+      throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(
         `Unknown preset "${requestedPreset}" for effect "${effectId}". Valid presets are: ${validNames || "none"}`,
         effectId
       );
@@ -321,7 +321,7 @@ async function createEffectAuthoringSession(source, options) {
       if (!validNames.includes(name)) {
         return { ok: false, message: `there is no control "${name}"; the controls are ${validNames.join(", ")}` };
       }
-      const errors = _chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, { [name]: value });
+      const errors = _chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, { [name]: value });
       if (errors.length > 0) {
         return { ok: false, message: valueErrorMessage(errors) };
       }
@@ -391,7 +391,7 @@ async function createEffectAuthoringSession(source, options) {
         if (!validNames.includes(k)) {
           return { ok: false, message: `there is no control "${k}"; the controls are ${validNames.join(", ")}` };
         }
-        const errors = _chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, { [k]: v });
+        const errors = _chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, { [k]: v });
         if (errors.length > 0) {
           return { ok: false, message: valueErrorMessage(errors) };
         }
@@ -528,7 +528,7 @@ async function createEffectAuthoringSession(source, options) {
         return { ok: false, message: `invalid easing: ${String(easing)}` };
       }
       const targetValue = value !== void 0 ? value : valuesAtTime(time, baseValues, tracks)[name];
-      const errors = _chunkRUZQMYXHcjs.effectValueErrors.call(void 0, description, { [name]: targetValue });
+      const errors = _chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, description, { [name]: targetValue });
       if (errors.length > 0) {
         return { ok: false, message: valueErrorMessage(errors) };
       }
@@ -705,7 +705,7 @@ async function createEffectAuthoringSession(source, options) {
     },
     async createPreview(opts) {
       if (disposed) {
-        throw new (0, _chunkRUZQMYXHcjs.EffectDisposedError)(effectId);
+        throw new (0, _chunkA3A5TI6Rcjs.EffectDisposedError)(effectId);
       }
       let renderer;
       try {
@@ -730,7 +730,7 @@ async function createEffectAuthoringSession(source, options) {
         height: renderer.height,
         depth: renderer.depth,
         render: async (req) => {
-          if (disposed) throw new (0, _chunkRUZQMYXHcjs.EffectDisposedError)(effectId);
+          if (disposed) throw new (0, _chunkA3A5TI6Rcjs.EffectDisposedError)(effectId);
           const effectiveValues = _nullishCoalesce(req.values, () => ( valuesAtTime(req.time, baseValues, tracks)));
           const pixels = await renderer.render({
             ...req,

package/dist/{chunk-7KWJEYIK.js → chunk-6G2NLMVK.js}

@@ -68,7 +68,20 @@ function resolveEffectValues(description, values) {
   if (errors.length) throw new EffectControlError(description.id, errors);
   return { ...description.defaults, ...values ?? {} };
 }
-var matchesFilters = (e, o) => (!o.kind || e.kind === o.kind) && (!o.category || e.category === o.category) && (!o.use || e.uses.includes(o.use));
+function normaliseEffectTag(tag) {
+  return tag.trim().toLowerCase().replace(/[\s_-]+/g, "-");
+}
+function hasEffectTags(e, tags) {
+  if (!tags?.length) return true;
+  const own = new Set((e.tags ?? []).map(normaliseEffectTag));
+  return tags.every((t) => own.has(normaliseEffectTag(t)));
+}
+function countEffectTags(effects) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const e of effects) for (const tag of new Set((e.tags ?? []).map(normaliseEffectTag))) if (tag) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  return [...counts].map(([tag, count]) => ({ tag, count })).sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag));
+}
+var matchesFilters = (e, o) => (!o.kind || e.kind === o.kind) && (!o.category || e.category === o.category) && (!o.use || e.uses.includes(o.use)) && hasEffectTags(e, o.tags);
 function searchEffectSummaries(catalog, query = "", options = {}) {
   const words = query.toLowerCase().split(/\s+/).filter(Boolean);
   const scored = [];
@@ -174,6 +187,12 @@ var object = (properties, required = []) => ({
   additionalProperties: false
 });
 var ENUM_LIMIT = 60;
+var TAG_LIMIT = 40;
+function nearestTags(tag, known) {
+  const t = normaliseEffectTag(tag);
+  const stem = t.slice(0, 4);
+  return known.filter((k) => k.tag.includes(t) || t.includes(k.tag) || stem.length === 4 && k.tag.startsWith(stem)).slice(0, 5).map((k) => k.tag);
+}
 var summaryOut = (e) => ({
   id: e.id,
   name: e.name,
@@ -181,6 +200,7 @@ var summaryOut = (e) => ({
   category: e.category,
   uses: e.uses,
   ...e.description ? { description: e.description } : {},
+  ...e.tags?.length ? { tags: e.tags } : {},
   transparent: e.transparent,
   loop: e.loop,
   ...e.duration !== void 0 ? { duration: e.duration } : {}
@@ -241,21 +261,30 @@ function createEffectToolProvider(host) {
     {
       name: "search_effects",
       title: "Search effects",
-      description: `Searches the effects provider's catalog. Every word of query must appear in an effect's id, name, category, tags or description; filter by kind (shader, vector, motion), category or use (${EFFECT_USES.join(", ")}). For this editor, apply_effect takes uses ${host.applyUses.join(" or ")}. Returns { provider, effects: [{ id, name, kind, category, uses, description, transparent, loop, duration (ms) }], total }. With no provider registered it returns available: false and the reason. Call describe_effect next for an effect's controls.`,
+      description: `Searches the effects provider's catalog. Every word of query must appear in an effect's id, name, category, tags or description; filter by kind (shader, vector, motion), category, use (${EFFECT_USES.join(", ")}) or tags (effects carrying every one). For this editor, apply_effect takes uses ${host.applyUses.join(" or ")}. Returns { provider, effects: [{ id, name, kind, category, uses, description, tags, transparent, loop, duration (ms) }], total, tags: [{ tag, count }] }: tags lists the tags of every match, the most used first, so a broad search (or none) shows the tags to narrow by. A tag the catalog does not have comes back in unknownTags with the nearest ones. With no provider registered it returns available: false and the reason. Call describe_effect next for an effect's controls.`,
       inputSchema: object({
         query: { type: "string", description: "Words to match (default: every effect)." },
         kind: { type: "string", enum: [...EFFECT_KINDS], description: "shader (pixels), vector (animated SVG) or motion (animates vector art)." },
         category: { type: "string", minLength: 1, description: `The provider's category, e.g. "gradient", "light", "transition".` },
         use: { type: "string", enum: [...EFFECT_USES], description: "What the effect is for: filter changes a picture, transition blends two, generator draws a background, overlay draws over content, title draws a title, motion animates vector art, interactive reacts to input." },
+        tags: { type: "array", items: { type: "string", minLength: 1 }, description: "Only effects carrying every one of these tags, as search_effects lists them (any case; spaces count as hyphens)." },
         limit: { type: "integer", minimum: 1, maximum: 200, description: "Most effects to return (default 20)." }
       }),
       annotations: { title: "Search effects", ...ANNOTATIONS.read },
       handler: async (args) => {
         const p = host.provider();
         if (!p) return { available: false, reason: NO_PROVIDER, effects: [], total: 0 };
-        const found = await explain(async () => p.search(args.query ?? "", { kind: args.kind, category: args.category, use: args.use }));
+        const tags = args.tags;
+        const found = (await explain(async () => p.search(args.query ?? "", { kind: args.kind, category: args.category, use: args.use, tags }))).filter((e) => hasEffectTags(e, tags));
         const limit = args.limit ?? 20;
-        return { available: true, provider: { id: p.id, name: p.name, capabilities: p.capabilities }, effects: found.slice(0, limit).map(summaryOut), total: found.length };
+        const out = { available: true, provider: { id: p.id, name: p.name, capabilities: p.capabilities }, effects: found.slice(0, limit).map(summaryOut), total: found.length, tags: countEffectTags(found).slice(0, TAG_LIMIT) };
+        if (tags?.length && !found.length) {
+          const known = countEffectTags(await explain(async () => p.list()));
+          const have = new Set(known.map((k) => k.tag));
+          const unknown = tags.filter((t) => !have.has(normaliseEffectTag(t)));
+          if (unknown.length) out.unknownTags = unknown.map((tag) => ({ tag, nearest: nearestTags(tag, known) }));
+        }
+        return out;
       }
     },
     {
@@ -374,6 +403,9 @@ export {
   isEffectError,
   effectValueErrors,
   resolveEffectValues,
+  normaliseEffectTag,
+  hasEffectTags,
+  countEffectTags,
   searchEffectSummaries,
   createEffectPixels,
   isEffectPixels,

package/dist/{chunk-RUZQMYXH.cjs → chunk-A3A5TI6R.cjs}

@@ -68,7 +68,20 @@ function resolveEffectValues(description, values) {
   if (errors.length) throw new EffectControlError(description.id, errors);
   return { ...description.defaults, ..._nullishCoalesce(values, () => ( {})) };
 }
-var matchesFilters = (e, o) => (!o.kind || e.kind === o.kind) && (!o.category || e.category === o.category) && (!o.use || e.uses.includes(o.use));
+function normaliseEffectTag(tag) {
+  return tag.trim().toLowerCase().replace(/[\s_-]+/g, "-");
+}
+function hasEffectTags(e, tags) {
+  if (!_optionalChain([tags, 'optionalAccess', _ => _.length])) return true;
+  const own = new Set((_nullishCoalesce(e.tags, () => ( []))).map(normaliseEffectTag));
+  return tags.every((t) => own.has(normaliseEffectTag(t)));
+}
+function countEffectTags(effects) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const e of effects) for (const tag of new Set((_nullishCoalesce(e.tags, () => ( []))).map(normaliseEffectTag))) if (tag) counts.set(tag, (_nullishCoalesce(counts.get(tag), () => ( 0))) + 1);
+  return [...counts].map(([tag, count]) => ({ tag, count })).sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag));
+}
+var matchesFilters = (e, o) => (!o.kind || e.kind === o.kind) && (!o.category || e.category === o.category) && (!o.use || e.uses.includes(o.use)) && hasEffectTags(e, o.tags);
 function searchEffectSummaries(catalog, query = "", options = {}) {
   const words = query.toLowerCase().split(/\s+/).filter(Boolean);
   const scored = [];
@@ -174,6 +187,12 @@ var object = (properties, required = []) => ({
   additionalProperties: false
 });
 var ENUM_LIMIT = 60;
+var TAG_LIMIT = 40;
+function nearestTags(tag, known) {
+  const t = normaliseEffectTag(tag);
+  const stem = t.slice(0, 4);
+  return known.filter((k) => k.tag.includes(t) || t.includes(k.tag) || stem.length === 4 && k.tag.startsWith(stem)).slice(0, 5).map((k) => k.tag);
+}
 var summaryOut = (e) => ({
   id: e.id,
   name: e.name,
@@ -181,6 +200,7 @@ var summaryOut = (e) => ({
   category: e.category,
   uses: e.uses,
   ...e.description ? { description: e.description } : {},
+  ..._optionalChain([e, 'access', _2 => _2.tags, 'optionalAccess', _3 => _3.length]) ? { tags: e.tags } : {},
   transparent: e.transparent,
   loop: e.loop,
   ...e.duration !== void 0 ? { duration: e.duration } : {}
@@ -191,7 +211,7 @@ function createEffectToolProvider(host) {
   const notify = () => listeners.forEach((l) => l());
   const catalogFor = (provider) => {
     if (!provider) return null;
-    if (_optionalChain([catalog, 'optionalAccess', _ => _.provider]) !== provider) {
+    if (_optionalChain([catalog, 'optionalAccess', _4 => _4.provider]) !== provider) {
       const entry = { provider, effects: null };
       catalog = entry;
       Promise.resolve().then(() => provider.list()).then((effects) => {
@@ -227,7 +247,7 @@ function createEffectToolProvider(host) {
     description: `${what}: control name \u2192 value, as listed by describe_effect (its "controls" schema: types, ranges, units and defaults). Only the given controls change; colours are "#rrggbb".${keyframes ? " A number control may instead be keyframes { keys: [{ t: ms from the start, v, ease }] }." : ""} Unknown controls and out-of-range values are refused with the valid ones.`
   });
   const effectIdSchema = (uses) => {
-    const effects = _optionalChain([catalogFor, 'call', _2 => _2(host.provider()), 'optionalAccess', _3 => _3.filter, 'call', _4 => _4((e) => (e.kind !== "motion" || uses.includes("motion")) && e.uses.some((u) => uses.includes(u)))]);
+    const effects = _optionalChain([catalogFor, 'call', _5 => _5(host.provider()), 'optionalAccess', _6 => _6.filter, 'call', _7 => _7((e) => (e.kind !== "motion" || uses.includes("motion")) && e.uses.some((u) => uses.includes(u)))]);
     const base = `An effect id from search_effects (use ${uses.map((u) => `"${u}"`).join(" or ")}).`;
     return effects && effects.length && effects.length <= ENUM_LIMIT ? { type: "string", enum: effects.map((e) => e.id), description: `${base} One of: ${effects.map((e) => `${e.id} (${e.name})`).join(", ")}.` } : { type: "string", minLength: 1, description: base };
   };
@@ -241,21 +261,30 @@ function createEffectToolProvider(host) {
     {
       name: "search_effects",
       title: "Search effects",
-      description: `Searches the effects provider's catalog. Every word of query must appear in an effect's id, name, category, tags or description; filter by kind (shader, vector, motion), category or use (${EFFECT_USES.join(", ")}). For this editor, apply_effect takes uses ${host.applyUses.join(" or ")}. Returns { provider, effects: [{ id, name, kind, category, uses, description, transparent, loop, duration (ms) }], total }. With no provider registered it returns available: false and the reason. Call describe_effect next for an effect's controls.`,
+      description: `Searches the effects provider's catalog. Every word of query must appear in an effect's id, name, category, tags or description; filter by kind (shader, vector, motion), category, use (${EFFECT_USES.join(", ")}) or tags (effects carrying every one). For this editor, apply_effect takes uses ${host.applyUses.join(" or ")}. Returns { provider, effects: [{ id, name, kind, category, uses, description, tags, transparent, loop, duration (ms) }], total, tags: [{ tag, count }] }: tags lists the tags of every match, the most used first, so a broad search (or none) shows the tags to narrow by. A tag the catalog does not have comes back in unknownTags with the nearest ones. With no provider registered it returns available: false and the reason. Call describe_effect next for an effect's controls.`,
       inputSchema: object({
         query: { type: "string", description: "Words to match (default: every effect)." },
         kind: { type: "string", enum: [...EFFECT_KINDS], description: "shader (pixels), vector (animated SVG) or motion (animates vector art)." },
         category: { type: "string", minLength: 1, description: `The provider's category, e.g. "gradient", "light", "transition".` },
         use: { type: "string", enum: [...EFFECT_USES], description: "What the effect is for: filter changes a picture, transition blends two, generator draws a background, overlay draws over content, title draws a title, motion animates vector art, interactive reacts to input." },
+        tags: { type: "array", items: { type: "string", minLength: 1 }, description: "Only effects carrying every one of these tags, as search_effects lists them (any case; spaces count as hyphens)." },
         limit: { type: "integer", minimum: 1, maximum: 200, description: "Most effects to return (default 20)." }
       }),
       annotations: { title: "Search effects", ...ANNOTATIONS.read },
       handler: async (args) => {
         const p = host.provider();
         if (!p) return { available: false, reason: NO_PROVIDER, effects: [], total: 0 };
-        const found = await explain(async () => p.search(_nullishCoalesce(args.query, () => ( "")), { kind: args.kind, category: args.category, use: args.use }));
+        const tags = args.tags;
+        const found = (await explain(async () => p.search(_nullishCoalesce(args.query, () => ( "")), { kind: args.kind, category: args.category, use: args.use, tags }))).filter((e) => hasEffectTags(e, tags));
         const limit = _nullishCoalesce(args.limit, () => ( 20));
-        return { available: true, provider: { id: p.id, name: p.name, capabilities: p.capabilities }, effects: found.slice(0, limit).map(summaryOut), total: found.length };
+        const out = { available: true, provider: { id: p.id, name: p.name, capabilities: p.capabilities }, effects: found.slice(0, limit).map(summaryOut), total: found.length, tags: countEffectTags(found).slice(0, TAG_LIMIT) };
+        if (_optionalChain([tags, 'optionalAccess', _8 => _8.length]) && !found.length) {
+          const known = countEffectTags(await explain(async () => p.list()));
+          const have = new Set(known.map((k) => k.tag));
+          const unknown = tags.filter((t) => !have.has(normaliseEffectTag(t)));
+          if (unknown.length) out.unknownTags = unknown.map((tag) => ({ tag, nearest: nearestTags(tag, known) }));
+        }
+        return out;
       }
     },
     {
@@ -348,16 +377,16 @@ function createEffectToolProvider(host) {
     ...host.description ? { description: host.description } : {},
     ...host.skill ? { skill: host.skill } : {},
     tools: () => {
-      const extra = _nullishCoalesce(_optionalChain([host, 'access', _5 => _5.extraTools, 'optionalCall', _6 => _6(context)]), () => ( []));
-      if (host.readOnlyReason()) return [...readTools(), ...extra.filter((t) => _optionalChain([t, 'access', _7 => _7.annotations, 'optionalAccess', _8 => _8.readOnlyHint]))];
+      const extra = _nullishCoalesce(_optionalChain([host, 'access', _9 => _9.extraTools, 'optionalCall', _10 => _10(context)]), () => ( []));
+      if (host.readOnlyReason()) return [...readTools(), ...extra.filter((t) => _optionalChain([t, 'access', _11 => _11.annotations, 'optionalAccess', _12 => _12.readOnlyHint]))];
       return [...readTools(), ...writeTools(), ...extra];
     },
     subscribe: (l) => {
       listeners.add(l);
-      const off = _optionalChain([host, 'access', _9 => _9.subscribe, 'optionalCall', _10 => _10(l)]);
+      const off = _optionalChain([host, 'access', _13 => _13.subscribe, 'optionalCall', _14 => _14(l)]);
       return () => {
         listeners.delete(l);
-        _optionalChain([off, 'optionalCall', _11 => _11()]);
+        _optionalChain([off, 'optionalCall', _15 => _15()]);
       };
     }
   };
@@ -385,4 +414,7 @@ function createEffectToolProvider(host) {
 
 
 
-exports.EFFECT_ERROR_CODES = EFFECT_ERROR_CODES; exports.EffectError = EffectError; exports.UnknownEffectError = UnknownEffectError; exports.EffectControlError = EffectControlError; exports.EffectUnsupportedError = EffectUnsupportedError; exports.EffectDisposedError = EffectDisposedError; exports.NoEffectsProviderError = NoEffectsProviderError; exports.isEffectError = isEffectError; exports.effectValueErrors = effectValueErrors; exports.resolveEffectValues = resolveEffectValues; exports.searchEffectSummaries = searchEffectSummaries; exports.createEffectPixels = createEffectPixels; exports.isEffectPixels = isEffectPixels; exports.srgbToLinear = srgbToLinear; exports.linearToSrgb = linearToSrgb; exports.encodeEffectFloat = encodeEffectFloat; exports.applyEffectMask = applyEffectMask; exports.EffectsSlot = EffectsSlot; exports.EFFECT_KINDS = EFFECT_KINDS; exports.EFFECT_USES = EFFECT_USES; exports.createEffectToolProvider = createEffectToolProvider;
+
+
+
+exports.EFFECT_ERROR_CODES = EFFECT_ERROR_CODES; exports.EffectError = EffectError; exports.UnknownEffectError = UnknownEffectError; exports.EffectControlError = EffectControlError; exports.EffectUnsupportedError = EffectUnsupportedError; exports.EffectDisposedError = EffectDisposedError; exports.NoEffectsProviderError = NoEffectsProviderError; exports.isEffectError = isEffectError; exports.effectValueErrors = effectValueErrors; exports.resolveEffectValues = resolveEffectValues; exports.normaliseEffectTag = normaliseEffectTag; exports.hasEffectTags = hasEffectTags; exports.countEffectTags = countEffectTags; exports.searchEffectSummaries = searchEffectSummaries; exports.createEffectPixels = createEffectPixels; exports.isEffectPixels = isEffectPixels; exports.srgbToLinear = srgbToLinear; exports.linearToSrgb = linearToSrgb; exports.encodeEffectFloat = encodeEffectFloat; exports.applyEffectMask = applyEffectMask; exports.EffectsSlot = EffectsSlot; exports.EFFECT_KINDS = EFFECT_KINDS; exports.EFFECT_USES = EFFECT_USES; exports.createEffectToolProvider = createEffectToolProvider;