reframe-video 0.6.0 → 0.6.1

package/dist/bin.js

@@ -349,12 +349,34 @@ 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 (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -899,6 +921,13 @@ var init_camera = __esm({
   }
 });
 
+// ../core/src/gradient.ts
+var init_gradient = __esm({
+  "../core/src/gradient.ts"() {
+    "use strict";
+  }
+});
+
 // ../core/src/presets.ts
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
@@ -1292,6 +1321,7 @@ var init_evaluate = __esm({
     "use strict";
     init_behaviors();
     init_camera();
+    init_gradient();
     init_interpolate();
     init_path();
   }
@@ -1354,6 +1384,7 @@ var init_src = __esm({
     init_compile();
     init_path();
     init_camera();
+    init_gradient();
     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));
@@ -344,6 +360,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;
 
@@ -709,8 +730,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,
@@ -748,17 +771,22 @@
         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) },
             ...clipSpread
           });
           return;
@@ -806,6 +834,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);
@@ -838,6 +891,7 @@
       ctx2.globalAlpha = Math.max(0, Math.min(1, op.opacity));
       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 +899,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 +922,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 +963,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

@@ -347,12 +347,34 @@ ${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 (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));
@@ -341,12 +357,34 @@ ${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 (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -917,6 +955,38 @@ 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/presets.ts
 var PRESET_NAMES = [
   "draw-bloom",
@@ -2919,8 +2989,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,
@@ -2958,17 +3030,22 @@ 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) },
           ...clipSpread
         });
         return;
@@ -3116,6 +3193,7 @@ export {
   compileScene,
   composeScene,
   composition,
+  conicGradient,
   cursor,
   cursorClick,
   cursorDouble,
@@ -3135,8 +3213,10 @@ export {
   ikReach,
   image,
   isColor,
+  isGradient,
   lerpValue,
   line,
+  linearGradient,
   motionOp,
   motionOpLabel,
   motionPath,
@@ -3149,6 +3229,7 @@ export {
   pathPoint,
   pathTangentAngle,
   poseTo,
+  radialGradient,
   rect,
   resolveAudioPlan,
   resolveCompositionAudioPlan,

package/dist/labels.js

@@ -341,12 +341,34 @@ ${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 (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);
@@ -32,6 +57,7 @@ function drawDisplayList(ctx, ops, images) {
     ctx.globalAlpha = Math.max(0, Math.min(1, op.opacity));
     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 +65,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 +88,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 +129,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/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,
@@ -31,8 +31,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 +41,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 +76,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,7 @@ 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 { 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

@@ -37,19 +37,48 @@ export interface BaseProps {
      */
     fixed?: boolean;
 }
+/**
+ * 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 {
@@ -104,8 +133,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,28 @@ 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`.
+
 ## 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.1",
   "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",