@pixerate/editor 0.171.0 → 0.174.0

package/dist/chart/index.d.cts

@@ -22,6 +22,7 @@ export * from './recommend.cjs';
 export * from './controller.cjs';
 export * from './commands.cjs';
 export * from './interaction.cjs';
+export * from './tooltip.cjs';
 export * from './mermaid.cjs';
 export * from './ooxml.cjs';
 export * from './tools.cjs';

package/dist/chart/index.d.ts

@@ -22,6 +22,7 @@ export * from './recommend.js';
 export * from './controller.js';
 export * from './commands.js';
 export * from './interaction.js';
+export * from './tooltip.js';
 export * from './mermaid.js';
 export * from './ooxml.js';
 export * from './tools.js';

package/dist/chart/index.js

@@ -47,7 +47,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-N3ACT6VJ.js";
+} from "../chunk-KPWG3PSW.js";
 import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
@@ -55,6 +55,7 @@ import {
   MAX_CHART_LINE_POINTS,
   MAX_CHART_MARKERS,
   chartBoxStats,
+  chartCategoryAtPoint,
   chartDateLabels,
   chartDateToSerial,
   chartHistogram,
@@ -98,7 +99,7 @@ import {
   suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-M52UCHVZ.js";
+} from "../chunk-OJQVKJYD.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -1336,6 +1337,71 @@ function chartHitTest(scene, point, measure = (t, s, w = 400) => t.length * s *
   return point.x >= 0 && point.y >= 0 && point.x <= scene.width && point.y <= scene.height ? { kind: "chart" } : null;
 }
 
+// src/chart/tooltip.ts
+var VALUE_FAMILIES = /* @__PURE__ */ new Set(["cartesian", "xy", "pie", "radar", "waterfall", "funnel", "parliament", "slope"]);
+var SLICE_FAMILIES = /* @__PURE__ */ new Set(["pie", "funnel", "parliament"]);
+function valueFormat(spec, series) {
+  return series.format ?? (series.axis === "secondary" ? spec.yAxis2.format : spec.yAxis.format);
+}
+var percentText = (share) => formatChartNumber(share, { style: "percent", decimals: share < 0.1 ? 1 : 0 });
+function item(spec, seriesIndex, index, share) {
+  const family = chartFamily(spec);
+  const series = spec.series[seriesIndex];
+  const value = series.values[index] ?? null;
+  const slice = SLICE_FAMILIES.has(family);
+  let text = formatChartNumber(value, valueFormat(spec, series));
+  if (family === "xy") {
+    const x = series.x?.[index];
+    if (x !== null && x !== void 0) text = `${formatChartNumber(x, spec.xAxis.format)}, ${text}`;
+  }
+  if (share !== void 0) text = `${text} (${percentText(share)})`;
+  return {
+    seriesId: series.id,
+    name: slice ? spec.categories[index] ?? series.name : series.name,
+    color: slice ? series.pointColors?.[index] ?? chartSliceColor(spec, index) : chartPointColor(spec, seriesIndex, index),
+    value,
+    ...share !== void 0 ? { share } : {},
+    text
+  };
+}
+function chartTooltipFor(spec, index, seriesId, anchor = { x: 0, y: 0 }) {
+  const family = chartFamily(spec);
+  if (!VALUE_FAMILIES.has(family)) return null;
+  if (!Number.isInteger(index) || index < 0 || index >= Math.max(spec.categories.length, ...spec.series.map((s) => s.values.length))) return null;
+  const visible = spec.series.map((s, i) => ({ s, i })).filter(({ s }) => !s.hidden && (!seriesId || s.id === seriesId));
+  const present = visible.filter(({ s }) => s.values[index] !== null && s.values[index] !== void 0 && Number.isFinite(s.values[index]));
+  if (!present.length) return null;
+  const shareOf = (s) => {
+    const v = s.values[index];
+    if (spec.stacking === "percent" && family === "cartesian") {
+      const total = spec.series.filter((t) => !t.hidden && t.axis === s.axis).reduce((sum, t) => sum + Math.abs(t.values[index] ?? 0), 0);
+      return total ? Math.abs(v) / total : void 0;
+    }
+    if (family === "pie") {
+      const total = s.values.reduce((sum, t) => sum + (t !== null && t > 0 ? t : 0), 0);
+      return total && v > 0 ? v / total : void 0;
+    }
+    return void 0;
+  };
+  const items = present.map(({ s, i }) => item(spec, i, index, shareOf(s)));
+  const title = family === "xy" ? spec.categories[index] || present[0].s.name : spec.categories[index] ?? "";
+  return { title, index, items, x: anchor.x, y: anchor.y };
+}
+function chartTooltipAt(spec, scene, point, options = {}) {
+  if (options.mode === "category" && scene.categoryScale) {
+    const index = chartCategoryAtPoint(scene, point);
+    if (index !== void 0) return chartTooltipFor(spec, index, void 0, point);
+  }
+  const target = chartHitTest(scene, point, options.measureText ?? estimateChartTextWidth);
+  if (target?.kind === "point") return chartTooltipFor(spec, target.index, target.seriesId, point);
+  if (target?.kind === "category" && scene.categoryScale && options.mode === "category") return chartTooltipFor(spec, target.index, void 0, point);
+  return null;
+}
+function sameChartTooltip(a, b) {
+  if (!a || !b) return a === b;
+  return a.index === b.index && a.items.length === b.items.length && a.items.every((it, i) => it.seriesId === b.items[i].seriesId && it.text === b.items[i].text);
+}
+
 // src/chart/presence.ts
 var ChartPresence = class extends PresenceStore {
 };
