@pooder/kit 6.2.0 → 6.2.2

package/dist/index.mjs

@@ -1192,967 +1192,1097 @@ import {
   controlsUtils
 } from "fabric";
 
-// src/extensions/geometry.ts
-import paper from "paper";
-
-// src/extensions/bridgeSelection.ts
-function pickExitIndex(hits) {
-  for (let i = 0; i < hits.length; i++) {
-    const h = hits[i];
-    if (h.insideBelow && !h.insideAbove) return i;
-  }
-  return -1;
+// src/shared/scene/frame.ts
+function emptyFrameRect() {
+  return { left: 0, top: 0, width: 0, height: 0 };
 }
-function scoreOutsideAbove(samples) {
-  let score = 0;
-  for (const s of samples) {
-    if (s.outsideAbove) score++;
+function resolveCutFrameRect(canvasService, configService) {
+  if (!canvasService || !configService) {
+    return emptyFrameRect();
   }
-  return score;
-}
-
-// src/extensions/wrappedOffsets.ts
-function wrappedDistance(total, start, end) {
-  if (!Number.isFinite(total) || total <= 0) return 0;
-  if (!Number.isFinite(start) || !Number.isFinite(end)) return 0;
-  const s = (start % total + total) % total;
-  const e = (end % total + total) % total;
-  return e >= s ? e - s : total - s + e;
-}
-function sampleWrappedOffsets(total, start, end, count) {
-  if (!Number.isFinite(total) || total <= 0) return [];
-  if (!Number.isFinite(start) || !Number.isFinite(end)) return [];
-  const n = Math.max(0, Math.floor(count));
-  if (n <= 0) return [];
-  const dist = wrappedDistance(total, start, end);
-  if (n === 1) return [(start % total + total) % total];
-  const step = dist / (n - 1);
-  const offsets = [];
-  for (let i = 0; i < n; i++) {
-    const raw = start + step * i;
-    const wrapped = (raw % total + total) % total;
-    offsets.push(wrapped);
+  const sizeState = readSizeState(configService);
+  const layout = computeSceneLayout(canvasService, sizeState);
+  if (!layout) {
+    return emptyFrameRect();
   }
-  return offsets;
+  return canvasService.toSceneRect({
+    left: layout.cutRect.left,
+    top: layout.cutRect.top,
+    width: layout.cutRect.width,
+    height: layout.cutRect.height
+  });
 }
-
-// src/extensions/geometry.ts
-function resolveFeaturePosition(feature, geometry) {
-  const { x, y, width, height } = geometry;
-  const left = x - width / 2;
-  const top = y - height / 2;
+function toLayoutSceneRect(rect) {
   return {
-    x: left + feature.x * width,
-    y: top + feature.y * height
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height,
+    space: "scene"
   };
 }
-function ensurePaper(width, height) {
-  if (!paper.project) {
-    paper.setup(new paper.Size(width, height));
-  } else {
-    paper.view.viewSize = new paper.Size(width, height);
-  }
-}
-var isBridgeDebugEnabled = () => Boolean(globalThis.__POODER_BRIDGE_DEBUG__);
-function normalizePathItem(shape) {
-  let result = shape;
-  if (typeof result.resolveCrossings === "function") result = result.resolveCrossings();
-  if (typeof result.reduce === "function") result = result.reduce({});
-  if (typeof result.reorient === "function") result = result.reorient(true, true);
-  if (typeof result.reduce === "function") result = result.reduce({});
-  return result;
-}
-function getBridgeDelta(itemBounds, overlap) {
-  return Math.max(overlap, Math.min(5, Math.max(1, itemBounds.height * 0.02)));
-}
-function getExitHit(args) {
-  const { mainShape, x, bridgeBottom, toY, eps, delta, overlap, op } = args;
-  const ray = new paper.Path.Line({
-    from: [x, bridgeBottom],
-    to: [x, toY],
-    insert: false
-  });
-  const intersections = mainShape.getIntersections(ray) || [];
-  ray.remove();
-  const validHits = intersections.filter((i) => i.point.y < bridgeBottom - eps);
-  if (validHits.length === 0) return null;
-  validHits.sort((a, b) => b.point.y - a.point.y);
-  const flags = validHits.map((h) => {
-    const above = h.point.add(new paper.Point(0, -delta));
-    const below = h.point.add(new paper.Point(0, delta));
-    return {
-      insideAbove: mainShape.contains(above),
-      insideBelow: mainShape.contains(below)
-    };
-  });
-  const idx = pickExitIndex(flags);
-  if (idx < 0) return null;
-  if (isBridgeDebugEnabled()) {
-    console.debug("Geometry: Bridge ray", {
-      x,
-      validHits: validHits.length,
-      idx,
-      delta,
-      overlap,
-      op
-    });
-  }
-  const hit = validHits[idx];
-  return { point: hit.point, location: hit };
+
+// src/shared/runtime/sessionState.ts
+function cloneWithJson(value) {
+  return JSON.parse(JSON.stringify(value));
 }
-function selectOuterChain(args) {
-  const { mainShape, pointsA, pointsB, delta, overlap, op } = args;
-  const scoreA = scoreOutsideAbove(
-    pointsA.map((p) => ({
-      outsideAbove: !mainShape.contains(p.add(new paper.Point(0, -delta)))
-    }))
-  );
-  const scoreB = scoreOutsideAbove(
-    pointsB.map((p) => ({
-      outsideAbove: !mainShape.contains(p.add(new paper.Point(0, -delta)))
-    }))
-  );
-  const ratioA = scoreA / pointsA.length;
-  const ratioB = scoreB / pointsB.length;
-  if (isBridgeDebugEnabled()) {
-    console.debug("Geometry: Bridge chain", {
-      scoreA,
-      scoreB,
-      lenA: pointsA.length,
-      lenB: pointsB.length,
-      ratioA,
-      ratioB,
-      delta,
-      overlap,
-      op
-    });
-  }
-  const ratioEps = 1e-6;
-  if (Math.abs(ratioA - ratioB) > ratioEps) {
-    return ratioA > ratioB ? pointsA : pointsB;
+function applyCommittedSnapshot(session, nextCommitted, options) {
+  const clone = options.clone;
+  session.committed = clone(nextCommitted);
+  const shouldPreserveDirtyWorking = options.toolActive && options.preserveDirtyWorking !== false && session.hasWorkingChanges;
+  if (!shouldPreserveDirtyWorking) {
+    session.working = clone(session.committed);
+    session.hasWorkingChanges = false;
   }
-  if (scoreA !== scoreB) return scoreA > scoreB ? pointsA : pointsB;
-  return pointsA.length <= pointsB.length ? pointsA : pointsB;
 }
-function fitPathItemToRect(item, rect, fitMode) {
-  const { left, top, width, height } = rect;
-  const bounds = item.bounds;
-  if (width <= 0 || height <= 0 || !Number.isFinite(bounds.width) || !Number.isFinite(bounds.height) || bounds.width <= 0 || bounds.height <= 0) {
-    item.position = new paper.Point(left + width / 2, top + height / 2);
-    return item;
-  }
-  item.translate(new paper.Point(-bounds.left, -bounds.top));
-  if (fitMode === "stretch") {
-    item.scale(width / bounds.width, height / bounds.height, new paper.Point(0, 0));
-    item.translate(new paper.Point(left, top));
-    return item;
+function runDeferredConfigUpdate(state, action, cooldownMs = 0) {
+  state.isUpdatingConfig = true;
+  action();
+  if (cooldownMs <= 0) {
+    state.isUpdatingConfig = false;
+    return;
   }
-  const uniformScale = Math.min(width / bounds.width, height / bounds.height);
-  item.scale(uniformScale, uniformScale, new paper.Point(0, 0));
-  const scaledWidth = bounds.width * uniformScale;
-  const scaledHeight = bounds.height * uniformScale;
-  item.translate(
-    new paper.Point(
-      left + (width - scaledWidth) / 2,
-      top + (height - scaledHeight) / 2
-    )
-  );
-  return item;
-}
-function createNormalizedHeartPath(params) {
-  const { lobeSpread, notchDepth, tipSharpness } = params;
-  const halfSpread = 0.22 + lobeSpread * 0.18;
-  const notchY = 0.06 + notchDepth * 0.2;
-  const shoulderY = 0.24 + notchDepth * 0.2;
-  const topLift = 0.12 + (1 - notchDepth) * 0.06;
-  const topY = notchY - topLift;
-  const sideCtrlY = shoulderY - (0.18 - notchDepth * 0.08);
-  const lowerCtrlY = 0.58 + (1 - tipSharpness) * 0.16;
-  const tipCtrlX = 0.34 - tipSharpness * 0.2;
-  const notchCtrlX = 0.06 + lobeSpread * 0.06;
-  const lobeCtrlX = 0.1 + lobeSpread * 0.08;
-  const notchCtrlY = notchY - topLift * 0.45;
-  const xPeakL = 0.5 - halfSpread;
-  const xPeakR = 0.5 + halfSpread;
-  const heartPath = new paper.Path({ insert: false });
-  heartPath.moveTo(new paper.Point(0.5, notchY));
-  heartPath.cubicCurveTo(
-    new paper.Point(0.5 - notchCtrlX, notchCtrlY),
-    new paper.Point(xPeakL + lobeCtrlX, topY),
-    new paper.Point(xPeakL, topY)
-  );
-  heartPath.cubicCurveTo(
-    new paper.Point(xPeakL - lobeCtrlX, topY),
-    new paper.Point(0, sideCtrlY),
-    new paper.Point(0, shoulderY)
-  );
-  heartPath.cubicCurveTo(
-    new paper.Point(0, lowerCtrlY),
-    new paper.Point(tipCtrlX, 1),
-    new paper.Point(0.5, 1)
-  );
-  heartPath.cubicCurveTo(
-    new paper.Point(1 - tipCtrlX, 1),
-    new paper.Point(1, lowerCtrlY),
-    new paper.Point(1, shoulderY)
-  );
-  heartPath.cubicCurveTo(
-    new paper.Point(1, sideCtrlY),
-    new paper.Point(xPeakR + lobeCtrlX, topY),
-    new paper.Point(xPeakR, topY)
-  );
-  heartPath.cubicCurveTo(
-    new paper.Point(xPeakR - lobeCtrlX, topY),
-    new paper.Point(0.5 + notchCtrlX, notchCtrlY),
-    new paper.Point(0.5, notchY)
-  );
-  heartPath.closed = true;
-  return heartPath;
+  setTimeout(() => {
+    state.isUpdatingConfig = false;
+  }, cooldownMs);
 }
-function createHeartBaseShape(options) {
-  const { x, y, width, height } = options;
-  const w = Math.max(0, width);
-  const h = Math.max(0, height);
-  const left = x - w / 2;
-  const top = y - h / 2;
-  const fitMode = getShapeFitMode(options.shapeStyle);
-  const heartParams = getHeartShapeParams(options.shapeStyle);
-  const rawHeart = createNormalizedHeartPath(heartParams);
-  return fitPathItemToRect(rawHeart, { left, top, width: w, height: h }, fitMode);
-}
-var BUILTIN_SHAPE_BUILDERS = {
-  rect: (options) => {
-    const { x, y, width, height, radius } = options;
-    return new paper.Path.Rectangle({
-      point: [x - width / 2, y - height / 2],
-      size: [Math.max(0, width), Math.max(0, height)],
-      radius: Math.max(0, radius)
-    });
-  },
-  circle: (options) => {
-    const { x, y, width, height } = options;
-    const r = Math.min(width, height) / 2;
-    return new paper.Path.Circle({
-      center: new paper.Point(x, y),
-      radius: Math.max(0, r)
-    });
-  },
-  ellipse: (options) => {
-    const { x, y, width, height } = options;
-    return new paper.Path.Ellipse({
-      center: new paper.Point(x, y),
-      radius: [Math.max(0, width / 2), Math.max(0, height / 2)]
-    });
-  },
-  heart: createHeartBaseShape
-};
-function createCustomBaseShape(options) {
-  var _a;
-  const {
-    pathData,
-    customSourceWidthPx,
-    customSourceHeightPx,
-    x,
-    y,
-    width,
-    height
-  } = options;
-  if (typeof pathData !== "string" || pathData.trim().length === 0) {
-    return null;
-  }
-  const center = new paper.Point(x, y);
-  const hasMultipleSubPaths = ((_a = (pathData.match(/[Mm]/g) || []).length) != null ? _a : 0) > 1;
-  const path = hasMultipleSubPaths ? new paper.CompoundPath(pathData) : (() => {
-    const single = new paper.Path();
-    single.pathData = pathData;
-    return single;
-  })();
-  const sourceWidth = Number(customSourceWidthPx != null ? customSourceWidthPx : 0);
-  const sourceHeight = Number(customSourceHeightPx != null ? customSourceHeightPx : 0);
-  if (Number.isFinite(sourceWidth) && Number.isFinite(sourceHeight) && sourceWidth > 0 && sourceHeight > 0 && width > 0 && height > 0) {
-    const targetLeft = x - width / 2;
-    const targetTop = y - height / 2;
-    path.scale(width / sourceWidth, height / sourceHeight, new paper.Point(0, 0));
-    path.translate(new paper.Point(targetLeft, targetTop));
-    return path;
-  }
-  if (width > 0 && height > 0 && path.bounds.width > 0 && path.bounds.height > 0) {
-    path.position = center;
-    path.scale(width / path.bounds.width, height / path.bounds.height);
-    return path;
-  }
-  path.position = center;
-  return path;
-}
-function createBaseShape(options) {
-  const { shape } = options;
-  if (shape === "custom") {
-    const customShape = createCustomBaseShape(options);
-    if (customShape) return customShape;
-    return BUILTIN_SHAPE_BUILDERS[DEFAULT_DIELINE_SHAPE](options);
-  }
-  return BUILTIN_SHAPE_BUILDERS[shape](options);
-}
-function resolveBridgeBasePath(shape, anchor) {
-  if (shape instanceof paper.Path) {
-    return shape;
-  }
-  if (shape instanceof paper.CompoundPath) {
-    const children = (shape.children || []).filter(
-      (child) => child instanceof paper.Path
-    );
-    if (!children.length) return null;
-    let best = children[0];
-    let bestDistance = Infinity;
-    for (const child of children) {
-      const location = child.getNearestLocation(anchor);
-      const point = location == null ? void 0 : location.point;
-      if (!point) continue;
-      const distance = point.getDistance(anchor);
-      if (distance < bestDistance) {
-        bestDistance = distance;
-        best = child;
+
+// src/extensions/image/commands.ts
+function createImageCommands(tool) {
+  return [
+    {
+      command: "addImage",
+      id: "addImage",
+      title: "Add Image",
+      handler: async (url, options) => {
+        const result = await tool.upsertImageEntry(url, {
+          mode: "add",
+          addOptions: options
+        });
+        return result.id;
       }
-    }
-    return best;
-  }
-  return null;
-}
-function createFeatureItem(feature, center) {
-  let item;
-  if (feature.shape === "rect") {
-    const w = feature.width || 10;
-    const h = feature.height || 10;
-    const r = feature.radius || 0;
-    item = new paper.Path.Rectangle({
-      point: [center.x - w / 2, center.y - h / 2],
-      size: [w, h],
-      radius: r
-    });
-  } else {
-    const r = feature.radius || 5;
-    item = new paper.Path.Circle({
-      center,
-      radius: r
-    });
-  }
-  if (feature.rotation) {
-    item.rotate(feature.rotation, center);
-  }
-  return item;
-}
-function getPerimeterShape(options) {
-  let mainShape = createBaseShape(options);
-  const { features } = options;
-  if (features && features.length > 0) {
-    const edgeFeatures = features.filter(
-      (f) => !f.renderBehavior || f.renderBehavior === "edge"
-    );
-    const adds = [];
-    const subtracts = [];
-    edgeFeatures.forEach((f) => {
-      const pos = resolveFeaturePosition(f, options);
-      const center = new paper.Point(pos.x, pos.y);
-      const item = createFeatureItem(f, center);
-      if (f.bridge && f.bridge.type === "vertical") {
-        const itemBounds = item.bounds;
-        const mainBounds = mainShape.bounds;
-        const bridgeTop = mainBounds.top;
-        const bridgeBottom = itemBounds.top;
-        if (bridgeBottom > bridgeTop) {
-          const overlap = 2;
-          const rayPadding = 10;
-          const eps = 0.1;
-          const delta = getBridgeDelta(itemBounds, overlap);
-          const toY = bridgeTop - rayPadding;
-          const inset = Math.min(1, Math.max(0, itemBounds.width * 0.01));
-          const xLeft = itemBounds.left + inset;
-          const xRight = itemBounds.right - inset;
-          const bridgeBasePath = resolveBridgeBasePath(mainShape, center);
-          const canBridge = !!bridgeBasePath && xRight - xLeft > eps;
-          if (canBridge && bridgeBasePath) {
-            const leftHit = getExitHit({
-              mainShape: bridgeBasePath,
-              x: xLeft,
-              bridgeBottom,
-              toY,
-              eps,
-              delta,
-              overlap,
-              op: f.operation
-            });
-            const rightHit = getExitHit({
-              mainShape: bridgeBasePath,
-              x: xRight,
-              bridgeBottom,
-              toY,
-              eps,
-              delta,
-              overlap,
-              op: f.operation
-            });
-            if (leftHit && rightHit) {
-              const pathLength = bridgeBasePath.length;
-              const leftOffset = leftHit.location.offset;
-              const rightOffset = rightHit.location.offset;
-              const distanceA = wrappedDistance(pathLength, leftOffset, rightOffset);
-              const distanceB = wrappedDistance(pathLength, rightOffset, leftOffset);
-              const countFor = (d) => Math.max(8, Math.min(80, Math.ceil(d / 6)));
-              const offsetsA = sampleWrappedOffsets(
-                pathLength,
-                leftOffset,
-                rightOffset,
-                countFor(distanceA)
-              );
-              const offsetsB = sampleWrappedOffsets(
-                pathLength,
-                rightOffset,
-                leftOffset,
-                countFor(distanceB)
-              );
-              const pointsA = offsetsA.map((o) => bridgeBasePath.getPointAt(o)).filter((p) => Boolean(p));
-              const pointsB = offsetsB.map((o) => bridgeBasePath.getPointAt(o)).filter((p) => Boolean(p));
-              if (pointsA.length >= 2 && pointsB.length >= 2) {
-                let topBase = selectOuterChain({
-                  mainShape: bridgeBasePath,
-                  pointsA,
-                  pointsB,
-                  delta,
-                  overlap,
-                  op: f.operation
-                });
-                const dist2 = (a, b) => {
-                  const dx = a.x - b.x;
-                  const dy = a.y - b.y;
-                  return dx * dx + dy * dy;
-                };
-                if (dist2(topBase[0], leftHit.point) > dist2(topBase[0], rightHit.point)) {
-                  topBase = topBase.slice().reverse();
-                }
-                topBase = topBase.slice();
-                topBase[0] = leftHit.point;
-                topBase[topBase.length - 1] = rightHit.point;
-                const capShiftY = f.operation === "subtract" ? -Math.max(overlap * 2, delta) : overlap;
-                const topPoints = topBase.map(
-                  (p) => p.add(new paper.Point(0, capShiftY))
-                );
-                const bridgeBottomY = bridgeBottom + overlap * 2;
-                const bridgePoly = new paper.Path({ insert: false });
-                for (const p of topPoints) bridgePoly.add(p);
-                bridgePoly.add(new paper.Point(xRight, bridgeBottomY));
-                bridgePoly.add(new paper.Point(xLeft, bridgeBottomY));
-                bridgePoly.closed = true;
-                const unitedItem = item.unite(bridgePoly);
-                item.remove();
-                bridgePoly.remove();
-                if (f.operation === "add") {
-                  adds.push(unitedItem);
-                } else {
-                  subtracts.push(unitedItem);
-                }
-                return;
-              }
-            }
-          }
-          if (f.operation === "add") {
-            adds.push(item);
-          } else {
-            subtracts.push(item);
-          }
-        } else {
-          if (f.operation === "add") {
-            adds.push(item);
-          } else {
-            subtracts.push(item);
+    },
+    {
+      command: "upsertImage",
+      id: "upsertImage",
+      title: "Upsert Image",
+      handler: async (url, options = {}) => {
+        return await tool.upsertImageEntry(url, options);
+      }
+    },
+    {
+      command: "getWorkingImages",
+      id: "getWorkingImages",
+      title: "Get Working Images",
+      handler: () => {
+        return tool.cloneItems(tool.workingItems);
+      }
+    },
+    {
+      command: "setWorkingImage",
+      id: "setWorkingImage",
+      title: "Set Working Image",
+      handler: (id, updates) => {
+        tool.updateImageInWorking(id, updates);
+      }
+    },
+    {
+      command: "resetWorkingImages",
+      id: "resetWorkingImages",
+      title: "Reset Working Images",
+      handler: () => {
+        tool.workingItems = tool.cloneItems(tool.items);
+        tool.hasWorkingChanges = false;
+        tool.updateImages();
+        tool.emitWorkingChange();
+      }
+    },
+    {
+      command: "completeImages",
+      id: "completeImages",
+      title: "Complete Images",
+      handler: async () => {
+        return await tool.commitWorkingImagesAsCropped();
+      }
+    },
+    {
+      command: "exportUserCroppedImage",
+      id: "exportUserCroppedImage",
+      title: "Export User Cropped Image",
+      handler: async (options = {}) => {
+        return await tool.exportUserCroppedImage(options);
+      }
+    },
+    {
+      command: "fitImageToArea",
+      id: "fitImageToArea",
+      title: "Fit Image to Area",
+      handler: async (id, area) => {
+        await tool.fitImageToArea(id, area);
+      }
+    },
+    {
+      command: "fitImageToDefaultArea",
+      id: "fitImageToDefaultArea",
+      title: "Fit Image to Default Area",
+      handler: async (id) => {
+        await tool.fitImageToDefaultArea(id);
+      }
+    },
+    {
+      command: "focusImage",
+      id: "focusImage",
+      title: "Focus Image",
+      handler: (id, options = {}) => {
+        return tool.setImageFocus(id, options);
+      }
+    },
+    {
+      command: "removeImage",
+      id: "removeImage",
+      title: "Remove Image",
+      handler: (id) => {
+        const removed = tool.items.find((item) => item.id === id);
+        const next = tool.items.filter((item) => item.id !== id);
+        if (next.length !== tool.items.length) {
+          tool.purgeSourceSizeCacheForItem(removed);
+          if (tool.focusedImageId === id) {
+            tool.setImageFocus(null, {
+              syncCanvasSelection: true,
+              skipRender: true
+            });
           }
-        }
-      } else {
-        if (f.operation === "add") {
-          adds.push(item);
-        } else {
-          subtracts.push(item);
+          tool.updateConfig(next);
         }
       }
-    });
-    if (adds.length > 0) {
-      for (const item of adds) {
-        try {
-          const temp = mainShape.unite(item);
-          mainShape.remove();
-          item.remove();
-          mainShape = normalizePathItem(temp);
-        } catch (e) {
-          console.error("Geometry: Failed to unite feature", e);
-          item.remove();
+    },
+    {
+      command: "updateImage",
+      id: "updateImage",
+      title: "Update Image",
+      handler: async (id, updates, options = {}) => {
+        await tool.updateImage(id, updates, options);
+      }
+    },
+    {
+      command: "clearImages",
+      id: "clearImages",
+      title: "Clear Images",
+      handler: () => {
+        tool.sourceSizeCache.clear();
+        tool.setImageFocus(null, {
+          syncCanvasSelection: true,
+          skipRender: true
+        });
+        tool.updateConfig([]);
+      }
+    },
+    {
+      command: "bringToFront",
+      id: "bringToFront",
+      title: "Bring Image to Front",
+      handler: (id) => {
+        const index = tool.items.findIndex((item) => item.id === id);
+        if (index !== -1 && index < tool.items.length - 1) {
+          const next = [...tool.items];
+          const [item] = next.splice(index, 1);
+          next.push(item);
+          tool.updateConfig(next);
         }
       }
-    }
-    if (subtracts.length > 0) {
-      for (const item of subtracts) {
-        try {
-          const temp = mainShape.subtract(item);
-          mainShape.remove();
-          item.remove();
-          mainShape = normalizePathItem(temp);
-        } catch (e) {
-          console.error("Geometry: Failed to subtract feature", e);
-          item.remove();
+    },
+    {
+      command: "sendToBack",
+      id: "sendToBack",
+      title: "Send Image to Back",
+      handler: (id) => {
+        const index = tool.items.findIndex((item) => item.id === id);
+        if (index > 0) {
+          const next = [...tool.items];
+          const [item] = next.splice(index, 1);
+          next.unshift(item);
+          tool.updateConfig(next);
         }
       }
     }
+  ];
+}
+
+// src/extensions/image/config.ts
+function createImageConfigurations() {
+  return [
+    {
+      id: "image.items",
+      type: "array",
+      label: "Images",
+      default: []
+    },
+    {
+      id: "image.debug",
+      type: "boolean",
+      label: "Image Debug Log",
+      default: false
+    },
+    {
+      id: "image.control.cornerSize",
+      type: "number",
+      label: "Image Control Corner Size",
+      min: 4,
+      max: 64,
+      step: 1,
+      default: 14
+    },
+    {
+      id: "image.control.touchCornerSize",
+      type: "number",
+      label: "Image Control Touch Corner Size",
+      min: 8,
+      max: 96,
+      step: 1,
+      default: 24
+    },
+    {
+      id: "image.control.cornerStyle",
+      type: "select",
+      label: "Image Control Corner Style",
+      options: ["circle", "rect"],
+      default: "circle"
+    },
+    {
+      id: "image.control.cornerColor",
+      type: "color",
+      label: "Image Control Corner Color",
+      default: "#ffffff"
+    },
+    {
+      id: "image.control.cornerStrokeColor",
+      type: "color",
+      label: "Image Control Corner Stroke Color",
+      default: "#1677ff"
+    },
+    {
+      id: "image.control.transparentCorners",
+      type: "boolean",
+      label: "Image Control Transparent Corners",
+      default: false
+    },
+    {
+      id: "image.control.borderColor",
+      type: "color",
+      label: "Image Control Border Color",
+      default: "#1677ff"
+    },
+    {
+      id: "image.control.borderScaleFactor",
+      type: "number",
+      label: "Image Control Border Width",
+      min: 0.5,
+      max: 8,
+      step: 0.1,
+      default: 1.5
+    },
+    {
+      id: "image.control.padding",
+      type: "number",
+      label: "Image Control Padding",
+      min: 0,
+      max: 64,
+      step: 1,
+      default: 0
+    },
+    {
+      id: "image.frame.strokeColor",
+      type: "color",
+      label: "Image Frame Stroke Color",
+      default: "#808080"
+    },
+    {
+      id: "image.frame.strokeWidth",
+      type: "number",
+      label: "Image Frame Stroke Width",
+      min: 0,
+      max: 20,
+      step: 0.5,
+      default: 2
+    },
+    {
+      id: "image.frame.strokeStyle",
+      type: "select",
+      label: "Image Frame Stroke Style",
+      options: ["solid", "dashed", "hidden"],
+      default: "dashed"
+    },
+    {
+      id: "image.frame.dashLength",
+      type: "number",
+      label: "Image Frame Dash Length",
+      min: 1,
+      max: 40,
+      step: 1,
+      default: 8
+    },
+    {
+      id: "image.frame.innerBackground",
+      type: "color",
+      label: "Image Frame Inner Background",
+      default: "rgba(0,0,0,0)"
+    },
+    {
+      id: "image.frame.outerBackground",
+      type: "color",
+      label: "Image Frame Outer Background",
+      default: "#f5f5f5"
+    }
+  ];
+}
+
+// src/extensions/geometry.ts
+import paper from "paper";
+
+// src/extensions/bridgeSelection.ts
+function pickExitIndex(hits) {
+  for (let i = 0; i < hits.length; i++) {
+    const h = hits[i];
+    if (h.insideBelow && !h.insideAbove) return i;
   }
-  return mainShape;
+  return -1;
 }
-function applySurfaceFeatures(shape, features, options) {
-  const surfaceFeatures = features.filter(
-    (f) => f.renderBehavior === "surface"
-  );
-  if (surfaceFeatures.length === 0) return shape;
-  let result = shape;
-  for (const f of surfaceFeatures) {
-    const pos = resolveFeaturePosition(f, options);
-    const center = new paper.Point(pos.x, pos.y);
-    const item = createFeatureItem(f, center);
-    try {
-      if (f.operation === "add") {
-        const temp = result.unite(item);
-        result.remove();
-        item.remove();
-        result = normalizePathItem(temp);
-      } else {
-        const temp = result.subtract(item);
-        result.remove();
-        item.remove();
-        result = normalizePathItem(temp);
-      }
-    } catch (e) {
-      console.error("Geometry: Failed to apply surface feature", e);
-      item.remove();
-    }
+function scoreOutsideAbove(samples) {
+  let score = 0;
+  for (const s of samples) {
+    if (s.outsideAbove) score++;
   }
-  return result;
+  return score;
 }
-function generateDielinePath(options) {
-  const paperWidth = options.canvasWidth || options.width * 2 || 2e3;
-  const paperHeight = options.canvasHeight || options.height * 2 || 2e3;
-  ensurePaper(paperWidth, paperHeight);
-  paper.project.activeLayer.removeChildren();
-  const perimeter = getPerimeterShape(options);
-  const finalShape = applySurfaceFeatures(perimeter, options.features, options);
-  const pathData = finalShape.pathData;
-  finalShape.remove();
-  return pathData;
+
+// src/extensions/wrappedOffsets.ts
+function wrappedDistance(total, start, end) {
+  if (!Number.isFinite(total) || total <= 0) return 0;
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return 0;
+  const s = (start % total + total) % total;
+  const e = (end % total + total) % total;
+  return e >= s ? e - s : total - s + e;
 }
-function generateBleedZonePath(originalOptions, offsetOptions, offset) {
-  const paperWidth = originalOptions.canvasWidth || originalOptions.width * 2 || 2e3;
-  const paperHeight = originalOptions.canvasHeight || originalOptions.height * 2 || 2e3;
-  ensurePaper(paperWidth, paperHeight);
-  paper.project.activeLayer.removeChildren();
-  const pOriginal = getPerimeterShape(originalOptions);
-  const shapeOriginal = applySurfaceFeatures(
-    pOriginal,
-    originalOptions.features,
-    originalOptions
-  );
-  const pOffset = getPerimeterShape(offsetOptions);
-  const shapeOffset = applySurfaceFeatures(
-    pOffset,
-    offsetOptions.features,
-    offsetOptions
-  );
-  let bleedZone;
-  if (offset > 0) {
-    bleedZone = shapeOffset.subtract(shapeOriginal);
-  } else {
-    bleedZone = shapeOriginal.subtract(shapeOffset);
+function sampleWrappedOffsets(total, start, end, count) {
+  if (!Number.isFinite(total) || total <= 0) return [];
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return [];
+  const n = Math.max(0, Math.floor(count));
+  if (n <= 0) return [];
+  const dist = wrappedDistance(total, start, end);
+  if (n === 1) return [(start % total + total) % total];
+  const step = dist / (n - 1);
+  const offsets = [];
+  for (let i = 0; i < n; i++) {
+    const raw = start + step * i;
+    const wrapped = (raw % total + total) % total;
+    offsets.push(wrapped);
   }
-  const pathData = bleedZone.pathData;
-  shapeOriginal.remove();
-  shapeOffset.remove();
-  bleedZone.remove();
-  return pathData;
+  return offsets;
 }
-function getLowestPointOnDieline(options) {
-  ensurePaper(options.width * 2, options.height * 2);
-  paper.project.activeLayer.removeChildren();
-  const shape = createBaseShape(options);
-  const bounds = shape.bounds;
-  const result = {
-    x: bounds.center.x,
-    y: bounds.bottom
+
+// src/extensions/geometry.ts
+function resolveFeaturePosition(feature, geometry) {
+  const { x, y, width, height } = geometry;
+  const left = x - width / 2;
+  const top = y - height / 2;
+  return {
+    x: left + feature.x * width,
+    y: top + feature.y * height
   };
-  shape.remove();
-  return result;
 }
-function getNearestPointOnDieline(point, options) {
-  ensurePaper(options.width * 2, options.height * 2);
-  paper.project.activeLayer.removeChildren();
-  const shape = createBaseShape(options);
-  const p = new paper.Point(point.x, point.y);
-  const location = shape.getNearestLocation(p);
-  const result = {
-    x: location.point.x,
-    y: location.point.y,
-    normal: location.normal ? { x: location.normal.x, y: location.normal.y } : void 0
-  };
-  shape.remove();
+function ensurePaper(width, height) {
+  if (!paper.project) {
+    paper.setup(new paper.Size(width, height));
+  } else {
+    paper.view.viewSize = new paper.Size(width, height);
+  }
+}
+var isBridgeDebugEnabled = () => Boolean(globalThis.__POODER_BRIDGE_DEBUG__);
+function normalizePathItem(shape) {
+  let result = shape;
+  if (typeof result.resolveCrossings === "function") result = result.resolveCrossings();
+  if (typeof result.reduce === "function") result = result.reduce({});
+  if (typeof result.reorient === "function") result = result.reorient(true, true);
+  if (typeof result.reduce === "function") result = result.reduce({});
   return result;
 }
-function getPathBounds(pathData) {
-  const path = new paper.Path();
-  path.pathData = pathData;
-  const bounds = path.bounds;
-  path.remove();
-  return {
-    x: bounds.x,
-    y: bounds.y,
-    width: bounds.width,
-    height: bounds.height
-  };
+function getBridgeDelta(itemBounds, overlap) {
+  return Math.max(overlap, Math.min(5, Math.max(1, itemBounds.height * 0.02)));
 }
-
-// src/shared/scene/frame.ts
-function emptyFrameRect() {
-  return { left: 0, top: 0, width: 0, height: 0 };
+function getExitHit(args) {
+  const { mainShape, x, bridgeBottom, toY, eps, delta, overlap, op } = args;
+  const ray = new paper.Path.Line({
+    from: [x, bridgeBottom],
+    to: [x, toY],
+    insert: false
+  });
+  const intersections = mainShape.getIntersections(ray) || [];
+  ray.remove();
+  const validHits = intersections.filter((i) => i.point.y < bridgeBottom - eps);
+  if (validHits.length === 0) return null;
+  validHits.sort((a, b) => b.point.y - a.point.y);
+  const flags = validHits.map((h) => {
+    const above = h.point.add(new paper.Point(0, -delta));
+    const below = h.point.add(new paper.Point(0, delta));
+    return {
+      insideAbove: mainShape.contains(above),
+      insideBelow: mainShape.contains(below)
+    };
+  });
+  const idx = pickExitIndex(flags);
+  if (idx < 0) return null;
+  if (isBridgeDebugEnabled()) {
+    console.debug("Geometry: Bridge ray", {
+      x,
+      validHits: validHits.length,
+      idx,
+      delta,
+      overlap,
+      op
+    });
+  }
+  const hit = validHits[idx];
+  return { point: hit.point, location: hit };
 }
-function resolveCutFrameRect(canvasService, configService) {
-  if (!canvasService || !configService) {
-    return emptyFrameRect();
+function selectOuterChain(args) {
+  const { mainShape, pointsA, pointsB, delta, overlap, op } = args;
+  const scoreA = scoreOutsideAbove(
+    pointsA.map((p) => ({
+      outsideAbove: !mainShape.contains(p.add(new paper.Point(0, -delta)))
+    }))
+  );
+  const scoreB = scoreOutsideAbove(
+    pointsB.map((p) => ({
+      outsideAbove: !mainShape.contains(p.add(new paper.Point(0, -delta)))
+    }))
+  );
+  const ratioA = scoreA / pointsA.length;
+  const ratioB = scoreB / pointsB.length;
+  if (isBridgeDebugEnabled()) {
+    console.debug("Geometry: Bridge chain", {
+      scoreA,
+      scoreB,
+      lenA: pointsA.length,
+      lenB: pointsB.length,
+      ratioA,
+      ratioB,
+      delta,
+      overlap,
+      op
+    });
   }
-  const sizeState = readSizeState(configService);
-  const layout = computeSceneLayout(canvasService, sizeState);
-  if (!layout) {
-    return emptyFrameRect();
+  const ratioEps = 1e-6;
+  if (Math.abs(ratioA - ratioB) > ratioEps) {
+    return ratioA > ratioB ? pointsA : pointsB;
+  }
+  if (scoreA !== scoreB) return scoreA > scoreB ? pointsA : pointsB;
+  return pointsA.length <= pointsB.length ? pointsA : pointsB;
+}
+function fitPathItemToRect(item, rect, fitMode) {
+  const { left, top, width, height } = rect;
+  const bounds = item.bounds;
+  if (width <= 0 || height <= 0 || !Number.isFinite(bounds.width) || !Number.isFinite(bounds.height) || bounds.width <= 0 || bounds.height <= 0) {
+    item.position = new paper.Point(left + width / 2, top + height / 2);
+    return item;
+  }
+  item.translate(new paper.Point(-bounds.left, -bounds.top));
+  if (fitMode === "stretch") {
+    item.scale(width / bounds.width, height / bounds.height, new paper.Point(0, 0));
+    item.translate(new paper.Point(left, top));
+    return item;
   }
-  return canvasService.toSceneRect({
-    left: layout.cutRect.left,
-    top: layout.cutRect.top,
-    width: layout.cutRect.width,
-    height: layout.cutRect.height
-  });
+  const uniformScale = Math.min(width / bounds.width, height / bounds.height);
+  item.scale(uniformScale, uniformScale, new paper.Point(0, 0));
+  const scaledWidth = bounds.width * uniformScale;
+  const scaledHeight = bounds.height * uniformScale;
+  item.translate(
+    new paper.Point(
+      left + (width - scaledWidth) / 2,
+      top + (height - scaledHeight) / 2
+    )
+  );
+  return item;
 }
-function toLayoutSceneRect(rect) {
-  return {
-    left: rect.left,
-    top: rect.top,
-    width: rect.width,
-    height: rect.height,
-    space: "scene"
-  };
+function createNormalizedHeartPath(params) {
+  const { lobeSpread, notchDepth, tipSharpness } = params;
+  const halfSpread = 0.22 + lobeSpread * 0.18;
+  const notchY = 0.06 + notchDepth * 0.2;
+  const shoulderY = 0.24 + notchDepth * 0.2;
+  const topLift = 0.12 + (1 - notchDepth) * 0.06;
+  const topY = notchY - topLift;
+  const sideCtrlY = shoulderY - (0.18 - notchDepth * 0.08);
+  const lowerCtrlY = 0.58 + (1 - tipSharpness) * 0.16;
+  const tipCtrlX = 0.34 - tipSharpness * 0.2;
+  const notchCtrlX = 0.06 + lobeSpread * 0.06;
+  const lobeCtrlX = 0.1 + lobeSpread * 0.08;
+  const notchCtrlY = notchY - topLift * 0.45;
+  const xPeakL = 0.5 - halfSpread;
+  const xPeakR = 0.5 + halfSpread;
+  const heartPath = new paper.Path({ insert: false });
+  heartPath.moveTo(new paper.Point(0.5, notchY));
+  heartPath.cubicCurveTo(
+    new paper.Point(0.5 - notchCtrlX, notchCtrlY),
+    new paper.Point(xPeakL + lobeCtrlX, topY),
+    new paper.Point(xPeakL, topY)
+  );
+  heartPath.cubicCurveTo(
+    new paper.Point(xPeakL - lobeCtrlX, topY),
+    new paper.Point(0, sideCtrlY),
+    new paper.Point(0, shoulderY)
+  );
+  heartPath.cubicCurveTo(
+    new paper.Point(0, lowerCtrlY),
+    new paper.Point(tipCtrlX, 1),
+    new paper.Point(0.5, 1)
+  );
+  heartPath.cubicCurveTo(
+    new paper.Point(1 - tipCtrlX, 1),
+    new paper.Point(1, lowerCtrlY),
+    new paper.Point(1, shoulderY)
+  );
+  heartPath.cubicCurveTo(
+    new paper.Point(1, sideCtrlY),
+    new paper.Point(xPeakR + lobeCtrlX, topY),
+    new paper.Point(xPeakR, topY)
+  );
+  heartPath.cubicCurveTo(
+    new paper.Point(xPeakR - lobeCtrlX, topY),
+    new paper.Point(0.5 + notchCtrlX, notchCtrlY),
+    new paper.Point(0.5, notchY)
+  );
+  heartPath.closed = true;
+  return heartPath;
 }
-
-// src/shared/runtime/sessionState.ts
-function cloneWithJson(value) {
-  return JSON.parse(JSON.stringify(value));
+function createHeartBaseShape(options) {
+  const { x, y, width, height } = options;
+  const w = Math.max(0, width);
+  const h = Math.max(0, height);
+  const left = x - w / 2;
+  const top = y - h / 2;
+  const fitMode = getShapeFitMode(options.shapeStyle);
+  const heartParams = getHeartShapeParams(options.shapeStyle);
+  const rawHeart = createNormalizedHeartPath(heartParams);
+  return fitPathItemToRect(rawHeart, { left, top, width: w, height: h }, fitMode);
 }
-function applyCommittedSnapshot(session, nextCommitted, options) {
-  const clone = options.clone;
-  session.committed = clone(nextCommitted);
-  const shouldPreserveDirtyWorking = options.toolActive && options.preserveDirtyWorking !== false && session.hasWorkingChanges;
-  if (!shouldPreserveDirtyWorking) {
-    session.working = clone(session.committed);
-    session.hasWorkingChanges = false;
+var BUILTIN_SHAPE_BUILDERS = {
+  rect: (options) => {
+    const { x, y, width, height, radius } = options;
+    return new paper.Path.Rectangle({
+      point: [x - width / 2, y - height / 2],
+      size: [Math.max(0, width), Math.max(0, height)],
+      radius: Math.max(0, radius)
+    });
+  },
+  circle: (options) => {
+    const { x, y, width, height } = options;
+    const r = Math.min(width, height) / 2;
+    return new paper.Path.Circle({
+      center: new paper.Point(x, y),
+      radius: Math.max(0, r)
+    });
+  },
+  ellipse: (options) => {
+    const { x, y, width, height } = options;
+    return new paper.Path.Ellipse({
+      center: new paper.Point(x, y),
+      radius: [Math.max(0, width / 2), Math.max(0, height / 2)]
+    });
+  },
+  heart: createHeartBaseShape
+};
+function createCustomBaseShape(options) {
+  var _a;
+  const {
+    pathData,
+    customSourceWidthPx,
+    customSourceHeightPx,
+    x,
+    y,
+    width,
+    height
+  } = options;
+  if (typeof pathData !== "string" || pathData.trim().length === 0) {
+    return null;
   }
-}
-function runDeferredConfigUpdate(state, action, cooldownMs = 0) {
-  state.isUpdatingConfig = true;
-  action();
-  if (cooldownMs <= 0) {
-    state.isUpdatingConfig = false;
-    return;
+  const center = new paper.Point(x, y);
+  const hasMultipleSubPaths = ((_a = (pathData.match(/[Mm]/g) || []).length) != null ? _a : 0) > 1;
+  const path = hasMultipleSubPaths ? new paper.CompoundPath(pathData) : (() => {
+    const single = new paper.Path();
+    single.pathData = pathData;
+    return single;
+  })();
+  const sourceWidth = Number(customSourceWidthPx != null ? customSourceWidthPx : 0);
+  const sourceHeight = Number(customSourceHeightPx != null ? customSourceHeightPx : 0);
+  if (Number.isFinite(sourceWidth) && Number.isFinite(sourceHeight) && sourceWidth > 0 && sourceHeight > 0 && width > 0 && height > 0) {
+    const targetLeft = x - width / 2;
+    const targetTop = y - height / 2;
+    path.scale(width / sourceWidth, height / sourceHeight, new paper.Point(0, 0));
+    path.translate(new paper.Point(targetLeft, targetTop));
+    return path;
   }
-  setTimeout(() => {
-    state.isUpdatingConfig = false;
-  }, cooldownMs);
+  if (width > 0 && height > 0 && path.bounds.width > 0 && path.bounds.height > 0) {
+    path.position = center;
+    path.scale(width / path.bounds.width, height / path.bounds.height);
+    return path;
+  }
+  path.position = center;
+  return path;
 }
-
-// src/extensions/image/commands.ts
-function createImageCommands(tool) {
-  return [
-    {
-      command: "addImage",
-      id: "addImage",
-      title: "Add Image",
-      handler: async (url, options) => {
-        const result = await tool.upsertImageEntry(url, {
-          mode: "add",
-          addOptions: options
-        });
-        return result.id;
-      }
-    },
-    {
-      command: "upsertImage",
-      id: "upsertImage",
-      title: "Upsert Image",
-      handler: async (url, options = {}) => {
-        return await tool.upsertImageEntry(url, options);
-      }
-    },
-    {
-      command: "getWorkingImages",
-      id: "getWorkingImages",
-      title: "Get Working Images",
-      handler: () => {
-        return tool.cloneItems(tool.workingItems);
-      }
-    },
-    {
-      command: "setWorkingImage",
-      id: "setWorkingImage",
-      title: "Set Working Image",
-      handler: (id, updates) => {
-        tool.updateImageInWorking(id, updates);
-      }
-    },
-    {
-      command: "resetWorkingImages",
-      id: "resetWorkingImages",
-      title: "Reset Working Images",
-      handler: () => {
-        tool.workingItems = tool.cloneItems(tool.items);
-        tool.hasWorkingChanges = false;
-        tool.updateImages();
-        tool.emitWorkingChange();
-      }
-    },
-    {
-      command: "completeImages",
-      id: "completeImages",
-      title: "Complete Images",
-      handler: async () => {
-        return await tool.commitWorkingImagesAsCropped();
-      }
-    },
-    {
-      command: "exportUserCroppedImage",
-      id: "exportUserCroppedImage",
-      title: "Export User Cropped Image",
-      handler: async (options = {}) => {
-        return await tool.exportUserCroppedImage(options);
-      }
-    },
-    {
-      command: "fitImageToArea",
-      id: "fitImageToArea",
-      title: "Fit Image to Area",
-      handler: async (id, area) => {
-        await tool.fitImageToArea(id, area);
-      }
-    },
-    {
-      command: "fitImageToDefaultArea",
-      id: "fitImageToDefaultArea",
-      title: "Fit Image to Default Area",
-      handler: async (id) => {
-        await tool.fitImageToDefaultArea(id);
-      }
-    },
-    {
-      command: "focusImage",
-      id: "focusImage",
-      title: "Focus Image",
-      handler: (id, options = {}) => {
-        return tool.setImageFocus(id, options);
+function createBaseShape(options) {
+  const { shape } = options;
+  if (shape === "custom") {
+    const customShape = createCustomBaseShape(options);
+    if (customShape) return customShape;
+    return BUILTIN_SHAPE_BUILDERS[DEFAULT_DIELINE_SHAPE](options);
+  }
+  return BUILTIN_SHAPE_BUILDERS[shape](options);
+}
+function resolveBridgeBasePath(shape, anchor) {
+  if (shape instanceof paper.Path) {
+    return shape;
+  }
+  if (shape instanceof paper.CompoundPath) {
+    const children = (shape.children || []).filter(
+      (child) => child instanceof paper.Path
+    );
+    if (!children.length) return null;
+    let best = children[0];
+    let bestDistance = Infinity;
+    for (const child of children) {
+      const location = child.getNearestLocation(anchor);
+      const point = location == null ? void 0 : location.point;
+      if (!point) continue;
+      const distance = point.getDistance(anchor);
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        best = child;
       }
-    },
-    {
-      command: "removeImage",
-      id: "removeImage",
-      title: "Remove Image",
-      handler: (id) => {
-        const removed = tool.items.find((item) => item.id === id);
-        const next = tool.items.filter((item) => item.id !== id);
-        if (next.length !== tool.items.length) {
-          tool.purgeSourceSizeCacheForItem(removed);
-          if (tool.focusedImageId === id) {
-            tool.setImageFocus(null, {
-              syncCanvasSelection: true,
-              skipRender: true
+    }
+    return best;
+  }
+  return null;
+}
+function createFeatureItem(feature, center) {
+  let item;
+  if (feature.shape === "rect") {
+    const w = feature.width || 10;
+    const h = feature.height || 10;
+    const r = feature.radius || 0;
+    item = new paper.Path.Rectangle({
+      point: [center.x - w / 2, center.y - h / 2],
+      size: [w, h],
+      radius: r
+    });
+  } else {
+    const r = feature.radius || 5;
+    item = new paper.Path.Circle({
+      center,
+      radius: r
+    });
+  }
+  if (feature.rotation) {
+    item.rotate(feature.rotation, center);
+  }
+  return item;
+}
+function getPerimeterShape(options) {
+  let mainShape = createBaseShape(options);
+  const { features } = options;
+  if (features && features.length > 0) {
+    const edgeFeatures = features.filter(
+      (f) => !f.renderBehavior || f.renderBehavior === "edge"
+    );
+    const adds = [];
+    const subtracts = [];
+    edgeFeatures.forEach((f) => {
+      const pos = resolveFeaturePosition(f, options);
+      const center = new paper.Point(pos.x, pos.y);
+      const item = createFeatureItem(f, center);
+      if (f.bridge && f.bridge.type === "vertical") {
+        const itemBounds = item.bounds;
+        const mainBounds = mainShape.bounds;
+        const bridgeTop = mainBounds.top;
+        const bridgeBottom = itemBounds.top;
+        if (bridgeBottom > bridgeTop) {
+          const overlap = 2;
+          const rayPadding = 10;
+          const eps = 0.1;
+          const delta = getBridgeDelta(itemBounds, overlap);
+          const toY = bridgeTop - rayPadding;
+          const inset = Math.min(1, Math.max(0, itemBounds.width * 0.01));
+          const xLeft = itemBounds.left + inset;
+          const xRight = itemBounds.right - inset;
+          const bridgeBasePath = resolveBridgeBasePath(mainShape, center);
+          const canBridge = !!bridgeBasePath && xRight - xLeft > eps;
+          if (canBridge && bridgeBasePath) {
+            const leftHit = getExitHit({
+              mainShape: bridgeBasePath,
+              x: xLeft,
+              bridgeBottom,
+              toY,
+              eps,
+              delta,
+              overlap,
+              op: f.operation
+            });
+            const rightHit = getExitHit({
+              mainShape: bridgeBasePath,
+              x: xRight,
+              bridgeBottom,
+              toY,
+              eps,
+              delta,
+              overlap,
+              op: f.operation
             });
+            if (leftHit && rightHit) {
+              const pathLength = bridgeBasePath.length;
+              const leftOffset = leftHit.location.offset;
+              const rightOffset = rightHit.location.offset;
+              const distanceA = wrappedDistance(pathLength, leftOffset, rightOffset);
+              const distanceB = wrappedDistance(pathLength, rightOffset, leftOffset);
+              const countFor = (d) => Math.max(8, Math.min(80, Math.ceil(d / 6)));
+              const offsetsA = sampleWrappedOffsets(
+                pathLength,
+                leftOffset,
+                rightOffset,
+                countFor(distanceA)
+              );
+              const offsetsB = sampleWrappedOffsets(
+                pathLength,
+                rightOffset,
+                leftOffset,
+                countFor(distanceB)
+              );
+              const pointsA = offsetsA.map((o) => bridgeBasePath.getPointAt(o)).filter((p) => Boolean(p));
+              const pointsB = offsetsB.map((o) => bridgeBasePath.getPointAt(o)).filter((p) => Boolean(p));
+              if (pointsA.length >= 2 && pointsB.length >= 2) {
+                let topBase = selectOuterChain({
+                  mainShape: bridgeBasePath,
+                  pointsA,
+                  pointsB,
+                  delta,
+                  overlap,
+                  op: f.operation
+                });
+                const dist2 = (a, b) => {
+                  const dx = a.x - b.x;
+                  const dy = a.y - b.y;
+                  return dx * dx + dy * dy;
+                };
+                if (dist2(topBase[0], leftHit.point) > dist2(topBase[0], rightHit.point)) {
+                  topBase = topBase.slice().reverse();
+                }
+                topBase = topBase.slice();
+                topBase[0] = leftHit.point;
+                topBase[topBase.length - 1] = rightHit.point;
+                const capShiftY = f.operation === "subtract" ? -Math.max(overlap * 2, delta) : overlap;
+                const topPoints = topBase.map(
+                  (p) => p.add(new paper.Point(0, capShiftY))
+                );
+                const bridgeBottomY = bridgeBottom + overlap * 2;
+                const bridgePoly = new paper.Path({ insert: false });
+                for (const p of topPoints) bridgePoly.add(p);
+                bridgePoly.add(new paper.Point(xRight, bridgeBottomY));
+                bridgePoly.add(new paper.Point(xLeft, bridgeBottomY));
+                bridgePoly.closed = true;
+                const unitedItem = item.unite(bridgePoly);
+                item.remove();
+                bridgePoly.remove();
+                if (f.operation === "add") {
+                  adds.push(unitedItem);
+                } else {
+                  subtracts.push(unitedItem);
+                }
+                return;
+              }
+            }
+          }
+          if (f.operation === "add") {
+            adds.push(item);
+          } else {
+            subtracts.push(item);
+          }
+        } else {
+          if (f.operation === "add") {
+            adds.push(item);
+          } else {
+            subtracts.push(item);
           }
-          tool.updateConfig(next);
+        }
+      } else {
+        if (f.operation === "add") {
+          adds.push(item);
+        } else {
+          subtracts.push(item);
         }
       }
-    },
-    {
-      command: "updateImage",
-      id: "updateImage",
-      title: "Update Image",
-      handler: async (id, updates, options = {}) => {
-        await tool.updateImage(id, updates, options);
-      }
-    },
-    {
-      command: "clearImages",
-      id: "clearImages",
-      title: "Clear Images",
-      handler: () => {
-        tool.sourceSizeCache.clear();
-        tool.setImageFocus(null, {
-          syncCanvasSelection: true,
-          skipRender: true
-        });
-        tool.updateConfig([]);
-      }
-    },
-    {
-      command: "bringToFront",
-      id: "bringToFront",
-      title: "Bring Image to Front",
-      handler: (id) => {
-        const index = tool.items.findIndex((item) => item.id === id);
-        if (index !== -1 && index < tool.items.length - 1) {
-          const next = [...tool.items];
-          const [item] = next.splice(index, 1);
-          next.push(item);
-          tool.updateConfig(next);
+    });
+    if (adds.length > 0) {
+      for (const item of adds) {
+        try {
+          const temp = mainShape.unite(item);
+          mainShape.remove();
+          item.remove();
+          mainShape = normalizePathItem(temp);
+        } catch (e) {
+          console.error("Geometry: Failed to unite feature", e);
+          item.remove();
         }
       }
-    },
-    {
-      command: "sendToBack",
-      id: "sendToBack",
-      title: "Send Image to Back",
-      handler: (id) => {
-        const index = tool.items.findIndex((item) => item.id === id);
-        if (index > 0) {
-          const next = [...tool.items];
-          const [item] = next.splice(index, 1);
-          next.unshift(item);
-          tool.updateConfig(next);
+    }
+    if (subtracts.length > 0) {
+      for (const item of subtracts) {
+        try {
+          const temp = mainShape.subtract(item);
+          mainShape.remove();
+          item.remove();
+          mainShape = normalizePathItem(temp);
+        } catch (e) {
+          console.error("Geometry: Failed to subtract feature", e);
+          item.remove();
         }
       }
     }
-  ];
+  }
+  return mainShape;
+}
+function applySurfaceFeatures(shape, features, options) {
+  const surfaceFeatures = features.filter(
+    (f) => f.renderBehavior === "surface"
+  );
+  if (surfaceFeatures.length === 0) return shape;
+  let result = shape;
+  for (const f of surfaceFeatures) {
+    const pos = resolveFeaturePosition(f, options);
+    const center = new paper.Point(pos.x, pos.y);
+    const item = createFeatureItem(f, center);
+    try {
+      if (f.operation === "add") {
+        const temp = result.unite(item);
+        result.remove();
+        item.remove();
+        result = normalizePathItem(temp);
+      } else {
+        const temp = result.subtract(item);
+        result.remove();
+        item.remove();
+        result = normalizePathItem(temp);
+      }
+    } catch (e) {
+      console.error("Geometry: Failed to apply surface feature", e);
+      item.remove();
+    }
+  }
+  return result;
+}
+function generateDielinePath(options) {
+  const paperWidth = options.canvasWidth || options.width * 2 || 2e3;
+  const paperHeight = options.canvasHeight || options.height * 2 || 2e3;
+  ensurePaper(paperWidth, paperHeight);
+  paper.project.activeLayer.removeChildren();
+  const perimeter = getPerimeterShape(options);
+  const finalShape = applySurfaceFeatures(perimeter, options.features, options);
+  const pathData = finalShape.pathData;
+  finalShape.remove();
+  return pathData;
+}
+function generateBleedZonePath(originalOptions, offsetOptions, offset) {
+  const paperWidth = originalOptions.canvasWidth || originalOptions.width * 2 || 2e3;
+  const paperHeight = originalOptions.canvasHeight || originalOptions.height * 2 || 2e3;
+  ensurePaper(paperWidth, paperHeight);
+  paper.project.activeLayer.removeChildren();
+  const pOriginal = getPerimeterShape(originalOptions);
+  const shapeOriginal = applySurfaceFeatures(
+    pOriginal,
+    originalOptions.features,
+    originalOptions
+  );
+  const pOffset = getPerimeterShape(offsetOptions);
+  const shapeOffset = applySurfaceFeatures(
+    pOffset,
+    offsetOptions.features,
+    offsetOptions
+  );
+  let bleedZone;
+  if (offset > 0) {
+    bleedZone = shapeOffset.subtract(shapeOriginal);
+  } else {
+    bleedZone = shapeOriginal.subtract(shapeOffset);
+  }
+  const pathData = bleedZone.pathData;
+  shapeOriginal.remove();
+  shapeOffset.remove();
+  bleedZone.remove();
+  return pathData;
+}
+function getLowestPointOnDieline(options) {
+  ensurePaper(options.width * 2, options.height * 2);
+  paper.project.activeLayer.removeChildren();
+  const shape = createBaseShape(options);
+  const bounds = shape.bounds;
+  const result = {
+    x: bounds.center.x,
+    y: bounds.bottom
+  };
+  shape.remove();
+  return result;
+}
+function getNearestPointOnDieline(point, options) {
+  ensurePaper(options.width * 2, options.height * 2);
+  paper.project.activeLayer.removeChildren();
+  const shape = createBaseShape(options);
+  const p = new paper.Point(point.x, point.y);
+  const location = shape.getNearestLocation(p);
+  const result = {
+    x: location.point.x,
+    y: location.point.y,
+    normal: location.normal ? { x: location.normal.x, y: location.normal.y } : void 0
+  };
+  shape.remove();
+  return result;
 }
 
-// src/extensions/image/config.ts
-function createImageConfigurations() {
+// src/extensions/image/sessionOverlay.ts
+var EPSILON = 1e-4;
+var SHAPE_OUTLINE_COLOR = "rgba(255, 0, 0, 0.9)";
+var DEFAULT_HATCH_FILL = "rgba(255, 0, 0, 0.22)";
+function buildRectPath(width, height) {
+  return `M 0 0 L ${width} 0 L ${width} ${height} L 0 ${height} Z`;
+}
+function buildViewportMaskPath(viewport, cutRect) {
+  const cutLeft = cutRect.left - viewport.left;
+  const cutTop = cutRect.top - viewport.top;
   return [
-    {
-      id: "image.items",
-      type: "array",
-      label: "Images",
-      default: []
-    },
-    {
-      id: "image.debug",
-      type: "boolean",
-      label: "Image Debug Log",
-      default: false
-    },
-    {
-      id: "image.control.cornerSize",
-      type: "number",
-      label: "Image Control Corner Size",
-      min: 4,
-      max: 64,
-      step: 1,
-      default: 14
-    },
-    {
-      id: "image.control.touchCornerSize",
-      type: "number",
-      label: "Image Control Touch Corner Size",
-      min: 8,
-      max: 96,
-      step: 1,
-      default: 24
-    },
-    {
-      id: "image.control.cornerStyle",
-      type: "select",
-      label: "Image Control Corner Style",
-      options: ["circle", "rect"],
-      default: "circle"
-    },
-    {
-      id: "image.control.cornerColor",
-      type: "color",
-      label: "Image Control Corner Color",
-      default: "#ffffff"
-    },
-    {
-      id: "image.control.cornerStrokeColor",
-      type: "color",
-      label: "Image Control Corner Stroke Color",
-      default: "#1677ff"
-    },
-    {
-      id: "image.control.transparentCorners",
-      type: "boolean",
-      label: "Image Control Transparent Corners",
-      default: false
-    },
-    {
-      id: "image.control.borderColor",
-      type: "color",
-      label: "Image Control Border Color",
-      default: "#1677ff"
-    },
-    {
-      id: "image.control.borderScaleFactor",
-      type: "number",
-      label: "Image Control Border Width",
-      min: 0.5,
-      max: 8,
-      step: 0.1,
-      default: 1.5
-    },
-    {
-      id: "image.control.padding",
-      type: "number",
-      label: "Image Control Padding",
-      min: 0,
-      max: 64,
-      step: 1,
-      default: 0
-    },
-    {
-      id: "image.frame.strokeColor",
-      type: "color",
-      label: "Image Frame Stroke Color",
-      default: "#808080"
-    },
-    {
-      id: "image.frame.strokeWidth",
-      type: "number",
-      label: "Image Frame Stroke Width",
-      min: 0,
-      max: 20,
-      step: 0.5,
-      default: 2
-    },
-    {
-      id: "image.frame.strokeStyle",
-      type: "select",
-      label: "Image Frame Stroke Style",
-      options: ["solid", "dashed", "hidden"],
-      default: "dashed"
-    },
-    {
-      id: "image.frame.dashLength",
-      type: "number",
-      label: "Image Frame Dash Length",
-      min: 1,
-      max: 40,
-      step: 1,
-      default: 8
-    },
-    {
-      id: "image.frame.innerBackground",
-      type: "color",
-      label: "Image Frame Inner Background",
-      default: "rgba(0,0,0,0)"
-    },
-    {
-      id: "image.frame.outerBackground",
-      type: "color",
-      label: "Image Frame Outer Background",
-      default: "#f5f5f5"
+    buildRectPath(viewport.width, viewport.height),
+    `M ${cutLeft} ${cutTop} L ${cutLeft + cutRect.width} ${cutTop} L ${cutLeft + cutRect.width} ${cutTop + cutRect.height} L ${cutLeft} ${cutTop + cutRect.height} Z`
+  ].join(" ");
+}
+function resolveCutShapeRadiusPx(geometry, cutRect) {
+  const visualRadius = Number.isFinite(geometry.radius) ? Math.max(0, geometry.radius) : 0;
+  const visualOffset = Number.isFinite(geometry.offset) ? geometry.offset : 0;
+  const rawCutRadius = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
+  const maxRadius = Math.max(0, Math.min(cutRect.width, cutRect.height) / 2);
+  return Math.max(0, Math.min(maxRadius, rawCutRadius));
+}
+function buildBuiltinShapeOverlayPaths(cutRect, geometry) {
+  if (!geometry || geometry.shape === "custom") {
+    return null;
+  }
+  const radius = resolveCutShapeRadiusPx(geometry, cutRect);
+  if (geometry.shape === "rect" && radius <= EPSILON) {
+    return null;
+  }
+  const shapePathData = generateDielinePath({
+    shape: geometry.shape,
+    shapeStyle: geometry.shapeStyle,
+    width: Math.max(1, cutRect.width),
+    height: Math.max(1, cutRect.height),
+    radius,
+    x: cutRect.width / 2,
+    y: cutRect.height / 2,
+    features: [],
+    canvasWidth: Math.max(1, cutRect.width),
+    canvasHeight: Math.max(1, cutRect.height)
+  });
+  if (!shapePathData) {
+    return null;
+  }
+  return {
+    shapePathData,
+    hatchPathData: `${buildRectPath(cutRect.width, cutRect.height)} ${shapePathData}`
+  };
+}
+function buildImageSessionOverlaySpecs(args) {
+  const { viewport, layout, geometry, visual, hatchPattern } = args;
+  const cutRect = layout.cutRect;
+  const specs = [];
+  specs.push({
+    id: "image.cropMask.rect",
+    type: "path",
+    space: "screen",
+    data: { id: "image.cropMask.rect", zIndex: 1 },
+    props: {
+      pathData: buildViewportMaskPath(viewport, cutRect),
+      left: viewport.left,
+      top: viewport.top,
+      originX: "left",
+      originY: "top",
+      fill: visual.outerBackground,
+      stroke: null,
+      fillRule: "evenodd",
+      selectable: false,
+      evented: false,
+      excludeFromExport: true,
+      objectCaching: false
+    }
+  });
+  const shapeOverlay = buildBuiltinShapeOverlayPaths(cutRect, geometry);
+  if (shapeOverlay) {
+    specs.push({
+      id: "image.cropShapeHatch",
+      type: "path",
+      space: "screen",
+      data: { id: "image.cropShapeHatch", zIndex: 5 },
+      props: {
+        pathData: shapeOverlay.hatchPathData,
+        left: cutRect.left,
+        top: cutRect.top,
+        originX: "left",
+        originY: "top",
+        fill: hatchPattern || DEFAULT_HATCH_FILL,
+        opacity: hatchPattern ? 1 : 0.8,
+        stroke: null,
+        fillRule: "evenodd",
+        selectable: false,
+        evented: false,
+        excludeFromExport: true,
+        objectCaching: false
+      }
+    });
+    specs.push({
+      id: "image.cropShapeOutline",
+      type: "path",
+      space: "screen",
+      data: { id: "image.cropShapeOutline", zIndex: 6 },
+      props: {
+        pathData: shapeOverlay.shapePathData,
+        left: cutRect.left,
+        top: cutRect.top,
+        originX: "left",
+        originY: "top",
+        fill: "transparent",
+        stroke: SHAPE_OUTLINE_COLOR,
+        strokeWidth: 1,
+        selectable: false,
+        evented: false,
+        excludeFromExport: true,
+        objectCaching: false
+      }
+    });
+  }
+  specs.push({
+    id: "image.cropFrame",
+    type: "rect",
+    space: "screen",
+    data: { id: "image.cropFrame", zIndex: 7 },
+    props: {
+      left: cutRect.left,
+      top: cutRect.top,
+      width: cutRect.width,
+      height: cutRect.height,
+      originX: "left",
+      originY: "top",
+      fill: visual.innerBackground,
+      stroke: visual.strokeStyle === "hidden" ? "rgba(0,0,0,0)" : visual.strokeColor,
+      strokeWidth: visual.strokeStyle === "hidden" ? 0 : visual.strokeWidth,
+      strokeDashArray: visual.strokeStyle === "dashed" ? [visual.dashLength, visual.dashLength] : void 0,
+      selectable: false,
+      evented: false,
+      excludeFromExport: true
     }
-  ];
+  });
+  return specs;
 }
 
 // src/extensions/image/ImageTool.ts
@@ -2614,11 +2744,21 @@ var ImageTool = class {
       (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
     }
   }
+  clearSnapGuideContext() {
+    var _a;
+    const topContext = (_a = this.canvasService) == null ? void 0 : _a.canvas.contextTop;
+    if (!this.canvasService || !topContext) return;
+    this.canvasService.canvas.clearContext(topContext);
+  }
   clearSnapPreview() {
     var _a;
+    const shouldClearCanvas = this.hasRenderedSnapGuides || !!this.activeSnapX || !!this.activeSnapY;
     this.activeSnapX = null;
     this.activeSnapY = null;
     this.hasRenderedSnapGuides = false;
+    if (shouldClearCanvas) {
+      this.clearSnapGuideContext();
+    }
     (_a = this.canvasService) == null ? void 0 : _a.requestRenderAll();
   }
   endMoveSnapInteraction() {
@@ -3022,9 +3162,6 @@ var ImageTool = class {
     }
     return this.canvasService.toScreenRect(frame || this.getFrameRect());
   }
-  toLayoutSceneRect(rect) {
-    return toLayoutSceneRect(rect);
-  }
   async resolveDefaultFitArea() {
     if (!this.canvasService) return null;
     const frame = this.getFrameRect();
@@ -3151,74 +3288,37 @@ var ImageTool = class {
       outerBackground: this.getConfig("image.frame.outerBackground", "#f5f5f5") || "#f5f5f5"
     };
   }
-  toSceneGeometryLike(raw) {
-    const shape = raw == null ? void 0 : raw.shape;
-    if (!isDielineShape(shape)) {
+  resolveSessionOverlayState() {
+    if (!this.canvasService || !this.context) {
       return null;
     }
-    const radiusRaw = Number(raw == null ? void 0 : raw.radius);
-    const offsetRaw = Number(raw == null ? void 0 : raw.offset);
-    const unit = typeof (raw == null ? void 0 : raw.unit) === "string" ? raw.unit : "px";
-    const radius = unit === "scene" || !this.canvasService ? radiusRaw : this.canvasService.toSceneLength(radiusRaw);
-    const offset = unit === "scene" || !this.canvasService ? offsetRaw : this.canvasService.toSceneLength(offsetRaw);
-    return {
-      shape,
-      shapeStyle: normalizeShapeStyle(raw == null ? void 0 : raw.shapeStyle),
-      radius: Number.isFinite(radius) ? radius : 0,
-      offset: Number.isFinite(offset) ? offset : 0
-    };
-  }
-  async resolveSceneGeometryForOverlay() {
-    if (!this.context) return null;
-    const commandService = this.context.services.get("CommandService");
-    if (commandService) {
-      try {
-        const raw = await Promise.resolve(
-          commandService.executeCommand("getSceneGeometry")
-        );
-        const geometry2 = this.toSceneGeometryLike(raw);
-        if (geometry2) {
-          this.debug("overlay:sceneGeometry:command", geometry2);
-          return geometry2;
-        }
-        this.debug("overlay:sceneGeometry:command:invalid", { raw });
-      } catch (error) {
-        this.debug("overlay:sceneGeometry:command:error", {
-          error: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
-    if (!this.canvasService) return null;
     const configService = this.context.services.get(
       "ConfigurationService"
     );
-    if (!configService) return null;
-    const sizeState = readSizeState(configService);
-    const layout = computeSceneLayout(this.canvasService, sizeState);
-    if (!layout) {
-      this.debug("overlay:sceneGeometry:fallback:missing-layout");
+    if (!configService) {
       return null;
     }
-    const geometry = this.toSceneGeometryLike(
-      buildSceneGeometry(configService, layout)
+    const layout = computeSceneLayout(
+      this.canvasService,
+      readSizeState(configService)
     );
-    if (geometry) {
-      this.debug("overlay:sceneGeometry:fallback", geometry);
+    if (!layout) {
+      this.debug("overlay:layout:missing");
+      return null;
     }
-    return geometry;
-  }
-  resolveCutShapeRadius(geometry, frame) {
-    const visualRadius = Number.isFinite(geometry.radius) ? Math.max(0, geometry.radius) : 0;
-    const visualOffset = Number.isFinite(geometry.offset) ? geometry.offset : 0;
-    const rawCutRadius = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
-    const maxRadius = Math.max(0, Math.min(frame.width, frame.height) / 2);
-    return Math.max(0, Math.min(maxRadius, rawCutRadius));
+    const geometry = buildSceneGeometry(configService, layout);
+    this.debug("overlay:state:resolved", {
+      cutRect: layout.cutRect,
+      shape: geometry.shape,
+      shapeStyle: geometry.shapeStyle,
+      radius: geometry.radius,
+      offset: geometry.offset
+    });
+    return { layout, geometry };
   }
   getCropShapeHatchPattern(color = "rgba(255, 0, 0, 0.6)") {
-    var _a;
     if (typeof document === "undefined") return void 0;
-    const sceneScale = ((_a = this.canvasService) == null ? void 0 : _a.getSceneScale()) || 1;
-    const cacheKey = `${color}::${sceneScale.toFixed(6)}`;
+    const cacheKey = color;
     if (this.cropShapeHatchPattern && this.cropShapeHatchPatternColor === color && this.cropShapeHatchPatternKey === cacheKey) {
       return this.cropShapeHatchPattern;
     }
@@ -3248,138 +3348,11 @@ var ImageTool = class {
       // @ts-ignore: Fabric Pattern accepts canvas source here.
       repetition: "repeat"
     });
-    pattern.patternTransform = [
-      1 / sceneScale,
-      0,
-      0,
-      1 / sceneScale,
-      0,
-      0
-    ];
     this.cropShapeHatchPattern = pattern;
     this.cropShapeHatchPatternColor = color;
     this.cropShapeHatchPatternKey = cacheKey;
     return pattern;
   }
-  buildCropShapeOverlaySpecs(frame, sceneGeometry) {
-    var _a, _b;
-    if (!sceneGeometry) {
-      this.debug("overlay:shape:skip", { reason: "scene-geometry-missing" });
-      return [];
-    }
-    if (sceneGeometry.shape === "custom") {
-      this.debug("overlay:shape:skip", { reason: "shape-custom" });
-      return [];
-    }
-    const shape = sceneGeometry.shape;
-    const shapeStyle = sceneGeometry.shapeStyle;
-    const inset = 0;
-    const shapeWidth = Math.max(1, frame.width);
-    const shapeHeight = Math.max(1, frame.height);
-    const radius = this.resolveCutShapeRadius(sceneGeometry, frame);
-    this.debug("overlay:shape:geometry", {
-      shape,
-      frameWidth: frame.width,
-      frameHeight: frame.height,
-      offset: sceneGeometry.offset,
-      shapeStyle,
-      inset,
-      shapeWidth,
-      shapeHeight,
-      baseRadius: sceneGeometry.radius,
-      radius
-    });
-    const isSameAsFrame = Math.abs(shapeWidth - frame.width) <= 1e-4 && Math.abs(shapeHeight - frame.height) <= 1e-4;
-    if (shape === "rect" && radius <= 1e-4 && isSameAsFrame) {
-      this.debug("overlay:shape:skip", {
-        reason: "shape-rect-no-radius"
-      });
-      return [];
-    }
-    const baseOptions = {
-      shape,
-      width: shapeWidth,
-      height: shapeHeight,
-      radius,
-      x: frame.width / 2,
-      y: frame.height / 2,
-      features: [],
-      shapeStyle,
-      canvasWidth: frame.width,
-      canvasHeight: frame.height
-    };
-    try {
-      const shapePathData = generateDielinePath(baseOptions);
-      const outerRectPathData = `M 0 0 L ${frame.width} 0 L ${frame.width} ${frame.height} L 0 ${frame.height} Z`;
-      const hatchPathData = `${outerRectPathData} ${shapePathData}`;
-      if (!shapePathData || !hatchPathData) {
-        this.debug("overlay:shape:skip", {
-          reason: "path-generation-empty",
-          shape,
-          radius
-        });
-        return [];
-      }
-      const patternFill = this.getCropShapeHatchPattern();
-      const hatchFill = patternFill || "rgba(255, 0, 0, 0.22)";
-      const shapeBounds = getPathBounds(shapePathData);
-      const hatchBounds = getPathBounds(hatchPathData);
-      const frameRect = this.toLayoutSceneRect(frame);
-      const hatchPathLength = hatchPathData.length;
-      const shapePathLength = shapePathData.length;
-      const specs = [
-        {
-          id: "image.cropShapeHatch",
-          type: "path",
-          data: { id: "image.cropShapeHatch", zIndex: 5 },
-          layout: {
-            reference: "custom",
-            referenceRect: frameRect,
-            alignX: "start",
-            alignY: "start",
-            offsetX: hatchBounds.x,
-            offsetY: hatchBounds.y
-          },
-          props: {
-            pathData: hatchPathData,
-            originX: "left",
-            originY: "top",
-            fill: hatchFill,
-            opacity: patternFill ? 1 : 0.8,
-            stroke: "rgba(255, 0, 0, 0.9)",
-            strokeWidth: (_b = (_a = this.canvasService) == null ? void 0 : _a.toSceneLength(1)) != null ? _b : 1,
-            fillRule: "evenodd",
-            selectable: false,
-            evented: false,
-            excludeFromExport: true,
-            objectCaching: false
-          }
-        }
-      ];
-      this.debug("overlay:shape:built", {
-        shape,
-        radius,
-        inset,
-        shapeWidth,
-        shapeHeight,
-        fillRule: "evenodd",
-        shapePathLength,
-        hatchPathLength,
-        shapeBounds,
-        hatchBounds,
-        hatchFillType: hatchFill && typeof hatchFill === "object" ? "pattern" : "color",
-        ids: specs.map((spec) => spec.id)
-      });
-      return specs;
-    } catch (error) {
-      this.debug("overlay:shape:error", {
-        shape,
-        radius,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      return [];
-    }
-  }
   resolveRenderImageState(item) {
     var _a;
     const active = this.isToolActive;
@@ -3424,209 +3397,72 @@ var ImageTool = class {
       lockScalingFlip: true,
       selectable: this.isImageEditingVisible(),
       evented: this.isImageEditingVisible(),
-      hasControls: this.isImageEditingVisible(),
-      hasBorders: this.isImageEditingVisible(),
-      opacity: render.opacity
-    };
-  }
-  toSceneObjectScale(value) {
-    if (!this.canvasService) return value;
-    return value / this.canvasService.getSceneScale();
-  }
-  getCurrentSrc(obj) {
-    var _a;
-    if (!obj) return void 0;
-    if (typeof obj.getSrc === "function") return obj.getSrc();
-    return (_a = obj == null ? void 0 : obj._originalElement) == null ? void 0 : _a.src;
-  }
-  async buildImageSpecs(items, frame) {
-    const specs = [];
-    for (const item of items) {
-      const render = this.resolveRenderImageState(item);
-      if (!render.src) continue;
-      const ensured = await this.ensureSourceSize(render.src);
-      const sourceSize = ensured || this.getSourceSize(render.src);
-      const props = this.computeCanvasProps(render, sourceSize, frame);
-      specs.push({
-        id: item.id,
-        type: "image",
-        src: render.src,
-        data: {
-          id: item.id,
-          layerId: IMAGE_OBJECT_LAYER_ID,
-          type: "image-item"
-        },
-        props
-      });
-    }
-    return specs;
-  }
-  buildOverlaySpecs(frame, sceneGeometry) {
-    const visible = this.isImageEditingVisible();
-    if (!visible || frame.width <= 0 || frame.height <= 0 || !this.canvasService) {
-      this.debug("overlay:hidden", {
-        visible,
-        frame,
-        isToolActive: this.isToolActive,
-        isImageSelectionActive: this.isImageSelectionActive,
-        focusedImageId: this.focusedImageId
-      });
-      return [];
-    }
-    const viewport = this.canvasService.getSceneViewportRect();
-    const canvasW = viewport.width || 0;
-    const canvasH = viewport.height || 0;
-    const canvasLeft = viewport.left || 0;
-    const canvasTop = viewport.top || 0;
-    const visual = this.getFrameVisualConfig();
-    const strokeWidthScene = this.canvasService.toSceneLength(
-      visual.strokeWidth
-    );
-    const dashLengthScene = this.canvasService.toSceneLength(visual.dashLength);
-    const frameLeft = Math.max(
-      canvasLeft,
-      Math.min(canvasLeft + canvasW, frame.left)
-    );
-    const frameTop = Math.max(
-      canvasTop,
-      Math.min(canvasTop + canvasH, frame.top)
-    );
-    const frameRight = Math.max(
-      frameLeft,
-      Math.min(canvasLeft + canvasW, frame.left + frame.width)
-    );
-    const frameBottom = Math.max(
-      frameTop,
-      Math.min(canvasTop + canvasH, frame.top + frame.height)
-    );
-    const visibleFrameH = Math.max(0, frameBottom - frameTop);
-    const topH = Math.max(0, frameTop - canvasTop);
-    const bottomH = Math.max(0, canvasTop + canvasH - frameBottom);
-    const leftW = Math.max(0, frameLeft - canvasLeft);
-    const rightW = Math.max(0, canvasLeft + canvasW - frameRight);
-    const viewportRect = this.toLayoutSceneRect({
-      left: canvasLeft,
-      top: canvasTop,
-      width: canvasW,
-      height: canvasH
-    });
-    const visibleFrameBandRect = this.toLayoutSceneRect({
-      left: canvasLeft,
-      top: frameTop,
-      width: canvasW,
-      height: visibleFrameH
-    });
-    const frameRect = this.toLayoutSceneRect(frame);
-    const shapeOverlay = this.buildCropShapeOverlaySpecs(frame, sceneGeometry);
-    const mask = [
-      {
-        id: "image.cropMask.top",
-        type: "rect",
-        data: { id: "image.cropMask.top", zIndex: 1 },
-        layout: {
-          reference: "custom",
-          referenceRect: viewportRect,
-          alignX: "start",
-          alignY: "start",
-          width: "100%",
-          height: topH
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.bottom",
-        type: "rect",
-        data: { id: "image.cropMask.bottom", zIndex: 2 },
-        layout: {
-          reference: "custom",
-          referenceRect: viewportRect,
-          alignX: "start",
-          alignY: "end",
-          width: "100%",
-          height: bottomH
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.left",
-        type: "rect",
-        data: { id: "image.cropMask.left", zIndex: 3 },
-        layout: {
-          reference: "custom",
-          referenceRect: visibleFrameBandRect,
-          alignX: "start",
-          alignY: "start",
-          width: leftW,
-          height: "100%"
-        },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      },
-      {
-        id: "image.cropMask.right",
-        type: "rect",
-        data: { id: "image.cropMask.right", zIndex: 4 },
-        layout: {
-          reference: "custom",
-          referenceRect: visibleFrameBandRect,
-          alignX: "end",
-          alignY: "start",
-          width: rightW,
-          height: "100%"
+      hasControls: this.isImageEditingVisible(),
+      hasBorders: this.isImageEditingVisible(),
+      opacity: render.opacity
+    };
+  }
+  toSceneObjectScale(value) {
+    if (!this.canvasService) return value;
+    return value / this.canvasService.getSceneScale();
+  }
+  getCurrentSrc(obj) {
+    var _a;
+    if (!obj) return void 0;
+    if (typeof obj.getSrc === "function") return obj.getSrc();
+    return (_a = obj == null ? void 0 : obj._originalElement) == null ? void 0 : _a.src;
+  }
+  async buildImageSpecs(items, frame) {
+    const specs = [];
+    for (const item of items) {
+      const render = this.resolveRenderImageState(item);
+      if (!render.src) continue;
+      const ensured = await this.ensureSourceSize(render.src);
+      const sourceSize = ensured || this.getSourceSize(render.src);
+      const props = this.computeCanvasProps(render, sourceSize, frame);
+      specs.push({
+        id: item.id,
+        type: "image",
+        src: render.src,
+        data: {
+          id: item.id,
+          layerId: IMAGE_OBJECT_LAYER_ID,
+          type: "image-item"
         },
-        props: {
-          originX: "left",
-          originY: "top",
-          fill: visual.outerBackground,
-          selectable: false,
-          evented: false
-        }
-      }
-    ];
-    const frameSpec = {
-      id: "image.cropFrame",
-      type: "rect",
-      data: { id: "image.cropFrame", zIndex: 7 },
-      layout: {
-        reference: "custom",
-        referenceRect: frameRect,
-        alignX: "start",
-        alignY: "start",
-        width: "100%",
-        height: "100%"
+        props
+      });
+    }
+    return specs;
+  }
+  buildOverlaySpecs(overlayState) {
+    const visible = this.isImageEditingVisible();
+    if (!visible || !overlayState || !this.canvasService) {
+      this.debug("overlay:hidden", {
+        visible,
+        cutRect: overlayState == null ? void 0 : overlayState.layout.cutRect,
+        isToolActive: this.isToolActive,
+        isImageSelectionActive: this.isImageSelectionActive,
+        focusedImageId: this.focusedImageId
+      });
+      return [];
+    }
+    const viewport = this.canvasService.getScreenViewportRect();
+    const visual = this.getFrameVisualConfig();
+    const specs = buildImageSessionOverlaySpecs({
+      viewport: {
+        left: viewport.left,
+        top: viewport.top,
+        width: viewport.width,
+        height: viewport.height
       },
-      props: {
-        originX: "left",
-        originY: "top",
-        fill: visual.innerBackground,
-        stroke: visual.strokeStyle === "hidden" ? "rgba(0,0,0,0)" : visual.strokeColor,
-        strokeWidth: visual.strokeStyle === "hidden" ? 0 : strokeWidthScene,
-        strokeDashArray: visual.strokeStyle === "dashed" ? [dashLengthScene, dashLengthScene] : void 0,
-        selectable: false,
-        evented: false
-      }
-    };
-    const specs = shapeOverlay.length > 0 ? [...mask, ...shapeOverlay] : [...mask, ...shapeOverlay, frameSpec];
+      layout: overlayState.layout,
+      geometry: overlayState.geometry,
+      visual,
+      hatchPattern: this.getCropShapeHatchPattern()
+    });
     this.debug("overlay:built", {
-      frame,
-      shape: sceneGeometry == null ? void 0 : sceneGeometry.shape,
+      cutRect: overlayState.layout.cutRect,
+      shape: overlayState.geometry.shape,
       overlayIds: specs.map((spec) => {
         var _a;
         return {
@@ -3655,10 +3491,9 @@ var ImageTool = class {
     }
     const imageSpecs = await this.buildImageSpecs(renderItems, frame);
     if (seq !== this.renderSeq) return;
-    const sceneGeometry = await this.resolveSceneGeometryForOverlay();
-    if (seq !== this.renderSeq) return;
+    const overlayState = this.resolveSessionOverlayState();
     this.imageSpecs = imageSpecs;
-    this.overlaySpecs = this.buildOverlaySpecs(frame, sceneGeometry);
+    this.overlaySpecs = this.buildOverlaySpecs(overlayState);
     await this.canvasService.flushRenderFromProducers();
     if (seq !== this.renderSeq) return;
     this.refreshImageObjectInteractionState();
@@ -4582,6 +4417,259 @@ function readDielineState(configService, fallback) {
   };
 }
 
+// src/extensions/constraints.ts
+var ConstraintRegistry = class {
+  static register(type, handler) {
+    this.handlers.set(type, handler);
+  }
+  static apply(x, y, feature, context, constraints) {
+    const list = constraints || feature.constraints;
+    if (!list || list.length === 0) {
+      return { x, y };
+    }
+    let currentX = x;
+    let currentY = y;
+    for (const constraint of list) {
+      const handler = this.handlers.get(constraint.type);
+      if (handler) {
+        const result = handler(currentX, currentY, feature, context, constraint.params || {});
+        currentX = result.x;
+        currentY = result.y;
+      }
+    }
+    return { x: currentX, y: currentY };
+  }
+};
+ConstraintRegistry.handlers = /* @__PURE__ */ new Map();
+var pathConstraint = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight, geometry } = context;
+  if (!geometry) return { x, y };
+  const minX = geometry.x - geometry.width / 2;
+  const minY = geometry.y - geometry.height / 2;
+  const absX = minX + x * geometry.width;
+  const absY = minY + y * geometry.height;
+  const nearest = getNearestPointOnDieline(
+    { x: absX, y: absY },
+    geometry
+  );
+  let finalX = nearest.x;
+  let finalY = nearest.y;
+  const hasOffsetParams = params.minOffset !== void 0 || params.maxOffset !== void 0;
+  if (hasOffsetParams && nearest.normal) {
+    const dx = absX - nearest.x;
+    const dy = absY - nearest.y;
+    const nx2 = nearest.normal.x;
+    const ny2 = nearest.normal.y;
+    const dist = dx * nx2 + dy * ny2;
+    const scale = dielineWidth > 0 ? geometry.width / dielineWidth : 1;
+    const rawMin = params.minOffset !== void 0 ? params.minOffset : 0;
+    const rawMax = params.maxOffset !== void 0 ? params.maxOffset : 0;
+    const minOffset = rawMin * scale;
+    const maxOffset = rawMax * scale;
+    const clampedDist = Math.max(minOffset, Math.min(dist, maxOffset));
+    finalX = nearest.x + nx2 * clampedDist;
+    finalY = nearest.y + ny2 * clampedDist;
+  }
+  const nx = geometry.width > 0 ? (finalX - minX) / geometry.width : 0.5;
+  const ny = geometry.height > 0 ? (finalY - minY) / geometry.height : 0.5;
+  return { x: nx, y: ny };
+};
+var edgeConstraint = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight } = context;
+  const allowedEdges = params.allowedEdges || [
+    "top",
+    "bottom",
+    "left",
+    "right"
+  ];
+  const confine = params.confine || false;
+  const offset = params.offset || 0;
+  const distances = [];
+  if (allowedEdges.includes("top"))
+    distances.push({ edge: "top", dist: y * dielineHeight });
+  if (allowedEdges.includes("bottom"))
+    distances.push({ edge: "bottom", dist: (1 - y) * dielineHeight });
+  if (allowedEdges.includes("left"))
+    distances.push({ edge: "left", dist: x * dielineWidth });
+  if (allowedEdges.includes("right"))
+    distances.push({ edge: "right", dist: (1 - x) * dielineWidth });
+  if (distances.length === 0) return { x, y };
+  distances.sort((a, b) => a.dist - b.dist);
+  const nearest = distances[0].edge;
+  let newX = x;
+  let newY = y;
+  const fw = feature.width || 0;
+  const fh = feature.height || 0;
+  switch (nearest) {
+    case "top":
+      newY = 0 + offset / dielineHeight;
+      if (confine) {
+        const minX = fw / 2 / dielineWidth;
+        const maxX = 1 - minX;
+        newX = Math.max(minX, Math.min(newX, maxX));
+      }
+      break;
+    case "bottom":
+      newY = 1 - offset / dielineHeight;
+      if (confine) {
+        const minX = fw / 2 / dielineWidth;
+        const maxX = 1 - minX;
+        newX = Math.max(minX, Math.min(newX, maxX));
+      }
+      break;
+    case "left":
+      newX = 0 + offset / dielineWidth;
+      if (confine) {
+        const minY = fh / 2 / dielineHeight;
+        const maxY = 1 - minY;
+        newY = Math.max(minY, Math.min(newY, maxY));
+      }
+      break;
+    case "right":
+      newX = 1 - offset / dielineWidth;
+      if (confine) {
+        const minY = fh / 2 / dielineHeight;
+        const maxY = 1 - minY;
+        newY = Math.max(minY, Math.min(newY, maxY));
+      }
+      break;
+  }
+  return { x: newX, y: newY };
+};
+var internalConstraint = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight } = context;
+  const margin = params.margin || 0;
+  const fw = feature.width || 0;
+  const fh = feature.height || 0;
+  const minX = (margin + fw / 2) / dielineWidth;
+  const maxX = 1 - (margin + fw / 2) / dielineWidth;
+  const minY = (margin + fh / 2) / dielineHeight;
+  const maxY = 1 - (margin + fh / 2) / dielineHeight;
+  const clampedX = minX > maxX ? 0.5 : Math.max(minX, Math.min(x, maxX));
+  const clampedY = minY > maxY ? 0.5 : Math.max(minY, Math.min(y, maxY));
+  return { x: clampedX, y: clampedY };
+};
+var tangentBottomConstraint = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight } = context;
+  const gap = params.gap || 0;
+  const confineX = params.confineX !== false;
+  const extentY = feature.shape === "circle" ? feature.radius || 0 : (feature.height || 0) / 2;
+  const newY = 1 + (extentY + gap) / dielineHeight;
+  let newX = x;
+  if (confineX) {
+    const extentX = feature.shape === "circle" ? feature.radius || 0 : (feature.width || 0) / 2;
+    const minX = extentX / dielineWidth;
+    const maxX = 1 - extentX / dielineWidth;
+    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
+  }
+  return { x: newX, y: newY };
+};
+var lowestTangentConstraint = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight, geometry } = context;
+  if (!geometry) return { x, y };
+  const lowest = getLowestPointOnDieline(geometry);
+  const minY = geometry.y - geometry.height / 2;
+  const normY = (lowest.y - minY) / geometry.height;
+  const gap = params.gap || 0;
+  const confineX = params.confineX !== false;
+  const extentY = feature.shape === "circle" ? feature.radius || 0 : (feature.height || 0) / 2;
+  const newY = normY + (extentY + gap) / dielineHeight;
+  let newX = x;
+  if (confineX) {
+    const extentX = feature.shape === "circle" ? feature.radius || 0 : (feature.width || 0) / 2;
+    const minX = extentX / dielineWidth;
+    const maxX = 1 - extentX / dielineWidth;
+    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
+  }
+  return { x: newX, y: newY };
+};
+ConstraintRegistry.register("path", pathConstraint);
+ConstraintRegistry.register("edge", edgeConstraint);
+ConstraintRegistry.register("internal", internalConstraint);
+ConstraintRegistry.register("tangent-bottom", tangentBottomConstraint);
+ConstraintRegistry.register("lowest-tangent", lowestTangentConstraint);
+
+// src/extensions/featureCoordinates.ts
+function resolveFeaturePosition2(feature, geometry) {
+  const { x, y, width, height } = geometry;
+  const left = x - width / 2;
+  const top = y - height / 2;
+  return {
+    x: left + feature.x * width,
+    y: top + feature.y * height
+  };
+}
+function normalizePointInGeometry(point, geometry) {
+  const left = geometry.x - geometry.width / 2;
+  const top = geometry.y - geometry.height / 2;
+  return {
+    x: geometry.width > 0 ? (point.x - left) / geometry.width : 0.5,
+    y: geometry.height > 0 ? (point.y - top) / geometry.height : 0.5
+  };
+}
+
+// src/extensions/featurePlacement.ts
+function scaleFeatureForRender(feature, scale, x, y) {
+  return {
+    ...feature,
+    x,
+    y,
+    width: feature.width !== void 0 ? feature.width * scale : void 0,
+    height: feature.height !== void 0 ? feature.height * scale : void 0,
+    radius: feature.radius !== void 0 ? feature.radius * scale : void 0
+  };
+}
+function resolveFeaturePlacements(features, geometry) {
+  const dielineWidth = geometry.scale > 0 ? geometry.width / geometry.scale : geometry.width;
+  const dielineHeight = geometry.scale > 0 ? geometry.height / geometry.scale : geometry.height;
+  return (features || []).map((feature) => {
+    var _a;
+    const activeConstraints = (_a = feature.constraints) == null ? void 0 : _a.filter(
+      (constraint) => !constraint.validateOnly
+    );
+    const constrained = ConstraintRegistry.apply(
+      feature.x,
+      feature.y,
+      feature,
+      {
+        dielineWidth,
+        dielineHeight,
+        geometry
+      },
+      activeConstraints
+    );
+    const center = resolveFeaturePosition2(
+      {
+        ...feature,
+        x: constrained.x,
+        y: constrained.y
+      },
+      geometry
+    );
+    return {
+      feature,
+      normalizedX: constrained.x,
+      normalizedY: constrained.y,
+      centerX: center.x,
+      centerY: center.y
+    };
+  });
+}
+function projectPlacedFeatures(placements, geometry, scale) {
+  return placements.map((placement) => {
+    const normalized = normalizePointInGeometry(
+      { x: placement.centerX, y: placement.centerY },
+      geometry
+    );
+    return scaleFeatureForRender(
+      placement.feature,
+      scale,
+      normalized.x,
+      normalized.y
+    );
+  });
+}
+
 // src/extensions/dieline/renderBuilder.ts
 var DEFAULT_IDS = {
   inside: "dieline.inside",
@@ -4591,16 +4679,6 @@ var DEFAULT_IDS = {
   clip: "dieline.clip.image",
   clipSource: "dieline.effect.clip-path"
 };
-function scaleFeatures(state, scale) {
-  return (state.features || []).map((feature) => ({
-    ...feature,
-    x: feature.x,
-    y: feature.y,
-    width: (feature.width || 0) * scale,
-    height: (feature.height || 0) * scale,
-    radius: (feature.radius || 0) * scale
-  }));
-}
 function buildDielineRenderBundle(options) {
   const ids = { ...DEFAULT_IDS, ...options.ids || {} };
   const {
@@ -4625,8 +4703,41 @@ function buildDielineRenderBundle(options) {
   const cutH = sceneLayout.cutRect.height;
   const visualOffset = (cutW - visualWidth) / 2;
   const cutR = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
-  const absoluteFeatures = scaleFeatures(state, scale);
-  const cutFeatures = absoluteFeatures.filter((feature) => !feature.skipCut);
+  const placements = resolveFeaturePlacements(state.features || [], {
+    shape,
+    shapeStyle,
+    pathData: state.pathData,
+    customSourceWidthPx: state.customSourceWidthPx,
+    customSourceHeightPx: state.customSourceHeightPx,
+    canvasWidth,
+    canvasHeight,
+    x: cx,
+    y: cy,
+    width: visualWidth,
+    height: visualHeight,
+    radius: visualRadius,
+    scale
+  });
+  const absoluteFeatures = projectPlacedFeatures(
+    placements,
+    {
+      x: cx,
+      y: cy,
+      width: visualWidth,
+      height: visualHeight
+    },
+    scale
+  );
+  const cutFeatures = projectPlacedFeatures(
+    placements.filter((placement) => !placement.feature.skipCut),
+    {
+      x: cx,
+      y: cy,
+      width: cutW,
+      height: cutH
+    },
+    scale
+  );
   const common = {
     shape,
     shapeStyle,
@@ -4636,6 +4747,13 @@ function buildDielineRenderBundle(options) {
     canvasWidth,
     canvasHeight
   };
+  const cutFrameRect = {
+    left: cx - cutW / 2,
+    top: cy - cutH / 2,
+    width: cutW,
+    height: cutH,
+    space: "screen"
+  };
   const specs = [];
   if (insideColor && insideColor !== "transparent" && insideColor !== "rgba(0,0,0,0)" && !hasImages) {
     specs.push({
@@ -4757,9 +4875,13 @@ function buildDielineRenderBundle(options) {
     width: cutW,
     height: cutH,
     radius: cutR,
-    x: cx,
-    y: cy,
-    features: cutFeatures
+    // Build the clip path in the cut frame's local coordinates so Fabric
+    // does not have to infer placement from the standalone path bounds.
+    x: cutW / 2,
+    y: cutH / 2,
+    features: cutFeatures,
+    canvasWidth: cutW,
+    canvasHeight: cutH
   });
   if (!clipPathData) {
     return { specs, effects: [] };
@@ -4776,6 +4898,12 @@ function buildDielineRenderBundle(options) {
           id: ids.clipSource,
           type: "path",
           space: "screen",
+          layout: {
+            reference: "custom",
+            referenceRect: cutFrameRect,
+            alignX: "start",
+            alignY: "start"
+          },
           data: {
             id: ids.clipSource,
             type: "dieline-effect",
@@ -5055,15 +5183,31 @@ var DielineTool = class {
     const visualRadius = radius * scale;
     const visualOffset = (cutW - sceneLayout.trimRect.width) / 2;
     const cutR = visualRadius === 0 ? 0 : Math.max(0, visualRadius + visualOffset);
-    const absoluteFeatures = (features || []).map((f) => ({
-      ...f,
-      x: f.x,
-      y: f.y,
-      width: (f.width || 0) * scale,
-      height: (f.height || 0) * scale,
-      radius: (f.radius || 0) * scale
-    }));
-    const cutFeatures = absoluteFeatures.filter((f) => !f.skipCut);
+    const placements = resolveFeaturePlacements(features || [], {
+      shape,
+      shapeStyle,
+      pathData,
+      customSourceWidthPx: this.state.customSourceWidthPx,
+      customSourceHeightPx: this.state.customSourceHeightPx,
+      canvasWidth: canvasW,
+      canvasHeight: canvasH,
+      x: cx,
+      y: cy,
+      width: sceneLayout.trimRect.width,
+      height: sceneLayout.trimRect.height,
+      radius: visualRadius,
+      scale
+    });
+    const cutFeatures = projectPlacedFeatures(
+      placements.filter((placement) => !placement.feature.skipCut),
+      {
+        x: cx,
+        y: cy,
+        width: cutW,
+        height: cutH
+      },
+      scale
+    );
     const generatedPathData = generateDielinePath({
       shape,
       width: cutW,
@@ -5189,178 +5333,6 @@ import {
 } from "@pooder/core";
 import { Pattern as Pattern3 } from "fabric";
 
-// src/extensions/constraints.ts
-var ConstraintRegistry = class {
-  static register(type, handler) {
-    this.handlers.set(type, handler);
-  }
-  static apply(x, y, feature, context, constraints) {
-    const list = constraints || feature.constraints;
-    if (!list || list.length === 0) {
-      return { x, y };
-    }
-    let currentX = x;
-    let currentY = y;
-    for (const constraint of list) {
-      const handler = this.handlers.get(constraint.type);
-      if (handler) {
-        const result = handler(currentX, currentY, feature, context, constraint.params || {});
-        currentX = result.x;
-        currentY = result.y;
-      }
-    }
-    return { x: currentX, y: currentY };
-  }
-};
-ConstraintRegistry.handlers = /* @__PURE__ */ new Map();
-var pathConstraint = (x, y, feature, context, params) => {
-  const { dielineWidth, dielineHeight, geometry } = context;
-  if (!geometry) return { x, y };
-  const minX = geometry.x - geometry.width / 2;
-  const minY = geometry.y - geometry.height / 2;
-  const absX = minX + x * geometry.width;
-  const absY = minY + y * geometry.height;
-  const nearest = getNearestPointOnDieline(
-    { x: absX, y: absY },
-    geometry
-  );
-  let finalX = nearest.x;
-  let finalY = nearest.y;
-  const hasOffsetParams = params.minOffset !== void 0 || params.maxOffset !== void 0;
-  if (hasOffsetParams && nearest.normal) {
-    const dx = absX - nearest.x;
-    const dy = absY - nearest.y;
-    const nx2 = nearest.normal.x;
-    const ny2 = nearest.normal.y;
-    const dist = dx * nx2 + dy * ny2;
-    const scale = dielineWidth > 0 ? geometry.width / dielineWidth : 1;
-    const rawMin = params.minOffset !== void 0 ? params.minOffset : 0;
-    const rawMax = params.maxOffset !== void 0 ? params.maxOffset : 0;
-    const minOffset = rawMin * scale;
-    const maxOffset = rawMax * scale;
-    const clampedDist = Math.max(minOffset, Math.min(dist, maxOffset));
-    finalX = nearest.x + nx2 * clampedDist;
-    finalY = nearest.y + ny2 * clampedDist;
-  }
-  const nx = geometry.width > 0 ? (finalX - minX) / geometry.width : 0.5;
-  const ny = geometry.height > 0 ? (finalY - minY) / geometry.height : 0.5;
-  return { x: nx, y: ny };
-};
-var edgeConstraint = (x, y, feature, context, params) => {
-  const { dielineWidth, dielineHeight } = context;
-  const allowedEdges = params.allowedEdges || [
-    "top",
-    "bottom",
-    "left",
-    "right"
-  ];
-  const confine = params.confine || false;
-  const offset = params.offset || 0;
-  const distances = [];
-  if (allowedEdges.includes("top"))
-    distances.push({ edge: "top", dist: y * dielineHeight });
-  if (allowedEdges.includes("bottom"))
-    distances.push({ edge: "bottom", dist: (1 - y) * dielineHeight });
-  if (allowedEdges.includes("left"))
-    distances.push({ edge: "left", dist: x * dielineWidth });
-  if (allowedEdges.includes("right"))
-    distances.push({ edge: "right", dist: (1 - x) * dielineWidth });
-  if (distances.length === 0) return { x, y };
-  distances.sort((a, b) => a.dist - b.dist);
-  const nearest = distances[0].edge;
-  let newX = x;
-  let newY = y;
-  const fw = feature.width || 0;
-  const fh = feature.height || 0;
-  switch (nearest) {
-    case "top":
-      newY = 0 + offset / dielineHeight;
-      if (confine) {
-        const minX = fw / 2 / dielineWidth;
-        const maxX = 1 - minX;
-        newX = Math.max(minX, Math.min(newX, maxX));
-      }
-      break;
-    case "bottom":
-      newY = 1 - offset / dielineHeight;
-      if (confine) {
-        const minX = fw / 2 / dielineWidth;
-        const maxX = 1 - minX;
-        newX = Math.max(minX, Math.min(newX, maxX));
-      }
-      break;
-    case "left":
-      newX = 0 + offset / dielineWidth;
-      if (confine) {
-        const minY = fh / 2 / dielineHeight;
-        const maxY = 1 - minY;
-        newY = Math.max(minY, Math.min(newY, maxY));
-      }
-      break;
-    case "right":
-      newX = 1 - offset / dielineWidth;
-      if (confine) {
-        const minY = fh / 2 / dielineHeight;
-        const maxY = 1 - minY;
-        newY = Math.max(minY, Math.min(newY, maxY));
-      }
-      break;
-  }
-  return { x: newX, y: newY };
-};
-var internalConstraint = (x, y, feature, context, params) => {
-  const { dielineWidth, dielineHeight } = context;
-  const margin = params.margin || 0;
-  const fw = feature.width || 0;
-  const fh = feature.height || 0;
-  const minX = (margin + fw / 2) / dielineWidth;
-  const maxX = 1 - (margin + fw / 2) / dielineWidth;
-  const minY = (margin + fh / 2) / dielineHeight;
-  const maxY = 1 - (margin + fh / 2) / dielineHeight;
-  const clampedX = minX > maxX ? 0.5 : Math.max(minX, Math.min(x, maxX));
-  const clampedY = minY > maxY ? 0.5 : Math.max(minY, Math.min(y, maxY));
-  return { x: clampedX, y: clampedY };
-};
-var tangentBottomConstraint = (x, y, feature, context, params) => {
-  const { dielineWidth, dielineHeight } = context;
-  const gap = params.gap || 0;
-  const confineX = params.confineX !== false;
-  const extentY = feature.shape === "circle" ? feature.radius || 0 : (feature.height || 0) / 2;
-  const newY = 1 + (extentY + gap) / dielineHeight;
-  let newX = x;
-  if (confineX) {
-    const extentX = feature.shape === "circle" ? feature.radius || 0 : (feature.width || 0) / 2;
-    const minX = extentX / dielineWidth;
-    const maxX = 1 - extentX / dielineWidth;
-    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
-  }
-  return { x: newX, y: newY };
-};
-var lowestTangentConstraint = (x, y, feature, context, params) => {
-  const { dielineWidth, dielineHeight, geometry } = context;
-  if (!geometry) return { x, y };
-  const lowest = getLowestPointOnDieline(geometry);
-  const minY = geometry.y - geometry.height / 2;
-  const normY = (lowest.y - minY) / geometry.height;
-  const gap = params.gap || 0;
-  const confineX = params.confineX !== false;
-  const extentY = feature.shape === "circle" ? feature.radius || 0 : (feature.height || 0) / 2;
-  const newY = normY + (extentY + gap) / dielineHeight;
-  let newX = x;
-  if (confineX) {
-    const extentX = feature.shape === "circle" ? feature.radius || 0 : (feature.width || 0) / 2;
-    const minX = extentX / dielineWidth;
-    const maxX = 1 - extentX / dielineWidth;
-    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
-  }
-  return { x: newX, y: newY };
-};
-ConstraintRegistry.register("path", pathConstraint);
-ConstraintRegistry.register("edge", edgeConstraint);
-ConstraintRegistry.register("internal", internalConstraint);
-ConstraintRegistry.register("tangent-bottom", tangentBottomConstraint);
-ConstraintRegistry.register("lowest-tangent", lowestTangentConstraint);
-
 // src/extensions/featureComplete.ts
 function validateFeaturesStrict(features, context) {
   const eps = 1e-6;
@@ -6136,9 +6108,29 @@ var FeatureTool = class {
     }
     const groups = /* @__PURE__ */ new Map();
     const singles = [];
-    this.workingFeatures.forEach((feature, index) => {
+    const placements = resolveFeaturePlacements(
+      this.workingFeatures,
+      {
+        shape: this.currentGeometry.shape,
+        shapeStyle: this.currentGeometry.shapeStyle,
+        pathData: this.currentGeometry.pathData,
+        customSourceWidthPx: this.currentGeometry.customSourceWidthPx,
+        customSourceHeightPx: this.currentGeometry.customSourceHeightPx,
+        x: this.currentGeometry.x,
+        y: this.currentGeometry.y,
+        width: this.currentGeometry.width,
+        height: this.currentGeometry.height,
+        radius: this.currentGeometry.radius,
+        scale: this.currentGeometry.scale || 1
+      }
+    );
+    placements.forEach((placement, index) => {
+      const feature = placement.feature;
       const geometry = this.getGeometryForFeature(this.currentGeometry, feature);
-      const position = resolveFeaturePosition(feature, geometry);
+      const position = {
+        x: placement.centerX,
+        y: placement.centerY
+      };
       const scale = geometry.scale || 1;
       const marker = {
         feature,
@@ -6715,11 +6707,12 @@ var EXTENSION_LINE_LENGTH = 5;
 var MIN_ARROW_SIZE = 4;
 var THICKNESS_TO_STROKE_WIDTH_RATIO = 20;
 var DEFAULT_THICKNESS = 20;
-var DEFAULT_GAP = 45;
+var DEFAULT_GAP = 65;
 var DEFAULT_FONT_SIZE = 10;
 var DEFAULT_BACKGROUND_COLOR = "#f0f0f0";
 var DEFAULT_TEXT_COLOR = "#333333";
 var DEFAULT_LINE_COLOR = "#999999";
+var RULER_DEBUG_KEY = "ruler.debug";
 var RULER_THICKNESS_MIN = 10;
 var RULER_THICKNESS_MAX = 100;
 var RULER_GAP_MIN = 0;
@@ -6738,6 +6731,7 @@ var RulerTool = class {
     this.textColor = DEFAULT_TEXT_COLOR;
     this.lineColor = DEFAULT_LINE_COLOR;
     this.fontSize = DEFAULT_FONT_SIZE;
+    this.debugEnabled = false;
     this.renderSeq = 0;
     this.numericProps = /* @__PURE__ */ new Set(["thickness", "gap", "fontSize"]);
     this.specs = [];
@@ -6786,7 +6780,14 @@ var RulerTool = class {
       this.syncConfig(configService);
       configService.onAnyChange((e) => {
         let shouldUpdate = false;
-        if (e.key.startsWith("ruler.")) {
+        if (e.key === RULER_DEBUG_KEY) {
+          this.debugEnabled = e.value === true;
+          this.log("config:update", {
+            key: e.key,
+            raw: e.value,
+            normalized: this.debugEnabled
+          });
+        } else if (e.key.startsWith("ruler.")) {
           const prop = e.key.split(".")[1];
           if (prop && prop in this) {
             if (this.numericProps.has(prop)) {
@@ -6873,6 +6874,12 @@ var RulerTool = class {
           min: RULER_FONT_SIZE_MIN,
           max: RULER_FONT_SIZE_MAX,
           default: DEFAULT_FONT_SIZE
+        },
+        {
+          id: RULER_DEBUG_KEY,
+          type: "boolean",
+          label: "Ruler Debug Log",
+          default: false
         }
       ],
       [ContributionPointIds8.COMMANDS]: [
@@ -6909,7 +6916,11 @@ var RulerTool = class {
       ]
     };
   }
+  isDebugEnabled() {
+    return this.debugEnabled;
+  }
   log(step, payload) {
+    if (!this.isDebugEnabled()) return;
     if (payload) {
       console.debug(`[RulerTool] ${step}`, payload);
       return;
@@ -6938,6 +6949,7 @@ var RulerTool = class {
       configService.get("ruler.fontSize", this.fontSize),
       DEFAULT_FONT_SIZE
     );
+    this.debugEnabled = configService.get(RULER_DEBUG_KEY, this.debugEnabled) === true;
     this.log("config:loaded", {
       thickness: this.thickness,
       gap: this.gap,