reframe-video 0.6.0 → 0.6.2

package/dist/bin.js

@@ -349,12 +349,36 @@ var init_compile = __esm({
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
   const collect = (nodes) => {
     for (const node of nodes) {
       if (nodeById.has(node.id)) {
         problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
       }
       nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -569,16 +593,17 @@ function validateComposition(comp) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
-var COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
+var FX_PROPS, COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
 var init_validate = __esm({
   "../core/src/validate.ts"() {
     "use strict";
-    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+    FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
     CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
     PROPS_BY_TYPE = {
       rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-      line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+      line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
       text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
       image: [...COMMON_PROPS, "src", "width", "height"],
       path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -899,6 +924,20 @@ var init_camera = __esm({
   }
 });
 
+// ../core/src/gradient.ts
+var init_gradient = __esm({
+  "../core/src/gradient.ts"() {
+    "use strict";
+  }
+});
+
+// ../core/src/effects.ts
+var init_effects = __esm({
+  "../core/src/effects.ts"() {
+    "use strict";
+  }
+});
+
 // ../core/src/presets.ts
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
@@ -1292,6 +1331,7 @@ var init_evaluate = __esm({
     "use strict";
     init_behaviors();
     init_camera();
+    init_gradient();
     init_interpolate();
     init_path();
   }
@@ -1354,6 +1394,8 @@ var init_src = __esm({
     init_compile();
     init_path();
     init_camera();
+    init_gradient();
+    init_effects();
     init_presets();
     init_devicePreset();
     init_cursor();

package/dist/browserEntry.js

@@ -6,6 +6,22 @@
   var DEFAULT_MOTIONPATH_DURATION = 1;
 
   // ../core/src/path.ts
+  function pathBBox(d) {
+    const nums = d.match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi);
+    if (!nums || nums.length < 2) return [0, 0, 1, 1];
+    let minx = Infinity, miny = Infinity, maxx = -Infinity, maxy = -Infinity;
+    for (let i = 0; i + 1 < nums.length; i += 2) {
+      const x = parseFloat(nums[i]);
+      const y = parseFloat(nums[i + 1]);
+      if (x < minx) minx = x;
+      if (x > maxx) maxx = x;
+      if (y < miny) miny = y;
+      if (y > maxy) maxy = y;
+    }
+    const w = maxx - minx;
+    const h = maxy - miny;
+    return [minx, miny, w > 0 ? w : 1, h > 0 ? h : 1];
+  }
   function locate(segCount, u) {
     if (segCount <= 0) return { i: 0, t: 0 };
     const clamped = Math.max(0, Math.min(1, u));
@@ -318,11 +334,12 @@
   }
 
   // ../core/src/validate.ts
-  var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+  var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+  var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
   var PROPS_BY_TYPE = {
     rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
     ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-    line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+    line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
     text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
     image: [...COMMON_PROPS, "src", "width", "height"],
     path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -344,6 +361,11 @@
     return [a, b, c, d, W / 2 - a * x - c * y, H / 2 - b * x - d * y];
   }
 
+  // ../core/src/gradient.ts
+  function isGradient(p) {
+    return typeof p === "object" && p !== null && (p.kind === "linear" || p.kind === "radial" || p.kind === "conic");
+  }
+
   // ../core/src/presets.ts
   var SET = 1 / 120;
 
@@ -658,9 +680,21 @@
       const v = valueAt(target, prop, base ?? "");
       return v === "" && base === void 0 ? void 0 : String(v);
     };
+    const effectFx = (id, p) => {
+      const fx = {};
+      if (p.blur !== void 0) fx.blur = num(id, "blur", p.blur);
+      if (p.shadowColor !== void 0) {
+        fx.shadowColor = str(id, "shadowColor", p.shadowColor);
+        fx.shadowBlur = num(id, "shadowBlur", p.shadowBlur ?? 0);
+        fx.shadowX = num(id, "shadowX", p.shadowX ?? 0);
+        fx.shadowY = num(id, "shadowY", p.shadowY ?? 0);
+      }
+      return fx;
+    };
     const walk = (node, parent, parentOpacity, clips) => {
       const id = node.id;
       const clipSpread = clips.length > 0 ? { clips } : void 0;
+      const fx = effectFx(id, node.props);
       if (node.type === "line") {
         const opacity2 = parentOpacity * num(id, "opacity", node.props.opacity ?? 1);
         if (opacity2 <= 0) return;
@@ -678,6 +712,7 @@
           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,
           ...clipSpread
         });
         return;
@@ -709,8 +744,10 @@
           const height = num(id, "height", node.props.height);
           const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
           const strokeWidth = num(id, "strokeWidth", node.props.strokeWidth ?? 1);
-          const fill = opt(id, "fill", node.props.fill);
-          const stroke = opt(id, "stroke", node.props.stroke);
+          const fillP = node.props.fill;
+          const strokeP = node.props.stroke;
+          const fill = isGradient(fillP) ? fillP : opt(id, "fill", fillP);
+          const stroke = isGradient(strokeP) ? strokeP : opt(id, "stroke", strokeP);
           ops.push({
             type: node.type,
             id,
@@ -723,6 +760,7 @@
             ...fill !== void 0 && { fill },
             ...stroke !== void 0 && { stroke, strokeWidth },
             ...node.type === "rect" && { radius: num(id, "radius", node.props.radius ?? 0) },
+            ...fx,
             ...clipSpread
           });
           return;
@@ -741,6 +779,7 @@
             height,
             offsetX: -width * ax,
             offsetY: -height * ay,
+            ...fx,
             ...clipSpread
           });
           return;
@@ -748,17 +787,23 @@
         case "path": {
           const ox = num(id, "originX", node.props.originX ?? 0);
           const oy = num(id, "originY", node.props.originY ?? 0);
-          const fill = opt(id, "fill", node.props.fill);
-          const stroke = opt(id, "stroke", node.props.stroke);
+          const fillP = node.props.fill;
+          const strokeP = node.props.stroke;
+          const fill = isGradient(fillP) ? fillP : opt(id, "fill", fillP);
+          const stroke = isGradient(strokeP) ? strokeP : opt(id, "stroke", strokeP);
+          const dStr = str(id, "d", node.props.d);
+          const needsBox = isGradient(fill) || isGradient(stroke);
           ops.push({
             type: "path",
             id,
             transform: ox === 0 && oy === 0 ? matrix : multiply(matrix, [1, 0, 0, 1, -ox, -oy]),
             opacity,
-            d: str(id, "d", node.props.d),
+            d: dStr,
             progress: Math.max(0, Math.min(1, num(id, "progress", node.props.progress ?? 1))),
             ...fill !== void 0 && { fill },
             ...stroke !== void 0 && { stroke, strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1) },
+            ...needsBox && { bbox: pathBBox(dStr) },
+            ...fx,
             ...clipSpread
           });
           return;
@@ -783,6 +828,7 @@
             letterSpacing: num(id, "letterSpacing", node.props.letterSpacing ?? 0),
             align: TEXT_ALIGN[ax] ?? "left",
             baseline: TEXT_BASELINE[ay] ?? "top",
+            ...fx,
             ...clipSpread
           });
           return;
@@ -806,6 +852,31 @@
   }
 
   // ../renderer-canvas/src/index.ts
+  function resolvePaint(ctx2, paint, box) {
+    if (typeof paint === "string") return paint;
+    const { x, y, w, h } = box;
+    let g;
+    if (paint.kind === "linear") {
+      const a = (paint.angle ?? 0) * Math.PI / 180;
+      const dx = Math.cos(a);
+      const dy = Math.sin(a);
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      const half = Math.abs(dx) * (w / 2) + Math.abs(dy) * (h / 2);
+      g = ctx2.createLinearGradient(cx - dx * half, cy - dy * half, cx + dx * half, cy + dy * half);
+    } else if (paint.kind === "radial") {
+      const cx = x + (paint.cx ?? 0.5) * w;
+      const cy = y + (paint.cy ?? 0.5) * h;
+      const r = Math.max((paint.r ?? 0.5) * Math.max(w, h), 1e-4);
+      g = ctx2.createRadialGradient(cx, cy, 0, cx, cy, r);
+    } else {
+      const cx = x + (paint.cx ?? 0.5) * w;
+      const cy = y + (paint.cy ?? 0.5) * h;
+      g = ctx2.createConicGradient((paint.angle ?? 0) * Math.PI / 180, cx, cy);
+    }
+    for (const s of paint.stops) g.addColorStop(Math.max(0, Math.min(1, s.offset)), s.color);
+    return g;
+  }
   function renderFrame(ctx2, compiled2, t, images2) {
     const { size, background } = compiled2.ir;
     ctx2.setTransform(1, 0, 0, 1, 0, 0);
@@ -836,8 +907,16 @@
       }
       ctx2.setTransform(...op.transform);
       ctx2.globalAlpha = Math.max(0, Math.min(1, op.opacity));
+      if (op.blur) ctx2.filter = `blur(${op.blur}px)`;
+      if (op.shadowColor) {
+        ctx2.shadowColor = op.shadowColor;
+        ctx2.shadowBlur = op.shadowBlur ?? 0;
+        ctx2.shadowOffsetX = op.shadowX ?? 0;
+        ctx2.shadowOffsetY = op.shadowY ?? 0;
+      }
       switch (op.type) {
         case "rect": {
+          const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
           ctx2.beginPath();
           if (op.radius && op.radius > 0) {
             ctx2.roundRect(op.offsetX, op.offsetY, op.width, op.height, op.radius);
@@ -845,17 +924,18 @@
             ctx2.rect(op.offsetX, op.offsetY, op.width, op.height);
           }
           if (op.fill) {
-            ctx2.fillStyle = op.fill;
+            ctx2.fillStyle = resolvePaint(ctx2, op.fill, box);
             ctx2.fill();
           }
           if (op.stroke) {
-            ctx2.strokeStyle = op.stroke;
+            ctx2.strokeStyle = resolvePaint(ctx2, op.stroke, box);
             ctx2.lineWidth = op.strokeWidth ?? 1;
             ctx2.stroke();
           }
           break;
         }
         case "ellipse": {
+          const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
           ctx2.beginPath();
           ctx2.ellipse(
             op.offsetX + op.width / 2,
@@ -867,11 +947,11 @@
             Math.PI * 2
           );
           if (op.fill) {
-            ctx2.fillStyle = op.fill;
+            ctx2.fillStyle = resolvePaint(ctx2, op.fill, box);
             ctx2.fill();
           }
           if (op.stroke) {
-            ctx2.strokeStyle = op.stroke;
+            ctx2.strokeStyle = resolvePaint(ctx2, op.stroke, box);
             ctx2.lineWidth = op.strokeWidth ?? 1;
             ctx2.stroke();
           }
@@ -908,12 +988,13 @@
         }
         case "path": {
           const p = new Path2D(op.d);
+          const box = op.bbox ? { x: op.bbox[0], y: op.bbox[1], w: op.bbox[2], h: op.bbox[3] } : { x: 0, y: 0, w: 1, h: 1 };
           if (op.fill) {
-            ctx2.fillStyle = op.fill;
+            ctx2.fillStyle = resolvePaint(ctx2, op.fill, box);
             ctx2.fill(p);
           }
           if (op.stroke && (op.strokeWidth ?? 1) > 0) {
-            ctx2.strokeStyle = op.stroke;
+            ctx2.strokeStyle = resolvePaint(ctx2, op.stroke, box);
             ctx2.lineWidth = op.strokeWidth ?? 1;
             ctx2.lineJoin = "round";
             ctx2.lineCap = "round";

package/dist/cli.js

@@ -324,12 +324,13 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -347,12 +348,36 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
   const collect = (nodes) => {
     for (const node of nodes) {
       if (nodeById.has(node.id)) {
         problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
       }
       nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/index.js

@@ -6,6 +6,22 @@ var DEFAULT_MOTIONPATH_DURATION = 1;
 var DEFAULT_FPS = 30;
 
 // ../core/src/path.ts
+function pathBBox(d) {
+  const nums = d.match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi);
+  if (!nums || nums.length < 2) return [0, 0, 1, 1];
+  let minx = Infinity, miny = Infinity, maxx = -Infinity, maxy = -Infinity;
+  for (let i = 0; i + 1 < nums.length; i += 2) {
+    const x = parseFloat(nums[i]);
+    const y = parseFloat(nums[i + 1]);
+    if (x < minx) minx = x;
+    if (x > maxx) maxx = x;
+    if (y < miny) miny = y;
+    if (y > maxy) maxy = y;
+  }
+  const w = maxx - minx;
+  const h = maxy - miny;
+  return [minx, miny, w > 0 ? w : 1, h > 0 ? h : 1];
+}
 function locate(segCount, u) {
   if (segCount <= 0) return { i: 0, t: 0 };
   const clamped = Math.max(0, Math.min(1, u));
@@ -318,12 +334,13 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -341,12 +358,36 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
   const collect = (nodes) => {
     for (const node of nodes) {
       if (nodeById.has(node.id)) {
         problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
       }
       nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -917,6 +958,46 @@ function cameraTo(props, opts = {}) {
   return tween(CAMERA_ID, props, opts);
 }
 
+// ../core/src/gradient.ts
+function isGradient(p) {
+  return typeof p === "object" && p !== null && (p.kind === "linear" || p.kind === "radial" || p.kind === "conic");
+}
+function toStops(stops) {
+  if (stops.length > 0 && typeof stops[0] === "object") return stops;
+  const cs = stops;
+  const n3 = cs.length;
+  return cs.map((color, i) => ({ offset: n3 <= 1 ? 0 : i / (n3 - 1), color }));
+}
+function linearGradient(stops, opts = {}) {
+  return { kind: "linear", ...opts.angle !== void 0 && { angle: opts.angle }, stops: toStops(stops) };
+}
+function radialGradient(stops, opts = {}) {
+  return {
+    kind: "radial",
+    ...opts.cx !== void 0 && { cx: opts.cx },
+    ...opts.cy !== void 0 && { cy: opts.cy },
+    ...opts.r !== void 0 && { r: opts.r },
+    stops: toStops(stops)
+  };
+}
+function conicGradient(stops, opts = {}) {
+  return {
+    kind: "conic",
+    ...opts.angle !== void 0 && { angle: opts.angle },
+    ...opts.cx !== void 0 && { cx: opts.cx },
+    ...opts.cy !== void 0 && { cy: opts.cy },
+    stops: toStops(stops)
+  };
+}
+
+// ../core/src/effects.ts
+function glow(color, blur = 24) {
+  return { shadowColor: color, shadowBlur: blur, shadowX: 0, shadowY: 0 };
+}
+function dropShadow(color, blur = 24, x = 0, y = 12) {
+  return { shadowColor: color, shadowBlur: blur, shadowX: x, shadowY: y };
+}
+
 // ../core/src/presets.ts
 var PRESET_NAMES = [
   "draw-bloom",
@@ -1456,11 +1537,11 @@ function ikReach(upper, lower, dx, dy, flip = false) {
 function humanoid(opts = {}) {
   const line2 = opts.color ?? DEFAULT_LINE;
   const fill = opts.fill ?? DEFAULT_FILL;
-  const glow = opts.glow;
+  const glow2 = opts.glow;
   const blob = (jid, a, b, cy) => {
     const d = ovalPath(a, b, 0, cy);
     const nodes = [];
-    if (glow) nodes.push(path({ id: `${jid}-glow`, d, x: 0, y: 0, fill: "none", stroke: glow, strokeWidth: GLOW_W, opacity: 0.18 }));
+    if (glow2) nodes.push(path({ id: `${jid}-glow`, d, x: 0, y: 0, fill: "none", stroke: glow2, strokeWidth: GLOW_W, opacity: 0.18 }));
     nodes.push(path({ id: `${jid}-shape`, d, x: 0, y: 0, fill, stroke: line2, strokeWidth: LINE_W }));
     return nodes;
   };
@@ -2868,9 +2949,21 @@ function evaluate(compiled, t) {
     const v = valueAt(target, prop, base ?? "");
     return v === "" && base === void 0 ? void 0 : String(v);
   };
+  const effectFx = (id, p) => {
+    const fx = {};
+    if (p.blur !== void 0) fx.blur = num(id, "blur", p.blur);
+    if (p.shadowColor !== void 0) {
+      fx.shadowColor = str(id, "shadowColor", p.shadowColor);
+      fx.shadowBlur = num(id, "shadowBlur", p.shadowBlur ?? 0);
+      fx.shadowX = num(id, "shadowX", p.shadowX ?? 0);
+      fx.shadowY = num(id, "shadowY", p.shadowY ?? 0);
+    }
+    return fx;
+  };
   const walk = (node, parent, parentOpacity, clips) => {
     const id = node.id;
     const clipSpread = clips.length > 0 ? { clips } : void 0;
+    const fx = effectFx(id, node.props);
     if (node.type === "line") {
       const opacity2 = parentOpacity * num(id, "opacity", node.props.opacity ?? 1);
       if (opacity2 <= 0) return;
@@ -2888,6 +2981,7 @@ 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,
         ...clipSpread
       });
       return;
@@ -2919,8 +3013,10 @@ function evaluate(compiled, t) {
         const height = num(id, "height", node.props.height);
         const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
         const strokeWidth = num(id, "strokeWidth", node.props.strokeWidth ?? 1);
-        const fill = opt(id, "fill", node.props.fill);
-        const stroke = opt(id, "stroke", node.props.stroke);
+        const fillP = node.props.fill;
+        const strokeP = node.props.stroke;
+        const fill = isGradient(fillP) ? fillP : opt(id, "fill", fillP);
+        const stroke = isGradient(strokeP) ? strokeP : opt(id, "stroke", strokeP);
         ops.push({
           type: node.type,
           id,
@@ -2933,6 +3029,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,
           ...clipSpread
         });
         return;
@@ -2951,6 +3048,7 @@ function evaluate(compiled, t) {
           height,
           offsetX: -width * ax,
           offsetY: -height * ay,
+          ...fx,
           ...clipSpread
         });
         return;
@@ -2958,17 +3056,23 @@ function evaluate(compiled, t) {
       case "path": {
         const ox = num(id, "originX", node.props.originX ?? 0);
         const oy = num(id, "originY", node.props.originY ?? 0);
-        const fill = opt(id, "fill", node.props.fill);
-        const stroke = opt(id, "stroke", node.props.stroke);
+        const fillP = node.props.fill;
+        const strokeP = node.props.stroke;
+        const fill = isGradient(fillP) ? fillP : opt(id, "fill", fillP);
+        const stroke = isGradient(strokeP) ? strokeP : opt(id, "stroke", strokeP);
+        const dStr = str(id, "d", node.props.d);
+        const needsBox = isGradient(fill) || isGradient(stroke);
         ops.push({
           type: "path",
           id,
           transform: ox === 0 && oy === 0 ? matrix : multiply(matrix, [1, 0, 0, 1, -ox, -oy]),
           opacity,
-          d: str(id, "d", node.props.d),
+          d: dStr,
           progress: Math.max(0, Math.min(1, num(id, "progress", node.props.progress ?? 1))),
           ...fill !== void 0 && { fill },
           ...stroke !== void 0 && { stroke, strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1) },
+          ...needsBox && { bbox: pathBBox(dStr) },
+          ...fx,
           ...clipSpread
         });
         return;
@@ -2993,6 +3097,7 @@ function evaluate(compiled, t) {
           letterSpacing: num(id, "letterSpacing", node.props.letterSpacing ?? 0),
           align: TEXT_ALIGN[ax] ?? "left",
           baseline: TEXT_BASELINE[ay] ?? "top",
+          ...fx,
           ...clipSpread
         });
         return;
@@ -3116,6 +3221,7 @@ export {
   compileScene,
   composeScene,
   composition,
+  conicGradient,
   cursor,
   cursorClick,
   cursorDouble,
@@ -3126,17 +3232,21 @@ export {
   deviceScreen,
   deviceScreenCenter,
   deviceScreenPoint,
+  dropShadow,
   ellipse,
   evaluate,
   figure,
   formatComposeReport,
+  glow,
   group,
   humanoid,
   ikReach,
   image,
   isColor,
+  isGradient,
   lerpValue,
   line,
+  linearGradient,
   motionOp,
   motionOpLabel,
   motionPath,
@@ -3149,6 +3259,7 @@ export {
   pathPoint,
   pathTangentAngle,
   poseTo,
+  radialGradient,
   rect,
   resolveAudioPlan,
   resolveCompositionAudioPlan,

package/dist/labels.js

@@ -318,12 +318,13 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -341,12 +342,36 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const checkPaint = (where, value) => {
+    if (typeof value !== "object" || value === null) return;
+    const g = value;
+    if (g.kind !== "linear" && g.kind !== "radial" && g.kind !== "conic") {
+      problems.push(`${where}: a paint object must be a gradient with kind "linear" / "radial" / "conic"`);
+      return;
+    }
+    if (!Array.isArray(g.stops) || g.stops.length === 0) {
+      problems.push(`${where}: gradient "${g.kind}" needs at least one color stop`);
+      return;
+    }
+    g.stops.forEach((s, i) => {
+      const st = s;
+      if (typeof st?.color !== "string") problems.push(`${where}: gradient stop ${i} needs a color string`);
+      if (typeof st?.offset !== "number" || st.offset < 0 || st.offset > 1) {
+        problems.push(`${where}: gradient stop ${i} "offset" must be a number in 0..1`);
+      }
+    });
+  };
   const collect = (nodes) => {
     for (const node of nodes) {
       if (nodeById.has(node.id)) {
         problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
       }
       nodeById.set(node.id, node);
+      const props = node.props;
+      checkPaint(`node "${node.id}" fill`, props.fill);
+      checkPaint(`node "${node.id}" stroke`, props.stroke);
+      if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
+      if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/renderer-canvas.js

@@ -1,5 +1,30 @@
 // ../renderer-canvas/src/index.ts
 import { evaluate } from "@reframe/core";
+function resolvePaint(ctx, paint, box) {
+  if (typeof paint === "string") return paint;
+  const { x, y, w, h } = box;
+  let g;
+  if (paint.kind === "linear") {
+    const a = (paint.angle ?? 0) * Math.PI / 180;
+    const dx = Math.cos(a);
+    const dy = Math.sin(a);
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+    const half = Math.abs(dx) * (w / 2) + Math.abs(dy) * (h / 2);
+    g = ctx.createLinearGradient(cx - dx * half, cy - dy * half, cx + dx * half, cy + dy * half);
+  } else if (paint.kind === "radial") {
+    const cx = x + (paint.cx ?? 0.5) * w;
+    const cy = y + (paint.cy ?? 0.5) * h;
+    const r = Math.max((paint.r ?? 0.5) * Math.max(w, h), 1e-4);
+    g = ctx.createRadialGradient(cx, cy, 0, cx, cy, r);
+  } else {
+    const cx = x + (paint.cx ?? 0.5) * w;
+    const cy = y + (paint.cy ?? 0.5) * h;
+    g = ctx.createConicGradient((paint.angle ?? 0) * Math.PI / 180, cx, cy);
+  }
+  for (const s of paint.stops) g.addColorStop(Math.max(0, Math.min(1, s.offset)), s.color);
+  return g;
+}
 function renderFrame(ctx, compiled, t, images) {
   const { size, background } = compiled.ir;
   ctx.setTransform(1, 0, 0, 1, 0, 0);
@@ -30,8 +55,16 @@ function drawDisplayList(ctx, ops, images) {
     }
     ctx.setTransform(...op.transform);
     ctx.globalAlpha = Math.max(0, Math.min(1, op.opacity));
+    if (op.blur) ctx.filter = `blur(${op.blur}px)`;
+    if (op.shadowColor) {
+      ctx.shadowColor = op.shadowColor;
+      ctx.shadowBlur = op.shadowBlur ?? 0;
+      ctx.shadowOffsetX = op.shadowX ?? 0;
+      ctx.shadowOffsetY = op.shadowY ?? 0;
+    }
     switch (op.type) {
       case "rect": {
+        const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
         ctx.beginPath();
         if (op.radius && op.radius > 0) {
           ctx.roundRect(op.offsetX, op.offsetY, op.width, op.height, op.radius);
@@ -39,17 +72,18 @@ function drawDisplayList(ctx, ops, images) {
           ctx.rect(op.offsetX, op.offsetY, op.width, op.height);
         }
         if (op.fill) {
-          ctx.fillStyle = op.fill;
+          ctx.fillStyle = resolvePaint(ctx, op.fill, box);
           ctx.fill();
         }
         if (op.stroke) {
-          ctx.strokeStyle = op.stroke;
+          ctx.strokeStyle = resolvePaint(ctx, op.stroke, box);
           ctx.lineWidth = op.strokeWidth ?? 1;
           ctx.stroke();
         }
         break;
       }
       case "ellipse": {
+        const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
         ctx.beginPath();
         ctx.ellipse(
           op.offsetX + op.width / 2,
@@ -61,11 +95,11 @@ function drawDisplayList(ctx, ops, images) {
           Math.PI * 2
         );
         if (op.fill) {
-          ctx.fillStyle = op.fill;
+          ctx.fillStyle = resolvePaint(ctx, op.fill, box);
           ctx.fill();
         }
         if (op.stroke) {
-          ctx.strokeStyle = op.stroke;
+          ctx.strokeStyle = resolvePaint(ctx, op.stroke, box);
           ctx.lineWidth = op.strokeWidth ?? 1;
           ctx.stroke();
         }
@@ -102,12 +136,13 @@ function drawDisplayList(ctx, ops, images) {
       }
       case "path": {
         const p = new Path2D(op.d);
+        const box = op.bbox ? { x: op.bbox[0], y: op.bbox[1], w: op.bbox[2], h: op.bbox[3] } : { x: 0, y: 0, w: 1, h: 1 };
         if (op.fill) {
-          ctx.fillStyle = op.fill;
+          ctx.fillStyle = resolvePaint(ctx, op.fill, box);
           ctx.fill(p);
         }
         if (op.stroke && (op.strokeWidth ?? 1) > 0) {
-          ctx.strokeStyle = op.stroke;
+          ctx.strokeStyle = resolvePaint(ctx, op.stroke, box);
           ctx.lineWidth = op.strokeWidth ?? 1;
           ctx.lineJoin = "round";
           ctx.lineCap = "round";

package/dist/trace-cli.js

@@ -6,11 +6,12 @@ import { resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],

package/dist/types/effects.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Drop-shadow / outer-glow sugar. These return a partial-props object you spread
+ * into a shape node; the underlying `shadow*` props stay animatable (e.g. pulse a
+ * glow with `oscillate(id, "shadowBlur", …)`). Units are screen pixels.
+ */
+import type { BaseProps } from "./ir.js";
+type ShadowProps = Pick<BaseProps, "shadowColor" | "shadowBlur" | "shadowX" | "shadowY">;
+/** An outer glow — a shadow with no offset. `rect({ …, ...glow("#FFD24B", 28) })`. */
+export declare function glow(color: string, blur?: number): ShadowProps;
+/** A drop shadow (offset downward by default). `rect({ …, ...dropShadow("#0008", 40, 0, 16) })`. */
+export declare function dropShadow(color: string, blur?: number, x?: number, y?: number): ShadowProps;
+export {};

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 { ClipShape, PropValue } from "./ir.js";
+import type { ClipShape, 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,
@@ -24,6 +24,12 @@ interface OpBase {
     opacity: number;
     /** Clip regions from ancestor groups (intersected by the renderer). */
     clips?: ClipRegion[];
+    /** Paint effects (screen-pixel space). Present only when authored. */
+    blur?: number;
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowX?: number;
+    shadowY?: number;
 }
 export type DisplayOp = (OpBase & {
     type: "rect";
@@ -31,8 +37,8 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     radius?: number;
 }) | (OpBase & {
@@ -41,8 +47,8 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
 }) | (OpBase & {
     type: "line";
@@ -76,9 +82,11 @@ export type DisplayOp = (OpBase & {
     d: string;
     /** 0..1 fraction of the stroke outline drawn (draw-on). */
     progress: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     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];
 });
 export type DisplayList = DisplayOp[];
 /**

package/dist/types/gradient.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Gradient paints — the structured alternative to a solid color `fill`/`stroke`.
+ *
+ * Coordinates are normalized to the node's bounding box (0..1), so a gradient is
+ * just an angle + color stops, independent of the node's size. The renderer maps
+ * 0..1 → the node's local box and the paint is applied in node-local space, so
+ * rotating/scaling the NODE moves the gradient with it (the "animated gradient"
+ * idiom — gradients themselves are static this version). Pure + deterministic.
+ */
+import type { ColorStop, Gradient, Paint } from "./ir.js";
+/** True when a paint is a gradient object (vs a plain color string). */
+export declare function isGradient(p: Paint | undefined): p is Gradient;
+/** A linear gradient. `angle` in degrees: 0 = left→right, 90 = top→bottom. */
+export declare function linearGradient(stops: (string | ColorStop)[], opts?: {
+    angle?: number;
+}): Gradient;
+/** A radial gradient. `cx/cy` centre (0..1 of the box, default 0.5), `r` radius (0..1, default 0.5). */
+export declare function radialGradient(stops: (string | ColorStop)[], opts?: {
+    cx?: number;
+    cy?: number;
+    r?: number;
+}): Gradient;
+/** A conic (angular sweep) gradient. `angle` start in degrees, `cx/cy` centre (0..1). */
+export declare function conicGradient(stops: (string | ColorStop)[], opts?: {
+    angle?: number;
+    cx?: number;
+    cy?: number;
+}): Gradient;

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport,
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
+export { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
+export { glow, dropShadow } from "./effects.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
 export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
 export { cursor, cursorTo, cursorPath, cursorClick, cursorDouble, type CursorStyle, type CursorOpts, type CursorToOpts, type CursorPathOpts, type CursorClickOpts } from "./cursor.js";

package/dist/types/ir.d.ts

@@ -36,20 +36,60 @@ export interface BaseProps {
      * for HUD / titles / watermark layers. No-op when the scene has no camera.
      */
     fixed?: boolean;
+    /**
+     * 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).
+     */
+    blur?: number;
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowX?: number;
+    shadowY?: number;
+}
+/**
+ * A paint is a solid color string OR a gradient. Coordinates are normalized to the
+ * node's bounding box (0..1, SVG `objectBoundingBox` style) so a gradient is just an
+ * angle + stops, size-independent. Applied in node-local space, so animating the
+ * node's transform (rotation/scale) moves the gradient with it. Build with
+ * `linearGradient`/`radialGradient`/`conicGradient` (`gradient.ts`).
+ */
+export interface ColorStop {
+    offset: number;
+    color: string;
 }
+export type Gradient = {
+    kind: "linear";
+    angle?: number;
+    stops: ColorStop[];
+} | {
+    kind: "radial";
+    cx?: number;
+    cy?: number;
+    r?: number;
+    stops: ColorStop[];
+} | {
+    kind: "conic";
+    angle?: number;
+    cx?: number;
+    cy?: number;
+    stops: ColorStop[];
+};
+export type Paint = string | Gradient;
 export interface RectProps extends BaseProps {
     width: number;
     height: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     radius?: number;
 }
 export interface EllipseProps extends BaseProps {
     width: number;
     height: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
 }
 export interface LineProps {
@@ -64,6 +104,12 @@ export interface LineProps {
     progress?: number;
     /** Pin to the screen so the scene `camera` does not move it (top-level only). */
     fixed?: boolean;
+    /** Paint effects (px, screen-space) — see BaseProps. */
+    blur?: number;
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowX?: number;
+    shadowY?: number;
 }
 export interface TextProps extends BaseProps {
     /** Numbers interpolate (count-up) and render via toFixed(contentDecimals). */
@@ -104,8 +150,8 @@ export interface GroupProps extends BaseProps {
 export interface PathProps extends BaseProps {
     /** SVG path data (the `d` attribute). Drawn as a true vector — crisp at any zoom. */
     d: string;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     /**
      * 0..1 — fraction of the OUTLINE drawn, for a self-drawing "draw-on" effect

package/dist/types/path.d.ts

@@ -9,6 +9,12 @@
  * spacing ever overshoots.
  */
 export type Pt = [number, number];
+/**
+ * A loose bounding box `[x, y, w, h]` from a path `d`'s coordinate extents — used
+ * only to map a gradient across the shape. Exact for M/L/C/Q/S/T paths (every
+ * number is an x/y coord, control points included); loose for the rare H/V/A.
+ */
+export declare function pathBBox(d: string): [number, number, number, number];
 /**
  * Position on the spline at progress u in [0,1]. `curviness` scales the
  * Catmull-Rom tangents (GSAP's idea): 1 = standard smooth (the default and the

package/guides/edsl-guide.md

@@ -150,6 +150,50 @@ scene({
 
 See `examples/scenes/camera-demo.ts`.
 
+## Gradients (fill / stroke)
+
+`fill` and `stroke` on **rect / ellipse / path** accept a gradient as well as a
+color string. Coordinates are normalized to the node's bounding box (0..1), so a
+gradient is just an angle + stops:
+
+```ts
+rect({ id: "card", x, y, width: 300, height: 300, anchor: "center",
+  fill: linearGradient(["#FF5C3A", "#FFC24B"], { angle: 60 }) })   // 0=L→R, 90=T→B
+ellipse({ id: "orb", /* … */ fill: radialGradient(["#9B7CFF", "#221A4A"], { cx: 0.4, cy: 0.4, r: 0.6 }) })
+path({ id: "star", d, fill: conicGradient(["#00C2A8", "#3AA0FF", "#7C5CFF", "#00C2A8"], { angle: -90 }) })
+ellipse({ id: "ring", /* … */ fill: "none", stroke: linearGradient(["#3AA0FF", "#46E5A0"]), strokeWidth: 10 })
+```
+
+- `linearGradient(stops, { angle })`, `radialGradient(stops, { cx, cy, r })`,
+  `conicGradient(stops, { angle, cx, cy })`. `stops` is a color array (even offsets)
+  or `[{ offset, color }]`. `cx/cy/r` are 0..1 of the box (centre defaults to 0.5).
+- **Gradients are static** (not keyframed). The gradient lives in the node's local
+  space, so **animate the NODE** (`tween(id, { rotation: 360 })`, scale, move) and the
+  gradient sweeps/stretches with it. Color-string fills still tween as today.
+- text fill and line stroke are color-only for now. See `examples/scenes/gradient-demo.ts`.
+
+## Shadow, glow & blur
+
+Drawable nodes (rect / ellipse / path / text / image / line) take animatable paint
+effects, in **screen pixels** (not transformed by the node or camera, so a shadow
+keeps a consistent light direction):
+
+```ts
+rect({ id: "card", /* … */, ...dropShadow("#000000", 64, 0, 34) })   // drop shadow
+ellipse({ id: "orb", /* … */, fill: radialGradient([...]), shadowColor: "#FFC24B", shadowBlur: 22 })
+oscillate("orb", "shadowBlur", { amplitude: 16, frequency: 0.9 })    // PULSING glow
+rect({ id: "card", /* … */, blur: 18 }); tween("card", { blur: 0 }, { duration: 1 }) // focus pull
+```
+
+- Props: `blur` (gaussian blur of the shape), `shadowColor` (turns the shadow/glow
+  on), `shadowBlur`, `shadowX`, `shadowY`. All **animatable** — `tween`/`oscillate`
+  them for pulsing glows, focus pulls, etc. (set a base value first so there's
+  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`.
+
 ## Character rig (skeleton, poses, IK)
 
 A first-class, declarative character rig that **compiles to plain IR** (nested

package/package.json

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