@@ -1767,6 +1833,24 @@ function createChartToolProvider(controller, options = {}) {
       return { trendline: line, coefficients: fit.coefficients, r2: fit.r2, equation: fit.equation, points: fit.points };
     }
   };
+  const getTooltip = {
+    name: "get_chart_tooltip",
+    title: "Read a chart tooltip",
+    description: "Returns what a viewer sees when hovering a category (or one series in it): the category label and, for each visible series with a value there, its name, colour, value, share (percent-stacked and pie charts, 0\u20131) and the value as the chart writes it. Returns null for charts without one value per category (histogram, box, treemap, sunburst, sankey, \u2026) or when no visible series has a value there.",
+    inputSchema: {
+      type: "object",
+      properties: { category: CATEGORY_REF, series: { ...SERIES_REF, description: `${SERIES_REF.description} Omit to include every visible series in the category.` } },
+      required: ["category"],
+      additionalProperties: false
+    },
+    annotations: { title: "Read a chart tooltip", ...READ },
+    handler: ({ category, series }) => {
+      const index = categoryIndex(category);
+      const seriesId = series === void 0 ? void 0 : seriesById(series).id;
+      const tooltip = chartTooltipFor(controller.toJSON(), index, seriesId);
+      return tooltip && { title: tooltip.title, index: tooltip.index, items: tooltip.items };
+    }
+  };
   const raceRanking = {
     name: "get_chart_race_ranking",
     title: "Read a bar race ranking",
@@ -2476,7 +2560,7 @@ function createChartToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, mapRegions, listPresets, exportMermaid, exportOoxml];
+  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, getTooltip, raceRanking, mapRegions, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -3246,6 +3330,7 @@ export {
   blendChartScenes,
   canDragChartPoint,
   chartBoxStats,
+  chartCategoryAtPoint,
   chartClientToScene,
   chartColorDistance,
   chartColorInputValue,
@@ -3305,6 +3390,8 @@ export {
   chartToMermaid,
   chartToOoxml,
   chartToSvg,
+  chartTooltipAt,
+  chartTooltipFor,
   chartTreeColumnLabels,
   chartTreeDepth,
   chartTreeFromRows,
@@ -3391,6 +3478,7 @@ export {
   removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,
+  sameChartTooltip,
   setChartLinkField,
   setChartTreeRowName,
   setChartTreeRowValue,

package/dist/chart/layout-shared.d.cts

@@ -1,5 +1,5 @@
 import { type NiceScale } from './scale.cjs';
-import type { ChartAxis, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.cjs';
+import type { ChartAxis, ChartCategoryScale, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.cjs';
 export type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
 export interface ChartLayoutOptions {
     width: number;
@@ -73,6 +73,7 @@ export interface FamilyResult {
     valueScale?: ChartValueScale;
     valueScale2?: ChartValueScale;
     xScale?: ChartValueScale;
+    categoryScale?: ChartCategoryScale;
     percent?: boolean;
 }
 export type ChartSceneBase = Omit<ChartScene, 'marks' | 'warnings' | 'theme' | 'width' | 'height'>;

package/dist/chart/layout-shared.d.ts

@@ -1,5 +1,5 @@
 import { type NiceScale } from './scale.js';
-import type { ChartAxis, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.js';
+import type { ChartAxis, ChartCategoryScale, ChartMark, ChartMarker, ChartRect, ChartScene, ChartSelection, ChartSpec, ChartTheme, ChartValueScale, ChartWarning } from './types.js';
 export type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
 export interface ChartLayoutOptions {
     width: number;
@@ -73,6 +73,7 @@ export interface FamilyResult {
     valueScale?: ChartValueScale;
     valueScale2?: ChartValueScale;
     xScale?: ChartValueScale;
+    categoryScale?: ChartCategoryScale;
     percent?: boolean;
 }
 export type ChartSceneBase = Omit<ChartScene, 'marks' | 'warnings' | 'theme' | 'width' | 'height'>;

package/dist/chart/layout.d.cts

@@ -18,6 +18,11 @@ export declare function chartValueAtPoint(scene: ChartScene, point: {
     x: number;
     y: number;
 }, secondary?: boolean): number | undefined;
+/** The category index under a scene point inside the plot of a bar, line or area chart, or `undefined`. */
+export declare function chartCategoryAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}): number | undefined;
 /** The x value at a scene point on a scatter or bubble chart, or `undefined` without a numeric x axis. */
 export declare function chartXAtPoint(scene: ChartScene, point: {
     x: number;

package/dist/chart/layout.d.ts

@@ -18,6 +18,11 @@ export declare function chartValueAtPoint(scene: ChartScene, point: {
     x: number;
     y: number;
 }, secondary?: boolean): number | undefined;
+/** The category index under a scene point inside the plot of a bar, line or area chart, or `undefined`. */
+export declare function chartCategoryAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}): number | undefined;
 /** The x value at a scene point on a scatter or bubble chart, or `undefined` without a numeric x axis. */
 export declare function chartXAtPoint(scene: ChartScene, point: {
     x: number;

package/dist/chart/tooltip.d.cts

@@ -0,0 +1,53 @@
+import { type ChartTextMeasure } from './layout-shared.cjs';
+import type { ChartScene, ChartSpec, ChartValue } from './types.cjs';
+/** `point`: the bar, point or slice under the pointer. `category`: every series in the category under the pointer (bar, line and area charts; other charts fall back to `point`). */
+export type ChartTooltipMode = 'point' | 'category';
+export interface ChartTooltipItem {
+    seriesId: string;
+    /** The series name (the category label on pie, funnel and parliament charts). */
+    name: string;
+    color: string;
+    value: ChartValue;
+    /** Share of the category (percent-stacked charts) or of the series (pie and donut charts), 0–1. */
+    share?: number;
+    /** The value as the chart writes it: the series format, else its value axis format. */
+    text: string;
+}
+export interface ChartTooltip {
+    /** The category label (the series name on scatter and bubble charts with x values). */
+    title: string;
+    /** The category the items belong to. */
+    index: number;
+    items: ChartTooltipItem[];
+    /** Where to anchor the tooltip, in scene pixels (the pointer). */
+    x: number;
+    y: number;
+}
+export interface ChartTooltipOptions {
+    /** Default `point`. */
+    mode?: ChartTooltipMode;
+    /** Text width for hit-testing labels (default: an estimate). */
+    measureText?: ChartTextMeasure;
+}
+/**
+ * What a tooltip shows for one category: the category label and each visible series' value
+ * there, written as the chart writes it. `seriesId` narrows it to one series (one bar, point
+ * or slice). Returns `null` for charts whose marks are not one value per category (histogram,
+ * box, treemap and sunburst with a tree, sankey, …), for an index out of range, or when no
+ * visible series has a value there.
+ */
+export declare function chartTooltipFor(spec: ChartSpec, index: number, seriesId?: string, anchor?: {
+    x: number;
+    y: number;
+}): ChartTooltip | null;
+/**
+ * The tooltip at a scene point (for hover), or `null` when the pointer is over nothing with a
+ * value. In `category` mode, anywhere in a category's band of a bar, line or area chart shows
+ * every series there; elsewhere both modes show the one bar, point or slice under the pointer.
+ */
+export declare function chartTooltipAt(spec: ChartSpec, scene: ChartScene, point: {
+    x: number;
+    y: number;
+}, options?: ChartTooltipOptions): ChartTooltip | null;
+/** Whether two tooltips show the same thing (so a host can skip re-rendering while the pointer moves within a mark). */
+export declare function sameChartTooltip(a: ChartTooltip | null, b: ChartTooltip | null): boolean;

package/dist/chart/tooltip.d.ts

@@ -0,0 +1,53 @@
+import { type ChartTextMeasure } from './layout-shared.js';
+import type { ChartScene, ChartSpec, ChartValue } from './types.js';
+/** `point`: the bar, point or slice under the pointer. `category`: every series in the category under the pointer (bar, line and area charts; other charts fall back to `point`). */
+export type ChartTooltipMode = 'point' | 'category';
+export interface ChartTooltipItem {
+    seriesId: string;
+    /** The series name (the category label on pie, funnel and parliament charts). */
+    name: string;
+    color: string;
+    value: ChartValue;
+    /** Share of the category (percent-stacked charts) or of the series (pie and donut charts), 0–1. */
+    share?: number;
+    /** The value as the chart writes it: the series format, else its value axis format. */
+    text: string;
+}
+export interface ChartTooltip {
+    /** The category label (the series name on scatter and bubble charts with x values). */
+    title: string;
+    /** The category the items belong to. */
+    index: number;
+    items: ChartTooltipItem[];
+    /** Where to anchor the tooltip, in scene pixels (the pointer). */
+    x: number;
+    y: number;
+}
+export interface ChartTooltipOptions {
+    /** Default `point`. */
+    mode?: ChartTooltipMode;
+    /** Text width for hit-testing labels (default: an estimate). */
+    measureText?: ChartTextMeasure;
+}
+/**
+ * What a tooltip shows for one category: the category label and each visible series' value
+ * there, written as the chart writes it. `seriesId` narrows it to one series (one bar, point
+ * or slice). Returns `null` for charts whose marks are not one value per category (histogram,
+ * box, treemap and sunburst with a tree, sankey, …), for an index out of range, or when no
+ * visible series has a value there.
+ */
+export declare function chartTooltipFor(spec: ChartSpec, index: number, seriesId?: string, anchor?: {
+    x: number;
+    y: number;
+}): ChartTooltip | null;
+/**
+ * The tooltip at a scene point (for hover), or `null` when the pointer is over nothing with a
+ * value. In `category` mode, anywhere in a category's band of a bar, line or area chart shows
+ * every series there; elsewhere both modes show the one bar, point or slice under the pointer.
+ */
+export declare function chartTooltipAt(spec: ChartSpec, scene: ChartScene, point: {
+    x: number;
+    y: number;
+}, options?: ChartTooltipOptions): ChartTooltip | null;
+/** Whether two tooltips show the same thing (so a host can skip re-rendering while the pointer moves within a mark). */
+export declare function sameChartTooltip(a: ChartTooltip | null, b: ChartTooltip | null): boolean;

package/dist/chart/types.d.cts

@@ -440,6 +440,18 @@ export interface ChartValueScale {
     /** Set when the axis is logarithmic: values map by their logarithm in this base. */
     logBase?: number;
 }
+/**
+ * The category bands of a bar, line or area chart: `count` equal bands of the category axis,
+ * from `start` for `length` pixels (the last category first when `reverse` is set).
+ */
+export interface ChartCategoryScale {
+    /** `x` for vertical charts, `y` for horizontal bars. */
+    axis: 'x' | 'y';
+    start: number;
+    length: number;
+    count: number;
+    reverse: boolean;
+}
 /** Something the layout had to leave out or shorten, as a sentence (for agents and screen readers). */
 export interface ChartWarning {
     code: 'labels-hidden' | 'labels-truncated' | 'legend-truncated' | 'points-decimated' | 'values-skipped' | 'data-labels-hidden' | 'type-fallback' | 'annotations-skipped' | 'highlight-unmatched';
@@ -459,6 +471,8 @@ export interface ChartScene {
     valueScale2?: ChartValueScale;
     /** The numeric x scale of a scatter or bubble chart with x values. */
     xScale?: ChartValueScale;
+    /** The category bands of a bar, line or area chart. */
+    categoryScale?: ChartCategoryScale;
     /** Percent-stacked: values are shown as shares, so dragging is disabled. */
     percent: boolean;
     theme: ChartTheme;

package/dist/chart/types.d.ts

@@ -440,6 +440,18 @@ export interface ChartValueScale {
     /** Set when the axis is logarithmic: values map by their logarithm in this base. */
     logBase?: number;
 }
+/**
+ * The category bands of a bar, line or area chart: `count` equal bands of the category axis,
+ * from `start` for `length` pixels (the last category first when `reverse` is set).
+ */
+export interface ChartCategoryScale {
+    /** `x` for vertical charts, `y` for horizontal bars. */
+    axis: 'x' | 'y';
+    start: number;
+    length: number;
+    count: number;
+    reverse: boolean;
+}
 /** Something the layout had to leave out or shorten, as a sentence (for agents and screen readers). */
 export interface ChartWarning {
     code: 'labels-hidden' | 'labels-truncated' | 'legend-truncated' | 'points-decimated' | 'values-skipped' | 'data-labels-hidden' | 'type-fallback' | 'annotations-skipped' | 'highlight-unmatched';
@@ -459,6 +471,8 @@ export interface ChartScene {
     valueScale2?: ChartValueScale;
     /** The numeric x scale of a scatter or bubble chart with x values. */
     xScale?: ChartValueScale;
+    /** The category bands of a bar, line or area chart. */
+    categoryScale?: ChartCategoryScale;
     /** Percent-stacked: values are shown as shares, so dragging is disabled. */
     percent: boolean;
     theme: ChartTheme;

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,