pixi-effects 0.16.1 → 0.16.2

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, j as StopEvent, k as StopImage, l as StopImagesOptions, T as TimelineData, m as TimelineHtmlOptions, n as TimelineRow, o as TimelineSvgOptions, p as TimelineTransition, V as VolumeEvent, q as dismissLoader, r as failLoader, s as resolveLoader } from './Movie-CJMfAizW.cjs';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, M as MusicOptions, P as Props, b as TransitionSpec, c as CompositionSpec, d as SequenceCommon } from './types-C8XEUoqe.cjs';
-export { A as ArcShapeSpec, e as AssetSpec, f as AudioAssetSpec, g as AudioMusicSpec, h as AudioSequenceSpec, i as AudioSfxSpec, j as ChromaKeyFilterSpec, k as CircleShapeSpec, l as CompositionSequenceSpec, m as CrossfadeTransition, n as CustomFilterSpec, D as DipTransition, o as DissolveTransition, E as EllipseShapeSpec, p as Expr, F as FilterSpec, G as GradientSpec, q as IrisTransition, L as LineShapeSpec, r as MusicDrum, s as MusicDrums, t as MusicInstrument, u as MusicLevel, v as MusicTrack, N as NullSequenceSpec, w as PathShapeSpec, x as PolygonShapeSpec, y as PropValue, R as RectShapeSpec, z as SfxKnobs, B as SfxOptions, H as SfxPreset, J as SfxVoice, O as ShapeSequenceSpec, Q as SlideTransition, U as Stop, V as StopSpec, W as TransitionCommon, X as VideoSequenceSpec, Y as WipeTransition, Z as ZoomTransition, _ as normalizeStops, $ as pictureStops } from './types-C8XEUoqe.cjs';
-import { S as Sequence } from './Base-DPEqyeB0.cjs';
+export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, j as StopEvent, k as StopImage, l as StopImagesOptions, T as TimelineData, m as TimelineHtmlOptions, n as TimelineRow, o as TimelineSvgOptions, p as TimelineTransition, V as VolumeEvent, q as dismissLoader, r as failLoader, s as resolveLoader } from './Movie-oA0SUAyb.cjs';
+import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, M as MusicOptions, P as Props, b as TransitionSpec, c as CompositionSpec, d as SequenceCommon } from './types-SS51lP6O.cjs';
+export { A as ArcShapeSpec, e as AssetSpec, f as AudioAssetSpec, g as AudioMusicSpec, h as AudioSequenceSpec, i as AudioSfxSpec, j as ChromaKeyFilterSpec, k as CircleShapeSpec, l as CompositionSequenceSpec, m as CrossfadeTransition, n as CustomFilterSpec, D as DipTransition, o as DissolveTransition, E as EllipseShapeSpec, p as Expr, F as FilterSpec, G as GradientSpec, q as IrisTransition, L as LineShapeSpec, r as MusicDrum, s as MusicDrums, t as MusicInstrument, u as MusicLevel, v as MusicTrack, N as NullSequenceSpec, w as PathShapeSpec, x as PolygonShapeSpec, y as PropValue, R as RectShapeSpec, z as SfxKnobs, B as SfxOptions, H as SfxPreset, J as SfxVoice, O as ShapeSequenceSpec, Q as SlideTransition, U as Stop, V as StopSpec, W as TransitionCommon, X as VideoSequenceSpec, Y as WipeTransition, Z as ZoomTransition, _ as normalizeStops, $ as pictureStops } from './types-SS51lP6O.cjs';
+import { S as Sequence } from './Base-OHqp8qvX.cjs';
 import 'pixi.js';
 import 'gsap';
 
