reframe-video 0.6.8 → 0.6.10

package/dist/bin.js

@@ -391,6 +391,14 @@ function validateScene(ir) {
             problems.push(`group "${node.id}" clip: width and height must be > 0`);
           }
         }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
         collect(node.children);
       }
     }

package/dist/browserEntry.js

@@ -737,7 +737,18 @@
       switch (node.type) {
         case "group": {
           const childClips = node.props.clip ? [...clips, { transform: matrix, shape: node.props.clip }] : clips;
-          for (const child of node.children) walk(child, matrix, opacity, childClips);
+          const hasFx = fx.blur !== void 0 || fx.shadowColor !== void 0 || fx.blend !== void 0;
+          if (hasFx) ops.push({ type: "group-fx-push", id, transform: matrix, opacity, ...fx, ...clipSpread });
+          if (node.props.matte && node.children.length >= 2) {
+            ops.push({ type: "matte-push", id, transform: matrix, opacity, mode: node.props.matte, ...clipSpread });
+            walk(node.children[0], matrix, opacity, childClips);
+            ops.push({ type: "matte-sep", id, transform: matrix, opacity });
+            for (let i = 1; i < node.children.length; i++) walk(node.children[i], matrix, opacity, childClips);
+            ops.push({ type: "matte-pop", id, transform: matrix, opacity });
+          } else {
+            for (const child of node.children) walk(child, matrix, opacity, childClips);
+          }
+          if (hasFx) ops.push({ type: "group-fx-pop", id, transform: matrix, opacity });
           return;
         }
         case "rect":
@@ -918,7 +929,96 @@
     drawDisplayList(ctx2, evaluate(compiled2, t), images2, videos2);
   }
   function drawDisplayList(ctx2, ops, images2, videos2) {
+    const stack = [];
+    const target = () => {
+      const f = stack[stack.length - 1];
+      if (!f) return ctx2;
+      if (f.kind === "fx") return f.ctx;
+      return f.phase === "content" && f.contentCtx ? f.contentCtx : f.matteCtx;
+    };
+    const newCtx = () => {
+      const c = document.createElement("canvas");
+      c.width = ctx2.canvas.width;
+      c.height = ctx2.canvas.height;
+      return c.getContext("2d");
+    };
+    const composite = (f) => {
+      if (f.kind === "matte") {
+        if (!f.contentCtx) return;
+        if (f.mode === "luma") lumaToAlpha(f.matteCtx);
+        f.contentCtx.save();
+        f.contentCtx.setTransform(1, 0, 0, 1, 0, 0);
+        f.contentCtx.globalCompositeOperation = "destination-in";
+        f.contentCtx.drawImage(f.matteCtx.canvas, 0, 0);
+        f.contentCtx.restore();
+        f.parent.save();
+        f.parent.setTransform(1, 0, 0, 1, 0, 0);
+        f.parent.globalAlpha = 1;
+        f.parent.globalCompositeOperation = "source-over";
+        f.parent.filter = "none";
+        f.parent.drawImage(f.contentCtx.canvas, 0, 0);
+        f.parent.restore();
+        return;
+      }
+      f.parent.save();
+      f.parent.setTransform(1, 0, 0, 1, 0, 0);
+      f.parent.globalAlpha = 1;
+      f.parent.globalCompositeOperation = f.blend ? mapBlend(f.blend) : "source-over";
+      f.parent.filter = f.blur ? `blur(${f.blur}px)` : "none";
+      if (f.shadowColor) {
+        f.parent.shadowColor = f.shadowColor;
+        f.parent.shadowBlur = f.shadowBlur ?? 0;
+        f.parent.shadowOffsetX = f.shadowX ?? 0;
+        f.parent.shadowOffsetY = f.shadowY ?? 0;
+      }
+      f.parent.drawImage(f.ctx.canvas, 0, 0);
+      f.parent.restore();
+    };
     for (const op of ops) {
+      if (op.type === "group-fx-push") {
+        stack.push({ kind: "fx", parent: target(), ctx: newCtx(), blur: op.blur, shadowColor: op.shadowColor, shadowBlur: op.shadowBlur, shadowX: op.shadowX, shadowY: op.shadowY, blend: op.blend });
+        continue;
+      }
+      if (op.type === "group-fx-pop") {
+        const f = stack.pop();
+        if (f) composite(f);
+        continue;
+      }
+      if (op.type === "matte-push") {
+        stack.push({ kind: "matte", mode: op.mode, parent: target(), matteCtx: newCtx(), phase: "matte" });
+        continue;
+      }
+      if (op.type === "matte-sep") {
+        const f = stack[stack.length - 1];
+        if (f && f.kind === "matte") {
+          f.contentCtx = newCtx();
+          f.phase = "content";
+        }
+        continue;
+      }
+      if (op.type === "matte-pop") {
+        const f = stack.pop();
+        if (f) composite(f);
+        continue;
+      }
+      drawOp(target(), op, images2, videos2);
+    }
+    while (stack.length) composite(stack.pop());
+  }
+  function lumaToAlpha(ctx2) {
+    const { width, height } = ctx2.canvas;
+    if (width === 0 || height === 0) return;
+    const img = ctx2.getImageData(0, 0, width, height);
+    const d = img.data;
+    for (let i = 0; i < d.length; i += 4) {
+      const a = d[i + 3] / 255;
+      const luma = 0.2126 * d[i] + 0.7152 * d[i + 1] + 0.0722 * d[i + 2];
+      d[i + 3] = Math.round(luma * a);
+    }
+    ctx2.putImageData(img, 0, 0);
+  }
+  function drawOp(ctx2, op, images2, videos2) {
+    {
       ctx2.save();
       if (op.clips) {
         for (const clip of op.clips) {

package/dist/cli.js

@@ -405,6 +405,14 @@ function validateScene(ir) {
             problems.push(`group "${node.id}" clip: width and height must be > 0`);
           }
         }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
         collect(node.children);
       }
     }

package/dist/index.js

@@ -415,6 +415,14 @@ function validateScene(ir) {
             problems.push(`group "${node.id}" clip: width and height must be > 0`);
           }
         }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
         collect(node.children);
       }
     }
