reframe-video 0.6.15 → 0.6.17

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();
@@ -325,6 +327,7 @@ function compileScene(ir) {
   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"));
+  const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
   return {
     ir,
     duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -336,7 +339,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 var key;
@@ -542,12 +546,16 @@ function validateScene(ir) {
       problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
     }
     for (const [key2, value] of Object.entries(ir.camera)) {
-      if (!CAMERA_PROPS.includes(key2)) {
-        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      if (key2 === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
       } else if (typeof value !== "number") {
         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 +637,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"],

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();
@@ -322,6 +324,7 @@
     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"));
+    const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
     return {
       ir,
       duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -333,7 +336,8 @@
       labelTimes,
       beatTimes,
       hasCamera,
-      hasPerspective
+      hasPerspective,
+      zSort
     };
   }
 
@@ -740,6 +744,17 @@
     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 zSort = compiled2.zSort;
+    const depthOf = (node, zAcc) => zAcc + num(node.id, "z", node.props.z ?? 0);
+    const depthOrder = (children, zAcc) => [...children].sort((a, b) => depthOf(b, zAcc) - depthOf(a, zAcc));
     const walk = (node, parent, parentOpacity, clips, zAcc, project) => {
       const id = node.id;
       const clipSpread = clips.length > 0 ? { clips } : void 0;
@@ -762,7 +777,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;
@@ -799,6 +815,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);
@@ -812,7 +829,8 @@
             for (let i = 1; i < node.children.length; i++) walk(node.children[i], matrix, opacity, childClips, depth, project);
             ops.push({ type: "matte-pop", id, transform: matrix, opacity });
           } else {
-            for (const child of node.children) walk(child, matrix, opacity, childClips, depth, project);
+            const kids = zSort && project ? depthOrder(node.children, depth) : node.children;
+            for (const child of kids) walk(child, matrix, opacity, childClips, depth, project);
           }
           if (hasFx) ops.push({ type: "group-fx-pop", id, transform: matrix, opacity });
           return;
@@ -839,7 +857,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;
@@ -859,7 +877,7 @@
             offsetX: -width * ax,
             offsetY: -height * ay,
             ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -886,7 +904,7 @@
             offsetY: -height * ay,
             frame,
             ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -911,7 +929,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;
@@ -938,7 +956,7 @@
             letterSpacing: num(id, "letterSpacing", node.props.letterSpacing ?? 0),
             align: TEXT_ALIGN[ax] ?? "left",
             baseline: TEXT_BASELINE[ay] ?? "top",
-            ...fx,
+            ...leafFx,
             ...clipSpread
           });
           return;
@@ -954,7 +972,12 @@
       },
       compiled2.ir.size
     ) : IDENTITY;
