pixi-effects 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { CompositionSequence } from './chunk-H55V3U56.js';
-import { resolveAt } from './chunk-VJCDG6YG.js';
-export { registerSequenceType } from './chunk-VJCDG6YG.js';
+import { CompositionSequence } from './chunk-DIJG2RSF.js';
+import { homeDistance, DEFAULT_FOV, DEG, resolveAt, collectPropKeys } from './chunk-PN5A6QA7.js';
+export { registerSequenceType } from './chunk-PN5A6QA7.js';
 import * as PIXI from 'pixi.js';
-import { extensions, CullerPlugin, Application, Container, Rectangle, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } from 'pixi.js';
+import { extensions, CullerPlugin, Application, Container, Rectangle, Culler, Assets, ExtensionType, Filter, UniformGroup, GpuProgram, GlProgram, defaultFilterVert } from 'pixi.js';
 import { gsap } from 'gsap';
 import { PixiPlugin } from 'gsap/PixiPlugin';
 import { QUALITY_VERY_HIGH, QUALITY_HIGH, QUALITY_MEDIUM, QUALITY_LOW, QUALITY_VERY_LOW, Output, BufferTarget, CanvasSource, AudioBufferSource, Input, ALL_FORMATS, BlobSource, WavOutputFormat, Conversion, VideoSampleSink, MkvOutputFormat, WebMOutputFormat, MovOutputFormat, Mp4OutputFormat } from 'mediabunny';
@@ -611,29 +611,34 @@ function expandTransitions(spec) {
     if (tStart < toStart || tEnd > toEnd) {
       throw new Error(`pixi-effects: ${tag} window [${tStart}, ${tEnd}] is not covered by \`to\` "${t.to}" (lives [${toStart}, ${toEnd}], so it starts at ${toStart})`);
     }
-    switch (t.kind) {
+    const abs = { ...t, at: tStart };
+    const nFrom = keyframeCount(fromEntry.seq);
+    const nTo = keyframeCount(toEntry.seq);
+    switch (abs.kind) {
       case "crossfade":
-        expandCrossfade(out, t, fromEntry.seq, toEntry.seq);
+        expandCrossfade(out, abs, fromEntry.seq, toEntry.seq);
         break;
       case "wipe":
-        expandMask(out, t, fromEntry.seq, toEntry.seq, i, wipeMode(t.direction), t.smoothing);
+        expandMask(out, abs, fromEntry.seq, toEntry.seq, i, wipeMode(abs.direction), abs.smoothing);
         break;
       case "iris":
-        expandMask(out, t, fromEntry.seq, toEntry.seq, i, t.mode === "out" ? "iris-out" : "iris-in", t.smoothing);
+        expandMask(out, abs, fromEntry.seq, toEntry.seq, i, abs.mode === "out" ? "iris-out" : "iris-in", abs.smoothing);
         break;
       case "slide":
-        expandSlide(out, t, fromEntry.seq, toEntry.seq);
+        expandSlide(out, abs, fromEntry.seq, toEntry.seq);
         break;
       case "dip":
-        expandDip(out, t, fromEntry.seq, toEntry.seq);
+        expandDip(out, abs, fromEntry.seq, toEntry.seq);
         break;
       case "zoom":
-        expandZoom(out, t, fromEntry.seq, toEntry.seq);
+        expandZoom(out, abs, fromEntry.seq, toEntry.seq);
         break;
       case "dissolve":
-        expandDissolve(out, t, fromEntry.seq, toEntry.seq, i);
+        expandDissolve(out, abs, fromEntry.seq, toEntry.seq, i);
         break;
     }
+    rebaseNewKeyframes(fromEntry.seq, nFrom, fromStart);
+    rebaseNewKeyframes(toEntry.seq, nTo, toStart);
   }
   delete out.transitions;
   return out;
@@ -665,6 +670,17 @@ function wrapAsFullComposition(seq, compW, compH) {
     sequences: [inner]
   };
 }
