apexify.js 4.9.26 → 4.9.28

package/lib/Canvas/utils/Image/imageProperties.ts

@@ -1,835 +1,382 @@
-import { Image, SKRSContext2D } from "@napi-rs/canvas";
-import { ImageProperties } from "../utils";
+import type { SKRSContext2D } from "@napi-rs/canvas";
+import type { borderPosition } from "../types";
 
-/**
- * Applies shadow to the canvas context.
- * @param ctx The canvas rendering context.
- * @param shadow The shadow properties.
- * @param x The x-coordinate of the shape.
- * @param y The y-coordinate of the shape.
- * @param width The width of the shape.
- * @param height The height of the shape.
- */
-export function applyShadow(
-    ctx: SKRSContext2D,
-    shadow: ImageProperties['shadow'],
-    x: number,
-    y: number,
-    width: number,
-    height: number
-  ): void {
-    ctx.save();
-  
-    if (shadow) {
-      ctx.globalAlpha = shadow.opacity ?? 1;
-      ctx.filter = `blur(${shadow.blur ?? 0}px)`;
-  
-      const shadowX = x + (shadow.offsetX ?? 0);
-      const shadowY = y + (shadow.offsetY ?? 0);
-  
-      objectRadius(
-        ctx,
-        shadowX,
-        shadowY,
-        width,
-        height,
-        shadow.borderRadius ?? 2,
-      );
-  
-      ctx.fillStyle = shadow.gradient
-          ? createGradient(
-              ctx, shadow.gradient, 
-              shadowX, shadowY,
-              shadowX + width, shadowY + height 
-          )
-          : shadow.color || "transparent";
-      ctx.fill();
-    }
-  
-    ctx.filter = "none";
-    ctx.globalAlpha = 1;
-    ctx.restore();
-  }
-  
-/**
- * Applies zoom (scaling) to the canvas context around a specified point.
- * @param ctx The canvas rendering context.
- * @param zoom An object with scale (zoom factor) and the x/y coordinates that act as the zoom origin.
- */
-export function applyZoom(
+export function buildPath(
   ctx: SKRSContext2D,
-  zoom?: { scale?: number; x?: number; y?: number }
+  x: number, y: number, w: number, h: number,
+  radius: number | "circular" = 0,
+  borderPos: borderPosition = "all"
 ): void {
-  if (!zoom) return;
-  const scale = zoom.scale ?? 1;
-  const zoomX = zoom.x ?? 0;
-  const zoomY = zoom.y ?? 0;
-  
-  ctx.translate(zoomX, zoomY);
-  ctx.scale(scale, scale);
-  ctx.translate(-zoomX, -zoomY);
-}
-
-
-/**
- * Applies stroke to the canvas context with support for selective side strokes.
- * Supports optional blur effect on the stroke.
- *
- * @param ctx The canvas rendering context.
- * @param stroke The stroke properties.
- * @param x The x-coordinate of the shape.
- * @param y The y-coordinate of the shape.
- * @param width The width of the shape.
- * @param height The height of the shape.
- * @param blur Optional blur effect on the stroke.
- */
-export function applyStroke(
-  ctx: SKRSContext2D,
-  stroke: ImageProperties["stroke"],
-  x: number,
-  y: number,
-  width: number,
-  height: number,
-  shapeName?: string,
-): void {
-  if (!stroke) return;
-
-  ctx.save();
+  ctx.beginPath();
 
-  if (stroke.blur && stroke.blur > 0) {
-      ctx.filter = `blur(${stroke.blur}px)`;
+  if (radius === "circular") {
+    const r = Math.min(w, h) / 2;
+    ctx.arc(x + w / 2, y + h / 2, r, 0, Math.PI * 2);
+    ctx.closePath();
+    return;
   }
 
-  ctx.strokeStyle = stroke.gradient
-      ? createGradient(ctx, stroke.gradient, x, y, x + width, y + height)
-      : stroke.color || "transparent";
-
-  ctx.lineWidth = stroke.width && stroke.width > 0 ? stroke.width : 2;
+  if (!radius || radius <= 0) {
+    ctx.rect(x, y, w, h);
+    ctx.closePath();
+    return;
+  }
 
-  ctx.beginPath();
-  const borderPos = stroke.position || 0;
+  const br = Math.min(radius, w / 2, h / 2);
+  const sel = new Set(borderPos.toLowerCase().split(",").map(s => s.trim()));
+
+  const has = (name: string) =>
+    sel.has("all") || sel.has(name) ||
+    (name === "top-left"     && (sel.has("top") || sel.has("left"))) ||
+    (name === "top-right"    && (sel.has("top") || sel.has("right"))) ||
+    (name === "bottom-right" && (sel.has("bottom") || sel.has("right"))) ||
+    (name === "bottom-left"  && (sel.has("bottom") || sel.has("left")));
+
+  const tl = has("top-left")     ? br : 0;
+  const tr = has("top-right")    ? br : 0;
+  const brR= has("bottom-right") ? br : 0;
+  const bl = has("bottom-left")  ? br : 0;
+
+  ctx.moveTo(x + tl, y);
+  ctx.lineTo(x + w - tr, y);
+  if (tr) ctx.arcTo(x + w, y, x + w, y + tr, tr);
+  ctx.lineTo(x + w, y + h - brR);
+  if (brR) ctx.arcTo(x + w, y + h, x + w - brR, y + h, brR);
+  ctx.lineTo(x + bl, y + h);
+  if (bl) ctx.arcTo(x, y + h, x, y + h - bl, bl);
+  ctx.lineTo(x, y + tl);
+  if (tl) ctx.arcTo(x, y, x + tl, y, tl);
 
-  // Adjust the bounding box by borderPos
-  //   - Positive borderPos moves stroke outward
-  //   - Negative borderPos moves stroke inward
-  const offsetX = x - borderPos;
-  const offsetY = y - borderPos;
-  const offsetW = width + 2 * borderPos;
-  const offsetH = height + 2 * borderPos;
+  ctx.closePath();
+}
 
-  ctx.beginPath();
+export function applyRotation(
+  ctx: SKRSContext2D,
+  deg: number | undefined,
+  x: number, y: number, w: number, h: number
+) {
+  if (!deg) return;
+  const cx = x + w / 2, cy = y + h / 2;
+  ctx.translate(cx, cy);
+  ctx.rotate((deg * Math.PI) / 180);
+  ctx.translate(-cx, -cy);
+}
 
-  // For known shapes (circle, star, etc.), re-draw with adjusted bounding box
-  if (
-    [
-      "heart", "arrow", "circle", "star",
-      "pentagon", "hexagon", "heptagon", "octagon",
-      "diamond", "trapezoid", "kite",
-    ].includes(shapeName as string)
-  ) {
-    switch (shapeName) {
-      case "circle":
-        // Circle centered in the new bounding box
-        ctx.arc(
-          offsetX + offsetW / 2,
-          offsetY + offsetH / 2,
-          offsetW / 2, // radius
-          0,
-          Math.PI * 2
-        );
-        break;
-
-      case "star":
-        drawStar(ctx, offsetX, offsetY, offsetW, offsetH);
-        break;
-
-      case "arrow":
-        drawArrow(ctx, offsetX, offsetY, offsetW, offsetH);
-        break;
-
-      case "pentagon":
-      case "hexagon":
-      case "heptagon":
-      case "octagon": {
-        const sides = parseInt(shapeName.replace(/\D/g, ""), 10);
-        drawPolygon(ctx, offsetX, offsetY, offsetW, offsetH, sides);
-        break;
-      }
-
-      case "diamond":
-        ctx.moveTo(offsetX + offsetW / 2, offsetY);
-        ctx.lineTo(offsetX + offsetW, offsetY + offsetH / 2);
-        ctx.lineTo(offsetX + offsetW / 2, offsetY + offsetH);
-        ctx.lineTo(offsetX, offsetY + offsetH / 2);
-        ctx.closePath();
-        break;
-
-      case "trapezoid": {
-        const topWidth = offsetW * 0.6;
-        const offsetVal = (offsetW - topWidth) / 2;
-        ctx.moveTo(offsetX + offsetVal, offsetY);
-        ctx.lineTo(offsetX + offsetVal + topWidth, offsetY);
-        ctx.lineTo(offsetX + offsetW, offsetY + offsetH);
-        ctx.lineTo(offsetX, offsetY + offsetH);
-        ctx.closePath();
-        break;
-      }
-
-      case "heart":
-        drawHeart(ctx, offsetX, offsetY, offsetW, offsetH);
-        break;
-
-      case "kite":
-        ctx.moveTo(offsetX + offsetW / 2, offsetY);
-        ctx.lineTo(offsetX + offsetW, offsetY + offsetH / 2);
-        ctx.lineTo(offsetX + offsetW / 2, offsetY + offsetH);
-        ctx.lineTo(offsetX, offsetY + offsetH / 2);
-        ctx.closePath();
-        break;
-    }
-  } else {
-    ctx.globalCompositeOperation = "source-atop";
-    objectRadius(ctx, offsetX, offsetY, offsetW, offsetH, stroke.borderRadius || 2, stroke.borderPosition);
-  }
 
-  ctx.stroke();
-  ctx.filter = "none";
-  ctx.restore();
+function rotatePoint(
+  x: number, y: number, px: number, py: number, deg = 0
+): [number, number] {
+  if (!deg) return [x, y];
+  const a = (deg * Math.PI) / 180;
+  const dx = x - px, dy = y - py;
+  return [px + dx * Math.cos(a) - dy * Math.sin(a),
+          py + dx * Math.sin(a) + dy * Math.cos(a)];
 }
 
+/**
+ * Build a gradient in **rect-local coordinates**:
+ * - Defaults for coords use rect {w,h}
+ * - Rotation pivot defaults to rect center
+ * - Offsets are applied by adding rect.x/rect.y to all points
+ */
+export function createGradientFill(
+  ctx: SKRSContext2D,
+  g: gradient,
+  rect: { x: number; y: number; w: number; h: number }
+): CanvasGradient {
+  const { x, y, w, h } = rect;
+
+  if (g.type === "linear") {
+    const {
+      startX = 0, startY = 0,
+      endX = w,  endY = 0,
+      rotate = 0,
+      pivotX = w / 2, pivotY = h / 2,
+      colors
+    } = g;
+
+    const [sx, sy] = rotatePoint(startX, startY, pivotX, pivotY, rotate);
+    const [ex, ey] = rotatePoint(endX,   endY,   pivotX, pivotY, rotate);
+
+    const grad = ctx.createLinearGradient(x + sx, y + sy, x + ex, y + ey);
+    colors.forEach(cs => grad.addColorStop(cs.stop, cs.color));
+    return grad;
+  }
 
-
-export function drawShape(ctx: SKRSContext2D, shapeSettings: any): void {
+  // radial
   const {
-    source,
-    x,
-    y,
-    width,
-    height,
-    opacity,
-    rotation = 0,
-    borderRadius = 0,
-    borderPosition = 'all',
-    stroke,
-    shadow,
-    isFilled = false,
-    color = "transparent",
-    gradient,
-    filling,
-  } = shapeSettings;
-
-  const shapeName = source.toLowerCase();
-  ctx.save();
-
-  applyRotation(ctx, rotation, x, y, width, height);
-  applyShadow(ctx, shadow, x, y, width, height);
+    startX = w / 2, startY = h / 2, startRadius = 0,
+    endX = w / 2,   endY = h / 2,   endRadius   = Math.max(w, h) / 2,
+    rotate = 0,
+    pivotX = w / 2, pivotY = h / 2,
+    colors
+  } = g;
+
+  const [sx, sy] = rotatePoint(startX, startY, pivotX, pivotY, rotate);
+  const [ex, ey] = rotatePoint(endX,   endY,   pivotX, pivotY, rotate);
+
+  const grad = ctx.createRadialGradient(
+    x + sx, y + sy, startRadius,
+    x + ex, y + ey, endRadius
+  );
+  colors.forEach(cs => grad.addColorStop(cs.stop, cs.color));
+  return grad;
+}
 
-  ctx.beginPath();
+// utils/imageMath.ts
+import type { AlignMode, FitMode } from "../types";
 
-  ctx.globalAlpha = opacity as number;
-
-  switch (shapeName) {
-    case 'circle': {
-      ctx.arc(x + width / 2, y + height / 2, width / 2, 0, Math.PI * 2);
-      break;
-    }
-    case 'square': {
-      ctx.rect(x, y, width, height);
-      break;
-    }
-    case 'triangle': {
-      ctx.moveTo(x + width / 2, y);
-      ctx.lineTo(x, y + height);
-      ctx.lineTo(x + width, y + height);
-      ctx.closePath();
-      break;
-    }
-    case 'pentagon': case 'hexagon': case 'heptagon': case 'octagon': {
-      const sides = parseInt(shapeName.replace(/\D/g, ""), 10);
-      drawPolygon(ctx, x, y, width, height, sides);
-      break;
-    }
-    case 'star': {
-      drawStar(ctx, x, y, width, height);
-      break;
-    }
-    case 'kite': {
-      ctx.moveTo(x + width / 2, y);
-      ctx.lineTo(x + width, y + height / 2);
-      ctx.lineTo(x + width / 2, y + height);
-      ctx.lineTo(x, y + height / 2);
-      ctx.closePath();
-      break;
-    }
-    case 'oval': {
-      ctx.ellipse(x + width / 2, y + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
-      break;
-    }
-    case 'arrow': {
-      drawArrow(ctx, x, y, width, height);
-      break;
-    }
-    case 'heart': {
-      drawHeart(ctx, x, y, width, height);
-      break;
-    }
-    case 'diamond': {
-      ctx.moveTo(x + width / 2, y);
-      ctx.lineTo(x + width, y + height / 2);
-      ctx.lineTo(x + width / 2, y + height);
-      ctx.lineTo(x, y + height / 2);
-      ctx.closePath();
-      break;
-    }
-    case 'trapezoid': {
-      const topWidth = width * 0.6;
-      const offset = (width - topWidth) / 2;
-      ctx.moveTo(x + offset, y);
-      ctx.lineTo(x + offset + topWidth, y);
-      ctx.lineTo(x + width, y + height);
-      ctx.lineTo(x, y + height);
-      ctx.closePath();
-      break;
-    }
-    default: {
-      ctx.restore();
-      throw new Error(`Unsupported shape: ${shapeName}`);
-    }
-  }
+export function fitInto(
+  boxX: number, boxY: number, boxW: number, boxH: number,
+  imgW: number, imgH: number,
+  fit: FitMode = "fill",
+  align: AlignMode = "center"
+) {
+  let dx = boxX, dy = boxY, dw = boxW, dh = boxH, sx = 0, sy = 0, sw = imgW, sh = imgH;
 
-  if (isFilled) {
-    if (borderRadius && shapeName !== 'circle' && shapeName !== 'oval') {
-      objectRadius(ctx, x, y, width, height, borderRadius, borderPosition);
-    }
-  
-    let fillStyle: string | CanvasGradient = color;
-  
-    if (gradient) {
-      fillStyle = createGradient(ctx, gradient, x, y, x + width, y + height);
-    }
-  
-    if (filling && filling.percentage <= 100) {
-      ctx.save();
-  
-      const isCustomShape = ["heart", "arrow", "star", "pentagon", "hexagon", "heptagon", "octagon", "diamond", "trapezoid", "kite", "oval", "circle"].includes(shapeName);
-      
-      if (isCustomShape) {
-        ctx.clip();
-      }
-  
-      let fillX = x;
-      let fillY = y;
-      let fillWidth = width;
-      let fillHeight = height;
-  
-      switch (filling.rotation) {
-        case 0:
-          fillHeight = (filling.percentage / 100) * height;
-          fillY = y + height - fillHeight;
-          break;
-  
-        case 180:
-          fillHeight = (filling.percentage / 100) * height;
-          break;
-  
-        case 90:
-          fillWidth = (filling.percentage / 100) * width;
-          break;
-  
-        case 270:
-          fillWidth = (filling.percentage / 100) * width;
-          fillX = x + width - fillWidth;
-          break;
-  
-        default:
-          console.warn(`Unsupported filling rotation: ${filling.rotation}, defaulting to 0 (Bottom to Top).`);
-          fillHeight = (filling.percentage / 100) * height;
-          fillY = y + height - fillHeight;
-      }
-  
-      ctx.beginPath();
-      ctx.rect(fillX, fillY, fillWidth, fillHeight);
-      ctx.fillStyle = fillStyle;
-      ctx.fill();
-  
-      ctx.restore();
-    } else {
-      ctx.fillStyle = fillStyle;
-      ctx.fill();
-    }
+  if (fit === "fill") {
+    return { dx, dy, dw, dh, sx, sy, sw, sh };
   }
 
-  ctx.globalAlpha = 1.0;
-
-  if (stroke) {
-    if (stroke?.opacity) ctx.globalAlpha = stroke.opacity as number;
-    applyStroke(ctx, stroke, x, y, width, height, shapeName);
-    ctx.globalAlpha = 1.0;
+  const s = fit === "contain"
+    ? Math.min(boxW / imgW, boxH / imgH)
+    : Math.max(boxW / imgW, boxH / imgH);
+
+  dw = imgW * s;
+  dh = imgH * s;
+
+  const cx = boxX + (boxW - dw) / 2;
+  const cy = boxY + (boxH - dh) / 2;
+
+  switch (align) {
+    case "top-left":     dx = boxX;         dy = boxY;          break;
+    case "top":          dx = cx;           dy = boxY;          break;
+    case "top-right":    dx = boxX + boxW - dw; dy = boxY;      break;
+    case "left":         dx = boxX;         dy = cy;            break;
+    case "center":       dx = cx;           dy = cy;            break;
+    case "right":        dx = boxX + boxW - dw; dy = cy;        break;
+    case "bottom-left":  dx = boxX;         dy = boxY + boxH - dh; break;
+    case "bottom":       dx = cx;           dy = boxY + boxH - dh; break;
+    case "bottom-right": dx = boxX + boxW - dw; dy = boxY + boxH - dh; break;
+    default:             dx = cx;           dy = cy;            break;
   }
 
-  ctx.restore();
+  return { dx, dy, dw, dh, sx, sy, sw, sh };
 }
 
-function drawHeart(ctx: SKRSContext2D, x: number, y: number, width: number, height: number): void {
-  ctx.beginPath();
-
-  ctx.moveTo(x + width / 2, y + height * 0.9);
-
-  ctx.bezierCurveTo(
-    x + (width * 35) / 100, y + (height * 60) / 100,
-    x + (width * 10) / 100, y + (height * 55) / 100,
-    x + (width * 10) / 100, y + (height * 33.33) / 100
-  );
 
-  ctx.bezierCurveTo(
-    x + (width * 10) / 100, y + (height * 10) / 100,
-    x + (width * 50) / 100, y + (height * 5) / 100,
-    x + (width * 50) / 100, y + (height * 33.33) / 100
-  );
-
-  ctx.bezierCurveTo(
-    x + (width * 50) / 100, y + (height * 5) / 100,
-    x + (width * 90) / 100, y + (height * 10) / 100,
-    x + (width * 90) / 100, y + (height * 33.33) / 100
-  );
+// utils/imageCache.ts
+import { loadImage, type Image } from "@napi-rs/canvas";
+import path from "path";
 
-  ctx.bezierCurveTo(
-    x + (width * 90) / 100, y + (height * 55) / 100,
-    x + (width * 65) / 100, y + (height * 60) / 100,
-    x + width / 2, y + height * 0.9
-  );
+const cache = new Map<string, Promise<Image>>();
 
-  ctx.closePath();
+export function loadImageCached(src: string | Buffer): Promise<Image> {
+  if (Buffer.isBuffer(src)) return loadImage(src);
+  const key = src.startsWith("http") ? src : path.resolve(process.cwd(), src);
+  if (!cache.has(key)) cache.set(key, loadImage(key));
+  return cache.get(key)!;
 }
 
 
-/** Draws a polygon with a given number of sides */
-function drawPolygon(ctx: SKRSContext2D, x: number, y: number, width: number, height: number, sides: number): void {
-  const cx = x + width / 2;
-  const cy = y + height / 2;
-  const radius = Math.min(width, height) / 2;
-  ctx.moveTo(cx + radius, cy);
-  for (let i = 1; i <= sides; i++) {
-    const angle = (Math.PI * 2 * i) / sides;
-    ctx.lineTo(cx + radius * Math.cos(angle), cy + radius * Math.sin(angle));
-  }
-  ctx.closePath();
-}
+// utils/drawPasses.ts
 
-function drawArrow(ctx: SKRSContext2D, x: number, y: number, width: number, height: number) {
-  const shaftWidth = width * 0.25;
-  const headWidth = width * 0.5;
-  const headHeight = height * 0.6;
+import type { BoxBackground, ShadowOptions, StrokeOptions, gradient } from "../types";
 
-  ctx.beginPath();
+/** Shadow pass (independent) — supports solid color or gradient fill */
+// Shared rect type
+type Rect = { x: number; y: number; w: number; h: number };
 
-  ctx.moveTo(x, y + height / 2 - shaftWidth / 2);
-  ctx.lineTo(x + width - headWidth, y + height / 2 - shaftWidth / 2);
-  ctx.lineTo(x + width - headWidth, y);
+/* ---------------------------------------------
+   SHADOW — overloaded to support both call styles
+   --------------------------------------------- */
 
-  ctx.lineTo(x + width, y + height / 2);
-  
-  ctx.lineTo(x + width - headWidth, y + height);
-  ctx.lineTo(x + width - headWidth, y + height / 2 + shaftWidth / 2);
+// Overload 1: rect-first (new style)
+export function applyShadow(
+  ctx: SKRSContext2D,
+  rect: Rect,
+  shadow?: ShadowOptions
+): void;
 
-  ctx.lineTo(x, y + height / 2 + shaftWidth / 2);
-  ctx.closePath();
-}
+// Overload 2: positional (legacy createCanvas style)
+export function applyShadow(
+  ctx: SKRSContext2D,
+  shadow: ShadowOptions | undefined,
+  x: number, y: number, width: number, height: number,
+  borderRadius?: number | "circular",
+  borderPosition?: borderPosition
+): void;
 
+// Single implementation handling both
+export function applyShadow(
+  ctx: SKRSContext2D,
+  a: any,
+  b?: any,
+  c?: any, d?: any, e?: any, f?: any, g?: any
+): void {
+  let rect: Rect;
+  let shadow: ShadowOptions | undefined;
+  let radius: number | "circular" | undefined;
+  let borderPos: borderPosition | undefined;
+
+  // Detect which overload we’re in
+  if (typeof a === "object" && "x" in a && "w" in a) {
+    // (ctx, rect, shadow)
+    rect = a as Rect;
+    shadow = b as ShadowOptions | undefined;
+    radius = shadow?.borderRadius ?? 0;
+    borderPos = shadow?.borderPosition ?? "all";
+  } else {
+    // (ctx, shadow, x, y, w, h, radius?, borderPos?)
+    shadow = a as ShadowOptions | undefined;
+    rect = { x: b as number, y: c as number, w: d as number, h: e as number };
+    radius = (f as number | "circular") ?? shadow?.borderRadius ?? 0;
+    borderPos = (g as borderPosition) ?? shadow?.borderPosition ?? "all";
+  }
 
-function drawStar(ctx: SKRSContext2D, x: number, y: number, width: number, height: number): void {
-  const cx = x + width / 2;
-  const cy = y + height / 2;
-  
-  const size = Math.min(width, height); 
+  if (!shadow) return;
 
-  const outerRadius = size / 2;
-  const innerRadius = outerRadius * 0.5; 
-  const rotationOffset = -Math.PI / 2;
+  const {
+    color = "rgba(0,0,0,1)",
+    gradient,
+    opacity = 0.4,
+    offsetX = 0,
+    offsetY = 0,
+    blur = 20
+  } = shadow;
 
-  ctx.beginPath();
+  const r = { x: rect.x + offsetX, y: rect.y + offsetY, w: rect.w, h: rect.h };
+
+  ctx.save();
+  ctx.globalAlpha = opacity;
+  if (blur > 0) ctx.filter = `blur(${blur}px)`;
 
-  for (let i = 0; i < 5; i++) {
-    let angle = (i * (Math.PI * 2)) / 5 + rotationOffset;
-    ctx.lineTo(cx + outerRadius * Math.cos(angle), cy + outerRadius * Math.sin(angle));
+  buildPath(ctx, r.x, r.y, r.w, r.h, radius!, borderPos!);
 
-    angle += Math.PI / 5;
-    ctx.lineTo(cx + innerRadius * Math.cos(angle), cy + innerRadius * Math.sin(angle));
+  if (gradient) {
+    const gfill = createGradientFill(ctx, gradient, r);
+    ctx.fillStyle = gfill;
+  } else {
+    ctx.fillStyle = color;
   }
+  ctx.fill();
 
-  ctx.closePath();
+  ctx.filter = "none";
+  ctx.globalAlpha = 1;
+  ctx.restore();
 }
 
-export function createGradient(
-  ctx: any,
-  gradientOptions: any,
-  startX: number,
-  startY: number,
-  endX: number,
-  endY: number
-) {
-  if (!gradientOptions || !gradientOptions.type || !gradientOptions.colors) {
-    throw new Error(
-      "Invalid gradient options. Provide a valid object with type and colors properties."
-    );
-  }
 
-  if (!Array.isArray(gradientOptions.colors)) {
-    throw new Error(
-      "Invalid gradient options. The colors property should be an array of color stops."
-    );
-  }
+/* ---------------------------------------------
+   STROKE — overloaded to support both call styles
+   --------------------------------------------- */
 
-  if (gradientOptions.type === "linear") {
-    if (
-      typeof startX !== "number" ||
-      typeof startY !== "number" ||
-      typeof endX !== "number" ||
-      typeof endY !== "number"
-    ) {
-      throw new Error(
-        "Invalid gradient options for linear gradient. Numeric values are required for startX, startY, endX, and endY."
-      );
-    }
-
-    if (typeof gradientOptions.rotate === "number") {
-      const centerX = (startX + endX) / 2;
-      const centerY = (startY + endY) / 2;
-      const dx = endX - startX;
-      const dy = endY - startY;
-      const length = Math.sqrt(dx * dx + dy * dy);
-      const angleRad = (gradientOptions.rotate * Math.PI) / 180;
-
-      startX = centerX - (length / 2) * Math.cos(angleRad);
-      startY = centerY - (length / 2) * Math.sin(angleRad);
-      endX = centerX + (length / 2) * Math.cos(angleRad);
-      endY = centerY + (length / 2) * Math.sin(angleRad);
-    }
-
-    const gradient = ctx.createLinearGradient(startX, startY, endX, endY);
-
-    for (const colorStop of gradientOptions.colors) {
-      if (
-        typeof colorStop.stop !== "number" ||
-        typeof colorStop.color !== "string"
-      ) {
-        throw new Error(
-          "Invalid color stop. Each color stop should have a numeric stop value and a color string."
-        );
-      }
-      gradient.addColorStop(colorStop.stop, colorStop.color);
-    }
-
-    return gradient;
-  } else if (gradientOptions.type === "radial") {
-    if (
-      typeof gradientOptions.startX !== "number" ||
-      typeof gradientOptions.startY !== "number" ||
-      typeof gradientOptions.startRadius !== "number" ||
-      typeof gradientOptions.endX !== "number" ||
-      typeof gradientOptions.endY !== "number" ||
-      typeof gradientOptions.endRadius !== "number"
-    ) {
-      throw new Error(
-        "Invalid gradient options for radial gradient. Numeric values are required for startX, startY, startRadius, endX, endY, and endRadius."
-      );
-    }
-
-    const gradient = ctx.createRadialGradient(
-      gradientOptions.startX,
-      gradientOptions.startY,
-      gradientOptions.startRadius,
-      gradientOptions.endX,
-      gradientOptions.endY,
-      gradientOptions.endRadius
-    );
-
-    for (const colorStop of gradientOptions.colors) {
-      if (
-        typeof colorStop.stop !== "number" ||
-        typeof colorStop.color !== "string"
-      ) {
-        throw new Error(
-          "Invalid color stop. Each color stop should have a numeric stop value and a color string."
-        );
-      }
-      gradient.addColorStop(colorStop.stop, colorStop.color);
-    }
-
-    return gradient;
-  } else {
-    throw new Error('Unsupported gradient type. Use "linear" or "radial".');
-  }
-}
+// Overload 1: rect-first (new style)
+export function applyStroke(
+  ctx: SKRSContext2D,
+  rect: Rect,
+  stroke?: StrokeOptions
+): void;
 
+// Overload 2: positional (legacy createCanvas style)
+export function applyStroke(
+  ctx: SKRSContext2D,
+  stroke: StrokeOptions | undefined,
+  x: number, y: number, width: number, height: number,
+  borderRadius?: number | "circular",
+  borderPosition?: borderPosition
+): void;
 
-/**
- * Applies rotation to the canvas context.
- * @param ctx The canvas rendering context.
- * @param rotation The rotation angle in degrees.
- * @param x The x-coordinate of the center of rotation.
- * @param y The y-coordinate of the center of rotation.
- * @param width The width of the shape.
- * @param height The height of the shape.
- */
-export function applyRotation(
-    ctx: SKRSContext2D,
-    rotation: number,
-    x: number,
-    y: number,
-    width: number,
-    height: number
-  ): void {
-    const rotationX = x + width / 2;
-    const rotationY = y + height / 2;
-    ctx.translate(rotationX, rotationY);
-    ctx.rotate((rotation * Math.PI) / 180);
-    ctx.translate(-rotationX, -rotationY);
-  }
-  
-  /**
-   * Applies border radius to the canvas context with selective corner support.
-   *
-   * @param ctx The canvas rendering context.
-   * @param image The image to be drawn (will be drawn after clipping).
-   * @param x The x-coordinate of the shape.
-   * @param y The y-coordinate of the shape.
-   * @param width The width of the shape.
-   * @param height The height of the shape.
-   * @param borderRadius The border radius value (number or "circular").
-   * @param borderPosition The sides or corners to round.
-   *   Valid values include:
-   *     - "all"
-   *     - "top", "bottom", "left", "right"
-   *     - "top-left", "top-right", "bottom-left", "bottom-right"
-   *     - Or a comma‑separated list (e.g., "top, left, bottom")
-   */
-  export function imageRadius(
-    ctx: SKRSContext2D,
-    image: any,
-    x: number,
-    y: number,
-    width: number,
-    height: number,
-    borderRadius: number | "circular",
-    borderPosition: string = "all"
-  ): void {
-    ctx.save();
-    ctx.beginPath();
-  
-    if (borderRadius === "circular") {
-      const circleRadius = Math.min(width, height) / 2;
-      ctx.arc(x + width / 2, y + height / 2, circleRadius, 0, 2 * Math.PI);
-      ctx.clip();
-    } else if (typeof borderRadius === "number" && borderRadius > 0) {
-      const br: number = Math.min(borderRadius, width / 2, height / 2);
-      const selectedPositions = new Set(borderPosition.toLowerCase().split(",").map((s) => s.trim()));
-  
-      const roundTopLeft = selectedPositions.has("all") || selectedPositions.has("top-left") || (selectedPositions.has("top") && selectedPositions.has("left"));
-      const roundTopRight = selectedPositions.has("all") || selectedPositions.has("top-right") || (selectedPositions.has("top") && selectedPositions.has("right"));
-      const roundBottomRight = selectedPositions.has("all") || selectedPositions.has("bottom-right") || (selectedPositions.has("bottom") && selectedPositions.has("right"));
-      const roundBottomLeft = selectedPositions.has("all") || selectedPositions.has("bottom-left") || (selectedPositions.has("bottom") && selectedPositions.has("left"));
-  
-      const tl = roundTopLeft ? br : 0;
-      const tr = roundTopRight ? br : 0;
-      const brR = roundBottomRight ? br : 0;
-      const bl = roundBottomLeft ? br : 0;
-  
-      ctx.moveTo(x + tl, y);
-      ctx.lineTo(x + width - tr, y);
-      if (tr > 0) ctx.arc(x + width - tr, y + tr, tr, -Math.PI / 2, 0, false);
-      ctx.lineTo(x + width, y + height - brR);
-      if (brR > 0) ctx.arc(x + width - brR, y + height - brR, brR, 0, Math.PI / 2, false);
-      ctx.lineTo(x + bl, y + height);
-      if (bl > 0) ctx.arc(x + bl, y + height - bl, bl, Math.PI / 2, Math.PI, false);
-      ctx.lineTo(x, y + tl);
-      if (tl > 0) ctx.arc(x + tl, y + tl, tl, Math.PI, -Math.PI / 2, false);
-  
-      ctx.closePath();
-      ctx.clip();
-    } else {
-      ctx.rect(x, y, width, height);
-      ctx.clip();
-    }
-  
-    ctx.drawImage(image, x, y, width, height);
-  
-    ctx.restore();
-  }
-  
-    
-  
-/**
- * Creates a rounded rectangle (or circular) path on the canvas context.
- * 
- * @param ctx The canvas rendering context.
- * @param x The x-coordinate of the rectangle.
- * @param y The y-coordinate of the rectangle.
- * @param width The width of the rectangle.
- * @param height The height of the rectangle.
- * @param borderRadius The radius for rounding. Use a number (or string "circular" for a circle).
- * @param borderPosition Which sides/corners to round. Valid values include:
- *   - "all" (default)
- *   - "top", "bottom", "left", "right"
- *   - "top-left", "top-right", "bottom-left", "bottom-right"
- *   - Or a comma-separated list, e.g. "top-left, bottom-right" or "top, left, bottom"
- */
-export function objectRadius(
+// Single implementation handling both
+export function applyStroke(
   ctx: SKRSContext2D,
-  x: number,
-  y: number,
-  width: number,
-  height: number,
-  borderRadius: number | "circular" = 0.1,
-  borderPosition: string = "all"
+  a: any,
+  b?: any,
+  c?: any, d?: any, e?: any, f?: any, g?: any
 ): void {
-  ctx.beginPath();
-
-  if (borderRadius === "circular") {
-    // Draw a circular shape
-    const circleRadius = Math.min(width, height) / 2;
-    ctx.arc(x + width / 2, y + height / 2, circleRadius, 0, 2 * Math.PI);
-  } else if (borderRadius > 0) {
-    const br: number = Math.min(borderRadius, width / 2, height / 2);
-    const selectedPositions = new Set(
-      borderPosition.toLowerCase().split(",").map((s) => s.trim())
-    );
-
-    // **Correct Grouping**
-    const roundTopLeft = selectedPositions.has("all") ||
-      selectedPositions.has("top-left") ||
-      selectedPositions.has("top") ||
-      selectedPositions.has("left");
-
-    const roundTopRight = selectedPositions.has("all") ||
-      selectedPositions.has("top-right") ||
-      selectedPositions.has("top") ||
-      selectedPositions.has("right");
-
-    const roundBottomRight = selectedPositions.has("all") ||
-      selectedPositions.has("bottom-right") ||
-      selectedPositions.has("bottom") ||
-      selectedPositions.has("right");
-
-    const roundBottomLeft = selectedPositions.has("all") ||
-      selectedPositions.has("bottom-left") ||
-      selectedPositions.has("bottom") ||
-      selectedPositions.has("left");
-
-    // **Assign correct radii**
-    const tl = roundTopLeft ? br : 0;
-    const tr = roundTopRight ? br : 0;
-    const brR = roundBottomRight ? br : 0;
-    const bl = roundBottomLeft ? br : 0;
-
-    // **Draw rounded rectangle**
-    ctx.moveTo(x + tl, y);
-    ctx.lineTo(x + width - tr, y);
-    if (tr > 0) ctx.arc(x + width - tr, y + tr, tr, -Math.PI / 2, 0, false);
-    ctx.lineTo(x + width, y + height - brR);
-    if (brR > 0) ctx.arc(x + width - brR, y + height - brR, brR, 0, Math.PI / 2, false);
-    ctx.lineTo(x + bl, y + height);
-    if (bl > 0) ctx.arc(x + bl, y + height - bl, bl, Math.PI / 2, Math.PI, false);
-    ctx.lineTo(x, y + tl);
-    if (tl > 0) ctx.arc(x + tl, y + tl, tl, Math.PI, -Math.PI / 2, false);
+  let rect: Rect;
+  let stroke: StrokeOptions | undefined;
+  let radius: number | "circular" | undefined;
+  let borderPos: borderPosition | undefined;
+
+  if (typeof a === "object" && "x" in a && "w" in a) {
+    // (ctx, rect, stroke)
+    rect = a as Rect;
+    stroke = b as StrokeOptions | undefined;
+    radius = stroke?.borderRadius ?? 0;
+    borderPos = stroke?.borderPosition ?? "all";
   } else {
-    // Default: Draw normal rectangle
-    ctx.rect(x, y, width, height);
+    // (ctx, stroke, x, y, w, h, radius?, borderPos?)
+    stroke = a as StrokeOptions | undefined;
+    rect = { x: b as number, y: c as number, w: d as number, h: e as number };
+    radius = (f as number | "circular") ?? stroke?.borderRadius ?? 0;
+    borderPos = (g as borderPosition) ?? stroke?.borderPosition ?? "all";
   }
 
-  ctx.closePath();
-}
-
-  
+  if (!stroke) return;
 
-  /**
- * Performs bilinear interpolation on four corners.
- * @param corners The four corners (topLeft, topRight, bottomRight, bottomLeft).
- * @param t Horizontal interpolation factor (0 to 1).
- * @param u Vertical interpolation factor (0 to 1).
- * @returns The interpolated point.
- */
-function bilinearInterpolate(corners: [{ x: number, y: number }, { x: number, y: number }, { x: number, y: number }, { x: number, y: number }], t: number, u: number): { x: number, y: number } {
-  const top: { x: number, y: number } = {
-    x: corners[0].x * (1 - t) + corners[1].x * t,
-    y: corners[0].y * (1 - t) + corners[1].y * t,
-  };
-  const bottom: { x: number, y: number } = {
-    x: corners[3].x * (1 - t) + corners[2].x * t,
-    y: corners[3].y * (1 - t) + corners[2].y * t,
-  };
-  return {
-    x: top.x * (1 - u) + bottom.x * u,
-    y: top.y * (1 - u) + bottom.y * u,
+  const {
+    color = "#000",
+    gradient,
+    width = 2,
+    position = 0,
+    blur = 0,
+    opacity = 1
+  } = stroke;
+
+  // expand/shrink by `position`
+  const r = {
+    x: rect.x - position,
+    y: rect.y - position,
+    w: rect.w + position * 2,
+    h: rect.h + position * 2
   };
+
+  ctx.save();
+  if (blur > 0) ctx.filter = `blur(${blur}px)`;
+  ctx.globalAlpha = opacity;
+
+  buildPath(ctx, r.x, r.y, r.w, r.h, radius!, borderPos!);
+
+  ctx.lineWidth = width;
+
+  if (gradient) {
+    const gstroke = createGradientFill(ctx, gradient, r);
+    ctx.strokeStyle = gstroke as any;
+  } else {
+    ctx.strokeStyle = color;
+  }
+  ctx.stroke();
+
+  ctx.filter = "none";
+  ctx.globalAlpha = 1;
+  ctx.restore();
 }
 
-/**
- * Applies a perspective warp to the given image by subdividing the source rectangle 
- * and drawing each cell with an affine transform approximating the local perspective.
- *
- * @param ctx The canvas rendering context.
- * @param image The source image.
- * @param x The x-coordinate where the image is drawn.
- * @param y The y-coordinate where the image is drawn.
- * @param width The width of the region to draw.
- * @param height The height of the region to draw.
- * @param perspective An object containing four destination corners:
- *                    { topLeft, topRight, bottomRight, bottomLeft }.
- * @param gridCols Number of columns to subdivide (default: 10).
- * @param gridRows Number of rows to subdivide (default: 10).
- */
-export async function applyPerspective(
+/** Optional “box background” under the bitmap, inside the image clip */
+export function drawBoxBackground(
   ctx: SKRSContext2D,
-  image: Image,
-  x: number,
-  y: number,
-  width: number,
-  height: number,
-  perspective: { topLeft: { x: number, y: number }; topRight: { x: number, y: number }; bottomRight: { x: number, y: number }; bottomLeft: { x: number, y: number }; },
-  gridCols: number = 10,
-  gridRows: number = 10
-): Promise<void> {
-  const cellWidth = width / gridCols;
-  const cellHeight = height / gridRows;
-
-  for (let row = 0; row < gridRows; row++) {
-    for (let col = 0; col < gridCols; col++) {
-      const sx = x + col * cellWidth;
-      const sy = y + row * cellHeight;
-
-      const t0 = col / gridCols;
-      const t1 = (col + 1) / gridCols;
-      const u0 = row / gridRows;
-      const u1 = (row + 1) / gridRows;
-
-      const destTL = bilinearInterpolate(
-        [perspective.topLeft, perspective.topRight, perspective.bottomRight, perspective.bottomLeft],
-        t0,
-        u0
-      );
-      const destTR = bilinearInterpolate(
-        [perspective.topLeft, perspective.topRight, perspective.bottomRight, perspective.bottomLeft],
-        t1,
-        u0
-      );
-      const destBL = bilinearInterpolate(
-        [perspective.topLeft, perspective.topRight, perspective.bottomRight, perspective.bottomLeft],
-        t0,
-        u1
-      );
-
-      const a = (destTR.x - destTL.x) / cellWidth;
-      const b = (destTR.y - destTL.y) / cellWidth;
-      const c = (destBL.x - destTL.x) / cellHeight;
-      const d = (destBL.y - destTL.y) / cellHeight;
-      const e = destTL.x;
-      const f = destTL.y;
-
-      ctx.save();
-      ctx.setTransform(a, b, c, d, e, f);
-      ctx.drawImage(image, sx, sy, cellWidth, cellHeight, 0, 0, cellWidth, cellHeight);
-      ctx.restore();
-    }
+  rect: { x: number; y: number; w: number; h: number },
+  boxBg?: BoxBackground,
+  borderRadius?: number | "circular",
+  borderPosition?: string
+) {
+  if (!boxBg) return;
+  const { color, gradient } = boxBg;
+
+  // clip to the box radius, then fill
+  ctx.save();
+  buildPath(ctx, rect.x, rect.y, rect.w, rect.h, borderRadius ?? 0, borderPosition ?? "all");
+  ctx.clip();
+
+  if (gradient) {
+    const g = createGradientFill(ctx, gradient, rect);
+    ctx.fillStyle = g as any;
+    ctx.fillRect(rect.x, rect.y, rect.w, rect.h);
+  } else if (color && color !== "transparent") {
+    ctx.fillStyle = color;
+    ctx.fillRect(rect.x, rect.y, rect.w, rect.h);
   }
-}
+
+  ctx.restore();
+}