-    for (const node of compiled2.ir.nodes) {
+    let roots = compiled2.ir.nodes;
+    if (zSort) {
+      const isHud = (n) => !!(n.props.fixed && compiled2.hasCamera);
+      roots = [...depthOrder(compiled2.ir.nodes.filter((n) => !isHud(n)), 0), ...compiled2.ir.nodes.filter(isHud)];
+    }
+    for (const node of roots) {
       const root = compiled2.hasCamera && node.props.fixed ? IDENTITY : cameraRoot;
       const project = persp && !(node.props.fixed && compiled2.hasCamera);
       walk(node, root, 1, [], 0, project);

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();
@@ -312,6 +314,7 @@ function compileScene(ir) {
   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"));
+  const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
   return {
     ir,
     duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -323,7 +326,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -344,7 +348,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,12 +560,16 @@ function validateScene(ir) {
       problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
     }
     for (const [key2, value] of Object.entries(ir.camera)) {
-      if (!CAMERA_PROPS.includes(key2)) {
-        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      if (key2 === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
       } else if (typeof value !== "number") {
         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`);
       }
     }
   }

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();
@@ -318,6 +320,7 @@ function compileScene(ir) {
   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"));
+  const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
   return {
     ir,
     duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -329,7 +332,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -350,7 +354,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,12 +566,16 @@ function validateScene(ir) {
       problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
     }
     for (const [key2, value] of Object.entries(ir.camera)) {
-      if (!CAMERA_PROPS.includes(key2)) {
-        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      if (key2 === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
       } else if (typeof value !== "number") {
         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`);
       }
     }
   }

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();
@@ -322,6 +324,7 @@ function compileScene(ir) {
   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"));
+  const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
   return {
     ir,
     duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -333,7 +336,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -354,7 +358,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"],
@@ -566,12 +570,16 @@ function validateScene(ir) {
       problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
     }
     for (const [key2, value] of Object.entries(ir.camera)) {
-      if (!CAMERA_PROPS.includes(key2)) {
-        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      if (key2 === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
       } else if (typeof value !== "number") {
         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`);
       }
     }
   }
@@ -3214,6 +3222,17 @@ 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 zSort = compiled.zSort;
+  const depthOf = (node, zAcc) => zAcc + num(node.id, "z", node.props.z ?? 0);
+  const depthOrder = (children, zAcc) => [...children].sort((a, b) => depthOf(b, zAcc) - depthOf(a, zAcc));
   const walk = (node, parent, parentOpacity, clips, zAcc, project) => {
     const id = node.id;
     const clipSpread = clips.length > 0 ? { clips } : void 0;
@@ -3236,7 +3255,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;
@@ -3273,6 +3293,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);
@@ -3286,7 +3307,8 @@ function evaluate(compiled, t) {
           for (let i = 1; i < node.children.length; i++) walk(node.children[i], matrix, opacity, childClips, depth, project);
           ops.push({ type: "matte-pop", id, transform: matrix, opacity });
         } else {
-          for (const child of node.children) walk(child, matrix, opacity, childClips, depth, project);
+          const kids = zSort && project ? depthOrder(node.children, depth) : node.children;
+          for (const child of kids) walk(child, matrix, opacity, childClips, depth, project);
         }
         if (hasFx) ops.push({ type: "group-fx-pop", id, transform: matrix, opacity });
         return;
@@ -3313,7 +3335,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;
@@ -3333,7 +3355,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;
@@ -3360,7 +3382,7 @@ function evaluate(compiled, t) {
           offsetY: -height * ay,
           frame,
           ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
-          ...fx,
+          ...leafFx,
           ...clipSpread
         });
         return;
@@ -3385,7 +3407,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;
@@ -3412,7 +3434,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;
@@ -3428,7 +3450,12 @@ function evaluate(compiled, t) {
     },
     compiled.ir.size
   ) : IDENTITY;
-  for (const node of compiled.ir.nodes) {
+  let roots = compiled.ir.nodes;
+  if (zSort) {
+    const isHud = (n3) => !!(n3.props.fixed && compiled.hasCamera);
+    roots = [...depthOrder(compiled.ir.nodes.filter((n3) => !isHud(n3)), 0), ...compiled.ir.nodes.filter(isHud)];
+  }
+  for (const node of roots) {
     const root = compiled.hasCamera && node.props.fixed ? IDENTITY : cameraRoot;
     const project = persp && !(node.props.fixed && compiled.hasCamera);
     walk(node, root, 1, [], 0, project);

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();
@@ -306,6 +308,7 @@ function compileScene(ir) {
   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"));
+  const zSort = !cameraIsNode && ir.camera?.zSort === true && hasPerspective;
   return {
     ir,
     duration: ir.duration ?? (inferredEnd > 0 ? inferredEnd : DEFAULT_STILL_DURATION),
@@ -317,7 +320,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -338,7 +342,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"],
@@ -550,12 +554,16 @@ function validateScene(ir) {
       problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
     }
     for (const [key2, value] of Object.entries(ir.camera)) {
-      if (!CAMERA_PROPS.includes(key2)) {
-        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      if (key2 === "zSort") {
+        if (typeof value !== "boolean") problems.push(`camera.zSort must be a boolean`);
+      } else if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}, zSort`);
       } else if (typeof value !== "number") {
         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`);
       }
     }
   }

package/dist/types/compile.d.ts

@@ -53,5 +53,7 @@ export interface CompiledScene {
     hasCamera: boolean;
     /** True iff the scene sets/animates `camera.perspective` (gates depth projection). */
     hasPerspective: boolean;
+    /** True iff `camera.zSort` is on (gates depth-ordered paint; needs perspective). */
+    zSort: boolean;
 }
 export declare function compileScene(ir: SceneIR): CompiledScene;

package/dist/types/ir.d.ts

@@ -461,6 +461,25 @@ 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;
+    /**
+     * Paint order by depth (requires `perspective`). Off by default — drawing stays
+     * array order. When `true`, siblings at each level are drawn far-to-near (larger
+     * world `z` first) so nearer nodes occlude farther ones without hand-ordering the
+     * tree. A `fixed` HUD stays on top; a track-matte group keeps its child order (the
+     * first child is the mask). Discrete flag, not animatable.
+     */
+    zSort?: boolean;
 }
 export interface SceneIR {
     version: 1;

package/guides/edsl-guide.md

@@ -215,11 +215,23 @@ 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`.
+- **Occlusion by depth** is opt-in: set `camera.zSort: true` and siblings paint far→near
+  (larger `z` first) so nearer nodes cover farther ones without hand-ordering the tree (a
+  `fixed` HUD stays on top; a track-matte group keeps its child order). Off by default — paint
+  stays array order. Gotcha: with `zSort`, a full-screen background rect at `z: 0` is the
+  NEAREST plane and paints on top — use the scene `background` color instead, or give the
+  backdrop a large `z`.
 - **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
-  (parallax, convergence, dolly) IS exact. `z` does NOT reorder drawing — paint stays array
-  order, so order your nodes back-to-front yourself. No GPU 3D, no z-buffer.
+  (parallax, convergence, dolly) IS exact. No GPU 3D, no z-buffer (per-pixel) — `zSort` orders
+  whole nodes, so two INTERSECTING planes can't visually cross.
 
 See `examples/scenes/perspective-cards.ts`.
 

package/package.json

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