@pixerate/flair 0.14.0 → 0.16.0

package/dist/svelte/index.d.ts

@@ -0,0 +1,135 @@
+import { ActionReturn } from 'svelte/action';
+import { V as VectorEffect } from '../types-9J6NWaN3.js';
+import { C as ControlValue } from '../controls-Syr6drzO.js';
+import { a as SvgTrigger, C as Clock, b as SvgPlayer, S as SvgMotion } from '../svg-XugR-6Ec.js';
+
+/**
+ * Svelte 5 bindings for Flair's vector effects, written as plain TypeScript so
+ * they need no Svelte compiler: the `vectorEffect` action plays a catalog
+ * effect (or any {@link SvgMotion}) in an element, and `vectorEffectStill`
+ * gives the markup and style of its still for server rendering.
+ *
+ * ```svelte
+ * <script>
+ *   import { vectorEffect, vectorEffectStill } from "@pixerate/flair/svelte";
+ *   const params = { id: "drip-text", values: { word: "Slop" }, loop: false };
+ *   const still = vectorEffectStill(params);
+ * </script>
+ *
+ * <span use:vectorEffect={params} style={still.style}>{@html still.markup}</span>
+ * ```
+ *
+ * The still is in place from the first paint; the live `SvgPlayer` takes over
+ * after mount and is disposed on destroy. Under `prefers-reduced-motion:
+ * reduce` the still stays.
+ *
+ * Needs Svelte 5 (an optional peer dependency of the package); only its types
+ * are imported.
+ *
+ * @packageDocumentation
+ */
+
+/** When to leave the still in place of the animation. */
+type ReducedMotion = "user" | "always" | "never";
+/** Options shared by an effect by id and a motion of your own. */
+interface SvgPlayerParams {
+    /** Start again at the end (default `true`); `false` plays once and stays on the last frame. */
+    loop?: boolean;
+    /** Start playing at once (default `true`). */
+    autoplay?: boolean;
+    /** Playback speed (default 1); changed without remaking the player. */
+    speed?: number;
+    /** Ms to rest on the last frame before looping (default 600, or the effect's). */
+    hold?: number;
+    /** Loop length in ms (default: the picture's own, plus `hold`). */
+    duration?: number;
+    /** Step start times in ms, for pictures that change on steps. */
+    steps?: readonly number[];
+    /** Plays in answer to the pointer (see `SvgTrigger`; default the effect's). */
+    trigger?: SvgTrigger;
+    /** Pause while scrolled out of view. */
+    pauseWhenHidden?: boolean;
+    /** Wait to start until scrolled into view. */
+    playOnEnter?: boolean;
+    /** Hide the picture while paused or reset. */
+    hideWhenPaused?: boolean;
+    /** Time source (default animation frames); a `ManualClock` steps frames yourself. */
+    clock?: Clock;
+    /** Called with the id of the innermost element with an id that is clicked. */
+    onPick?: (id: string) => void;
+    /** Called with the player once it is made, and `undefined` when it is disposed. */
+    onPlayer?: (player: SvgPlayer | undefined) => void;
+    /**
+     * The still shown before the player starts and instead of it under reduced
+     * motion: `"last"` (default; the rest frame, `"first"` for a hover or press
+     * trigger), `"first"` or a time in ms.
+     */
+    poster?: "first" | "last" | number;
+    /**
+     * `"user"` (default) shows the still when the visitor prefers reduced
+     * motion, `"always"` always does, `"never"` always plays.
+     */
+    reducedMotion?: ReducedMotion;
+    /**
+     * Size it as a word in a line of text: `display: inline-block` with the
+     * viewBox's aspect ratio and `height` 0.72em (the cap height of a heavy
+     * sans; pass a CSS length for another). Default: the effect's `inline`
+     * control. Otherwise it is a block as wide as its container with the
+     * viewBox's aspect ratio.
+     */
+    inline?: boolean | string;
+}
+/** A catalog vector effect by id (or the effect itself), with its values. */
+interface VectorEffectByIdParams extends SvgPlayerParams {
+    /** A vector effect's catalog id (`"drip-text"`), or the effect itself. */
+    id: string | VectorEffect;
+    /** Control values; missing ones take the preset's, then the defaults. Compared by content. */
+    values?: Record<string, ControlValue>;
+    /** A preset's name to start from. */
+    preset?: string;
+    motion?: never;
+}
+/** Any {@link SvgMotion}; a new object restarts the player. */
+interface SvgMotionParams extends SvgPlayerParams {
+    /** The picture and its animations. */
+    motion: SvgMotion;
+    id?: never;
+    values?: never;
+    preset?: never;
+}
+/** What `vectorEffect` and `vectorEffectStill` take: an effect by `id`, or a `motion`. */
+type VectorEffectParams = VectorEffectByIdParams | SvgMotionParams;
+/** A still of the picture, for `{@html markup}` inside an element with `style`. */
+interface VectorEffectStill {
+    /** The still's layer: safe `<svg>` markup (see `svgFrameMarkup`) in an absolutely placed `<span>`. */
+    markup: string;
+    /** The host's inline style: its position and size from the viewBox. */
+    style: string;
+}
+/**
+ * The still of an effect or motion, for server rendering: put `markup` in the
+ * element that has the `vectorEffect` action, with `style` as its style, so
+ * the page shows the picture before the player starts (and instead of it
+ * under reduced motion), in the room the player will take.
+ * Throws when `id` is not a vector effect.
+ */
+declare function vectorEffectStill(params: VectorEffectParams): VectorEffectStill;
+/**
+ * A Svelte action that plays a vector effect in its element:
+ * `<span use:vectorEffect={{ id: "drip-text", values: { word: "Slop" }, loop: false }} />`.
+ *
+ * It makes an `SvgPlayer` in a layer of its own, remakes it when the params
+ * change (values by content; `speed` without remaking) and disposes it on
+ * destroy. A still from {@link vectorEffectStill} in the element is hidden
+ * while the player runs and shown again after; without one, the action makes
+ * its own (so reduced motion still shows the picture) and sizes the element
+ * from the viewBox, leaving alone any of `position`, `display`, `height` and
+ * `aspect-ratio` the element's style already sets.
+ *
+ * For an attachment, `{@attach fromAction(vectorEffect, () => params)}`
+ * (`fromAction` is from `svelte/attachments`). Throws when `id` is not a
+ * vector effect.
+ */
+declare function vectorEffect(node: HTMLElement, initial: VectorEffectParams): ActionReturn<VectorEffectParams>;
+
+export { type ReducedMotion, SvgMotion, type SvgMotionParams, SvgPlayer, type SvgPlayerParams, SvgTrigger, type VectorEffectByIdParams, type VectorEffectParams, type VectorEffectStill, vectorEffect, vectorEffectStill };