@@ -268,6 +268,38 @@ interface FollowPathOptions {
  */
 declare function followPath(opts: FollowPathOptions): Keyframe[];
 
+interface CameraPathOptions {
+    /** The route: `[x, y, z]` points the camera passes, in order (at least two). */
+    points: Array<[number, number, number]>;
+    /** Start, in seconds from the start of the camera layer. Default 0. */
+    at?: number;
+    /** How long the flight takes, in seconds. Required. */
+    duration: number;
+    /** GSAP ease for the progress along the route (default `'none'`: constant speed; `'power2.in'` is an accelerating rush). */
+    ease?: string;
+    /** Where the camera looks: a fixed `[x, y, z]`, or `'ahead'` (default): a point further along the route, so it faces where it flies. */
+    look?: [number, number, number] | 'ahead';
+    /** With `look: 'ahead'`: how far ahead, as a fraction 0–1 of the route's length (default 0.08). Past the end it continues along the last direction. */
+    lookAhead?: number;
+    /** `true` (default): a smooth curve through the points (Catmull-Rom). `false`: straight lines between them. */
+    smooth?: boolean;
+    /** Where on the route to start and stop, as fractions 0–1 of its length (default 0 → 1). `from: 1, to: 0` flies it backwards. */
+    from?: number;
+    to?: number;
+    /** Samples per second: set it to your movie's `frameRate`. Default 30. */
+    frameRate?: number;
+}
+/**
+ * A camera flight as keyframes for `x`, `y`, `z`, `lookAtX`, `lookAtY` and `lookAtZ`: put the result in a camera layer's `keyframes`.
+ * The route is walked by arc length (an even speed whatever the curve; an `ease` shapes it) and sampled once per frame as short
+ * straight steps, so the camera is exactly on the route at every rendered frame when `frameRate` matches the movie's.
+ *
+ * ```js
+ * { type: 'camera', keyframes: cameraPath({ points: [[640, 360, 2400], [700, 340, 900], [640, 360, -1500]], duration: 8, ease: 'power2.in', frameRate: 30 }) }
+ * ```
+ */
+declare function cameraPath(opts: CameraPathOptions): Keyframe[];
+
 interface StaggerOptions {
     /** Seconds between neighbours (the farthest one waits `each` × its distance). Default 0.1. Not together with `amount`. */
     each?: number;
@@ -684,4 +716,4 @@ interface WithFadeOptions {
  */
 declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
 
-export { type AnimateTextOptions, type AnimateTextTween, type AudioEnvelope, type AudioEnvelopeSource, CameraSequenceSpec, CompositionSpec, type DeckOptions, type DeckPage, type DeckResult, type DeckTransition, type EnvelopeOptions, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, MusicOptions, type OrbitOptions, type ParticlesOptions, Props, type ReactOptions, type ReactProp, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, TransitionSpec, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, audioEnvelope, bpmEnvelope, computeEnvelope, deck, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, noise, orbit, particles, rand, random, react, registerSequenceType, splitText, stagger, wiggle, withFade };
+export { type AnimateTextOptions, type AnimateTextTween, type AudioEnvelope, type AudioEnvelopeSource, type CameraPathOptions, CameraSequenceSpec, CompositionSpec, type DeckOptions, type DeckPage, type DeckResult, type DeckTransition, type EnvelopeOptions, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, MusicOptions, type OrbitOptions, type ParticlesOptions, Props, type ReactOptions, type ReactProp, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, TransitionSpec, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, audioEnvelope, bpmEnvelope, cameraPath, computeEnvelope, deck, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, noise, orbit, particles, rand, random, react, registerSequenceType, splitText, stagger, wiggle, withFade };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, j as StopEvent, k as StopImage, l as StopImagesOptions, T as TimelineData, m as TimelineHtmlOptions, n as TimelineRow, o as TimelineSvgOptions, p as TimelineTransition, V as VolumeEvent, q as dismissLoader, r as failLoader, s as resolveLoader } from './Movie-BIGDIla0.js';
-import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, M as MusicOptions, P as Props, b as TransitionSpec, c as CompositionSpec, d as SequenceCommon } from './types-C8XEUoqe.js';
-export { A as ArcShapeSpec, e as AssetSpec, f as AudioAssetSpec, g as AudioMusicSpec, h as AudioSequenceSpec, i as AudioSfxSpec, j as ChromaKeyFilterSpec, k as CircleShapeSpec, l as CompositionSequenceSpec, m as CrossfadeTransition, n as CustomFilterSpec, D as DipTransition, o as DissolveTransition, E as EllipseShapeSpec, p as Expr, F as FilterSpec, G as GradientSpec, q as IrisTransition, L as LineShapeSpec, r as MusicDrum, s as MusicDrums, t as MusicInstrument, u as MusicLevel, v as MusicTrack, N as NullSequenceSpec, w as PathShapeSpec, x as PolygonShapeSpec, y as PropValue, R as RectShapeSpec, z as SfxKnobs, B as SfxOptions, H as SfxPreset, J as SfxVoice, O as ShapeSequenceSpec, Q as SlideTransition, U as Stop, V as StopSpec, W as TransitionCommon, X as VideoSequenceSpec, Y as WipeTransition, Z as ZoomTransition, _ as normalizeStops, $ as pictureStops } from './types-C8XEUoqe.js';
-import { S as Sequence } from './Base-qvqNxvyt.js';
+export { A as AudioInspectOptions, a as AudioReport, b as AudioSourceReport, C as ContactSheetOptions, F as FrameEvent, I as InspectOptions, c as InspectReport, L as LayerInfo, d as LoaderOption, M as MotionBlurOptions, e as MotionBlurSpec, f as Movie, g as MovieErrorEvent, h as MovieOptions, P as ProgressEvent, R as RenderOptions, S as SnapshotOptions, i as SoundMeasure, j as StopEvent, k as StopImage, l as StopImagesOptions, T as TimelineData, m as TimelineHtmlOptions, n as TimelineRow, o as TimelineSvgOptions, p as TimelineTransition, V as VolumeEvent, q as dismissLoader, r as failLoader, s as resolveLoader } from './Movie-DilBC348.js';
+import { S as SequenceSpec, C as CompositionShape, I as ImageSequenceSpec, a as CameraSequenceSpec, K as Keyframe, T as TextSequenceSpec, M as MusicOptions, P as Props, b as TransitionSpec, c as CompositionSpec, d as SequenceCommon } from './types-SS51lP6O.js';
+export { A as ArcShapeSpec, e as AssetSpec, f as AudioAssetSpec, g as AudioMusicSpec, h as AudioSequenceSpec, i as AudioSfxSpec, j as ChromaKeyFilterSpec, k as CircleShapeSpec, l as CompositionSequenceSpec, m as CrossfadeTransition, n as CustomFilterSpec, D as DipTransition, o as DissolveTransition, E as EllipseShapeSpec, p as Expr, F as FilterSpec, G as GradientSpec, q as IrisTransition, L as LineShapeSpec, r as MusicDrum, s as MusicDrums, t as MusicInstrument, u as MusicLevel, v as MusicTrack, N as NullSequenceSpec, w as PathShapeSpec, x as PolygonShapeSpec, y as PropValue, R as RectShapeSpec, z as SfxKnobs, B as SfxOptions, H as SfxPreset, J as SfxVoice, O as ShapeSequenceSpec, Q as SlideTransition, U as Stop, V as StopSpec, W as TransitionCommon, X as VideoSequenceSpec, Y as WipeTransition, Z as ZoomTransition, _ as normalizeStops, $ as pictureStops } from './types-SS51lP6O.js';
+import { S as Sequence } from './Base-BQUodYZK.js';
 import 'pixi.js';
 import 'gsap';
 
@@ -268,6 +268,38 @@ interface FollowPathOptions {
  */
 declare function followPath(opts: FollowPathOptions): Keyframe[];
 
+interface CameraPathOptions {
+    /** The route: `[x, y, z]` points the camera passes, in order (at least two). */
+    points: Array<[number, number, number]>;
+    /** Start, in seconds from the start of the camera layer. Default 0. */
+    at?: number;
+    /** How long the flight takes, in seconds. Required. */
+    duration: number;
+    /** GSAP ease for the progress along the route (default `'none'`: constant speed; `'power2.in'` is an accelerating rush). */
+    ease?: string;
+    /** Where the camera looks: a fixed `[x, y, z]`, or `'ahead'` (default): a point further along the route, so it faces where it flies. */
+    look?: [number, number, number] | 'ahead';
+    /** With `look: 'ahead'`: how far ahead, as a fraction 0–1 of the route's length (default 0.08). Past the end it continues along the last direction. */
+    lookAhead?: number;
+    /** `true` (default): a smooth curve through the points (Catmull-Rom). `false`: straight lines between them. */
+    smooth?: boolean;
+    /** Where on the route to start and stop, as fractions 0–1 of its length (default 0 → 1). `from: 1, to: 0` flies it backwards. */
+    from?: number;
+    to?: number;
+    /** Samples per second: set it to your movie's `frameRate`. Default 30. */
+    frameRate?: number;
+}
+/**
+ * A camera flight as keyframes for `x`, `y`, `z`, `lookAtX`, `lookAtY` and `lookAtZ`: put the result in a camera layer's `keyframes`.
+ * The route is walked by arc length (an even speed whatever the curve; an `ease` shapes it) and sampled once per frame as short
+ * straight steps, so the camera is exactly on the route at every rendered frame when `frameRate` matches the movie's.
+ *
+ * ```js
+ * { type: 'camera', keyframes: cameraPath({ points: [[640, 360, 2400], [700, 340, 900], [640, 360, -1500]], duration: 8, ease: 'power2.in', frameRate: 30 }) }
+ * ```
+ */
+declare function cameraPath(opts: CameraPathOptions): Keyframe[];
+
 interface StaggerOptions {
     /** Seconds between neighbours (the farthest one waits `each` × its distance). Default 0.1. Not together with `amount`. */
     each?: number;
@@ -684,4 +716,4 @@ interface WithFadeOptions {
  */
 declare function withFade<T extends SequenceCommon>(spec: T, opts: WithFadeOptions): T;
 
-export { type AnimateTextOptions, type AnimateTextTween, type AudioEnvelope, type AudioEnvelopeSource, CameraSequenceSpec, CompositionSpec, type DeckOptions, type DeckPage, type DeckResult, type DeckTransition, type EnvelopeOptions, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, MusicOptions, type OrbitOptions, type ParticlesOptions, Props, type ReactOptions, type ReactProp, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, TransitionSpec, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, audioEnvelope, bpmEnvelope, computeEnvelope, deck, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, noise, orbit, particles, rand, random, react, registerSequenceType, splitText, stagger, wiggle, withFade };
+export { type AnimateTextOptions, type AnimateTextTween, type AudioEnvelope, type AudioEnvelopeSource, type CameraPathOptions, CameraSequenceSpec, CompositionSpec, type DeckOptions, type DeckPage, type DeckResult, type DeckTransition, type EnvelopeOptions, type FollowPathOptions, ImageSequenceSpec, type KenBurnsOptions, Keyframe, type MeasureStyle, MusicOptions, type OrbitOptions, type ParticlesOptions, Props, type ReactOptions, type ReactProp, SequenceCommon, type SequenceCtor, SequenceSpec, type SplitOptions, type StaggerOptions, type TextPiece, type TextPreset, TextSequenceSpec, type TextSize, TransitionSpec, type WiggleOptions, type WiggleProp, type WithFadeOptions, animateText, audioEnvelope, bpmEnvelope, cameraPath, computeEnvelope, deck, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, noise, orbit, particles, rand, random, react, registerSequenceType, splitText, stagger, wiggle, withFade };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { CompositionSequence } from './chunk-I2YXLHIU.js';
-import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, random, noise, flattenSvgPath, rand, DEG, resolveAt, collectPropKeys } from './chunk-7D7RAQWM.js';
-export { noise, rand, random, registerSequenceType } from './chunk-7D7RAQWM.js';
+import { CompositionSequence } from './chunk-XTIHKODH.js';
+import { ensureFilterLibrary, homeDistance, DEFAULT_FOV, random, noise, flattenSvgPath, rand, DEG, resolveAt, collectPropKeys } from './chunk-ZNKQH356.js';
+export { noise, rand, random, registerSequenceType } from './chunk-ZNKQH356.js';
 import { warnUnknownOptions, suggestName } from './chunk-DKGG7WD4.js';
 import * as PIXI from 'pixi.js';
 import { extensions, CullerPlugin, Application, Container, Rectangle, Culler, CanvasTextMetrics, TextStyle, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } from 'pixi.js';
@@ -2120,7 +2120,8 @@ var Movie = class {
   _renderNow() {
     const app = this.app;
     if (!app?.renderer) return;
-    this._rootSequence?.syncFrame();
+    if (!this._synced) this._rootSequence?.syncFrame();
+    this._synced = false;
     Culler.shared.cull(app.stage, app.renderer.screen, false);
     app.renderer.render({ container: app.stage });
   }
@@ -2129,9 +2130,17 @@ var Movie = class {
       throw new Error(`pixi-effects: movie.${what}() needs a ready movie \u2014 await movie.init(...) first`);
     }
   }
-  /** Projects every `threeD` layer for the current frame (see src/space). */
+  /** True when the layers were already synced to the playhead for the frame about to be drawn (so `_renderNow` need not do it again). */
+  _synced = false;
+  /**
+   * Projects every `threeD` layer for the current frame (see src/space). A threeD card is drawn into its own texture HERE, before the stage is
+   * drawn, so the shapes inside it must be brought up to the playhead first: syncing only in `_renderNow` left every card showing the state of
+   * the frame before (after a jump seek, a card whose children were animated showed a stale picture).
+   */
   _updateSpace(t = this._timeOf(this.currentFrame)) {
     if (!this._rootSequence || !this.app) return;
+    this._rootSequence.syncFrame();
+    this._synced = true;
     this._rootSequence.updateSpace(t, this.app.renderer);
   }
   /** The motion blur an operation uses: its own option when given (`false` is off), otherwise the movie's. */
@@ -2436,6 +2445,9 @@ function splitText(text, style = {}, opts = {}) {
     align = "left";
   }
   const x0 = opts.x ?? 0, y0 = opts.y ?? 0;
+  for (const [n, v] of [["x", x0], ["y", y0]]) {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`splitText(): ${n} must be a number of pixels (e.g. ${n}: 640), got ${JSON.stringify(v)}: the pieces are placed by measuring, so an expression such as 'GW/2' cannot be used here. \`y\` is the top of the line.`);
+  }
   if (text === "") return [];
   const ts = new TextStyle(style);
   const lineHeight = CanvasTextMetrics.measureText("M", ts).lineHeight ?? CanvasTextMetrics.measureText("M", ts).height;
@@ -2796,6 +2808,78 @@ function followPath(opts) {
   return out;
 }
 
+// src/presets/cameraPath.ts
+var KEYS4 = ["points", "at", "duration", "ease", "look", "lookAhead", "smooth", "from", "to", "frameRate"];
+var MAX_STEPS2 = 4e3;
+var PER_SPAN = 48;
+function cameraPath(opts) {
+  warnUnknownOptions("cameraPath()", opts, KEYS4);
+  const { points, at = 0, duration, ease = "none", look = "ahead", lookAhead = 0.08, smooth = true, from = 0, to = 1, frameRate = 30 } = opts;
+  if (!Array.isArray(points) || points.length < 2) throw new Error("cameraPath(): points needs at least two points: [[x, y, z], [x, y, z], \u2026]");
+  points.forEach((p, i) => {
+    if (!Array.isArray(p) || p.length !== 3 || !p.every(Number.isFinite)) throw new Error(`cameraPath(): points[${i}] must be [x, y, z] numbers, got ${JSON.stringify(p)}`);
+  });
+  if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`cameraPath(): duration must be a positive number of seconds, got ${duration}`);
+  if (!(Number.isFinite(frameRate) && frameRate > 0)) throw new Error(`cameraPath(): frameRate must be a positive number (samples per second), got ${frameRate}`);
+  if (look !== "ahead" && !(Array.isArray(look) && look.length === 3 && look.every(Number.isFinite))) throw new Error(`cameraPath(): look must be 'ahead' or [x, y, z] numbers, got ${JSON.stringify(look)}`);
+  if (!(Number.isFinite(lookAhead) && lookAhead >= 0 && lookAhead <= 1)) throw new Error(`cameraPath(): lookAhead must be a fraction of the route between 0 and 1, got ${lookAhead}`);
+  for (const [n, v] of [["from", from], ["to", to]]) {
+    if (!(Number.isFinite(v) && v >= 0 && v <= 1)) throw new Error(`cameraPath(): ${n} must be a fraction of the route between 0 and 1, got ${v}`);
+  }
+  const steps = Math.max(1, Math.round(duration * frameRate));
+  if (steps > MAX_STEPS2) throw new Error(`cameraPath(): ${steps} samples is too many (max ${MAX_STEPS2}); lower frameRate or duration`);
+  const curve = [];
+  if (smooth && points.length > 2) {
+    const pts = points;
+    for (let i = 0; i < pts.length - 1; i++) {
+      const p0 = pts[Math.max(i - 1, 0)], p1 = pts[i], p2 = pts[i + 1], p3 = pts[Math.min(i + 2, pts.length - 1)];
+      for (let s = 0; s < PER_SPAN; s++) curve.push(catmullRom(p0, p1, p2, p3, s / PER_SPAN));
+    }
+    curve.push(pts[pts.length - 1]);
+  } else curve.push(...points);
+  const cum = [0];
+  for (let i = 1; i < curve.length; i++) cum.push(cum[i - 1] + dist(curve[i - 1], curve[i]));
+  const total = cum[cum.length - 1];
+  if (!(total > 0)) throw new Error("cameraPath(): the route has no length (the points are all the same)");
+  const find = (s) => {
+    let lo = 0, hi = cum.length - 1;
+    while (lo < hi - 1) {
+      const mid = lo + hi >> 1;
+      if (cum[mid] <= s) lo = mid;
+      else hi = mid;
+    }
+    return lo;
+  };
+  const along = (fraction) => {
+    const s = fraction * total;
+    if (s >= total) {
+      const a2 = curve[curve.length - 2], b2 = curve[curve.length - 1], len = dist(a2, b2) || 1, extra = s - total;
+      return [b2[0] + (b2[0] - a2[0]) / len * extra, b2[1] + (b2[1] - a2[1]) / len * extra, b2[2] + (b2[2] - a2[2]) / len * extra];
+    }
+    const i = find(Math.max(s, 0)), span = cum[i + 1] - cum[i], t = span > 0 ? (s - cum[i]) / span : 0;
+    const a = curve[i], b = curve[i + 1];
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+  };
+  const shape = parseEase(ease);
+  const round3 = (v) => Math.round(v * 1e6) / 1e6;
+  const sample = (k) => {
+    const p = from + (to - from) * shape(k / steps);
+    const pos = along(Math.min(Math.max(p, 0), 1));
+    const target = look === "ahead" ? along(Math.max(p + (to >= from ? lookAhead : -lookAhead), 0)) : look;
+    return { x: round3(pos[0]), y: round3(pos[1]), z: round3(pos[2]), lookAtX: round3(target[0]), lookAtY: round3(target[1]), lookAtZ: round3(target[2]) };
+  };
+  const out = [{ at, set: sample(0) }];
+  const step = duration / steps;
+  for (let k = 1; k <= steps; k++) out.push({ at: round3(at + (k - 1) * step), to: sample(k), duration: round3(step), ease: "none" });
+  return out;
+}
+var dist = (a, b) => Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+function catmullRom(p0, p1, p2, p3, t) {
+  const t2 = t * t, t3 = t2 * t;
+  const c = (a, b, d, e) => 0.5 * (2 * b + (d - a) * t + (2 * a - 5 * b + 4 * d - e) * t2 + (3 * b - a - 3 * d + e) * t3);
+  return [c(p0[0], p1[0], p2[0], p3[0]), c(p0[1], p1[1], p2[1], p3[1]), c(p0[2], p1[2], p2[2], p3[2])];
+}
+
 // src/presets/stagger.ts
 var STAGGER_KEYS = ["each", "amount", "from", "grid", "ease", "seed"];
 var FROM_NAMES = ["start", "end", "center", "edges", "random"];
@@ -2815,11 +2899,11 @@ function stagger(items, options = {}) {
   if (grid && !(Array.isArray(grid) && grid.length === 2 && grid.every((g) => Number.isInteger(g) && g > 0) && grid[0] * grid[1] >= n)) {
     throw new Error(`stagger(): grid must be [columns, rows] and hold all ${n} items, got ${JSON.stringify(grid)}`);
   }
-  const dist = distances(n, from, grid, seed);
-  const max = dist.reduce((m, d) => Math.max(m, d), 0);
+  const dist2 = distances(n, from, grid, seed);
+  const max = dist2.reduce((m, d) => Math.max(m, d), 0);
   const total = amount !== void 0 ? amount : (each ?? 0.1) * max;
   const shape = parseEase(ease);
-  const delays = dist.map((d) => max === 0 ? 0 : Math.round(total * shape(d / max) * 1e6) / 1e6);
+  const delays = dist2.map((d) => max === 0 ? 0 : Math.round(total * shape(d / max) * 1e6) / 1e6);
   if (isCount) return delays;
   return items.map((layer, i) => ({ ...layer, at: Math.round(((layer.at ?? 0) + delays[i]) * 1e6) / 1e6 }));
 }
@@ -2862,7 +2946,7 @@ function distances(n, from, grid, seed) {
 
 // src/presets/wiggle.ts
 var WIGGLE_KEYS = ["at", "duration", "freq", "seed", "ease", "props"];
-var MAX_STEPS2 = 2e3;
+var MAX_STEPS3 = 2e3;
 function wiggle(opts) {
   warnUnknownOptions("wiggle()", opts, WIGGLE_KEYS);
   const { at = 0, duration, freq = 3, seed = 0, ease = "sine.inOut", props } = opts;
@@ -2876,7 +2960,7 @@ function wiggle(opts) {
     if (p.around === void 0 || p.around === null || p.around === "") throw new Error(`wiggle(): props.${n}.around is missing`);
   }
   const steps = Math.ceil(duration * freq - 1e-9);
-  if (steps > MAX_STEPS2) throw new Error(`wiggle(): ${steps} steps is too many (max ${MAX_STEPS2}); lower freq or duration`);
+  if (steps > MAX_STEPS3) throw new Error(`wiggle(): ${steps} steps is too many (max ${MAX_STEPS3}); lower freq or duration`);
   const set = {};
   for (const n of names) set[n] = props[n].around;
   const out = [{ at, set }];
@@ -2898,7 +2982,7 @@ function wiggle(opts) {
 }
 
 // src/presets/animateText.ts
-var KEYS4 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
+var KEYS5 = ["by", "x", "y", "align", "name", "at", "duration", "in", "out", "stagger", "idle", "styleFor"];
 var PRESETS = {
   rise: { from: { y: 40, alpha: 0 }, duration: 0.5, ease: "back.out(2)" },
   drop: { from: { y: -50, alpha: 0 }, duration: 0.7, ease: "bounce.out" },
@@ -2910,8 +2994,13 @@ var PRESETS = {
 };
 var PRESET_NAMES = Object.keys(PRESETS);
 function animateText(text, style, options) {
-  warnUnknownOptions("animateText()", options, KEYS4);
+  warnUnknownOptions("animateText()", options, KEYS5);
   const { by = "chars", x = 0, y = 0, align = "left", name = "text", at = 0, duration, idle, styleFor } = options;
+  for (const [n, v] of [["x", x], ["y", y]]) {
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      throw new Error(`animateText(): ${n} must be a number of pixels (e.g. ${n}: 640), got ${JSON.stringify(v)}. The letters are measured once, when the layers are made, so an expression such as 'GW/2' cannot be used here: compute the number (W / 2) yourself. \`y\` is the TOP of the line.`);
+    }
+  }
   if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`animateText(): duration must be a positive number of seconds (how long until the last piece is gone), got ${duration}`);
   const pieces = splitText(text, style, { by, x, y, align });
   if (pieces.length === 0) return [];
@@ -2994,11 +3083,11 @@ function resolveTween(spec, which) {
 }
 
 // src/presets/react.ts
-var KEYS5 = ["at", "duration", "props", "audioOffset", "loop", "frameRate"];
+var KEYS6 = ["at", "duration", "props", "audioOffset", "loop", "frameRate"];
 var PROP_KEYS = ["base", "amount", "band", "beats", "decay", "attack", "release", "invert", "curve"];
-var MAX_STEPS3 = 4e3;
+var MAX_STEPS4 = 4e3;
 function react(env, options) {
-  warnUnknownOptions("react()", options, KEYS5);
+  warnUnknownOptions("react()", options, KEYS6);
   const { at = 0, duration, props, audioOffset = 0, loop = false } = options;
   const frameRate = options.frameRate ?? env.frameRate;
   if (!(Number.isFinite(duration) && duration > 0)) throw new Error(`react(): duration must be a positive number of seconds, got ${duration}`);
@@ -3013,7 +3102,7 @@ function react(env, options) {
     if (p.beats && !(p.decay === void 0 || Number.isFinite(p.decay) && p.decay > 0)) throw new Error(`react(): props.${n}.decay must be a positive number of seconds, got ${p.decay}`);
   }
   const steps = Math.max(1, Math.round(duration * frameRate));
-  if (steps > MAX_STEPS3) throw new Error(`react(): too many keyframes (${steps} steps, max ${MAX_STEPS3}); lower frameRate (now ${frameRate}) or duration`);
+  if (steps > MAX_STEPS4) throw new Error(`react(): too many keyframes (${steps} steps, max ${MAX_STEPS4}); lower frameRate (now ${frameRate}) or duration`);
   const wrap = (a) => loop && env.duration > 0 ? (a % env.duration + env.duration) % env.duration : a;
   const beatPulse = (a, decay) => {
     const beats = env.beats;
@@ -3347,6 +3436,6 @@ function withFade(spec, opts) {
   return spec;
 }
 
-export { Movie, animateText, audioEnvelope, bpmEnvelope, computeEnvelope, deck, dismissLoader, failLoader, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, normalizeStops, orbit, particles, pictureStops, react, resolveLoader, splitText, stagger, wiggle, withFade };
+export { Movie, animateText, audioEnvelope, bpmEnvelope, cameraPath, computeEnvelope, deck, dismissLoader, failLoader, followPath, kenBurns, measureText, musicBuffer, musicEnvelope, normalizeStops, orbit, particles, pictureStops, react, resolveLoader, splitText, stagger, wiggle, withFade };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map