reframe-video 0.6.16 → 0.6.18

package/dist/bin.js

@@ -327,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),
@@ -338,7 +339,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 var key;
@@ -544,8 +546,10 @@ 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) {
@@ -574,6 +578,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -640,7 +653,7 @@ var init_validate = __esm({
       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"],
+      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
     };
@@ -1247,7 +1260,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -1289,6 +1302,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1981,6 +1997,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -2009,7 +2029,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -2017,6 +2044,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);

package/dist/browserEntry.js

@@ -324,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),
@@ -335,7 +336,8 @@
       labelTimes,
       beatTimes,
       hasCamera,
-      hasPerspective
+      hasPerspective,
+      zSort
     };
   }
 
@@ -348,7 +350,7 @@
     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"],
+    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
   };
@@ -750,6 +752,9 @@
       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;
@@ -824,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;
@@ -966,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

@@ -314,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),
@@ -325,7 +326,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -353,7 +355,7 @@ var PROPS_BY_TYPE = {
   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"],
+  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
 };
@@ -558,8 +560,10 @@ 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) {
@@ -588,6 +592,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -915,7 +928,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -957,6 +970,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1034,6 +1050,9 @@ function resolveCompositionAudioPlan(comp) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -1453,6 +1472,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -1481,7 +1504,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -1489,6 +1519,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);

package/dist/diff.js

@@ -320,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),
@@ -331,7 +332,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -359,7 +361,7 @@ var PROPS_BY_TYPE = {
   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"],
+  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
 };
@@ -564,8 +566,10 @@ 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) {
@@ -594,6 +598,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {

package/dist/index.js

@@ -324,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),
@@ -335,7 +336,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -363,7 +365,7 @@ var PROPS_BY_TYPE = {
   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"],
+  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
 };
@@ -568,8 +570,10 @@ 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) {
@@ -598,6 +602,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -2686,7 +2699,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -2728,6 +2741,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -2805,6 +2821,9 @@ function resolveCompositionAudioPlan(comp) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      fadeIn: cue.fadeIn ?? 0,
+      fadeOut: cue.fadeOut ?? 0,
+      pan: cue.pan ?? 0,
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
@@ -3226,6 +3245,9 @@ function evaluate(compiled, t) {
     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;
@@ -3300,7 +3322,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;
@@ -3442,7 +3465,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

@@ -308,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),
@@ -319,7 +320,8 @@ function compileScene(ir) {
     labelTimes,
     beatTimes,
     hasCamera,
-    hasPerspective
+    hasPerspective,
+    zSort
   };
 }
 
@@ -347,7 +349,7 @@ var PROPS_BY_TYPE = {
   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"],
+  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
 };
@@ -552,8 +554,10 @@ 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) {
@@ -582,6 +586,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {

package/dist/trace-cli.js

@@ -14,7 +14,7 @@ var PROPS_BY_TYPE = {
   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"],
+  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
 };

package/dist/types/audio.d.ts

@@ -15,6 +15,12 @@ export interface ResolvedCue {
     t: number;
     gain: number;
     duration: number;
+    /** Fade in over N seconds from the cue start (0 = none). */
+    fadeIn: number;
+    /** Fade out over N seconds before the cue end (0 = none). */
+    fadeOut: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
     source: {
         kind: "sfx";
         name: SfxName;
@@ -36,6 +42,10 @@ export interface ClipAudio {
     clipStart: number;
     /** Linear gain. */
     gain: number;
+    /** Fade in over N seconds from the clip's `start` (0 = none). */
+    fadeIn: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
 }
 export interface AudioPlan {
     duration: number;

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

@@ -256,6 +256,10 @@ export interface VideoProps extends BaseProps {
      * (trimmed from `clipStart`, sped by `rate`). Default 1; `0` mutes the clip.
      */
     volume?: number;
+    /** Fade the clip audio in over N seconds from `start` (default 0 = hard in). */
+    fadeIn?: number;
+    /** Stereo balance for the clip audio: -1 full left, 0 centre, +1 full right. */
+    pan?: number;
 }
 export type NodeIR = {
     type: "rect";
@@ -420,6 +424,12 @@ export interface AudioCueIR {
     file?: string;
     /** Linear gain, default 1. */
     gain?: number;
+    /** Fade the cue in over N seconds from its start (default 0 = hard in). */
+    fadeIn?: number;
+    /** Fade the cue out over N seconds before its end (default 0 = hard out). */
+    fadeOut?: number;
+    /** Stereo balance: -1 full left, 0 centre (default), +1 full right. */
+    pan?: number;
     /** Synth parameter overrides (seed, duration, …) — numbers only. */
     params?: Record<string, number>;
 }
@@ -472,6 +482,14 @@ export interface CameraIR {
      */
     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

@@ -221,11 +221,17 @@ scene({
   `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`.
 
@@ -504,15 +510,19 @@ Label-anchored sound design — cues follow retiming and regeneration:
 audio: {
   bgm: { synth: "ambient-pad", gain: 0.3, fadeIn: 1, fadeOut: 2, duck: { depth: 0.5 } },
   cues: [
-    { at: "enter", sfx: "whoosh", gain: 0.8 },          // anchored to a timeline label
-    { at: "enter", offset: 0.2, sfx: "pop" },
-    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },   // absolute seconds; file from assets/sfx/
+    { at: "enter", sfx: "whoosh", gain: 0.8, pan: -0.6 },     // anchored to a label; panned left
+    { at: "enter", offset: 0.2, sfx: "pop", fadeIn: 0.05, fadeOut: 0.1 },
+    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },         // absolute seconds; file from assets/sfx/
   ],
 }
 ```
 
 Procedural sfx names: `whoosh` `pop` `tick` `rise` `shimmer` `thud` (deterministic,
 seedable via `params: { seed }`). Exactly one of `sfx`/`file` per cue.
+**Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan` (-1 left … 0 centre …
++1 right). A `video` clip's audio takes `fadeIn` and `pan` too (clip fade-out isn't
+supported yet — a clip has no fixed length in the plan). The bed auto-ducks under cues
+(`bgm.duck`).
 
 ## Rules
 

package/package.json

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