package/dist/svelte/index.js

@@ -0,0 +1,190 @@
+import {
+  effectDefaults,
+  getEffect,
+  renderVectorEffect
+} from "../chunk-KWNFZ5NC.js";
+import {
+  svgFrameMarkup,
+  svgViewBox
+} from "../chunk-DVVQRZJ5.js";
+import {
+  SvgPlayer
+} from "../chunk-4RGHZWQC.js";
+import "../chunk-OHW7UG6D.js";
+import "../chunk-EHDJ3CPJ.js";
+import "../chunk-WMZQCUFJ.js";
+import "../chunk-WC3VADZC.js";
+
+// src/svelte/index.ts
+var CAP_HEIGHT = "0.72em";
+var STILL_ATTR = "data-flair-still";
+var LAYER = "position:absolute;inset:0;display:block";
+function resolve(params, cache) {
+  if (params.motion) return { motion: params.motion, hold: params.hold, trigger: params.trigger, inline: params.inline };
+  const { id, values, preset } = params;
+  const effect = typeof id === "string" ? getEffect(id) : id;
+  if (!effect || effect.kind !== "vector")
+    throw new Error(
+      `"${typeof id === "string" ? id : effect?.id ?? id}" is not a vector effect; pick one from findEffects({ kind: "vector" }), or pass a motion`
+    );
+  const key = JSON.stringify([preset ?? null, values ?? {}]);
+  let motion;
+  if (cache?.current && cache.current.effect === effect && cache.current.key === key) motion = cache.current.motion;
+  else {
+    motion = renderVectorEffect(effect, effectDefaults(effect, { preset, values }));
+    if (cache) cache.current = { key, effect, motion };
+  }
+  return {
+    motion,
+    hold: params.hold ?? effect.hold,
+    trigger: params.trigger ?? effect.trigger,
+    inline: params.inline ?? values?.inline === true
+  };
+}
+function hostStyle(svg, inline) {
+  const box = svgViewBox(svg);
+  const style = [
+    ["position", "relative"],
+    ["display", inline ? "inline-block" : "block"]
+  ];
+  if (inline) style.push(["height", typeof inline === "string" ? inline : CAP_HEIGHT]);
+  if (box) style.push(["aspect-ratio", `${box[2]} / ${box[3]}`]);
+  return style;
+}
+function stillMarkup(r, params) {
+  const at = params.poster ?? (r.trigger === "hover" || r.trigger === "press" ? "first" : "last");
+  return svgFrameMarkup(r.motion, { at, steps: params.steps }) ?? "";
+}
+function vectorEffectStill(params) {
+  const r = resolve(params);
+  return {
+    markup: `<span ${STILL_ATTR} aria-hidden="true" style="${LAYER}">${stillMarkup(r, params)}</span>`,
+    style: hostStyle(r.motion.svg, r.inline).map(([k, v]) => `${k}: ${v}`).join("; ")
+  };
+}
+function prefersReducedMotion() {
+  return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function playerKey(r, p) {
+  return [
+    r.motion,
+    p.loop,
+    p.autoplay,
+    r.hold,
+    p.duration,
+    p.steps?.join(","),
+    r.trigger,
+    p.pauseWhenHidden,
+    p.playOnEnter,
+    p.hideWhenPaused,
+    p.clock,
+    p.reducedMotion ?? "user"
+  ];
+}
+function vectorEffect(node, initial) {
+  const cache = {};
+  const doc = node.ownerDocument;
+  const mount = doc.createElement("span");
+  mount.style.cssText = LAYER;
+  node.appendChild(mount);
+  let params = initial;
+  let resolved = resolve(params, cache);
+  let player;
+  let key = [];
+  let ownStill;
+  const sized = /* @__PURE__ */ new Set();
+  const stills = () => node.querySelectorAll(`:scope > [${STILL_ATTR}]`);
+  const showStills = (show) => {
+    for (const s of stills()) s.style.display = show ? "block" : "none";
+  };
+  const reattach = () => {
+    if (mount.parentNode !== node) node.appendChild(mount);
+    if (player) showStills(false);
+  };
+  const observer = typeof MutationObserver === "function" ? new MutationObserver(reattach) : void 0;
+  observer?.observe(node, { childList: true });
+  const size = () => {
+    const style = hostStyle(resolved.motion.svg, resolved.inline);
+    for (const [prop, value] of style) {
+      if (!sized.has(prop) && node.style.getPropertyValue(prop)) continue;
+      node.style.setProperty(prop, value);
+      sized.add(prop);
+    }
+    for (const prop of sized)
+      if (!style.some(([p]) => p === prop)) {
+        node.style.removeProperty(prop);
+        sized.delete(prop);
+      }
+  };
+  if (stills().length === 0) {
+    ownStill = doc.createElement("span");
+    ownStill.setAttribute(STILL_ATTR, "");
+    ownStill.setAttribute("aria-hidden", "true");
+    ownStill.style.cssText = LAYER;
+    node.insertBefore(ownStill, mount);
+    size();
+  }
+  const stop = () => {
+    if (!player) return;
+    player.dispose();
+    player = void 0;
+    showStills(true);
+    params.onPlayer?.(void 0);
+  };
+  const start = () => {
+    const reduced = params.reducedMotion ?? "user";
+    if (reduced === "always" || reduced === "user" && prefersReducedMotion()) return;
+    player = new SvgPlayer(mount, resolved.motion, {
+      loop: params.loop,
+      autoplay: params.autoplay,
+      speed: params.speed,
+      hold: resolved.hold,
+      duration: params.duration,
+      steps: params.steps,
+      trigger: resolved.trigger,
+      pauseWhenHidden: params.pauseWhenHidden,
+      playOnEnter: params.playOnEnter,
+      hideWhenPaused: params.hideWhenPaused,
+      clock: params.clock,
+      // The latest params' callback, without remaking the player.
+      onPick: (id) => params.onPick?.(id)
+    });
+    showStills(false);
+    params.onPlayer?.(player);
+  };
+  const apply = () => {
+    reattach();
+    if (ownStill) {
+      ownStill.innerHTML = stillMarkup(resolved, params);
+      size();
+    }
+    const next = playerKey(resolved, params);
+    if (player && next.every((v, i) => v === key[i])) {
+      player.setSpeed(params.speed ?? 1);
+      return;
+    }
+    key = next;
+    stop();
+    start();
+  };
+  apply();
+  return {
+    update(next) {
+      params = next;
+      resolved = resolve(params, cache);
+      apply();
+    },
+    destroy() {
+      observer?.disconnect();
+      stop();
+      mount.remove();
+      ownStill?.remove();
+      for (const prop of sized) node.style.removeProperty(prop);
+    }
+  };
+}
+export {
+  vectorEffect,
+  vectorEffectStill
+};
+//# sourceMappingURL=index.js.map

package/dist/svelte/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/svelte/index.ts"],"sourcesContent":["/**\n * Svelte 5 bindings for Flair's vector effects, written as plain TypeScript so\n * they need no Svelte compiler: the `vectorEffect` action plays a catalog\n * effect (or any {@link SvgMotion}) in an element, and `vectorEffectStill`\n * gives the markup and style of its still for server rendering.\n *\n * ```svelte\n * <script>\n *   import { vectorEffect, vectorEffectStill } from \"@pixerate/flair/svelte\";\n *   const params = { id: \"drip-text\", values: { word: \"Slop\" }, loop: false };\n *   const still = vectorEffectStill(params);\n * </script>\n *\n * <span use:vectorEffect={params} style={still.style}>{@html still.markup}</span>\n * ```\n *\n * The still is in place from the first paint; the live `SvgPlayer` takes over\n * after mount and is disposed on destroy. Under `prefers-reduced-motion:\n * reduce` the still stays.\n *\n * Needs Svelte 5 (an optional peer dependency of the package); only its types\n * are imported.\n *\n * @packageDocumentation\n */\n\nimport type { ActionReturn } from \"svelte/action\";\nimport { getEffect, effectDefaults } from \"../catalog/index.js\";\nimport { renderVectorEffect, type VectorEffect as VectorEffectDefinition } from \"../catalog/types.js\";\nimport type { ControlValue } from \"../shader/controls.js\";\nimport type { Clock } from \"../time/clock.js\";\nimport type { SvgMotion } from \"../vector/motion.js\";\nimport { svgFrameMarkup, svgViewBox } from \"../vector/static.js\";\nimport { SvgPlayer, type SvgTrigger } from \"../vector/svg.js\";\n\n/** Cap height of a heavy sans, as a share of its font size: what an inline word is framed to. */\nconst CAP_HEIGHT = \"0.72em\";\n\n/** Marks the still's layer, so the action can find it (and hide it while the player runs). */\nconst STILL_ATTR = \"data-flair-still\";\n\nconst LAYER = \"position:absolute;inset:0;display:block\";\n\n/** When to leave the still in place of the animation. */\nexport type ReducedMotion = \"user\" | \"always\" | \"never\";\n\n/** Options shared by an effect by id and a motion of your own. */\nexport interface SvgPlayerParams {\n  /** Start again at the end (default `true`); `false` plays once and stays on the last frame. */\n  loop?: boolean;\n  /** Start playing at once (default `true`). */\n  autoplay?: boolean;\n  /** Playback speed (default 1); changed without remaking the player. */\n  speed?: number;\n  /** Ms to rest on the last frame before looping (default 600, or the effect's). */\n  hold?: number;\n  /** Loop length in ms (default: the picture's own, plus `hold`). */\n  duration?: number;\n  /** Step start times in ms, for pictures that change on steps. */\n  steps?: readonly number[];\n  /** Plays in answer to the pointer (see `SvgTrigger`; default the effect's). */\n  trigger?: SvgTrigger;\n  /** Pause while scrolled out of view. */\n  pauseWhenHidden?: boolean;\n  /** Wait to start until scrolled into view. */\n  playOnEnter?: boolean;\n  /** Hide the picture while paused or reset. */\n  hideWhenPaused?: boolean;\n  /** Time source (default animation frames); a `ManualClock` steps frames yourself. */\n  clock?: Clock;\n  /** Called with the id of the innermost element with an id that is clicked. */\n  onPick?: (id: string) => void;\n  /** Called with the player once it is made, and `undefined` when it is disposed. */\n  onPlayer?: (player: SvgPlayer | undefined) => void;\n  /**\n   * The still shown before the player starts and instead of it under reduced\n   * motion: `\"last\"` (default; the rest frame, `\"first\"` for a hover or press\n   * trigger), `\"first\"` or a time in ms.\n   */\n  poster?: \"first\" | \"last\" | number;\n  /**\n   * `\"user\"` (default) shows the still when the visitor prefers reduced\n   * motion, `\"always\"` always does, `\"never\"` always plays.\n   */\n  reducedMotion?: ReducedMotion;\n  /**\n   * Size it as a word in a line of text: `display: inline-block` with the\n   * viewBox's aspect ratio and `height` 0.72em (the cap height of a heavy\n   * sans; pass a CSS length for another). Default: the effect's `inline`\n   * control. Otherwise it is a block as wide as its container with the\n   * viewBox's aspect ratio.\n   */\n  inline?: boolean | string;\n}\n\n/** A catalog vector effect by id (or the effect itself), with its values. */\nexport interface VectorEffectByIdParams extends SvgPlayerParams {\n  /** A vector effect's catalog id (`\"drip-text\"`), or the effect itself. */\n  id: string | VectorEffectDefinition;\n  /** Control values; missing ones take the preset's, then the defaults. Compared by content. */\n  values?: Record<string, ControlValue>;\n  /** A preset's name to start from. */\n  preset?: string;\n  motion?: never;\n}\n\n/** Any {@link SvgMotion}; a new object restarts the player. */\nexport interface SvgMotionParams extends SvgPlayerParams {\n  /** The picture and its animations. */\n  motion: SvgMotion;\n  id?: never;\n  values?: never;\n  preset?: never;\n}\n\n/** What `vectorEffect` and `vectorEffectStill` take: an effect by `id`, or a `motion`. */\nexport type VectorEffectParams = VectorEffectByIdParams | SvgMotionParams;\n\n/** A still of the picture, for `{@html markup}` inside an element with `style`. */\nexport interface VectorEffectStill {\n  /** The still's layer: safe `<svg>` markup (see `svgFrameMarkup`) in an absolutely placed `<span>`. */\n  markup: string;\n  /** The host's inline style: its position and size from the viewBox. */\n  style: string;\n}\n\ninterface Resolved {\n  motion: SvgMotion;\n  hold?: number;\n  trigger?: SvgTrigger;\n  inline?: boolean | string;\n}\n\n/** Remembers the last motion made from an effect, so values compared by content do not remake it. */\ntype MotionCache = { key: string; effect: VectorEffectDefinition; motion: SvgMotion };\n\nfunction resolve(params: VectorEffectParams, cache?: { current?: MotionCache }): Resolved {\n  if (params.motion) return { motion: params.motion, hold: params.hold, trigger: params.trigger, inline: params.inline };\n  const { id, values, preset } = params as VectorEffectByIdParams;\n  const effect = typeof id === \"string\" ? getEffect(id) : id;\n  if (!effect || effect.kind !== \"vector\")\n    throw new Error(\n      `\"${typeof id === \"string\" ? id : (effect?.id ?? id)}\" is not a vector effect; pick one from findEffects({ kind: \"vector\" }), or pass a motion`,\n    );\n  const key = JSON.stringify([preset ?? null, values ?? {}]);\n  let motion: SvgMotion;\n  if (cache?.current && cache.current.effect === effect && cache.current.key === key) motion = cache.current.motion;\n  else {\n    motion = renderVectorEffect(effect, effectDefaults(effect, { preset, values }));\n    if (cache) cache.current = { key, effect, motion };\n  }\n  return {\n    motion,\n    hold: params.hold ?? effect.hold,\n    trigger: params.trigger ?? effect.trigger,\n    inline: params.inline ?? values?.inline === true,\n  };\n}\n\n/** The host's sizing from the picture's viewBox, so the still and the player take the same room. */\nfunction hostStyle(svg: string, inline: boolean | string | undefined): [string, string][] {\n  const box = svgViewBox(svg);\n  const style: [string, string][] = [\n    [\"position\", \"relative\"],\n    [\"display\", inline ? \"inline-block\" : \"block\"],\n  ];\n  if (inline) style.push([\"height\", typeof inline === \"string\" ? inline : CAP_HEIGHT]);\n  if (box) style.push([\"aspect-ratio\", `${box[2]} / ${box[3]}`]);\n  return style;\n}\n\nfunction stillMarkup(r: Resolved, params: SvgPlayerParams): string {\n  const at = params.poster ?? (r.trigger === \"hover\" || r.trigger === \"press\" ? \"first\" : \"last\");\n  return svgFrameMarkup(r.motion, { at, steps: params.steps }) ?? \"\";\n}\n\n/**\n * The still of an effect or motion, for server rendering: put `markup` in the\n * element that has the `vectorEffect` action, with `style` as its style, so\n * the page shows the picture before the player starts (and instead of it\n * under reduced motion), in the room the player will take.\n * Throws when `id` is not a vector effect.\n */\nexport function vectorEffectStill(params: VectorEffectParams): VectorEffectStill {\n  const r = resolve(params);\n  return {\n    markup: `<span ${STILL_ATTR} aria-hidden=\"true\" style=\"${LAYER}\">${stillMarkup(r, params)}</span>`,\n    style: hostStyle(r.motion.svg, r.inline)\n      .map(([k, v]) => `${k}: ${v}`)\n      .join(\"; \"),\n  };\n}\n\nfunction prefersReducedMotion(): boolean {\n  return typeof matchMedia === \"function\" && matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n}\n\n/** The options whose change remakes the player (`speed` is set on it instead). */\nfunction playerKey(r: Resolved, p: SvgPlayerParams): unknown[] {\n  return [\n    r.motion,\n    p.loop,\n    p.autoplay,\n    r.hold,\n    p.duration,\n    p.steps?.join(\",\"),\n    r.trigger,\n    p.pauseWhenHidden,\n    p.playOnEnter,\n    p.hideWhenPaused,\n    p.clock,\n    p.reducedMotion ?? \"user\",\n  ];\n}\n\n/**\n * A Svelte action that plays a vector effect in its element:\n * `<span use:vectorEffect={{ id: \"drip-text\", values: { word: \"Slop\" }, loop: false }} />`.\n *\n * It makes an `SvgPlayer` in a layer of its own, remakes it when the params\n * change (values by content; `speed` without remaking) and disposes it on\n * destroy. A still from {@link vectorEffectStill} in the element is hidden\n * while the player runs and shown again after; without one, the action makes\n * its own (so reduced motion still shows the picture) and sizes the element\n * from the viewBox, leaving alone any of `position`, `display`, `height` and\n * `aspect-ratio` the element's style already sets.\n *\n * For an attachment, `{@attach fromAction(vectorEffect, () => params)}`\n * (`fromAction` is from `svelte/attachments`). Throws when `id` is not a\n * vector effect.\n */\nexport function vectorEffect(node: HTMLElement, initial: VectorEffectParams): ActionReturn<VectorEffectParams> {\n  const cache: { current?: MotionCache } = {};\n  const doc = node.ownerDocument;\n  const mount = doc.createElement(\"span\");\n  mount.style.cssText = LAYER;\n  node.appendChild(mount);\n\n  let params = initial;\n  let resolved = resolve(params, cache);\n  let player: SvgPlayer | undefined;\n  let key: unknown[] = [];\n  /** The still the action made itself, when the element had none. */\n  let ownStill: HTMLElement | undefined;\n  /** Sizing properties the action set (the element's own style had them empty). */\n  const sized = new Set<string>();\n\n  const stills = () => node.querySelectorAll<HTMLElement>(`:scope > [${STILL_ATTR}]`);\n  const showStills = (show: boolean) => {\n    for (const s of stills()) s.style.display = show ? \"block\" : \"none\";\n  };\n  // When the params change Svelte replaces a server still (`{@html}`), and when\n  // it is the element's only child, by setting `innerHTML`, which takes the\n  // player's layer out too: put the layer back, and keep a new still hidden.\n  const reattach = () => {\n    if (mount.parentNode !== node) node.appendChild(mount);\n    if (player) showStills(false);\n  };\n  const observer = typeof MutationObserver === \"function\" ? new MutationObserver(reattach) : undefined;\n  observer?.observe(node, { childList: true });\n\n  const size = () => {\n    const style = hostStyle(resolved.motion.svg, resolved.inline);\n    for (const [prop, value] of style) {\n      if (!sized.has(prop) && node.style.getPropertyValue(prop)) continue;\n      node.style.setProperty(prop, value);\n      sized.add(prop);\n    }\n    // A property the new sizing drops (`height` when no longer inline) is cleared.\n    for (const prop of sized)\n      if (!style.some(([p]) => p === prop)) {\n        node.style.removeProperty(prop);\n        sized.delete(prop);\n      }\n  };\n\n  if (stills().length === 0) {\n    ownStill = doc.createElement(\"span\");\n    ownStill.setAttribute(STILL_ATTR, \"\");\n    ownStill.setAttribute(\"aria-hidden\", \"true\");\n    ownStill.style.cssText = LAYER;\n    node.insertBefore(ownStill, mount);\n    size();\n  }\n\n  const stop = () => {\n    if (!player) return;\n    player.dispose();\n    player = undefined;\n    showStills(true);\n    params.onPlayer?.(undefined);\n  };\n\n  const start = () => {\n    const reduced = params.reducedMotion ?? \"user\";\n    if (reduced === \"always\" || (reduced === \"user\" && prefersReducedMotion())) return;\n    player = new SvgPlayer(mount, resolved.motion, {\n      loop: params.loop,\n      autoplay: params.autoplay,\n      speed: params.speed,\n      hold: resolved.hold,\n      duration: params.duration,\n      steps: params.steps,\n      trigger: resolved.trigger,\n      pauseWhenHidden: params.pauseWhenHidden,\n      playOnEnter: params.playOnEnter,\n      hideWhenPaused: params.hideWhenPaused,\n      clock: params.clock,\n      // The latest params' callback, without remaking the player.\n      onPick: (id) => params.onPick?.(id),\n    });\n    showStills(false);\n    params.onPlayer?.(player);\n  };\n\n  const apply = () => {\n    reattach();\n    if (ownStill) {\n      ownStill.innerHTML = stillMarkup(resolved, params);\n      size();\n    }\n    const next = playerKey(resolved, params);\n    if (player && next.every((v, i) => v === key[i])) {\n      player.setSpeed(params.speed ?? 1);\n      return;\n    }\n    key = next;\n    stop();\n    start();\n  };\n\n  apply();\n\n  return {\n    update(next) {\n      params = next;\n      resolved = resolve(params, cache);\n      apply();\n    },\n    destroy() {\n      observer?.disconnect();\n      stop();\n      mount.remove();\n      ownStill?.remove();\n      for (const prop of sized) node.style.removeProperty(prop);\n    },\n  };\n}\n\nexport type { SvgPlayer, SvgMotion, SvgTrigger };\n"],"mappings":"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","names":[]}

