reframe-video 0.6.24 → 0.6.26

package/dist/labels.js

@@ -325,7 +325,67 @@ function compileScene(ir) {
   };
 }
 
+// ../core/src/interpolate.ts
+var BACK_C1 = 1.70158;
+var BACK_C2 = BACK_C1 * 1.525;
+var BACK_C3 = BACK_C1 + 1;
+var ELASTIC_C4 = 2 * Math.PI / 3;
+var ELASTIC_C5 = 2 * Math.PI / 4.5;
+function springEase(stiffness, damping, velocity) {
+  const K = 5;
+  const zeta = Math.min(0.999, Math.max(0.05, damping / (2 * Math.sqrt(Math.max(1e-6, stiffness)))));
+  const wd = K / zeta * Math.sqrt(1 - zeta * zeta);
+  const coef = (K - velocity) / wd;
+  return (u) => {
+    if (u <= 0) return 0;
+    if (u >= 1) return 1;
+    return 1 - Math.exp(-K * u) * (Math.cos(wd * u) + coef * Math.sin(wd * u));
+  };
+}
+function easeOutBounce(u) {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (u < 1 / d1) return n1 * u * u;
+  if (u < 2 / d1) return n1 * (u -= 1.5 / d1) * u + 0.75;
+  if (u < 2.5 / d1) return n1 * (u -= 2.25 / d1) * u + 0.9375;
+  return n1 * (u -= 2.625 / d1) * u + 0.984375;
+}
+var EASE_TABLE = {
+  linear: (u) => u,
+  easeInQuad: (u) => u * u,
+  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
+  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
+  easeInCubic: (u) => u ** 3,
+  easeOutCubic: (u) => 1 - (1 - u) ** 3,
+  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
+  easeInQuart: (u) => u ** 4,
+  easeOutQuart: (u) => 1 - (1 - u) ** 4,
+  easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
+  easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
+  easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
+  easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2,
+  // --- expressive eases (GSAP's signature feel) — standard Penner equations ---
+  // back: overshoots past the target then settles (pop / snap)
+  easeInBack: (u) => BACK_C3 * u ** 3 - BACK_C1 * u * u,
+  easeOutBack: (u) => 1 + BACK_C3 * (u - 1) ** 3 + BACK_C1 * (u - 1) ** 2,
+  easeInOutBack: (u) => u < 0.5 ? (2 * u) ** 2 * ((BACK_C2 + 1) * 2 * u - BACK_C2) / 2 : ((2 * u - 2) ** 2 * ((BACK_C2 + 1) * (2 * u - 2) + BACK_C2) + 2) / 2,
+  // elastic: rings around the target before settling (playful spring)
+  easeInElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : -(2 ** (10 * u - 10)) * Math.sin((u * 10 - 10.75) * ELASTIC_C4),
+  easeOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : 2 ** (-10 * u) * Math.sin((u * 10 - 0.75) * ELASTIC_C4) + 1,
+  easeInOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? -(2 ** (20 * u - 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5)) / 2 : 2 ** (-20 * u + 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5) / 2 + 1,
+  // bounce: drops and bounces to rest (lands without overshoot)
+  easeInBounce: (u) => 1 - easeOutBounce(1 - u),
+  easeOutBounce,
+  easeInOutBounce: (u) => u < 0.5 ? (1 - easeOutBounce(1 - 2 * u)) / 2 : (1 + easeOutBounce(2 * u - 1)) / 2,
+  // damped-spring presets (ζ from damping/(2√stiffness)): 0.5 / 0.30 / 0.90
+  spring: springEase(100, 10, 0),
+  springBouncy: springEase(180, 8, 0),
+  springStiff: springEase(210, 26, 0)
+};
+var EASE_NAMES = Object.keys(EASE_TABLE);
+
 // ../core/src/validate.ts
