reframe-video 0.6.14 → 0.6.16

package/dist/bin.js

@@ -162,6 +162,8 @@ function compileScene(ir) {
     initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
     initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
     if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+    if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+    if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
   }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
@@ -548,6 +550,8 @@ function validateScene(ir) {
         problems.push(`camera.${key2} must be a number`);
       } else if (key2 === "perspective" && value <= 0) {
         problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key2 === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
       }
     }
   }
@@ -629,7 +633,7 @@ var init_validate = __esm({
     ]);
     IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
     COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-    CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+    CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
     PROPS_BY_TYPE = {
       rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -1347,6 +1351,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;
@@ -1390,7 +1405,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);
   }

package/dist/browserEntry.js

@@ -159,6 +159,8 @@
       initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
       initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
       if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+      if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+      if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
     }
     const segments = /* @__PURE__ */ new Map();
     const motionPaths = /* @__PURE__ */ new Map();
@@ -409,6 +411,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;
@@ -443,7 +456,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) {
@@ -453,6 +470,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) {
@@ -721,6 +742,14 @@
     const dPersp = persp ? num("camera", "perspective", 0) : 0;
     const vx = persp ? compiled2.ir.size.width / 2 : 0;
     const vy = persp ? compiled2.ir.size.height / 2 : 0;
+    const aperture = persp ? num("camera", "aperture", 0) : 0;
+    const focus = persp ? num("camera", "focus", 0) : 0;
+    const dofFx = (fx, depth, project) => {
+      if (!project || aperture <= 0) return fx;
+      const extra = aperture * Math.abs(depth - focus);
+      if (extra <= 0) return fx;
+      return { ...fx, blur: z0((fx.blur ?? 0) + extra) };
+    };
     const walk = (node, parent, parentOpacity, clips, zAcc, project) => {
       const id = node.id;
       const clipSpread = clips.length > 0 ? { clips } : void 0;
@@ -743,7 +772,8 @@
           y2: y1 + (num(id, "y2", node.props.y2) - y1) * progress,
           stroke: str(id, "stroke", node.props.stroke),
           strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1),
-          ...fx,
+          // a line carries no z of its own — DOF uses the inherited subtree depth
+          ...dofFx(fx, zAcc, project),
           ...clipSpread
         });
         return;
@@ -780,6 +810,7 @@
         const tilted = rotX !== 0 || rotY !== 0 ? tiltSkew(m, rotX, rotY, hw, hh, dPersp) : m;
         return projectDepth(tilted, depth, vx, vy, dPersp);
       };
+      const leafFx = dofFx(fx, depth, project);
       switch (node.type) {
         case "group": {
           const clipTf = projDraw(matrix, 0, 0);
@@ -820,7 +851,7 @@
             ...fill !== void 0 && { fill },
             ...stroke !== void 0 && { stroke, strokeWidth },
             ...node.type === "rect" && { radius: num(id, "radius", node.props.radius ?? 0) },
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -840,7 +871,7 @@
             offsetX: -width * ax,
             offsetY: -height * ay,
             ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -867,7 +898,7 @@
             offsetY: -height * ay,
             frame,
             ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -892,7 +923,7 @@
             ...fill !== void 0 && { fill },
             ...stroke !== void 0 && { stroke, strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1) },
             ...needsBox && { bbox: pathBBox(dStr) },
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -919,7 +950,7 @@
             letterSpacing: num(id, "letterSpacing", node.props.letterSpacing ?? 0),
             align: TEXT_ALIGN[ax] ?? "left",
             baseline: TEXT_BASELINE[ay] ?? "top",
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;

package/dist/cli.js

@@ -149,6 +149,8 @@ function compileScene(ir) {
     initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
     initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
     if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+    if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+    if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
   }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
@@ -344,7 +346,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
 ]);
 var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -562,6 +564,8 @@ function validateScene(ir) {
         problems.push(`camera.${key2} must be a number`);
       } else if (key2 === "perspective" && value <= 0) {
         problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key2 === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
       }
     }
   }
@@ -1051,6 +1055,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;
@@ -1085,7 +1100,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

@@ -155,6 +155,8 @@ function compileScene(ir) {
     initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
     initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
     if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+    if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+    if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
   }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
@@ -350,7 +352,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
 ]);
 var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -568,6 +570,8 @@ function validateScene(ir) {
         problems.push(`camera.${key2} must be a number`);
       } else if (key2 === "perspective" && value <= 0) {
         problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key2 === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
       }
     }
   }
@@ -640,6 +644,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;
@@ -674,7 +689,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

@@ -159,6 +159,8 @@ function compileScene(ir) {
     initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
     initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
     if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+    if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+    if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
   }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
@@ -354,7 +356,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
 ]);
 var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -572,6 +574,8 @@ function validateScene(ir) {
         problems.push(`camera.${key2} must be a number`);
       } else if (key2 === "perspective" && value <= 0) {
         problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key2 === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
       }
     }
   }