@@ -3169,7 +3177,18 @@ function evaluate(compiled, t) {
     switch (node.type) {
       case "group": {
         const childClips = node.props.clip ? [...clips, { transform: matrix, shape: node.props.clip }] : clips;
-        for (const child of node.children) walk(child, matrix, opacity, childClips);
+        const hasFx = fx.blur !== void 0 || fx.shadowColor !== void 0 || fx.blend !== void 0;
+        if (hasFx) ops.push({ type: "group-fx-push", id, transform: matrix, opacity, ...fx, ...clipSpread });
+        if (node.props.matte && node.children.length >= 2) {
+          ops.push({ type: "matte-push", id, transform: matrix, opacity, mode: node.props.matte, ...clipSpread });
+          walk(node.children[0], matrix, opacity, childClips);
+          ops.push({ type: "matte-sep", id, transform: matrix, opacity });
+          for (let i = 1; i < node.children.length; i++) walk(node.children[i], matrix, opacity, childClips);
+          ops.push({ type: "matte-pop", id, transform: matrix, opacity });
+        } else {
+          for (const child of node.children) walk(child, matrix, opacity, childClips);
+        }
+        if (hasFx) ops.push({ type: "group-fx-pop", id, transform: matrix, opacity });
         return;
       }
       case "rect":

package/dist/labels.js

@@ -399,6 +399,14 @@ function validateScene(ir) {
             problems.push(`group "${node.id}" clip: width and height must be > 0`);
           }
         }
+        const matte = node.props.matte;
+        if (matte !== void 0) {
+          if (matte !== "alpha" && matte !== "luma") {
+            problems.push(`group "${node.id}" matte: unknown mode "${String(matte)}" \u2014 use "alpha" or "luma"`);
+          } else if (node.children.length < 2) {
+            problems.push(`group "${node.id}" matte: needs \u22652 children (first masks the rest)`);
+          }
+        }
         collect(node.children);
       }
     }

package/dist/renderer-canvas.js