+var EASE_SET = new Set(EASE_NAMES);
 var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
 var BLEND_MODES = /* @__PURE__ */ new Set([
   "normal",
@@ -457,6 +517,26 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const checkEase = (path3, ease) => {
+    if (ease === void 0) return;
+    if (typeof ease === "string") {
+      if (!EASE_SET.has(ease)) {
+        problems.push(`${path3}: unknown ease "${ease}" \u2014 valid: ${EASE_NAMES.join(", ")} (note: there are no *Sine eases)`);
+      }
+      return;
+    }
+    if (typeof ease === "object" && ease !== null) {
+      const o = ease;
+      if ("spring" in o) return;
+      if ("cubicBezier" in o) {
+        if (!Array.isArray(o.cubicBezier) || o.cubicBezier.length !== 4) {
+          problems.push(`${path3}: ease cubicBezier must be [x1, y1, x2, y2]`);
+        }
+        return;
+      }
+    }
+    problems.push(`${path3}: invalid ease \u2014 use a name, { spring }, or { cubicBezier: [x1,y1,x2,y2] }`);
+  };
   const checkTimeline = (tl, path3) => {
     if ("label" in tl && tl.label !== void 0) {
       if (labels.has(tl.label)) {
@@ -484,6 +564,7 @@ function validateScene(ir) {
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path3}: to("${tl.state}") duration must be > 0`);
         }
+        checkEase(path3, tl.ease);
         for (const id of tl.filter ?? []) {
           if (!nodeById.has(id)) problems.push(`${path3}: filter contains unknown node "${id}"`);
         }
@@ -493,6 +574,7 @@ function validateScene(ir) {
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path3}: tween duration must be > 0`);
         }
+        checkEase(path3, tl.ease);
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
@@ -513,6 +595,7 @@ function validateScene(ir) {
         if (tl.curviness !== void 0 && tl.curviness < 0) {
           problems.push(`${path3}: motionPath "${tl.target}" curviness must be >= 0`);
         }
+        checkEase(path3, tl.ease);
         break;
       }
       case "wait":
@@ -609,65 +692,6 @@ function validateScene(ir) {
 // ../core/src/presets.ts
 var SET = 1 / 120;
 
-// ../core/src/interpolate.ts
-var BACK_C1 = 1.70158;
-var BACK_C2 = BACK_C1 * 1.525;
-var BACK_C3 = BACK_C1 + 1;
-var ELASTIC_C4 = 2 * Math.PI / 3;
-var ELASTIC_C5 = 2 * Math.PI / 4.5;
-function springEase(stiffness, damping, velocity) {
-  const K = 5;
-  const zeta = Math.min(0.999, Math.max(0.05, damping / (2 * Math.sqrt(Math.max(1e-6, stiffness)))));
-  const wd = K / zeta * Math.sqrt(1 - zeta * zeta);
-  const coef = (K - velocity) / wd;
-  return (u) => {
-    if (u <= 0) return 0;
-    if (u >= 1) return 1;
-    return 1 - Math.exp(-K * u) * (Math.cos(wd * u) + coef * Math.sin(wd * u));
-  };
-}
-function easeOutBounce(u) {
-  const n1 = 7.5625;
-  const d1 = 2.75;
-  if (u < 1 / d1) return n1 * u * u;
-  if (u < 2 / d1) return n1 * (u -= 1.5 / d1) * u + 0.75;
-  if (u < 2.5 / d1) return n1 * (u -= 2.25 / d1) * u + 0.9375;
-  return n1 * (u -= 2.625 / d1) * u + 0.984375;
-}
-var EASE_TABLE = {
-  linear: (u) => u,
-  easeInQuad: (u) => u * u,
-  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
-  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
-  easeInCubic: (u) => u ** 3,
-  easeOutCubic: (u) => 1 - (1 - u) ** 3,
-  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
-  easeInQuart: (u) => u ** 4,
-  easeOutQuart: (u) => 1 - (1 - u) ** 4,
-  easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
-  easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
-  easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
-  easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2,
-  // --- expressive eases (GSAP's signature feel) — standard Penner equations ---
-  // back: overshoots past the target then settles (pop / snap)
-  easeInBack: (u) => BACK_C3 * u ** 3 - BACK_C1 * u * u,
-  easeOutBack: (u) => 1 + BACK_C3 * (u - 1) ** 3 + BACK_C1 * (u - 1) ** 2,
-  easeInOutBack: (u) => u < 0.5 ? (2 * u) ** 2 * ((BACK_C2 + 1) * 2 * u - BACK_C2) / 2 : ((2 * u - 2) ** 2 * ((BACK_C2 + 1) * (2 * u - 2) + BACK_C2) + 2) / 2,
-  // elastic: rings around the target before settling (playful spring)
-  easeInElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : -(2 ** (10 * u - 10)) * Math.sin((u * 10 - 10.75) * ELASTIC_C4),
-  easeOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : 2 ** (-10 * u) * Math.sin((u * 10 - 0.75) * ELASTIC_C4) + 1,
-  easeInOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? -(2 ** (20 * u - 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5)) / 2 : 2 ** (-20 * u + 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5) / 2 + 1,
-  // bounce: drops and bounces to rest (lands without overshoot)
-  easeInBounce: (u) => 1 - easeOutBounce(1 - u),
-  easeOutBounce,
-  easeInOutBounce: (u) => u < 0.5 ? (1 - easeOutBounce(1 - 2 * u)) / 2 : (1 + easeOutBounce(2 * u - 1)) / 2,
-  // damped-spring presets (ζ from damping/(2√stiffness)): 0.5 / 0.30 / 0.90
-  spring: springEase(100, 10, 0),
-  springBouncy: springEase(180, 8, 0),
-  springStiff: springEase(210, 26, 0)
-};
-var EASE_NAMES = Object.keys(EASE_TABLE);
-
 // ../core/src/evaluate.ts
 var DEG = Math.PI / 180;
 

package/dist/trace-cli.js

@@ -5,37 +5,6 @@ import { writeFile as writeFile2 } from "node:fs/promises";
 import { resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
-// ../core/src/validate.ts
-var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-var PROPS_BY_TYPE = {
-  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
-  ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
-  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
-  path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
-  group: COMMON_PROPS
-};
-
-// ../core/src/dsl.ts
-function seq(...children) {
-  return { kind: "seq", children };
-}
-function par(...children) {
-  return { kind: "par", children };
-}
-function tween(target, props, opts = {}) {
-  return { kind: "tween", target, props, ...opts };
-}
-function wait(duration, label) {
-  return { kind: "wait", duration, ...label !== void 0 && { label } };
-}
-
-// ../core/src/presets.ts
-var SET = 1 / 120;
-
 // ../core/src/interpolate.ts
 var BACK_C1 = 1.70158;
 var BACK_C2 = BACK_C1 * 1.525;
@@ -95,6 +64,38 @@ var EASE_TABLE = {
 };
 var EASE_NAMES = Object.keys(EASE_TABLE);
 
+// ../core/src/validate.ts
+var EASE_SET = new Set(EASE_NAMES);
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
+var PROPS_BY_TYPE = {
+  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
+  ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
+  path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
+  group: COMMON_PROPS
+};
+
+// ../core/src/dsl.ts
+function seq(...children) {
+  return { kind: "seq", children };
+}
+function par(...children) {
+  return { kind: "par", children };
+}
+function tween(target, props, opts = {}) {
+  return { kind: "tween", target, props, ...opts };
+}
+function wait(duration, label) {
+  return { kind: "wait", duration, ...label !== void 0 && { label } };
+}
+
+// ../core/src/presets.ts
+var SET = 1 / 120;
+
 // ../core/src/evaluate.ts
 var DEG = Math.PI / 180;
 

package/dist/types/camera.d.ts

@@ -24,6 +24,33 @@ export declare const CAMERA_PROPS: readonly ["x", "y", "zoom", "rotation", "pers
  * collapse to the identity.
  */
 export declare function cameraMatrix(cam: CameraIR, size: Size): Mat2D;
+/**
+ * Frame a scene-space bounding box in the viewport — returns `{ x, y, zoom }` to
+ * spread into `cameraTo`, GUARANTEED not to clip the box. The visible scene rect
+ * is `W/zoom × H/zoom` centred on `(x, y)`; fitting `box` (+ `margin` padding on
+ * the tight axis) means `zoom = min(W/(box.w+2m), H/(box.h+2m))`, capped by
+ * `maxZoom` so a tiny target doesn't zoom absurdly close.
+ *
+ *   cameraTo(cameraFit({ x: 200, y: 760, width: 740, height: 360 }, { margin: 90 }),
+ *            { duration: 1, ease: "easeInOutCubic" })
+ *
+ * `box` is a top-left rect in scene coords (a centre-anchored panel at (px,py) of
+ * size (pw,ph) is `{ x: px-pw/2, y: py-ph/2, width: pw, height: ph }`).
+ */
+export declare function cameraFit(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, opts?: {
+    size?: Size;
+    margin?: number;
+    maxZoom?: number;
+}): {
+    x: number;
+    y: number;
+    zoom: number;
+};
 /** Keyframe the camera: a `tween` on the reserved "camera" target. */
 export declare function cameraTo(props: CameraIR, opts?: {
     duration?: number;

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { compileComposition, type CompiledComposition, type ScenePlacement, } fr
 export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport, } from "./compose.js";
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
-export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
+export { cameraTo, cameraFit, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
 export { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
 export { glow, dropShadow } from "./effects.js";
 export { row, column, grid, type RowOpts, type GridOpts } from "./layout.js";

package/guides/edsl-guide.md

@@ -90,6 +90,14 @@ row(3, { center: 960, gap: 60, itemWidth: 440 }).map((x, i) =>
 
 `column` is `row` for the y axis.
 
+**Charts/widgets in a panel — derive geometry from the box, and `clip` it.** Don't
+hand-pick a pixels-per-unit scale (bars routinely overflow the panel that way).
+Define the panel rect ONCE, then size from it — bar height `(v/max) · innerH`, x via
+`row(...)` across the panel width — so a tall value can't exceed the box. As a safety
+net, wrap the chart in a clipped group so nothing can ever punch out the panel:
+`group({ clip: { kind: "rect", x, y, width, height, radius } }, [ ...bars ])`. See
+`examples/scenes/annual-report.ts` (and `cameraFit` above to frame the panel).
+
 ## States: declare looks, not motion
 
 Base props on nodes describe the **finished design**. A state is a sparse
@@ -178,6 +186,14 @@ scene({
   `tween` on the `"camera"` target, so `motionPath("camera", pts, …)` (pan along
   a curve) and `oscillate/wiggle("camera", "rotation"|"x"|…)` (handheld drift)
   also work.
+- **Frame a region without clipping — use `cameraFit`, not a guessed `zoom`.** The
+  visible scene rect is `W/zoom × H/zoom` centred on `(camera.x, camera.y)`, so a
+  hand-picked `zoom` that's too big crops the target. `cameraFit(box, { margin })`
+  returns `{ x, y, zoom }` that frames a scene-space bbox (top-left `{x,y,width,
+  height}`) with padding, guaranteed in-bounds: `cameraTo(cameraFit({ x, y, width,
+  height }, { margin: 80 }), { duration: 1, ease: "easeInOutCubic" })`. A centre-
+  anchored panel at `(px,py)` size `(pw,ph)` is `{ x: px-pw/2, y: py-ph/2, width:
+  pw, height: ph }`. `maxZoom` (default 2.4) caps absurd close-ups.
 - **Pin HUD/titles to the screen** with `fixed: true` on a TOP-LEVEL node — the
   camera won't move it (for overlays, watermarks, captions).
 - Defaults are the identity, so a scene without a camera is unchanged. Don't name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",