@@ -2851,6 +2855,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;
@@ -2885,7 +2900,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) {
@@ -2895,6 +2914,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) {
@@ -3195,6 +3218,14 @@ function evaluate(compiled, t) {
   const dPersp = persp ? num("camera", "perspective", 0) : 0;
   const vx = persp ? compiled.ir.size.width / 2 : 0;
   const vy = persp ? compiled.ir.size.height / 2 : 0;
+  const aperture = persp ? num("camera", "aperture", 0) : 0;
+  const focus = persp ? num("camera", "focus", 0) : 0;
+  const dofFx = (fx, depth, project) => {
+    if (!project || aperture <= 0) return fx;
+    const extra = aperture * Math.abs(depth - focus);
+    if (extra <= 0) return fx;
+    return { ...fx, blur: z0((fx.blur ?? 0) + extra) };
+  };
   const walk = (node, parent, parentOpacity, clips, zAcc, project) => {
     const id = node.id;
     const clipSpread = clips.length > 0 ? { clips } : void 0;
@@ -3217,7 +3248,8 @@ function evaluate(compiled, t) {
         y2: y1 + (num(id, "y2", node.props.y2) - y1) * progress,
         stroke: str(id, "stroke", node.props.stroke),
         strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1),
-        ...fx,
+        // a line carries no z of its own — DOF uses the inherited subtree depth
+        ...dofFx(fx, zAcc, project),
         ...clipSpread
       });
       return;
@@ -3254,6 +3286,7 @@ function evaluate(compiled, t) {
       const tilted = rotX !== 0 || rotY !== 0 ? tiltSkew(m, rotX, rotY, hw, hh, dPersp) : m;
       return projectDepth(tilted, depth, vx, vy, dPersp);
     };
+    const leafFx = dofFx(fx, depth, project);
     switch (node.type) {
       case "group": {
         const clipTf = projDraw(matrix, 0, 0);
@@ -3294,7 +3327,7 @@ function evaluate(compiled, t) {
           ...fill !== void 0 && { fill },
           ...stroke !== void 0 && { stroke, strokeWidth },
           ...node.type === "rect" && { radius: num(id, "radius", node.props.radius ?? 0) },
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;
@@ -3314,7 +3347,7 @@ function evaluate(compiled, t) {
           offsetX: -width * ax,
           offsetY: -height * ay,
           ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;
@@ -3341,7 +3374,7 @@ function evaluate(compiled, t) {
           offsetY: -height * ay,
           frame,
           ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;
@@ -3366,7 +3399,7 @@ function evaluate(compiled, t) {
           ...fill !== void 0 && { fill },
           ...stroke !== void 0 && { stroke, strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1) },
           ...needsBox && { bbox: pathBBox(dStr) },
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;
@@ -3393,7 +3426,7 @@ function evaluate(compiled, t) {
           letterSpacing: num(id, "letterSpacing", node.props.letterSpacing ?? 0),
           align: TEXT_ALIGN[ax] ?? "left",
           baseline: TEXT_BASELINE[ay] ?? "top",
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;

package/dist/labels.js

@@ -143,6 +143,8 @@ function compileScene(ir) {
     initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
     initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
     if (cam.perspective !== void 0) initialValues.set(key("camera", "perspective"), cam.perspective);
+    if (cam.focus !== void 0) initialValues.set(key("camera", "focus"), cam.focus);
+    if (cam.aperture !== void 0) initialValues.set(key("camera", "aperture"), cam.aperture);
   }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
@@ -338,7 +340,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
 ]);
 var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "z", "rotateX", "rotateY", "anchor", "fixed", ...FX_PROPS];
-var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation", "perspective", "focus", "aperture"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -556,6 +558,8 @@ function validateScene(ir) {
         problems.push(`camera.${key2} must be a number`);
       } else if (key2 === "perspective" && value <= 0) {
         problems.push(`camera.perspective must be > 0 (focal distance in px) \u2014 drop it to disable perspective`);
+      } else if (key2 === "aperture" && value < 0) {
+        problems.push(`camera.aperture must be >= 0 (blur px per unit depth) \u2014 0 disables depth of field`);
       }
     }
   }
@@ -598,6 +602,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;
@@ -632,7 +647,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;
@@ -447,6 +461,17 @@ export interface CameraIR {
      * focal pull). A node BEHIND the camera (`perspective + z <= 0`) is culled.
      */
     perspective?: number;
+    /**
+     * Depth of field (requires `perspective`). `aperture` is the blur strength —
+     * screen-pixels of gaussian blur added per unit of depth away from the focal
+     * plane; absent / 0 ⇒ no DOF (byte-identical). `focus` is the in-focus depth
+     * (same units as a node's world `z`, default 0 = the camera plane). A drawn op
+     * at depth `d` gains `aperture · |d − focus|` blur on top of any authored blur,
+     * so far (and near) layers soften while the focal plane stays sharp. Both are
+     * keyframable — animate `focus` for a rack focus, `aperture` for an iris pull.
+     */
+    focus?: number;
+    aperture?: number;
 }
 export interface SceneIR {
     version: 1;

package/guides/edsl-guide.md

@@ -135,7 +135,10 @@ 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`.
+`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.
@@ -212,6 +215,12 @@ scene({
 - A node needs a base value to tween (`rotateY: 0` on the card before tweening it to 360).
 - A tilted **group** foreshortens its whole subtree (cos folds into children). Clips project
   by the group's depth. A `fixed` HUD ignores depth (perspective is part of the camera).
+- **Depth of field** (needs `perspective`): add `camera.aperture` (blur px per unit depth) and
+  `camera.focus` (the in-focus `z`, default 0). A layer at depth `d` softens by
+  `aperture·|d − focus|` while the focal plane stays sharp; keyframe `focus` for a **rack focus**,
+  `aperture` for an iris pull. Absent/`0` ⇒ no blur. HUD/UI text should be `fixed` so it stays
+  crisp (a `fixed` node opts out of DOF too). It feeds the same `blur` op, so it composes with an
+  authored `blur`.
 - **Limits (honest):** `rotateX`/`rotateY` are an affine approximation (cos-foreshorten +
   keystone skew) — a single rotated quad is really a trapezoid Canvas 2D can't draw, so it
   reads as a flip/tilt, not a pixel-true 3D face (that needs WebGL). Depth positioning

package/package.json

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