reframe-video 0.6.13 → 0.6.15

package/dist/bin.js

@@ -10,13 +10,14 @@ var __export = (target, all) => {
 };
 
 // ../core/src/ir.ts
-var DEFAULT_TO_DURATION, DEFAULT_TWEEN_DURATION, DEFAULT_MOTIONPATH_DURATION;
+var DEFAULT_TO_DURATION, DEFAULT_TWEEN_DURATION, DEFAULT_MOTIONPATH_DURATION, DEFAULT_STILL_DURATION;
 var init_ir = __esm({
   "../core/src/ir.ts"() {
     "use strict";
     DEFAULT_TO_DURATION = 0.5;
     DEFAULT_TWEEN_DURATION = 0.5;
     DEFAULT_MOTIONPATH_DURATION = 1;
+    DEFAULT_STILL_DURATION = 1;
   }
 });
 
@@ -319,14 +320,14 @@ function compileScene(ir) {
       }
     }
   };
-  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
   return {
     ir,
-    duration: ir.duration ?? inferredEnd,
+    duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
     segments,
     motionPaths,
     initialValues,
@@ -1346,6 +1347,17 @@ var init_behaviors = __esm({
 });
 
 // ../core/src/interpolate.ts
+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;
@@ -1389,7 +1401,11 @@ var init_interpolate = __esm({
       // 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
+      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)
     };
     EASE_NAMES = Object.keys(EASE_TABLE);
   }