+function keyframeCount(seq) {
+  return seq.keyframes?.length ?? 0;
+}
+function rebaseNewKeyframes(seq, from, seqStart) {
+  const kfs = seq.keyframes;
+  if (!kfs) return;
+  for (let i = from; i < kfs.length; i++) {
+    const kf = kfs[i];
+    if (typeof kf.at === "number") kfs[i] = { ...kf, at: kf.at - seqStart };
+  }
+}
 function ensureKeyframes(seq) {
   const s = seq;
   if (!s.keyframes) s.keyframes = [];
@@ -881,6 +897,153 @@ function rejectReservedNameCollision(filters, seqName) {
   }
 }
 
+// src/core/inspect.ts
+var FAINT = 0.3;
+var intersection = (a, b) => {
+  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+  return w > 0 && h > 0 ? w * h : 0;
+};
+function inspectScene(root, frame, time, canvas, opts = {}) {
+  const layers = [];
+  const view = { x: 0, y: 0, width: canvas.width, height: canvas.height };
+  const walk = (comp, prefix, insideThreeD, parentVisible) => {
+    comp.layers().forEach(({ seq, display, threeD }, i) => {
+      const t = seq.target;
+      const name = seq.spec.name;
+      const label = name ?? `${seq.spec.type}#${i}`;
+      const alpha = t?.alpha ?? 1;
+      const alive = threeD ? display.visible : t?.renderable ?? true;
+      const visible = parentVisible && alive && alpha > 0;
+      let bounds = null;
+      if (!insideThreeD) {
+        const b = display.getBounds();
+        bounds = { x: b.x, y: b.y, width: b.width, height: b.height };
+      }
+      let onCanvas = null;
+      if (bounds) {
+        const inter = intersection(bounds, view);
+        const area = bounds.width * bounds.height;
+        onCanvas = inter === 0 && area > 0 ? "none" : inter >= area - 1e-6 ? "full" : "partial";
+        if (area === 0) onCanvas = "none";
+      }
+      const keys = collectPropKeys(seq.spec);
+      const moving = (seq.spec.keyframes ?? []).length > 0 && (keys.has("x") || keys.has("y"));
+      layers.push({ path: prefix + label, name, type: seq.spec.type, threeD, visible, alpha, moving, bounds, onCanvas });
+      if (seq instanceof CompositionSequence) walk(seq, prefix + label + "/", insideThreeD || threeD, visible);
+    });
+  };
+  walk(root, "", false, true);
+  const issues = [];
+  const texts = layers.filter((l) => l.type === "text" && l.visible && l.alpha >= FAINT && l.bounds);
+  for (const l of texts) {
+    const b = l.bounds;
+    const who = `text layer "${l.path}"`;
+    if (b.width < 1 || b.height < 1) {
+      issues.push(`${who} has no size (empty text, or not drawn yet)`);
+    } else if (l.moving) ; else if (l.onCanvas === "none") {
+      issues.push(`${who} is entirely outside the canvas (at ${Math.round(b.x)},${Math.round(b.y)}, ${Math.round(b.width)}\xD7${Math.round(b.height)})`);
+    } else if (l.onCanvas === "partial") {
+      const over = [];
+      if (b.x < 0) over.push(`${Math.round(-b.x)}px beyond the left edge`);
+      if (b.x + b.width > canvas.width) over.push(`${Math.round(b.x + b.width - canvas.width)}px beyond the right edge`);
+      if (b.y < 0) over.push(`${Math.round(-b.y)}px beyond the top edge`);
+      if (b.y + b.height > canvas.height) over.push(`${Math.round(b.y + b.height - canvas.height)}px beyond the bottom edge`);
+      issues.push(`${who} is cut off by the canvas edge: ${over.join(", ")}`);
+    }
+  }
+  for (let i = 0; i < texts.length; i++) {
+    for (let j = i + 1; j < texts.length; j++) {
+      const a = texts[i].bounds, b = texts[j].bounds;
+      const smaller = Math.min(a.width * a.height, b.width * b.height);
+      if (smaller <= 0) continue;
+      const share = intersection(a, b) / smaller;
+      if (share > 0.25) issues.push(`text layers "${texts[i].path}" and "${texts[j].path}" overlap by ${Math.round(share * 100)}% of the smaller one`);
+    }
+  }
+  const mode = opts.layers ?? "all";
+  const listed = mode === "none" ? [] : mode === "visible" ? layers.filter((l) => l.visible) : layers;
+  return { frame, time, canvas, summary: { layers: layers.length, visible: layers.filter((l) => l.visible).length }, issues, layers: listed };
+}
+
+// src/core/frames.ts
+function pickFrames(lastFrame, count) {
+  const last = Math.max(0, Math.floor(lastFrame));
+  const n = Math.max(1, Math.floor(count));
+  if (n === 1) return [0];
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const f = Math.round(last * i / (n - 1));
+    if (out[out.length - 1] !== f) out.push(f);
+  }
+  return out;
+}
+function sheetLayout(n, columns, cellW, srcW, srcH, labelH) {
+  const cols = Math.max(1, Math.min(Math.floor(columns), n));
+  const rows = Math.ceil(n / cols);
+  const cellH = Math.round(cellW * srcH / srcW);
+  const positions = Array.from({ length: n }, (_, i) => ({ x: i % cols * cellW, y: Math.floor(i / cols) * (cellH + labelH) }));
+  return { cols, rows, cellW, cellH, width: cols * cellW, height: rows * (cellH + labelH), positions };
+}
+
+// src/core/options.ts
+function distance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+    }
+  }
+  return dp[a.length][b.length];
+}
+var isSubsequence = (small, big) => {
+  let i = 0;
+  for (const ch of big) if (i < small.length && ch === small[i]) i++;
+  return i === small.length;
+};
+var COMMON_ALIASES = {
+  fps: "frameRate",
+  framerate: "frameRate",
+  frame_rate: "frameRate",
+  bg: "background",
+  backgroundcolor: "background",
+  bgcolor: "background",
+  seconds: "duration",
+  length: "duration",
+  time: "duration",
+  w: "width",
+  h: "height",
+  cols: "columns",
+  sweep: "degrees",
+  angle: "degrees"
+};
+function suggestName(name, valid) {
+  const n = name.toLowerCase();
+  const alias = COMMON_ALIASES[n];
+  if (alias && valid.includes(alias)) return alias;
+  let best = null;
+  for (const v of valid) {
+    const lv = v.toLowerCase();
+    const d = distance(n, lv);
+    const close = d <= Math.max(1, Math.floor(Math.min(n.length, lv.length) / 3));
+    const abbreviation = n.length >= 3 && isSubsequence(n, lv) || lv.length >= 2 && n.length > lv.length && n.includes(lv);
+    if (!close && !abbreviation) continue;
+    const score = close ? d : 3 + (lv.length - n.length) / 100;
+    if (!best || score < best.score) best = { v, score };
+  }
+  return best ? best.v : null;
+}
+function warnUnknownOptions(where, opts, valid) {
+  if (!opts || typeof opts !== "object") return;
+  for (const key of Object.keys(opts)) {
+    if (valid.includes(key)) continue;
+    const guess = suggestName(key, valid);
+    console.warn(`pixi-effects: ${where}: unknown option "${key}"${guess ? ` \u2014 did you mean "${guess}"?` : ""} (valid: ${valid.join(", ")})`);
+  }
+}
+
 // src/core/Movie.ts
 extensions.add(CullerPlugin);
 gsap.registerPlugin(PixiPlugin);