package/dist/{svg-C_TWBtEN.d.ts → svg-XugR-6Ec.d.ts}

@@ -382,4 +382,4 @@ interface AnimateCountOptions {
  */
 declare function animateCount(options: AnimateCountOptions): () => void;
 
-export { type AnimateCountOptions as A, svgMotionIssues as B, type Clock as C, type DataKey as D, EASES as E, svgOpeningTag as F, svgView as G, writtenText as H, ManualClock as M, type SvgMotion as S, type SvgTrigger as a, type EaseName as b, SCRAMBLE_MS as c, STEP_MS as d, SVG_PICTURE as e, type SvgAnimation as f, type SvgBox as g, type SvgElementFrame as h, SvgPlayer as i, type SvgPlayerOptions as j, type SvgView as k, type SvgViewOptions as l, animateCount as m, defaultDataKey as n, formatCount as o, jitter as p, lerpAttr as q, lerpData as r, pageHidden as s, parseSvg as t, realClock as u, stepData as v, stepProgress as w, stepStart as x, svgDuration as y, svgFrame as z };
+export { type AnimateCountOptions as A, svgMotionIssues as B, type Clock as C, type DataKey as D, EASES as E, svgOpeningTag as F, svgView as G, writtenText as H, ManualClock as M, type SvgMotion as S, type SvgTrigger as a, SvgPlayer as b, type EaseName as c, SCRAMBLE_MS as d, STEP_MS as e, SVG_PICTURE as f, type SvgAnimation as g, type SvgBox as h, type SvgElementFrame as i, type SvgPlayerOptions as j, type SvgView as k, type SvgViewOptions as l, animateCount as m, defaultDataKey as n, formatCount as o, jitter as p, lerpAttr as q, lerpData as r, pageHidden as s, parseSvg as t, realClock as u, stepData as v, stepProgress as w, stepStart as x, svgDuration as y, svgFrame as z };

package/dist/{types-CGsNkP5U.d.ts → types-9J6NWaN3.d.ts}

@@ -1,5 +1,5 @@
 import { C as ControlValue, a as ControlDef } from './controls-Syr6drzO.js';
-import { S as SvgMotion, a as SvgTrigger } from './svg-C_TWBtEN.js';
+import { S as SvgMotion, a as SvgTrigger } from './svg-XugR-6Ec.js';
 
 /** What an effect is for, used to group the catalog. */
 type EffectCategory = "gradient" | "organic" | "pattern" | "light" | "space" | "retro" | "image" | "overlay" | "text" | "morph" | "interaction" | "pyrotechnics" | "timewarp" | "melt" | "electric" | "transition" | "loader" | "data" | "icon";
@@ -111,4 +111,4 @@ declare function colorControl(name: string, hex: string, label?: string): Vector
 /** A number control for vector effects. */
 declare function numberControl(name: string, value: number, min: number, max: number, label?: string, step?: number): VectorControl;
 
-export { type EffectDefinition as E, type ShaderEffect as S, VECTOR_CONTROL_TYPES as V, type EffectCategory as a, EFFECT_CATEGORIES as b, type EffectPreset as c, type VectorControl as d, type VectorEffect as e, colorControl as f, vectorControlIssues as g, vectorControls as h, vectorEffectControls as i, numberControl as n, renderVectorEffect as r, vectorControlDef as v };
+export { type EffectDefinition as E, type ShaderEffect as S, type VectorEffect as V, type EffectCategory as a, EFFECT_CATEGORIES as b, type EffectPreset as c, VECTOR_CONTROL_TYPES as d, type VectorControl as e, colorControl as f, vectorControlIssues as g, vectorControls as h, vectorEffectControls as i, numberControl as n, renderVectorEffect as r, vectorControlDef as v };

package/dist/vector/index.d.ts

@@ -1,5 +1,5 @@
-import { g as SvgBox } from '../svg-C_TWBtEN.js';
-export { A as AnimateCountOptions, D as DataKey, E as EASES, b as EaseName, c as SCRAMBLE_MS, d as STEP_MS, e as SVG_PICTURE, f as SvgAnimation, h as SvgElementFrame, S as SvgMotion, i as SvgPlayer, j as SvgPlayerOptions, a as SvgTrigger, k as SvgView, l as SvgViewOptions, m as animateCount, n as defaultDataKey, o as formatCount, q as lerpAttr, r as lerpData, t as parseSvg, v as stepData, w as stepProgress, x as stepStart, y as svgDuration, z as svgFrame, B as svgMotionIssues, F as svgOpeningTag, G as svgView, H as writtenText } from '../svg-C_TWBtEN.js';
+import { h as SvgBox, S as SvgMotion } from '../svg-XugR-6Ec.js';
+export { A as AnimateCountOptions, D as DataKey, E as EASES, c as EaseName, d as SCRAMBLE_MS, e as STEP_MS, f as SVG_PICTURE, g as SvgAnimation, i as SvgElementFrame, b as SvgPlayer, j as SvgPlayerOptions, a as SvgTrigger, k as SvgView, l as SvgViewOptions, m as animateCount, n as defaultDataKey, o as formatCount, q as lerpAttr, r as lerpData, t as parseSvg, v as stepData, w as stepProgress, x as stepStart, y as svgDuration, z as svgFrame, B as svgMotionIssues, F as svgOpeningTag, G as svgView, H as writtenText } from '../svg-XugR-6Ec.js';
 
 /**
  * Shape morphing: any SVG paths turned into paths with the same structure, so
@@ -28,6 +28,38 @@ declare function morphSequence(paths: readonly string[], options?: MorphOptions)
  */
 declare function morphPaths(from: string, to: string, options?: MorphOptions): [string, string];
 
+/**
+ * An {@link SvgMotion}'s frame as markup, with no DOM: for server rendering
+ * (a still that hydrates without a blank flash), reduced motion and other
+ * places a live player is not wanted.
+ */
+
+/** A `viewBox` attribute's box, or undefined when it has none or it is malformed. */
+declare function parseViewBox(value: string | null | undefined): SvgBox | undefined;
+/** The `viewBox` on an SVG's opening tag (see {@link parseViewBox}). */
+declare function svgViewBox(markup: string): SvgBox | undefined;
+interface SvgFrameMarkupOptions {
+    /**
+     * The time shown, in ms: a number, `"first"` (0) or `"last"` (the end of
+     * its last change, see `svgDuration`; the default).
+     */
+    at?: number | "first" | "last";
+    /** Step start times in ms, as a player's `steps` (default none). */
+    steps?: readonly number[];
+}
+/**
+ * The picture of an {@link SvgMotion} at a moment, as `<svg>` markup made safe
+ * the way `parseSvg` makes it (no scripts, handlers, `<foreignObject>` or
+ * outside links), with no DOM needed: render it on a server, show it under
+ * `prefers-reduced-motion`, or anywhere a still will do. It is sized to fill
+ * its container, as `SvgPlayer` draws it.
+ *
+ * It matches the player's frame except where that needs layout: a change
+ * `along` a path, and a `view` that frames an element by id, stay where the
+ * markup puts them. Undefined when `motion.svg` is not an `<svg>`.
+ */
+declare function svgFrameMarkup(motion: SvgMotion, options?: SvgFrameMarkupOptions): string | undefined;
+
 type BoxFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
 type BoxAlignment = 'topLeft' | 'topCenter' | 'topRight' | 'centerLeft' | 'center' | 'centerRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
 interface FittedBoxResult {
@@ -81,4 +113,4 @@ interface FormatUnitOptions {
  */
 declare function formatUnit(value: number, format?: UnitFormat, options?: FormatUnitOptions): string;
 
-export { type BoxAlignment, type BoxFit, type FittedBoxResult, type FormatUnitOptions, type MorphOptions, type StackLayoutOptions, SvgBox, type UnitFormat, computeBoxFit, formatUnit, layoutStack, morphPaths, morphSequence, remap, stepVariant };
+export { type BoxAlignment, type BoxFit, type FittedBoxResult, type FormatUnitOptions, type MorphOptions, type StackLayoutOptions, SvgBox, type SvgFrameMarkupOptions, SvgMotion, type UnitFormat, computeBoxFit, formatUnit, layoutStack, morphPaths, morphSequence, parseViewBox, remap, stepVariant, svgFrameMarkup, svgViewBox };

package/dist/vector/index.js

@@ -4,7 +4,12 @@ import {
   layoutStack,
   remap,
   stepVariant
-} from "../chunk-H355R6U4.js";
+} from "../chunk-VP6IEWIK.js";
+import {
+  parseViewBox,
+  svgFrameMarkup,
+  svgViewBox
+} from "../chunk-DVVQRZJ5.js";
 import {
   EASES,
   SCRAMBLE_MS,
@@ -49,6 +54,7 @@ export {
   morphPaths,
   morphSequence,
   parseSvg,
+  parseViewBox,
   remap,
   stepData,
   stepProgress,
@@ -56,9 +62,11 @@ export {
   stepVariant,
   svgDuration,
   svgFrame,
+  svgFrameMarkup,
   svgMotionIssues,
   svgOpeningTag,
   svgView,
+  svgViewBox,
   writtenText
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/flair",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Web visual effects and motion graphics: WebGL2 shader effects, animated vector effects, a catalog of ready-made effects, and a UI-agnostic, agent-ready effect editor.",
   "author": "Pixerate",
   "license": "MIT",
@@ -38,6 +38,14 @@
       "types": "./dist/vector/index.d.ts",
       "import": "./dist/vector/index.js"
     },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "import": "./dist/svelte/index.js"
+    },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -57,25 +65,40 @@
     "effects",
     "generative",
     "editor",
-    "ai-agents"
+    "ai-agents",
+    "react",
+    "svelte"
   ],
   "dependencies": {
     "commander": "^12.0.0",
     "gifenc": "^1.0.3"
   },
   "peerDependencies": {
-    "@pixerate/editor": ">=0.29.0 <1"
+    "@pixerate/editor": ">=0.29.0 <1",
+    "react": ">=18",
+    "svelte": ">=5"
   },
   "peerDependenciesMeta": {
     "@pixerate/editor": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.12",
     "@pixerate/editor": "^0.29.0",
     "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "jsdom": "^30.1.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "svelte": "^5.57.2",
     "tsup": "^8.5",
     "typescript": "^5.9",
     "vitest": "^4.1.11"