@@ -2843,10 +2859,16 @@ ${USAGE}`);
       }
       preflightFfmpeg();
       const outBase = PACKAGED ? join9(USER_CWD, "out") : join9(ROOT2, "out");
+      const stem = `${basename(input).replace(/\.[^.]+$/, "")}.mp4`;
       let outArgs = args;
-      if (!args.includes("-o")) {
+      const oIdx = args.indexOf("-o");
+      if (oIdx === -1) {
         await mkdir4(outBase, { recursive: true });
-        outArgs = [...args, "-o", join9(outBase, `${basename(input).replace(/\.[^.]+$/, "")}.mp4`)];
+        outArgs = [...args, "-o", join9(outBase, stem)];
+      } else if (args[oIdx + 1] && !args[oIdx + 1].startsWith("-") && !/\.\w{2,4}$/.test(args[oIdx + 1])) {
+        const dir = userPath(args[oIdx + 1]);
+        await mkdir4(dir, { recursive: true });
+        outArgs = args.map((a, i) => i === oIdx + 1 ? join9(dir, stem) : a);
       }
       outArgs = outArgs.map(
         (a, i) => outArgs[i - 1] === "--overlay" || outArgs[i - 1] === "-o" ? userPath(a) : a

package/dist/browserEntry.js

@@ -4,6 +4,7 @@
   var DEFAULT_TO_DURATION = 0.5;
   var DEFAULT_TWEEN_DURATION = 0.5;
   var DEFAULT_MOTIONPATH_DURATION = 1;
+  var DEFAULT_STILL_DURATION = 1;
 
   // ../core/src/path.ts
   function pathBBox(d) {
@@ -316,14 +317,14 @@
         }
       }
     };
-    const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+    const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
     for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
     for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
     const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
     const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
     return {
       ir,
-      duration: ir.duration ?? inferredEnd,
+      duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
       segments,
       motionPaths,
       initialValues,
@@ -408,6 +409,17 @@
   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;
@@ -442,7 +454,11 @@
     // 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
+    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);
   function resolveEase(ease) {
@@ -452,6 +468,10 @@
       if (!fn) throw new Error(`unknown ease "${ease}" \u2014 valid: ${Object.keys(EASE_TABLE).join(", ")}`);
       return fn;
     }
+    if ("spring" in ease) {
+      const { stiffness = 100, damping = 10, velocity = 0 } = ease.spring;
+      return springEase(stiffness, damping, velocity);
+    }
     return cubicBezierEase(...ease.cubicBezier);
   }
   function cubicBezierEase(x1, y1, x2, y2) {

package/dist/cli.js

@@ -10,6 +10,7 @@ var DEFAULT_CROSSFADE = 0.5;
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
+var DEFAULT_STILL_DURATION = 1;
 
 // ../core/src/path.ts
 function locate(segCount, u) {
@@ -306,14 +307,14 @@ function compileScene(ir) {
       }
     }
   };
-  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
   return {
     ir,
-    duration: ir.duration ?? inferredEnd,
+    duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
     segments,
     motionPaths,
     initialValues,
@@ -1050,6 +1051,17 @@ 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;
@@ -1084,7 +1096,11 @@ var EASE_TABLE = {
   // 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
+  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);
 

package/dist/diff.js

@@ -16,6 +16,7 @@ import { fileURLToPath } from "node:url";
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
+var DEFAULT_STILL_DURATION = 1;
 
 // ../core/src/path.ts
 function locate(segCount, u) {
@@ -312,14 +313,14 @@ function compileScene(ir) {
       }
     }
   };
-  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
   return {
     ir,
-    duration: ir.duration ?? inferredEnd,
+    duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
     segments,
     motionPaths,
     initialValues,
@@ -639,6 +640,17 @@ 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;
@@ -673,7 +685,11 @@ var EASE_TABLE = {
   // 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
+  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);
 

package/dist/index.js

@@ -4,6 +4,7 @@ var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
 var DEFAULT_FPS = 30;
+var DEFAULT_STILL_DURATION = 1;
 
 // ../core/src/path.ts
 function pathBBox(d) {
@@ -316,14 +317,14 @@ function compileScene(ir) {
       }
     }
   };
-  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
   return {
     ir,
-    duration: ir.duration ?? inferredEnd,
+    duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
     segments,
     motionPaths,
     initialValues,
@@ -2850,6 +2851,17 @@ 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 K3 = 5;
+  const zeta = Math.min(0.999, Math.max(0.05, damping / (2 * Math.sqrt(Math.max(1e-6, stiffness)))));
+  const wd = K3 / zeta * Math.sqrt(1 - zeta * zeta);
+  const coef = (K3 - velocity) / wd;
+  return (u) => {
+    if (u <= 0) return 0;
+    if (u >= 1) return 1;
+    return 1 - Math.exp(-K3 * u) * (Math.cos(wd * u) + coef * Math.sin(wd * u));
+  };
+}
 function easeOutBounce(u) {
   const n1 = 7.5625;
   const d1 = 2.75;
@@ -2884,7 +2896,11 @@ var EASE_TABLE = {
   // 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
+  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);
 function resolveEase(ease) {
@@ -2894,6 +2910,10 @@ function resolveEase(ease) {
     if (!fn) throw new Error(`unknown ease "${ease}" \u2014 valid: ${Object.keys(EASE_TABLE).join(", ")}`);
     return fn;
   }
+  if ("spring" in ease) {
+    const { stiffness = 100, damping = 10, velocity = 0 } = ease.spring;
+    return springEase(stiffness, damping, velocity);
+  }
   return cubicBezierEase(...ease.cubicBezier);
 }
 function cubicBezierEase(x1, y1, x2, y2) {
@@ -3505,6 +3525,7 @@ export {
   DEFAULT_CROSSFADE,
   DEFAULT_FPS,
   DEFAULT_MOTIONPATH_DURATION,
+  DEFAULT_STILL_DURATION,
   DEFAULT_TO_DURATION,
   DEFAULT_TWEEN_DURATION,
   DEVICE_PRESET_NAMES,

package/dist/labels.js

@@ -4,6 +4,7 @@
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
+var DEFAULT_STILL_DURATION = 1;
 
 // ../core/src/path.ts
 function locate(segCount, u) {
@@ -300,14 +301,14 @@ function compileScene(ir) {
       }
     }
   };
-  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  const inferredEnd = (ir.timeline ? walk(ir.timeline, 0) : 0) || 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
   const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   const hasPerspective = !cameraIsNode && (ir.camera?.perspective !== void 0 || segments.has("camera.perspective"));
   return {
     ir,
-    duration: ir.duration ?? inferredEnd,
+    duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
     segments,
     motionPaths,
     initialValues,
@@ -597,6 +598,17 @@ 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;
@@ -631,7 +643,11 @@ var EASE_TABLE = {
   // 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
+  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);
 

package/dist/trace-cli.js

@@ -42,6 +42,17 @@ 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;
@@ -76,7 +87,11 @@ var EASE_TABLE = {
   // 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
+  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);
 

package/dist/types/ir.d.ts

@@ -8,10 +8,24 @@
  * Semantics: a scene is evaluated as a pure function of continuous time
  * `evaluate(scene, tSeconds) -> DisplayList`. `fps` is a render hint only.
  */
-export type EaseName = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo" | "easeInBack" | "easeOutBack" | "easeInOutBack" | "easeInElastic" | "easeOutElastic" | "easeInOutElastic" | "easeInBounce" | "easeOutBounce" | "easeInOutBounce";
+export type EaseName = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo" | "easeInBack" | "easeOutBack" | "easeInOutBack" | "easeInElastic" | "easeOutElastic" | "easeInOutElastic" | "easeInBounce" | "easeOutBounce" | "easeInOutBounce" | "spring" | "springBouncy" | "springStiff";
+/**
+ * A custom spring: a damped harmonic oscillator sampled over the tween's normalized
+ * 0..1 window (mass = 1). `stiffness`/`damping` set the damping ratio
+ * ζ = damping / (2·√stiffness) — the SHAPE knob (low ζ ⇒ bouncy, high ζ ⇒ snappy);
+ * `velocity` is an initial launch slope. Defaults: stiffness 100, damping 10
+ * (ζ = 0.5), velocity 0.
+ */
+export interface SpringEase {
+    spring: {
+        stiffness?: number;
+        damping?: number;
+        velocity?: number;
+    };
+}
 export type Ease = EaseName | {
     cubicBezier: [number, number, number, number];
-};
+} | SpringEase;
 export type Anchor = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
 export interface Size {
     width: number;
@@ -508,3 +522,6 @@ export declare const DEFAULT_TO_DURATION = 0.5;
 export declare const DEFAULT_TWEEN_DURATION = 0.5;
 export declare const DEFAULT_MOTIONPATH_DURATION = 1;
 export declare const DEFAULT_FPS = 30;
+/** Fallback length (seconds) for a scene with no animating timeline — a static
+ *  frame still needs a positive duration to render. Override with scene `duration`. */
+export declare const DEFAULT_STILL_DURATION = 1;

package/guides/directing-guide.md

@@ -43,6 +43,11 @@ reframe diff ref.png scene.ts --mode blend  # 50% overlay — spot drift
 
 Loop: `--mode grid` to measure → write the node tree → `--mode side`/`diff` to compare →
 fix coordinates/sizes/colors → repeat until faithful. Pick the frame with `--t <sec>`.
+The grid is rendered at the reference's **full resolution** — the printed numbers are
+exact scene pixels, so place nodes at the labelled coordinates directly (no scaling).
+`diff`/`blend` are sharpest on hard edges (type, icons, frames); over large **soft
+gradients/glows** they always light up "different" even when close, so tune those by
+eye with `--mode side` rather than chasing the diff to black.
 
 ### 3. Apply the cinematic-craft checklist
 

package/guides/edsl-guide.md

@@ -68,6 +68,9 @@ Factories return plain data. Every node needs a unique `id`.
 `"top-left"` (default) | `"top-center"` | `"top-right"` | `"center-left"` |
 `"center"` | `"center-right"` | `"bottom-left"` | `"bottom-center"` | `"bottom-right"`.
 Example: a bar that grows upward = `anchor: "bottom-left"` + animate `height`.
+**Text alignment is `anchor`, not a separate `align` prop:** the anchor's horizontal
+half sets the text align — `"…-left"` left-aligns, `"…-center"`/`"center"` centers,
+`"…-right"` right-aligns (a right-aligned wordmark in a corner = `anchor: "bottom-right"`).
 Font: use `fontFamily: "Inter"` (weights 400/700/800 are available).
 
 ### Layout helpers (evenly spacing things)
@@ -132,8 +135,13 @@ Expressive eases for a premium feel: `easeIn/Out/InOutBack` (overshoots past the
 target then settles — a pop/snap), `easeIn/Out/InOutElastic` (rings around the
 target — a playful spring), `easeIn/Out/InOutBounce` (drops and bounces to rest).
 A logo or card "popping" in usually wants `easeOutBack`; a stamp landing,
-`easeOutBounce`.
-Scene duration is inferred from the timeline.
+`easeOutBounce`. Physical springs settle to rest within the tween's duration:
+`spring` (a natural settle), `springBouncy` (rings more), `springStiff` (snappy,
+barely overshoots) — or tune your own with `{ spring: { stiffness, damping, velocity } }`
+(damping ratio = `damping / (2·√stiffness)`; lower ⇒ bouncier).
+Scene duration is inferred from the timeline. For a **static frame** you can omit
+`timeline` entirely (or set scene `duration: <seconds>`) — a still defaults to a 1s
+render; no throwaway `wait` is needed.
 
 ## Behaviors: continuous motion during holds
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "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",