@@ -939,6 +1102,7 @@ var Movie = class {
     return this._audioContext;
   }
   async init(options = {}) {
+    warnUnknownOptions("movie.init()", options, ["width", "height", "duration", "frameRate", "background", "canvas", "assets", "composition"]);
     this._initState = "pending";
     try {
       this.width = options.width ?? 1920;
@@ -1003,7 +1167,7 @@ var Movie = class {
       this.timeline.progress(1).progress(0);
       await this._awaitVideoFrames();
       this._updateSpace();
-      this.app.renderer.render({ container: this.app.stage });
+      this._renderNow();
       this._initState = "ready";
       this.emit("ready");
     } catch (err) {
@@ -1022,7 +1186,7 @@ var Movie = class {
     this.timeline.time(this.currentFrame / this.frameRate);
     await this._awaitVideoFrames();
     this._updateSpace();
-    this.app?.renderer?.render({ container: this.app.stage });
+    this._renderNow();
     this.emit("frame", { frame: this.currentFrame, totalFrames: this.totalFrames });
   }
   async _awaitVideoFrames() {
@@ -1036,6 +1200,75 @@ var Movie = class {
       return v.awaitFrameAt(local);
     }));
   }
+  async snapshot(frame = this.currentFrame, opts = {}) {
+    warnUnknownOptions("movie.snapshot()", opts, ["scale", "type", "as"]);
+    this._requireReady("snapshot");
+    await this.gotoFrame(clampFrame(frame, this.totalFrames), true);
+    const scale = opts.scale ?? 1;
+    const out = document.createElement("canvas");
+    out.width = Math.max(1, Math.round(this.width * scale));
+    out.height = Math.max(1, Math.round(this.height * scale));
+    out.getContext("2d").drawImage(this.app.canvas, 0, 0, out.width, out.height);
+    return encodeCanvas(out, opts.type ?? "image/png", opts.as ?? "blob");
+  }
+  async contactSheet(opts = {}) {
+    warnUnknownOptions("movie.contactSheet()", opts, ["frames", "times", "count", "columns", "cellWidth", "as"]);
+    this._requireReady("contactSheet");
+    const frames = (opts.frames ?? opts.times?.map((t) => Math.round(t * this.frameRate)) ?? pickFrames(this.totalFrames, opts.count ?? 6)).map((f) => clampFrame(f, this.totalFrames));
+    const LABEL_H = 26;
+    const L = sheetLayout(frames.length, opts.columns ?? 3, opts.cellWidth ?? 480, this.width, this.height, LABEL_H);
+    const sheet = document.createElement("canvas");
+    sheet.width = L.width;
+    sheet.height = L.height;
+    const g = sheet.getContext("2d");
+    g.fillStyle = "#10131c";
+    g.fillRect(0, 0, L.width, L.height);
+    const back = this.currentFrame;
+    try {
+      for (let i = 0; i < frames.length; i++) {
+        const f = frames[i];
+        await this.gotoFrame(f, true);
+        const { x, y } = L.positions[i];
+        g.drawImage(this.app.canvas, x, y + LABEL_H, L.cellW, L.cellH);
+        g.fillStyle = "#e8ecf8";
+        g.font = "600 15px system-ui, sans-serif";
+        g.textBaseline = "middle";
+        g.fillText(`frame ${f}  \xB7  ${(f / this.frameRate).toFixed(2)}s`, x + 8, y + LABEL_H / 2);
+      }
+    } finally {
+      await this.gotoFrame(back, true);
+    }
+    return encodeCanvas(sheet, "image/png", opts.as ?? "blob");
+  }
+  /**
+   * Where every layer is drawn at `frame` (canvas pixels, visibility) plus `issues` — text that is off
+   * the canvas, cut by an edge, empty, or overlapping other text. Seeks there and stays there.
+   */
+  async inspect(frame = this.currentFrame, opts = { layers: "visible" }) {
+    warnUnknownOptions("movie.inspect()", opts, ["layers"]);
+    this._requireReady("inspect");
+    const f = clampFrame(frame, this.totalFrames);
+    await this.gotoFrame(f, true);
+    return inspectScene(this._rootSequence, f, f / this.frameRate, { width: this.width, height: this.height }, opts);
+  }
+  /**
+   * Draw the stage now. PixiJS's CullerPlugin only culls inside `app.render()` (the ticker), and we render
+   * by hand — while seeking and especially during `render()`, which stops the ticker — so without this the
+   * `culled` flags are whatever the last tick left: a layer that is now on screen can stay culled and be
+   * missing from the frame or from the exported video. Cull again (updating transforms: the timeline just
+   * moved things) right before drawing.
+   */
+  _renderNow() {
+    const app = this.app;
+    if (!app?.renderer) return;
+    Culler.shared.cull(app.stage, app.renderer.screen, false);
+    app.renderer.render({ container: app.stage });
+  }
+  _requireReady(what) {
+    if (this._initState !== "ready" || !this._rootSequence || !this.app) {
+      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). */
   _updateSpace() {
     if (!this._rootSequence || !this.app) return;
@@ -1121,6 +1354,7 @@ var Movie = class {
     return this.muted;
   }
   async render(options) {
+    warnUnknownOptions("movie.render()", options, ["format", "video", "audio"]);
     return await exportFrames(this, options);
   }
   async destroy() {
@@ -1138,6 +1372,11 @@ var Movie = class {
     this._initState = "destroyed";
   }
 };
+var clampFrame = (f, last) => Math.max(0, Math.min(Math.round(f), last));
+function encodeCanvas(canvas, type, as) {
+  if (as === "dataURL") return Promise.resolve(canvas.toDataURL(type));
+  return new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(new Error("pixi-effects: could not encode the image")), type));
+}
 function safeRun(fn) {
   try {
     fn();
@@ -1156,7 +1395,9 @@ function collectVideoSequences(seq, out) {
 }
 
 // src/presets/kenBurns.ts
+var KEN_BURNS_KEYS = ["asset", "name", "at", "duration", "fit", "ease", "motion", "origin", "zoom", "direction", "angle", "from", "to"];
 function kenBurns(opts) {
+  warnUnknownOptions("kenBurns()", opts, KEN_BURNS_KEYS);
   const {
     asset,
     name,
@@ -1166,7 +1407,6 @@ function kenBurns(opts) {
     ease = "sine.inOut"
   } = opts;
   const baseScale = fit;
-  const baseAt = at ?? 0;
   let initial;
   let keyframes;
   if (opts.motion === "still") {
@@ -1197,7 +1437,7 @@ function kenBurns(opts) {
       scale: initialScale
     };
     keyframes = [
-      { at: baseAt, to: { scale: `${baseScale} * ${toZ}` }, duration, ease }
+      { at: 0, to: { scale: `${baseScale} * ${toZ}` }, duration, ease }
     ];
   } else if (opts.motion === "rotation") {
     const angle = clamp(opts.angle ?? 8, 0, 30);
@@ -1228,7 +1468,7 @@ function kenBurns(opts) {
       const tHere = duration * tFrac;
       const tPrev = duration * ((i - 1) / (sampleCount - 1));
       keyframes.push({
-        at: baseAt + tPrev,
+        at: tPrev,
         to: { rotation: angleHere, scale: scaleAt(angleHere) },
         duration: tHere - tPrev,
         ease: i === 1 ? ease : "none"
@@ -1249,7 +1489,7 @@ function kenBurns(opts) {
       scale: scaleExpr
     };
     keyframes = [
-      { at: baseAt, to: { x: xExpr(to[0]), y: yExpr(to[1]) }, duration, ease }
+      { at: 0, to: { x: xExpr(to[0]), y: yExpr(to[1]) }, duration, ease }
     ];
   }
   const spec = {
@@ -1266,13 +1506,72 @@ function kenBurns(opts) {
 function clamp(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
+function parseEase(name) {
+  return gsap.parseEase(name);
+}
+
+// src/presets/orbit.ts
+var ORBIT_KEYS = ["duration", "degrees", "start", "radius", "center", "width", "height", "fov", "ease", "dollyZoom", "at", "name", "stepsPerSecond"];
+function orbit(opts) {
+  warnUnknownOptions("orbit()", opts, ORBIT_KEYS);
+  const {
+    duration,
+    degrees,
+    width = 1280,
+    height = 720,
+    fov,
+    ease = "sine.inOut",
+    stepsPerSecond = 10
+  } = opts;
+  if (!(duration > 0)) throw new Error(`pixi-effects: orbit duration must be > 0 (got ${duration})`);
+  const dolly = opts.dollyZoom;
+  if (dolly && opts.radius !== void 0) {
+    throw new Error("pixi-effects: orbit() cannot combine `radius` with `dollyZoom` \u2014 the radius follows the animated fov");
+  }
+  const [cx, cy] = opts.center ?? [width / 2, height / 2];
+  const fixedR = opts.radius ?? homeDistance(height, fov ?? DEFAULT_FOV);
+  const start = opts.start ?? -degrees / 2;
+  const steps = Math.max(1, Math.round(duration * stepsPerSecond));
+  const easeFn = parseEase(ease);
+  const dollyEase = dolly ? parseEase(dolly.ease ?? ease) : null;
+  const pos = (i) => {
+    const p = i / steps;
+    const a = (start + degrees * easeFn(p)) * DEG;
+    if (!dolly) return { x: cx + fixedR * Math.sin(a), z: fixedR * Math.cos(a) };
+    const f = dolly.from + (dolly.to - dolly.from) * dollyEase(p);
+    const R = homeDistance(height, f);
+    return { x: cx + R * Math.sin(a), z: R * Math.cos(a), fov: f };
+  };
+  const keyframes = [];
+  for (let i = 0; i < steps; i++) {
+    keyframes.push({ at: duration * i / steps, to: pos(i + 1), duration: duration / steps, ease: "none" });
+  }
+  const p0 = pos(0);
+  const spec = {
+    type: "camera",
+    duration,
+    initial: {
+      x: p0.x,
+      y: cy,
+      z: p0.z,
+      lookAtX: cx,
+      lookAtY: cy,
+      lookAtZ: 0,
+      ...p0.fov !== void 0 ? { fov: p0.fov } : fov !== void 0 ? { fov } : {}
+    },
+    keyframes
+  };
+  if (opts.at !== void 0) spec.at = opts.at;
+  if (opts.name !== void 0) spec.name = opts.name;
+  return spec;
+}
 
 // src/transforms/withFade.ts
 function withFade(spec, opts) {
-  const at = spec.at ?? 0;
+  warnUnknownOptions("withFade()", opts, ["in", "out"]);
   if (opts.in != null && opts.in > 0) {
     spec.initial = { ...spec.initial ?? {}, alpha: 0 };
-    const kf = { at, to: { alpha: 1 }, duration: opts.in };
+    const kf = { at: 0, to: { alpha: 1 }, duration: opts.in };
     spec.keyframes = [...spec.keyframes ?? [], kf];
   }
   if (opts.out != null && opts.out > 0) {
@@ -1281,12 +1580,12 @@ function withFade(spec, opts) {
         "withFade(spec, { out }) requires spec.duration to be set so the fade-out can be anchored to the sequence end. Set spec.duration before passing the spec in."
       );
     }
-    const kf = { at: at + spec.duration - opts.out, to: { alpha: 0 }, duration: opts.out };
+    const kf = { at: spec.duration - opts.out, to: { alpha: 0 }, duration: opts.out };
     spec.keyframes = [...spec.keyframes ?? [], kf];
   }
   return spec;
 }
 
-export { Movie, kenBurns, withFade };
+export { Movie, kenBurns, orbit, withFade };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map