@twick/canvas 0.15.14 → 0.15.15

package/dist/index.js

@@ -53,7 +53,11 @@ const CANVAS_OPERATIONS = {
   /** Caption properties have been updated */
   CAPTION_PROPS_UPDATED: "CAPTION_PROPS_UPDATED",
   /** Watermark has been updated */
-  WATERMARK_UPDATED: "WATERMARK_UPDATED"
+  WATERMARK_UPDATED: "WATERMARK_UPDATED",
+  /** A new element was added via drop on canvas; payload is { element } */
+  ADDED_NEW_ELEMENT: "ADDED_NEW_ELEMENT",
+  /** Z-order changed (bring to front / send to back). Payload is { elementId, direction }. Timeline should reorder tracks. */
+  Z_ORDER_CHANGED: "Z_ORDER_CHANGED"
 };
 const ELEMENT_TYPES = {
   /** Text element type */
@@ -163,6 +167,49 @@ const reorderElementsByZIndex = (canvas) => {
   objects.forEach((obj) => canvas.add(obj));
   canvas.renderAll();
 };
+const changeZOrder = (canvas, elementId, direction) => {
+  var _a, _b;
+  if (!canvas) return null;
+  const objects = canvas.getObjects();
+  const sorted = [...objects].sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+  const idx = sorted.findIndex((obj2) => {
+    var _a2;
+    return ((_a2 = obj2.get) == null ? void 0 : _a2.call(obj2, "id")) === elementId;
+  });
+  if (idx < 0) return null;
+  const minZ = ((_a = sorted[0]) == null ? void 0 : _a.zIndex) ?? 0;
+  const maxZ = ((_b = sorted[sorted.length - 1]) == null ? void 0 : _b.zIndex) ?? 0;
+  const obj = sorted[idx];
+  if (direction === "front") {
+    obj.set("zIndex", maxZ + 1);
+    reorderElementsByZIndex(canvas);
+    return maxZ + 1;
+  }
+  if (direction === "back") {
+    obj.set("zIndex", minZ - 1);
+    reorderElementsByZIndex(canvas);
+    return minZ - 1;
+  }
+  if (direction === "forward" && idx < sorted.length - 1) {
+    const next = sorted[idx + 1];
+    const myZ = obj.zIndex ?? idx;
+    const nextZ = next.zIndex ?? idx + 1;
+    obj.set("zIndex", nextZ);
+    next.set("zIndex", myZ);
+    reorderElementsByZIndex(canvas);
+    return nextZ;
+  }
+  if (direction === "backward" && idx > 0) {
+    const prev = sorted[idx - 1];
+    const myZ = obj.zIndex ?? idx;
+    const prevZ = prev.zIndex ?? idx - 1;
+    obj.set("zIndex", prevZ);
+    prev.set("zIndex", myZ);
+    reorderElementsByZIndex(canvas);
+    return prevZ;
+  }
+  return obj.zIndex ?? idx;
+};
 const getCanvasContext = (canvas) => {
   var _a, _b, _c, _d;
   if (!canvas || !((_b = (_a = canvas.elements) == null ? void 0 : _a.lower) == null ? void 0 : _b.ctx)) return;
@@ -183,12 +230,31 @@ const convertToCanvasPosition = (x, y, canvasMetadata) => {
     y: y * canvasMetadata.scaleY + canvasMetadata.height / 2
   };
 };
+const getObjectCanvasCenter = (obj) => {
+  if (obj.getCenterPoint) {
+    const p = obj.getCenterPoint();
+    return { x: p.x, y: p.y };
+  }
+  return { x: obj.left ?? 0, y: obj.top ?? 0 };
+};
+const getObjectCanvasAngle = (obj) => {
+  if (typeof obj.getTotalAngle === "function") {
+    return obj.getTotalAngle();
+  }
+  return obj.angle ?? 0;
+};
 const convertToVideoPosition = (x, y, canvasMetadata, videoSize) => {
   return {
     x: Number((x / canvasMetadata.scaleX - videoSize.width / 2).toFixed(2)),
     y: Number((y / canvasMetadata.scaleY - videoSize.height / 2).toFixed(2))
   };
 };
+const convertToVideoDimensions = (widthCanvas, heightCanvas, canvasMetadata) => {
+  return {
+    width: Number((widthCanvas / canvasMetadata.scaleX).toFixed(2)),
+    height: Number((heightCanvas / canvasMetadata.scaleY).toFixed(2))
+  };
+};
 const getCurrentFrameEffect = (item, seekTime) => {
   var _a;
   let currentFrameEffect;
@@ -722,7 +788,8 @@ const setImageProps = ({
   img,
   element,
   index,
-  canvasMetadata
+  canvasMetadata,
+  lockAspectRatio = true
 }) => {
   var _a, _b, _c, _d, _e;
   const width = (((_a = element.props) == null ? void 0 : _a.width) || 0) * canvasMetadata.scaleX || canvasMetadata.width;
@@ -742,13 +809,15 @@ const setImageProps = ({
   img.set("selectable", true);
   img.set("hasControls", true);
   img.set("touchAction", "all");
+  img.set("lockUniScaling", lockAspectRatio);
 };
 const addCaptionElement = ({
   element,
   index,
   canvas,
   captionProps,
-  canvasMetadata
+  canvasMetadata,
+  lockAspectRatio = false
 }) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J;
   const { x, y } = convertToCanvasPosition(
@@ -787,6 +856,7 @@ const addCaptionElement = ({
   });
   caption.set("id", element.id);
   caption.set("zIndex", index);
+  caption.set("lockUniScaling", lockAspectRatio);
   caption.controls.mt = disabledControl;
   caption.controls.mb = disabledControl;
   caption.controls.ml = disabledControl;
@@ -834,7 +904,8 @@ const addImageElement = async ({
   index,
   canvas,
   canvasMetadata,
-  currentFrameEffect
+  currentFrameEffect,
+  lockAspectRatio = true
 }) => {
   try {
     const img = await fabric.FabricImage.fromURL(imageUrl || element.props.src || "");
@@ -843,7 +914,7 @@ const addImageElement = async ({
       originY: "center",
       lockMovementX: false,
       lockMovementY: false,
-      lockUniScaling: true,
+      lockUniScaling: lockAspectRatio,
       hasControls: false,
       selectable: false
     });
@@ -854,10 +925,11 @@ const addImageElement = async ({
         index,
         canvas,
         canvasMetadata,
-        currentFrameEffect
+        currentFrameEffect,
+        lockAspectRatio
       });
     } else {
-      setImageProps({ img, element, index, canvasMetadata });
+      setImageProps({ img, element, index, canvasMetadata, lockAspectRatio });
       canvas.add(img);
       return img;
     }
@@ -870,7 +942,8 @@ const addMediaGroup = ({
   index,
   canvas,
   canvasMetadata,
-  currentFrameEffect
+  currentFrameEffect,
+  lockAspectRatio = true
 }) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
   let frameSize;
@@ -959,6 +1032,7 @@ const addMediaGroup = ({
   group.controls.mtr = rotateControl;
   group.set("id", element.id);
   group.set("zIndex", index);
+  group.set("lockUniScaling", lockAspectRatio);
   canvas.add(group);
   return group;
 };
@@ -966,7 +1040,8 @@ const addRectElement = ({
   element,
   index,
   canvas,
-  canvasMetadata
+  canvasMetadata,
+  lockAspectRatio = false
 }) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
   const { x, y } = convertToCanvasPosition(
@@ -1004,6 +1079,7 @@ const addRectElement = ({
   });
   rect.set("id", element.id);
   rect.set("zIndex", index);
+  rect.set("lockUniScaling", lockAspectRatio);
   rect.controls.mtr = rotateControl;
   canvas.add(rect);
   return rect;
@@ -1012,9 +1088,10 @@ const addCircleElement = ({
   element,
   index,
   canvas,
-  canvasMetadata
+  canvasMetadata,
+  lockAspectRatio = true
 }) => {
-  var _a, _b, _c, _d, _e, _f;
+  var _a, _b, _c, _d, _e, _f, _g;
   const { x, y } = convertToCanvasPosition(
     ((_a = element.props) == null ? void 0 : _a.x) || 0,
     ((_b = element.props) == null ? void 0 : _b.y) || 0,
@@ -1030,7 +1107,9 @@ const addCircleElement = ({
     stroke: ((_e = element.props) == null ? void 0 : _e.stroke) || "#000000",
     strokeWidth: (((_f = element.props) == null ? void 0 : _f.lineWidth) || 0) * canvasMetadata.scaleX,
     originX: "center",
-    originY: "center"
+    originY: "center",
+    // Respect element opacity (0–1). Defaults to fully opaque.
+    opacity: ((_g = element.props) == null ? void 0 : _g.opacity) ?? 1
   });
   circle.controls.mt = disabledControl;
   circle.controls.mb = disabledControl;
@@ -1039,6 +1118,7 @@ const addCircleElement = ({
   circle.controls.mtr = disabledControl;
   circle.set("id", element.id);
   circle.set("zIndex", index);
+  circle.set("lockUniScaling", lockAspectRatio);
   canvas.add(circle);
   return circle;
 };
@@ -1108,19 +1188,23 @@ const VideoElement = {
     }
   },
   updateFromFabricObject(object, element, context) {
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
+    const scaledW = (object.width ?? 0) * (object.scaleX ?? 1);
+    const scaledH = (object.height ?? 0) * (object.scaleY ?? 1);
+    const { width: fw, height: fh } = convertToVideoDimensions(
+      scaledW,
+      scaledH,
+      context.canvasMetadata
+    );
+    const updatedFrameSize = [fw, fh];
     const currentFrameEffect = context.elementFrameMapRef.current[element.id];
-    let updatedFrameSize;
     if (currentFrameEffect) {
-      updatedFrameSize = [
-        currentFrameEffect.props.frameSize[0] * object.scaleX,
-        currentFrameEffect.props.frameSize[1] * object.scaleY
-      ];
       context.elementFrameMapRef.current[element.id] = {
         ...currentFrameEffect,
         props: {
@@ -1146,16 +1230,12 @@ const VideoElement = {
       };
     }
     const frame = element.frame;
-    updatedFrameSize = [
-      (frame.size[0] ?? 0) * object.scaleX,
-      (frame.size[1] ?? 0) * object.scaleY
-    ];
     return {
       element: {
         ...element,
         frame: {
           ...frame,
-          rotation: object.angle,
+          rotation: getObjectCanvasAngle(object),
           size: updatedFrameSize,
           x,
           y
@@ -1167,12 +1247,14 @@ const VideoElement = {
 const ImageElement = {
   name: ELEMENT_TYPES.IMAGE,
   async add(params) {
-    const { element, index, canvas, canvasMetadata } = params;
+    var _a;
+    const { element, index, canvas, canvasMetadata, lockAspectRatio } = params;
     await addImageElement({
       element,
       index,
       canvas,
-      canvasMetadata
+      canvasMetadata,
+      lockAspectRatio: lockAspectRatio ?? ((_a = element.props) == null ? void 0 : _a.lockAspectRatio)
     });
     if (element.timelineType === "scene") {
       await addBackgroundColor({
@@ -1184,21 +1266,24 @@ const ImageElement = {
     }
   },
   updateFromFabricObject(object, element, context) {
-    var _a, _b;
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
     const currentFrameEffect = context.elementFrameMapRef.current[element.id];
     if (object.type === "group") {
-      let updatedFrameSize;
+      const scaledW2 = (object.width ?? 0) * (object.scaleX ?? 1);
+      const scaledH2 = (object.height ?? 0) * (object.scaleY ?? 1);
+      const { width: fw, height: fh } = convertToVideoDimensions(
+        scaledW2,
+        scaledH2,
+        context.canvasMetadata
+      );
+      const updatedFrameSize = [fw, fh];
       if (currentFrameEffect) {
-        updatedFrameSize = [
-          currentFrameEffect.props.frameSize[0] * object.scaleX,
-          currentFrameEffect.props.frameSize[1] * object.scaleY
-        ];
         context.elementFrameMapRef.current[element.id] = {
           ...currentFrameEffect,
           props: {
@@ -1210,6 +1295,15 @@ const ImageElement = {
         return {
           element: {
             ...element,
+            // Keep the base frame in sync with the active frame effect
+            // so visualizer `Rect {...element.frame}` reflects the same size/position.
+            frame: element.frame ? {
+              ...element.frame,
+              rotation: getObjectCanvasAngle(object),
+              size: updatedFrameSize,
+              x,
+              y
+            } : element.frame,
             frameEffects: (element.frameEffects || []).map(
               (fe) => fe.id === (currentFrameEffect == null ? void 0 : currentFrameEffect.id) ? {
                 ...fe,
@@ -1224,16 +1318,12 @@ const ImageElement = {
         };
       }
       const frame = element.frame;
-      updatedFrameSize = [
-        (frame.size[0] ?? 0) * object.scaleX,
-        (frame.size[1] ?? 0) * object.scaleY
-      ];
       return {
         element: {
           ...element,
           frame: {
             ...frame,
-            rotation: object.angle,
+            rotation: getObjectCanvasAngle(object),
             size: updatedFrameSize,
             x,
             y
@@ -1241,14 +1331,21 @@ const ImageElement = {
         }
       };
     }
+    const scaledW = (object.width ?? 0) * (object.scaleX ?? 1);
+    const scaledH = (object.height ?? 0) * (object.scaleY ?? 1);
+    const { width, height } = convertToVideoDimensions(
+      scaledW,
+      scaledH,
+      context.canvasMetadata
+    );
     return {
       element: {
         ...element,
         props: {
           ...element.props,
-          rotation: object.angle,
-          width: (((_a = element.props) == null ? void 0 : _a.width) ?? 0) * object.scaleX,
-          height: (((_b = element.props) == null ? void 0 : _b.height) ?? 0) * object.scaleY,
+          rotation: getObjectCanvasAngle(object),
+          width,
+          height,
           x,
           y
         }
@@ -1259,19 +1356,22 @@ const ImageElement = {
 const RectElement = {
   name: ELEMENT_TYPES.RECT,
   async add(params) {
-    const { element, index, canvas, canvasMetadata } = params;
+    var _a;
+    const { element, index, canvas, canvasMetadata, lockAspectRatio } = params;
     await addRectElement({
       element,
       index,
       canvas,
-      canvasMetadata
+      canvasMetadata,
+      lockAspectRatio: lockAspectRatio ?? ((_a = element.props) == null ? void 0 : _a.lockAspectRatio)
     });
   },
   updateFromFabricObject(object, element, context) {
     var _a, _b;
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
@@ -1280,7 +1380,7 @@ const RectElement = {
         ...element,
         props: {
           ...element.props,
-          rotation: object.angle,
+          rotation: getObjectCanvasAngle(object),
           width: (((_a = element.props) == null ? void 0 : _a.width) ?? 0) * object.scaleX,
           height: (((_b = element.props) == null ? void 0 : _b.height) ?? 0) * object.scaleY,
           x,
@@ -1293,36 +1393,41 @@ const RectElement = {
 const CircleElement = {
   name: ELEMENT_TYPES.CIRCLE,
   async add(params) {
-    const { element, index, canvas, canvasMetadata } = params;
+    var _a;
+    const { element, index, canvas, canvasMetadata, lockAspectRatio } = params;
     await addCircleElement({
       element,
       index,
       canvas,
-      canvasMetadata
+      canvasMetadata,
+      lockAspectRatio: lockAspectRatio ?? ((_a = element.props) == null ? void 0 : _a.lockAspectRatio)
     });
   },
   updateFromFabricObject(object, element, context) {
-    var _a;
+    var _a, _b;
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
     const radius = Number(
       ((((_a = element.props) == null ? void 0 : _a.radius) ?? 0) * object.scaleX).toFixed(2)
     );
+    const opacity = object.opacity != null ? object.opacity : (_b = element.props) == null ? void 0 : _b.opacity;
     return {
       element: {
         ...element,
         props: {
           ...element.props,
-          rotation: object.angle,
+          rotation: getObjectCanvasAngle(object),
           radius,
           height: radius * 2,
           width: radius * 2,
           x,
-          y
+          y,
+          ...opacity != null && { opacity }
         }
       }
     };
@@ -1340,9 +1445,10 @@ const TextElement = {
     });
   },
   updateFromFabricObject(object, element, context) {
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
@@ -1351,7 +1457,7 @@ const TextElement = {
         ...element,
         props: {
           ...element.props,
-          rotation: object.angle,
+          rotation: getObjectCanvasAngle(object),
           x,
           y
         }
@@ -1362,20 +1468,23 @@ const TextElement = {
 const CaptionElement = {
   name: ELEMENT_TYPES.CAPTION,
   async add(params) {
-    const { element, index, canvas, captionProps, canvasMetadata } = params;
+    var _a;
+    const { element, index, canvas, captionProps, canvasMetadata, lockAspectRatio } = params;
     await addCaptionElement({
       element,
       index,
       canvas,
       captionProps: captionProps ?? {},
-      canvasMetadata
+      canvasMetadata,
+      lockAspectRatio: lockAspectRatio ?? ((_a = element.props) == null ? void 0 : _a.lockAspectRatio)
     });
   },
   updateFromFabricObject(object, element, context) {
     var _a;
+    const canvasCenter = getObjectCanvasCenter(object);
     const { x, y } = convertToVideoPosition(
-      object.left,
-      object.top,
+      canvasCenter.x,
+      canvasCenter.y,
       context.canvasMetadata,
       context.videoSize
     );
@@ -1481,7 +1590,15 @@ function registerElements() {
 registerElements();
 const useTwickCanvas = ({
   onCanvasReady,
-  onCanvasOperation
+  onCanvasOperation,
+  /**
+   * When true, holding Shift while dragging an object will lock movement to
+   * the dominant axis (horizontal or vertical). This mirrors behavior in
+   * professional editors and improves precise alignment.
+   *
+   * Default: false (opt‑in to avoid surprising existing consumers).
+   */
+  enableShiftAxisLock = false
 }) => {
   const [twickCanvas, setTwickCanvas] = react.useState(null);
   const elementMap = react.useRef({});
@@ -1491,6 +1608,7 @@ const useTwickCanvas = ({
   const videoSizeRef = react.useRef({ width: 1, height: 1 });
   const canvasResolutionRef = react.useRef({ width: 1, height: 1 });
   const captionPropsRef = react.useRef(null);
+  const axisLockStateRef = react.useRef(null);
   const canvasMetadataRef = react.useRef({
     width: 0,
     height: 0,
@@ -1505,6 +1623,57 @@ const useTwickCanvas = ({
       canvasMetadataRef.current.scaleY = canvasMetadataRef.current.height / videoSize.height;
     }
   };
+  const handleObjectMoving = (event) => {
+    var _a;
+    if (!enableShiftAxisLock) return;
+    const target = event == null ? void 0 : event.target;
+    const transform = event == null ? void 0 : event.transform;
+    const pointerEvent = event == null ? void 0 : event.e;
+    if (!target || !transform || !pointerEvent) {
+      axisLockStateRef.current = null;
+      return;
+    }
+    if (!pointerEvent.shiftKey) {
+      axisLockStateRef.current = null;
+      return;
+    }
+    const original = transform.original;
+    if (!original || typeof target.left !== "number" || typeof target.top !== "number") {
+      axisLockStateRef.current = null;
+      return;
+    }
+    if (!axisLockStateRef.current) {
+      const dx = Math.abs(target.left - original.left);
+      const dy = Math.abs(target.top - original.top);
+      axisLockStateRef.current = {
+        axis: dx >= dy ? "x" : "y"
+      };
+    }
+    if (axisLockStateRef.current.axis === "x") {
+      target.top = original.top;
+    } else {
+      target.left = original.left;
+    }
+    (_a = target.canvas) == null ? void 0 : _a.requestRenderAll();
+  };
+  const applyMarqueeSelectionControls = () => {
+    const canvasInstance = twickCanvasRef.current;
+    if (!canvasInstance) return;
+    const activeObject = canvasInstance.getActiveObject();
+    if (!activeObject) return;
+    if (activeObject instanceof fabric.ActiveSelection) {
+      activeObject.controls.mt = disabledControl;
+      activeObject.controls.mb = disabledControl;
+      activeObject.controls.ml = disabledControl;
+      activeObject.controls.mr = disabledControl;
+      activeObject.controls.bl = disabledControl;
+      activeObject.controls.br = disabledControl;
+      activeObject.controls.tl = disabledControl;
+      activeObject.controls.tr = disabledControl;
+      activeObject.controls.mtr = rotateControl;
+      canvasInstance.requestRenderAll();
+    }
+  };
   const buildCanvas = ({
     videoSize,
     canvasSize,
@@ -1524,6 +1693,9 @@ const useTwickCanvas = ({
     if (twickCanvasRef.current) {
       twickCanvasRef.current.off("mouse:up", handleMouseUp);
       twickCanvasRef.current.off("text:editing:exited", onTextEdit);
+      twickCanvasRef.current.off("object:moving", handleObjectMoving);
+      twickCanvasRef.current.off("selection:created", applyMarqueeSelectionControls);
+      twickCanvasRef.current.off("selection:updated", applyMarqueeSelectionControls);
       twickCanvasRef.current.dispose();
     }
     const { canvas, canvasMetadata } = createCanvas({
@@ -1541,6 +1713,9 @@ const useTwickCanvas = ({
     videoSizeRef.current = videoSize;
     canvas == null ? void 0 : canvas.on("mouse:up", handleMouseUp);
     canvas == null ? void 0 : canvas.on("text:editing:exited", onTextEdit);
+    canvas == null ? void 0 : canvas.on("object:moving", handleObjectMoving);
+    canvas == null ? void 0 : canvas.on("selection:created", applyMarqueeSelectionControls);
+    canvas == null ? void 0 : canvas.on("selection:updated", applyMarqueeSelectionControls);
     canvasResolutionRef.current = canvasSize;
     setTwickCanvas(canvas);
     twickCanvasRef.current = canvas;
@@ -1570,7 +1745,8 @@ const useTwickCanvas = ({
     if (event.target) {
       const object = event.target;
       const elementId = object.get("id");
-      if (((_a = event.transform) == null ? void 0 : _a.action) === "drag") {
+      const action = (_a = event.transform) == null ? void 0 : _a.action;
+      if (action === "drag") {
         const original = event.transform.original;
         if (object.left === original.left && object.top === original.top) {
           onCanvasOperation == null ? void 0 : onCanvasOperation(
@@ -1580,7 +1756,38 @@ const useTwickCanvas = ({
           return;
         }
       }
-      switch ((_b = event.transform) == null ? void 0 : _b.action) {
+      const context = {
+        canvasMetadata: canvasMetadataRef.current,
+        videoSize: videoSizeRef.current,
+        elementFrameMapRef: elementFrameMap,
+        captionPropsRef,
+        watermarkPropsRef
+      };
+      if (object instanceof fabric.ActiveSelection && (action === "drag" || action === "rotate")) {
+        const objects = object.getObjects();
+        for (const fabricObj of objects) {
+          const id = fabricObj.get("id");
+          if (!id || id === "e-watermark") continue;
+          const currentElement = elementMap.current[id];
+          if (!currentElement) continue;
+          const handler = elementController.get(currentElement.type);
+          const result = (_b = handler == null ? void 0 : handler.updateFromFabricObject) == null ? void 0 : _b.call(
+            handler,
+            fabricObj,
+            currentElement,
+            context
+          );
+          if (result) {
+            elementMap.current[id] = result.element;
+            onCanvasOperation == null ? void 0 : onCanvasOperation(
+              result.operation ?? CANVAS_OPERATIONS.ITEM_UPDATED,
+              result.payload ?? result.element
+            );
+          }
+        }
+        return;
+      }
+      switch (action) {
         case "drag":
         case "scale":
         case "scaleX":
@@ -1590,13 +1797,7 @@ const useTwickCanvas = ({
           const handler = elementController.get(
             elementId === "e-watermark" ? "watermark" : currentElement == null ? void 0 : currentElement.type
           );
-          const result = (_c = handler == null ? void 0 : handler.updateFromFabricObject) == null ? void 0 : _c.call(handler, object, currentElement ?? { id: elementId, type: "text", props: {} }, {
-            canvasMetadata: canvasMetadataRef.current,
-            videoSize: videoSizeRef.current,
-            elementFrameMapRef: elementFrameMap,
-            captionPropsRef,
-            watermarkPropsRef
-          });
+          const result = (_c = handler == null ? void 0 : handler.updateFromFabricObject) == null ? void 0 : _c.call(handler, object, currentElement ?? { id: elementId, type: "text", props: {} }, context);
           if (result) {
             elementMap.current[elementId] = result.element;
             onCanvasOperation == null ? void 0 : onCanvasOperation(
@@ -1614,7 +1815,8 @@ const useTwickCanvas = ({
     watermark,
     seekTime = 0,
     captionProps,
-    cleanAndAdd = false
+    cleanAndAdd = false,
+    lockAspectRatio
   }) => {
     if (!twickCanvas || !getCanvasContext(twickCanvas)) return;
     try {
@@ -1627,16 +1829,26 @@ const useTwickCanvas = ({
         }
       }
       captionPropsRef.current = captionProps;
+      const uniqueElements = [];
+      const seenIds = /* @__PURE__ */ new Set();
+      for (const el of elements) {
+        if (!el || !el.id) continue;
+        if (seenIds.has(el.id)) continue;
+        seenIds.add(el.id);
+        uniqueElements.push(el);
+      }
       await Promise.all(
-        elements.map(async (element, index) => {
+        uniqueElements.map(async (element, index) => {
           try {
             if (!element) return;
+            const zOrder = element.zIndex ?? index;
             await addElementToCanvas({
               element,
-              index,
+              index: zOrder,
               reorder: false,
               seekTime,
-              captionProps
+              captionProps,
+              lockAspectRatio
             });
           } catch {
           }
@@ -1656,8 +1868,10 @@ const useTwickCanvas = ({
     index,
     reorder = true,
     seekTime,
-    captionProps
+    captionProps,
+    lockAspectRatio
   }) => {
+    var _a;
     if (!twickCanvas) return;
     const handler = elementController.get(element.type);
     if (handler) {
@@ -1669,10 +1883,11 @@ const useTwickCanvas = ({
         seekTime,
         captionProps: captionProps ?? null,
         elementFrameMapRef: elementFrameMap,
-        getCurrentFrameEffect
+        getCurrentFrameEffect,
+        lockAspectRatio: lockAspectRatio ?? ((_a = element.props) == null ? void 0 : _a.lockAspectRatio)
       });
     }
-    elementMap.current[element.id] = element;
+    elementMap.current[element.id] = { ...element, zIndex: element.zIndex ?? index };
     if (reorder) {
       reorderElementsByZIndex(twickCanvas);
     }
@@ -1693,13 +1908,30 @@ const useTwickCanvas = ({
       elementMap.current[element.id] = element;
     }
   };
+  const applyZOrder = (elementId, direction) => {
+    if (!twickCanvas) return false;
+    const newZIndex = changeZOrder(twickCanvas, elementId, direction);
+    if (newZIndex == null) return false;
+    const element = elementMap.current[elementId];
+    if (element) elementMap.current[elementId] = { ...element, zIndex: newZIndex };
+    onCanvasOperation == null ? void 0 : onCanvasOperation(CANVAS_OPERATIONS.Z_ORDER_CHANGED, { elementId, direction });
+    return true;
+  };
+  const bringToFront = (elementId) => applyZOrder(elementId, "front");
+  const sendToBack = (elementId) => applyZOrder(elementId, "back");
+  const bringForward = (elementId) => applyZOrder(elementId, "forward");
+  const sendBackward = (elementId) => applyZOrder(elementId, "backward");
   return {
     twickCanvas,
     buildCanvas,
     onVideoSizeChange,
     addWatermarkToCanvas,
     addElementToCanvas,
-    setCanvasElements
+    setCanvasElements,
+    bringToFront,
+    sendToBack,
+    bringForward,
+    sendBackward
   };
 };
 exports.CANVAS_OPERATIONS = CANVAS_OPERATIONS;