reframe-video 0.6.8 → 0.6.9

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,6 +737,14 @@
       switch (node.type) {
         case "group": {
           const childClips = node.props.clip ? [...clips, { transform: matrix, shape: node.props.clip }] : clips;
+          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 });
+            return;
+          }
           for (const child of node.children) walk(child, matrix, opacity, childClips);
           return;
         }
@@ -918,7 +926,70 @@
     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;
+      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.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();
+    };
     for (const op of ops) {
+      if (op.type === "matte-push") {
+        stack.push({ mode: op.mode, parent: target(), matteCtx: newCtx(), phase: "matte" });
+        continue;
+      }
+      if (op.type === "matte-sep") {
+        const f = stack[stack.length - 1];
+        if (f) {
+          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,6 +3177,14 @@ function evaluate(compiled, t) {
     switch (node.type) {
       case "group": {
         const childClips = node.props.clip ? [...clips, { transform: matrix, shape: node.props.clip }] : clips;
+        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 });
+          return;
+        }
         for (const child of node.children) walk(child, matrix, opacity, childClips);
         return;
       }

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,70 @@ 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;
+    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.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();
+  };
   for (const op of ops) {
+    if (op.type === "matte-push") {
+      stack.push({ mode: op.mode, parent: target(), matteCtx: newCtx(), phase: "matte" });
+      continue;
+    }
+    if (op.type === "matte-sep") {
+      const f = stack[stack.length - 1];
+      if (f) {
+        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,13 @@ 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";
 });
 export type DisplayList = DisplayOp[];
 /**

package/dist/types/ir.d.ts

@@ -151,7 +151,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

@@ -348,6 +348,28 @@ 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`.
+
 ## 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.9",
   "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,10 @@ 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":
+      return []; // boundary markers have no geometry
   }
 }