@@ -36,7 +36,96 @@ function renderFrame(ctx, compiled, t, images, videos) {
   drawDisplayList(ctx, evaluate(compiled, t), images, videos);
 }
 function drawDisplayList(ctx, ops, images, videos) {
+  const stack = [];
+  const target = () => {
+    const f = stack[stack.length - 1];
+    if (!f) return ctx;
+    if (f.kind === "fx") return f.ctx;
+    return f.phase === "content" && f.contentCtx ? f.contentCtx : f.matteCtx;
+  };
+  const newCtx = () => {
+    const c = document.createElement("canvas");
+    c.width = ctx.canvas.width;
+    c.height = ctx.canvas.height;
+    return c.getContext("2d");
+  };
+  const composite = (f) => {
+    if (f.kind === "matte") {
+      if (!f.contentCtx) return;
+      if (f.mode === "luma") lumaToAlpha(f.matteCtx);
+      f.contentCtx.save();
+      f.contentCtx.setTransform(1, 0, 0, 1, 0, 0);
+      f.contentCtx.globalCompositeOperation = "destination-in";
+      f.contentCtx.drawImage(f.matteCtx.canvas, 0, 0);
+      f.contentCtx.restore();
+      f.parent.save();
+      f.parent.setTransform(1, 0, 0, 1, 0, 0);
+      f.parent.globalAlpha = 1;
+      f.parent.globalCompositeOperation = "source-over";
+      f.parent.filter = "none";
+      f.parent.drawImage(f.contentCtx.canvas, 0, 0);
+      f.parent.restore();
+      return;
+    }
+    f.parent.save();
+    f.parent.setTransform(1, 0, 0, 1, 0, 0);
+    f.parent.globalAlpha = 1;
+    f.parent.globalCompositeOperation = f.blend ? mapBlend(f.blend) : "source-over";
+    f.parent.filter = f.blur ? `blur(${f.blur}px)` : "none";
+    if (f.shadowColor) {
+      f.parent.shadowColor = f.shadowColor;
+      f.parent.shadowBlur = f.shadowBlur ?? 0;
+      f.parent.shadowOffsetX = f.shadowX ?? 0;
+      f.parent.shadowOffsetY = f.shadowY ?? 0;
+    }
+    f.parent.drawImage(f.ctx.canvas, 0, 0);
+    f.parent.restore();
+  };
   for (const op of ops) {
+    if (op.type === "group-fx-push") {
+      stack.push({ kind: "fx", parent: target(), ctx: newCtx(), blur: op.blur, shadowColor: op.shadowColor, shadowBlur: op.shadowBlur, shadowX: op.shadowX, shadowY: op.shadowY, blend: op.blend });
+      continue;
+    }
+    if (op.type === "group-fx-pop") {
+      const f = stack.pop();
+      if (f) composite(f);
+      continue;
+    }
+    if (op.type === "matte-push") {
+      stack.push({ kind: "matte", mode: op.mode, parent: target(), matteCtx: newCtx(), phase: "matte" });
+      continue;
+    }
+    if (op.type === "matte-sep") {
+      const f = stack[stack.length - 1];
+      if (f && f.kind === "matte") {
+        f.contentCtx = newCtx();
+        f.phase = "content";
+      }
+      continue;
+    }
+    if (op.type === "matte-pop") {
+      const f = stack.pop();
+      if (f) composite(f);
+      continue;
+    }
+    drawOp(target(), op, images, videos);
+  }
+  while (stack.length) composite(stack.pop());
+}
+function lumaToAlpha(ctx) {
+  const { width, height } = ctx.canvas;
+  if (width === 0 || height === 0) return;
+  const img = ctx.getImageData(0, 0, width, height);
+  const d = img.data;
+  for (let i = 0; i < d.length; i += 4) {
+    const a = d[i + 3] / 255;
+    const luma = 0.2126 * d[i] + 0.7152 * d[i + 1] + 0.0722 * d[i + 2];
+    d[i + 3] = Math.round(luma * a);
+  }
+  ctx.putImageData(img, 0, 0);
+}
+function drawOp(ctx, op, images, videos) {
+  {
     ctx.save();
     if (op.clips) {
       for (const clip of op.clips) {

package/dist/types/evaluate.d.ts

@@ -4,7 +4,7 @@
  * always. Renderers only draw; they never compute animation.
  */
 import type { CompiledScene } from "./compile.js";
-import type { BlendMode, ClipShape, ImageFit, Paint, PropValue } from "./ir.js";
+import type { BlendMode, ClipShape, ImageFit, MatteMode, Paint, PropValue } from "./ir.js";
 /** Canvas-style 2D affine matrix [a, b, c, d, e, f]. */
 export type Mat2D = [number, number, number, number, number, number];
 /** A clip from an ancestor group: its shape in the group's coordinate space,
@@ -103,6 +103,17 @@ export type DisplayOp = (OpBase & {
     strokeWidth?: number;
     /** Local-space bbox [x,y,w,h] for mapping a gradient paint (set only when one is used). */
     bbox?: [number, number, number, number];
+}) | (OpBase & {
+    type: "matte-push";
+    mode: MatteMode;
+}) | (OpBase & {
+    type: "matte-sep";
+}) | (OpBase & {
+    type: "matte-pop";
+}) | (OpBase & {
+    type: "group-fx-push";
+}) | (OpBase & {
+    type: "group-fx-pop";
 });
 export type DisplayList = DisplayOp[];
 /**

package/dist/types/ir.d.ts

@@ -40,7 +40,8 @@ export interface BaseProps {
      * Paint effects (animatable scalars, in screen pixels — not transformed by the
      * node's rotation/scale or the camera, so a shadow keeps a consistent light
      * direction). `shadowColor` enables a drop shadow / outer glow (`glow`/`dropShadow`
-     * helpers). No-op on a `group` (use a child; group/composite blur is a later add).
+     * helpers). On a `group` these apply to the WHOLE subtree as one composite (the
+     * renderer renders it offscreen, then draws it back with the effect once).
      */
     blur?: number;
     shadowColor?: string;
@@ -48,7 +49,8 @@ export interface BaseProps {
     shadowX?: number;
     shadowY?: number;
     /** How this node composites with what's already drawn (default "normal"). `screen`/
-     *  `add` brighten (additive light/glow), `multiply` tints/deepens. No-op on a group. */
+     *  `add` brighten (additive light/glow), `multiply` tints/deepens. On a `group` the
+     *  whole subtree composites as one layer (offscreen) — true group blend. */
     blend?: BlendMode;
 }
 /** Compositing modes (Canvas `globalCompositeOperation`; `add` maps to `lighter`). */
@@ -151,7 +153,15 @@ export type ClipShape = {
 export interface GroupProps extends BaseProps {
     /** Clip the group's children to this shape (group-local coords). */
     clip?: ClipShape;
+    /**
+     * Track matte: the group's FIRST child masks the rest. `"alpha"` masks by the
+     * matte's alpha (e.g. video-filled text), `"luma"` by its luminance (e.g. a
+     * gradient wipe). Needs ≥2 children; the renderer composites it offscreen.
+     */
+    matte?: MatteMode;
 }
+/** Track-matte mode: mask the content by the matte's `alpha` or `luma`. */
+export type MatteMode = "alpha" | "luma";
 export interface PathProps extends BaseProps {
     /** SVG path data (the `d` attribute). Drawn as a true vector — crisp at any zoom. */
     d: string;

package/guides/edsl-guide.md

@@ -193,8 +193,8 @@ rect({ id: "card", /* … */, blur: 18 }); tween("card", { blur: 0 }, { duration
   something to animate from).
 - Sugar: `glow(color, blur)` (offset 0) and `dropShadow(color, blur, x, y)` return
   a partial you spread into props (`...glow("#FFD24B", 28)`); still animatable.
-- No-op on a `group` (apply to a child; group/composite blur is a later add). See
-  `examples/scenes/shadow-demo.ts`.
+- On a `group` these apply to the whole subtree as one composite (focus pull / one
+  silhouette shadow) — see "Group effects" below. `examples/scenes/shadow-demo.ts`.
 
 ### Blend modes (compositing)
 
@@ -210,8 +210,8 @@ rect({ id: "neon", fill: linearGradient([...]), shadowColor: "#7A4DFF", blend: "
 - Modes: `normal` (default), `multiply`, `screen`, `overlay`, `lighten`, `darken`,
   `add` (additive light), `color-dodge`, `soft-light`, `hard-light`, `difference`.
 - **Discrete**, not interpolated — set per node (a static string). Default `normal`.
-- Per-shape. A whole-group blend (composite the subtree, then blend) is a later add;
-  on a `group` the prop is a no-op. See `examples/scenes/blend-demo.ts`.
+- Per-shape, or on a `group` to blend the whole composited subtree against the bg as one
+  layer (see "Group effects" below). See `examples/scenes/blend-demo.ts`.
 
 ## Character rig (skeleton, poses, IK)
 
@@ -348,6 +348,50 @@ tween("clip", { scale: 1.08 }, { duration: 5 })  // transform composes with play
   sources are not rendered in `reframe player` / artifacts (mp4 only). See
   `examples/scenes/video-demo.ts`.
 
+## Track mattes (`group({ matte })`)
+
+Use one layer's alpha or luminance to mask another — video-filled text, shape /
+PNG punch-through, luma wipes. In a **matte group the FIRST child is the matte**;
+the remaining children are the masked content.
+
+```ts
+// the clip shows ONLY inside the letters (alpha matte)
+group({ id: "reveal", x: W/2, y: H/2, anchor: "center", matte: "alpha" }, [
+  text({ id: "mask", x: 0, y: 0, anchor: "center", content: "PLAY", fontSize: 300, fontWeight: 800, fill: "#fff" }),
+  video({ id: "clip", x: 0, y: 0, width: W, height: H, anchor: "center", fit: "cover", src: "shot.mp4" }),
+])
+```
+
+- `matte: "alpha"` keeps content where the matte is opaque; `"luma"` where it's bright
+  (animate a gradient/shape as the matte for a wipe). Needs ≥2 children.
+- The group's transform / opacity / clip apply as usual (a centered group scales about
+  its middle; fading the group fades the masked result). Mattes can nest.
+- Rendered by **offscreen compositing** (the matte + content draw to separate buffers,
+  combined via `destination-in`). Deterministic same-machine. See
+  `examples/scenes/matte-demo.ts`.
+
+## Group effects (blur / shadow / blend on a whole group)
+
+The paint effects (`blur`, `shadowColor`/`shadowBlur`/`shadowX`/`shadowY`, `blend`) also
+work on a **group** — there they apply to the whole subtree as ONE composite layer, not per
+child. The classic uses: a depth-of-field **focus pull** on a multi-node lockup, a single
+**silhouette drop shadow** under a multi-shape mark, and a group that **blends against the
+background** as one layer (so its own overlaps composite together).
+
+```ts
+// the whole lockup sharpens as one image (animate the GROUP's blur)
+group({ id: "lockup", x: 0, y: 0, blur: 20 }, [ card, dot, label ])
+// timeline: tween("lockup", { blur: 0 }, { duration: 1.1, ease: "easeInOutCubic" })
+
+group({ id: "mark", x: 0, y: 0, ...dropShadow("#000", 40, 0, 26) }, [ shapeA, shapeB, dot ]) // one shadow
+group({ id: "burst", x, y, blend: "screen" }, [ disc1, disc2, disc3 ])                        // one screen layer
+```
+
+- Group `blur` is **animatable** (`tween(group, { blur })`); shadow scalars too.
+- Same **offscreen compositing** as mattes (the subtree renders to a buffer, drawn back once
+  with the effect). It wraps a matte group and nests. The effects are screen-pixel space.
+  See `examples/scenes/group-fx-demo.ts`.
+
 ## Cursor (UI demos)
 
 A vector mouse pointer that glides across the scene and clicks things — for app

package/package.json

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

package/preview/src/main.ts

@@ -573,6 +573,12 @@ function opCorners(op: DisplayOp): [number, number][] {
     case "path":
       // No cheap bbox for an arbitrary `d`; mark the origin for selection.
       return [applyMat(op.transform, 0, 0)];
+    case "matte-push":
+    case "matte-sep":
+    case "matte-pop":
+    case "group-fx-push":
+    case "group-fx-pop":
+      return []; // boundary markers have no geometry
   }
 }