@widgetic/canvas 0.5.4

package/dist/canvas/shapes/FrameShape.js

@@ -0,0 +1,951 @@
+/**
+ * FrameShape - A container shape extending Fabric.js Group
+ *
+ * Features:
+ * - Extends fabric.Group to act as a container for child objects
+ * - interactive: true — children can be selected/edited directly (tldraw-like)
+ *   - Click on a child → selects that child for individual editing
+ *   - Click on frame background → selects the frame itself
+ * - ClipPath for bounding/clipping content inside frame boundaries
+ * - Customizable label drawn above the frame (with text wrapping, rotation support)
+ * - Custom controls: corner resize only, no rotation handle
+ * - Minimum size enforcement
+ * - Serialization support with custom properties
+ * - addObjectToFrame / removeObjectFromFrame with automatic coordinate conversion
+ *   (Fabric's native _enterGroup/_exitGroup handles absolute ↔ group-relative transforms)
+ *
+ * Containment detection (drag in/out) is handled by Canvas.svelte's
+ * object:modified handler since it requires canvas-level access.
+ */
+import { Group, Rect, Control, controlsUtils, util, LayoutManager, FixedLayout, classRegistry } from 'fabric';
+import { canvasLog, canvasWarn } from '../canvasLogger';
+// ─────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────
+export const MIN_FRAME_WIDTH = 50;
+export const MIN_FRAME_HEIGHT = 30;
+const DEFAULT_LABEL_FONT_SIZE = 16;
+const DEFAULT_LABEL_FONT_FAMILY = 'Inter, system-ui, sans-serif';
+const DEFAULT_LABEL_COLOR = '#1f2937';
+const DEFAULT_LABEL_BG_COLOR = '#ffffff';
+const DEFAULT_FILL = '#ffffff';
+export const DEFAULT_STROKE = '#2563eb';
+// Slightly darker blue shown on border/label hover (replaces separate overlay border)
+export const FRAME_HOVER_STROKE = '#1d4ed8';
+const DEFAULT_STROKE_WIDTH = 3;
+// ─────────────────────────────────────────────
+// Helper: Wrap text into lines that fit a max width
+// Handles both word-level and character-level wrapping for long words
+// ─────────────────────────────────────────────
+function wrapText(ctx, text, maxWidth) {
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+    // Break a single long word into character chunks
+    function breakWord(word) {
+        if (ctx.measureText(word).width <= maxWidth)
+            return [word];
+        const chunks = [];
+        let chunk = '';
+        for (const char of word) {
+            const test = chunk + char;
+            if (ctx.measureText(test).width > maxWidth && chunk) {
+                chunks.push(chunk);
+                chunk = char;
+            }
+            else {
+                chunk = test;
+            }
+        }
+        if (chunk)
+            chunks.push(chunk);
+        return chunks;
+    }
+    for (const word of words) {
+        if (ctx.measureText(word).width > maxWidth) {
+            // Word itself is too long - break by characters
+            if (currentLine) {
+                lines.push(currentLine);
+                currentLine = '';
+            }
+            const broken = breakWord(word);
+            for (let i = 0; i < broken.length - 1; i++) {
+                lines.push(broken[i]);
+            }
+            currentLine = broken[broken.length - 1] || '';
+        }
+        else {
+            const testLine = currentLine ? `${currentLine} ${word}` : word;
+            if (ctx.measureText(testLine).width > maxWidth && currentLine) {
+                lines.push(currentLine);
+                currentLine = word;
+            }
+            else {
+                currentLine = testLine;
+            }
+        }
+    }
+    if (currentLine)
+        lines.push(currentLine);
+    return lines.length > 0 ? lines : [text];
+}
+// ─────────────────────────────────────────────
+// Helper: Draw the label above the frame
+// ─────────────────────────────────────────────
+function renderFrameLabel(ctx, frame) {
+    const text = frame._labelText || 'Frame';
+    const fontSize = frame._labelFontSize || DEFAULT_LABEL_FONT_SIZE;
+    const fontFamily = frame._labelFontFamily || DEFAULT_LABEL_FONT_FAMILY;
+    const textColor = frame._labelColor || DEFAULT_LABEL_COLOR;
+    const bgColor = frame._labelBackgroundColor || DEFAULT_LABEL_BG_COLOR;
+    const textAlign = frame._labelTextAlign || 'left';
+    const fontWeight = frame._labelFontWeight || 'normal';
+    const fontStyle = frame._labelFontStyle || 'normal';
+    const underline = frame._labelUnderline || false;
+    // Use FULL visual dimensions (including parent group scales).
+    // The calling code positions the context at the frame's center via this.transform()
+    // then counter-scales to 1:1 via getObjectScaling(). In this 1:1 context, the
+    // frame's visual extent from center is (width/2 * totalScale), not (width/2 * localScale).
+    const scaling = frame.getObjectScaling ? frame.getObjectScaling() : { x: frame.scaleX || 1, y: frame.scaleY || 1 };
+    const frameW = (frame.width || 100) * scaling.x;
+    const frameH = (frame.height || 100) * scaling.y;
+    ctx.save();
+    // Set font to measure text
+    ctx.font = `${fontStyle} ${fontWeight} ${fontSize}px ${fontFamily}`;
+    const padding = 6;
+    const gap = 4;
+    const lineHeight = fontSize * 1.2;
+    // Label width matches the frame's visual width (clipPath boundary).
+    // The background rect's stroke is centered on the edge; the outward half is clipped,
+    // so the visible frame width is exactly frameW.
+    const minLabelWidth = 50;
+    const labelBgWidth = Math.max(frameW, minLabelWidth);
+    const maxTextWidth = labelBgWidth - padding * 2;
+    // Wrap text
+    const lines = wrapText(ctx, text, maxTextWidth);
+    const labelBgHeight = lines.length * lineHeight + padding * 2;
+    // Position: label sits above the frame
+    // In Group's local coordinate system, center is (0, 0)
+    // So top-left of frame content area is at (-frameW/2, -frameH/2)
+    const labelBgX = -frameW / 2;
+    const labelBgY = -frameH / 2 - labelBgHeight - gap;
+    // Draw label background
+    ctx.fillStyle = bgColor;
+    ctx.fillRect(labelBgX, labelBgY, labelBgWidth, labelBgHeight);
+    // Clip to label bounds (overflow hidden)
+    ctx.beginPath();
+    ctx.rect(labelBgX, labelBgY, labelBgWidth, labelBgHeight);
+    ctx.clip();
+    // Draw text lines
+    ctx.fillStyle = textColor;
+    ctx.textBaseline = 'top';
+    lines.forEach((line, index) => {
+        const lineWidth = ctx.measureText(line).width;
+        let textX;
+        switch (textAlign) {
+            case 'center':
+                textX = labelBgX + (labelBgWidth - lineWidth) / 2;
+                break;
+            case 'right':
+                textX = labelBgX + labelBgWidth - lineWidth - padding;
+                break;
+            default:
+                textX = labelBgX + padding;
+                break;
+        }
+        const textY = labelBgY + padding + index * lineHeight;
+        ctx.fillText(line, textX, textY);
+        // Draw underline if enabled
+        if (underline) {
+            ctx.beginPath();
+            ctx.strokeStyle = textColor;
+            ctx.lineWidth = 1;
+            ctx.moveTo(textX, textY + fontSize);
+            ctx.lineTo(textX + lineWidth, textY + fontSize);
+            ctx.stroke();
+        }
+    });
+    ctx.restore();
+}
+// ─────────────────────────────────────────────
+// FrameShape — registered Fabric class
+// Extends Group with a unique type so Fabric's classRegistry
+// dispatches loadFromJSON to FrameShape.fromObject, which calls
+// reapplyFrameRender automatically. New saves use type: 'FrameShape'.
+// Old saves (type: 'Group' with _isFrame: true) are handled by the
+// object:added fallback in Canvas.svelte for backward compatibility.
+// ─────────────────────────────────────────────
+export class FrameShape extends Group {
+    static type = 'FrameShape';
+    /**
+     * Serialise the frame with type = 'FrameShape' plus all custom label/style
+     * props so they survive a canvas.toJSON() → loadFromJSON() round-trip.
+     * FRAME_CUSTOM_PROPS and _objectId are always included regardless of what
+     * the canvas passes as propertiesToInclude.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toObject(propertiesToInclude) {
+        return {
+            // Merge FRAME_CUSTOM_PROPS + _objectId with whatever the canvas requests
+            ...super.toObject([
+                ...FRAME_CUSTOM_PROPS,
+                '_objectId',
+                ...(propertiesToInclude || []),
+            ]),
+            type: FrameShape.type,
+        };
+    }
+    /**
+     * Deserialise a saved FrameShape.
+     * Delegates to Group.fromObject (handles enlivenObjects, FixedLayout setup,
+     * and subscribeTargets) then upgrades the plain Group to a proper FrameShape
+     * instance via Object.setPrototypeOf before re-applying the custom render.
+     *
+     * WHY setPrototypeOf:
+     * Group.fromObject always returns `new Group(...)` whose prototype is Group.prototype.
+     * After setPrototypeOf → FrameShape.prototype, the instance:
+     *   • reports type === 'FrameShape' (via FrameShape.prototype.type)
+     *   • calls FrameShape.prototype.toObject() on save → emits type:'FrameShape' + custom props
+     *   • classRegistry dispatches FrameShape.fromObject on next reload
+     */
+    static fromObject(object, options) {
+        // Treat as a plain Group first so Group.fromObject handles all the
+        // heavy lifting (enlivenObjects, LayoutManager, coords, etc.)
+        const groupJson = { ...object, type: 'Group' };
+        canvasLog('FrameShape.fromObject: deserialising frame label=' + object._labelText
+            + ' children=' + (object.objects || []).length);
+        return Group.fromObject(groupJson, options).then((group) => {
+            // Upgrade Group instance → FrameShape instance.
+            // This must happen BEFORE reapplyFrameRender so that
+            // reapplyFrameRender's prototype check (below) is a no-op.
+            Object.setPrototypeOf(group, FrameShape.prototype);
+            reapplyFrameRender(group);
+            canvasLog('FrameShape.fromObject: restored frame label=' + group._labelText
+                + ' children=' + group.getObjects().length
+                + ' type=' + group.type);
+            return group;
+        });
+    }
+}
+// Register with Fabric so classRegistry.getClass('FrameShape') resolves in loadFromJSON.
+// NOTE: Fabric's type getter reads this.constructor.type.toLowerCase().
+// Object.setPrototypeOf(group, FrameShape.prototype) changes group.constructor to FrameShape,
+// so group.type becomes 'frameshape' automatically — no prototype.type setter needed.
+classRegistry.setClass(FrameShape);
+// ─────────────────────────────────────────────
+// Create a new FrameShape instance
+// ─────────────────────────────────────────────
+export function createFrameShape(options = {}) {
+    const { left = 0, top = 0, width = 200, height = 150, fill = DEFAULT_FILL, stroke = DEFAULT_STROKE, strokeWidth = DEFAULT_STROKE_WIDTH, labelText = 'Frame', labelFontSize = DEFAULT_LABEL_FONT_SIZE, labelFontFamily = DEFAULT_LABEL_FONT_FAMILY, labelColor = DEFAULT_LABEL_COLOR, labelBackgroundColor = DEFAULT_LABEL_BG_COLOR, labelTextAlign = 'left', labelFontWeight = 'normal', labelFontStyle = 'normal', labelUnderline = false, } = options;
+    // Enforce minimum dimensions
+    const finalWidth = Math.max(width, MIN_FRAME_WIDTH);
+    const finalHeight = Math.max(height, MIN_FRAME_HEIGHT);
+    // Create the background rectangle (visual frame body)
+    // In Group's local coords, origin is center, so rect goes from -w/2 to w/2
+    const backgroundRect = new Rect({
+        left: 0,
+        top: 0,
+        width: finalWidth,
+        height: finalHeight,
+        fill: fill,
+        stroke: stroke,
+        strokeWidth: strokeWidth,
+        strokeUniform: true,
+        originX: 'center',
+        originY: 'center',
+        // Background rect is NOT interactive - clicks on it pass through to the frame group
+        // This allows clicking on the frame's empty area to select the frame itself
+        selectable: false,
+        evented: false,
+    });
+    // Tag the background rect so we can identify it
+    backgroundRect._isFrameBackground = true;
+    // Use FrameShape (registered Fabric class) so canvas.toJSON() emits
+    // type: 'FrameShape', allowing loadFromJSON to call FrameShape.fromObject
+    // which restores the custom render automatically on reload.
+    const frame = new FrameShape([backgroundRect], {
+        left: left,
+        top: top,
+        originX: 'left',
+        originY: 'top',
+        // Sub-target check allows detecting clicks on children inside the group
+        subTargetCheck: true,
+        // Interactive: children can be selected/edited directly without entering edit mode
+        // Click on a child → selects that child for individual editing
+        // Click on frame background → selects the frame itself
+        interactive: true,
+        selectable: true,
+        // No rotation for frames
+        lockRotation: true,
+        // Minimum scale limit
+        minScaleLimit: 0.1,
+        // Disable object caching so children render directly on canvas.
+        // This ensures property changes on children are immediately visible.
+        objectCaching: false,
+        // Show move cursor when hovering over frame body
+        hoverCursor: 'move',
+        moveCursor: 'move',
+        // FixedLayout: frame keeps its explicit size, children don't expand selection border
+        layoutManager: new LayoutManager(new FixedLayout()),
+    });
+    // ─── Custom properties ───
+    const frameAny = frame;
+    frameAny._customType = 'frame';
+    frameAny._isFrame = true;
+    // Label properties (editable via PropsPanel)
+    frameAny._labelText = labelText;
+    frameAny._labelFontSize = labelFontSize;
+    frameAny._labelFontFamily = labelFontFamily;
+    frameAny._labelColor = labelColor;
+    frameAny._labelBackgroundColor = labelBackgroundColor;
+    frameAny._labelTextAlign = labelTextAlign;
+    frameAny._labelFontWeight = labelFontWeight;
+    frameAny._labelFontStyle = labelFontStyle;
+    frameAny._labelUnderline = labelUnderline;
+    // Frame visual properties (stored separately from Fabric's defaults)
+    frameAny._frameFill = fill;
+    frameAny._frameStroke = stroke;
+    frameAny._frameStrokeWidth = strokeWidth;
+    // ─── ClipPath: clips children to frame boundaries ───
+    setupClipPath(frame);
+    // ─── Custom controls: corner resize only, no rotation ───
+    setupFrameControls(frame);
+    // ─── Custom render: draw label above the frame ───
+    const originalRender = frame.render.bind(frame);
+    frame.render = function (ctx) {
+        // Render the group normally (background rect + any children)
+        originalRender(ctx);
+        // Draw the label on top.
+        // After originalRender (Group.render → FabricObject.render → save/transform/restore),
+        // the ctx is back to the parent's coordinate space. We use Fabric's own transform()
+        // method to apply the frame's transform correctly (handles _transformDone flag and
+        // group chain automatically). This works for both top-level and nested frames.
+        ctx.save();
+        this.transform(ctx);
+        // Counter-scale so label text stays crisp at 1:1 size.
+        // getObjectScaling() returns the total visual scale including parent groups.
+        const scaling = this.getObjectScaling();
+        ctx.scale(1 / scaling.x, 1 / scaling.y);
+        // Now context is at frame center, at 1:1 scale.
+        // renderFrameLabel uses local dimensions (frame.width * frame.scaleX).
+        renderFrameLabel(ctx, this);
+        ctx.restore();
+    };
+    // ─── Border-only hit test: frame is selectable only at its border/stroke ───
+    // or label — clicking the empty interior is a click-through so the user
+    // can start a rubber-band selection of frame children from there.
+    applyFrameHitTest(frame);
+    // Mark the frame as dirty so it renders immediately
+    frame.dirty = true;
+    canvasLog('FrameShape created', {
+        width: finalWidth,
+        height: finalHeight,
+        left,
+        top,
+        labelText
+    });
+    return frame;
+}
+// ─────────────────────────────────────────────
+// Setup ClipPath on a frame Group
+// Clips children to frame boundaries so content doesn't overflow
+// ─────────────────────────────────────────────
+export function setupClipPath(frame) {
+    const clipRect = new Rect({
+        left: 0,
+        top: 0,
+        width: frame.width,
+        height: frame.height,
+        originX: 'center',
+        originY: 'center',
+        absolutePositioned: false, // Relative to the group
+    });
+    frame.clipPath = clipRect;
+}
+// ─────────────────────────────────────────────
+// Update ClipPath when frame is resized
+// Call this after frame dimensions change
+// ─────────────────────────────────────────────
+export function updateClipPath(frame) {
+    // Preserve corner radius from the frame's custom property
+    const cornerRadius = frame._frameCornerRadius || 0;
+    if (frame.clipPath) {
+        frame.clipPath.set({
+            width: frame.width,
+            height: frame.height,
+            rx: cornerRadius,
+            ry: cornerRadius,
+        });
+    }
+    else {
+        setupClipPath(frame);
+    }
+}
+// ─────────────────────────────────────────────
+// Update corner radius on frame's background rect + clip path
+// Called from Canvas.svelte when the user changes the roundness slider
+// ─────────────────────────────────────────────
+export function updateFrameCornerRadius(frame, radiusPixels) {
+    const bg = getFrameBackground(frame);
+    if (bg) {
+        bg.set({ rx: radiusPixels, ry: radiusPixels });
+        bg.dirty = true;
+    }
+    // Also update the clip path so children are clipped to rounded bounds
+    if (frame.clipPath) {
+        frame.clipPath.set({ rx: radiusPixels, ry: radiusPixels });
+    }
+    // Store the pixel value on the frame for serialization/restoration
+    frame._frameCornerRadius = radiusPixels;
+    frame.dirty = true;
+}
+// ─────────────────────────────────────────────
+// Setup custom controls for the frame
+// Corner resize only (no rotation handle)
+// ─────────────────────────────────────────────
+function setupFrameControls(frame) {
+    // Remove the default rotation control (mtr)
+    // Keep corner controls for resize and middle controls for width/height
+    if (frame.controls && frame.controls.mtr) {
+        delete frame.controls.mtr;
+    }
+}
+// ─────────────────────────────────────────────
+// Add an object into the frame
+//
+// Uses frame.add() for correct coordinate conversion and internal state.
+// The key challenge: Fabric's _enterGroup (line ~11795 in index.node.mjs)
+// calls object.setCoords() BEFORE setting object.group and object.canvas,
+// producing wrong aCoords (no group context) and no oCoords (no canvas).
+//
+// Solution: Temporarily replace object.setCoords with a no-op during
+// frame.add(), then restore it and call setCoords() ourselves AFTER
+// _enterGroup has set object.group and object.canvas.
+//
+// IMPORTANT: We do NOT touch frame._shouldSetNestedCoords — that would
+// break the prototype chain and prevent Group.setCoords() from propagating
+// to children when the frame is moved.
+// ─────────────────────────────────────────────
+export function addObjectToFrame(frame, object, canvas) {
+    try {
+        // Skip if object is already in this frame (by group ref)
+        if (object.group === frame) {
+            canvasLog('addObjectToFrame: Object already in this frame (group ref)');
+            return;
+        }
+        // Skip if object is already in frame._objects (safety for edge cases
+        // where group ref wasn't set due to a previous partial add)
+        if (frame._objects && frame._objects.includes(object)) {
+            canvasWarn('addObjectToFrame: Object already in frame._objects array, fixing state');
+            // Fix: manually set group and canvas if they weren't set
+            if (object.group !== frame) {
+                object._set('group', frame);
+            }
+            if (!object.canvas && frame.canvas) {
+                object._set('canvas', frame.canvas);
+            }
+            object.setCoords();
+            return;
+        }
+        // Skip if object is the frame's background rect
+        if (object._isFrameBackground) {
+            canvasLog('addObjectToFrame: Cannot add frame background to itself');
+            return;
+        }
+        // Prevent self-nesting and circular nesting
+        if (object === frame) {
+            canvasLog('addObjectToFrame: Cannot add frame to itself');
+            return;
+        }
+        if (object._isFrame && isFrameShape(object)) {
+            let parent = frame.group;
+            while (parent) {
+                if (parent === object) {
+                    canvasLog('addObjectToFrame: Circular nesting prevented');
+                    return;
+                }
+                parent = parent.group;
+            }
+        }
+        // ── 1. Clear ALL stale matrix caches ──
+        object.matrixCache = undefined;
+        object.ownMatrixCache = undefined;
+        frame.matrixCache = undefined;
+        frame.ownMatrixCache = undefined;
+        // ── 2. Save frame dimensions (frame.add can trigger layout side-effects) ──
+        const savedFrameWidth = frame.width;
+        const savedFrameHeight = frame.height;
+        const savedFrameLeft = frame.left;
+        const savedFrameTop = frame.top;
+        // ── 3. Remove from current location ──
+        if (object.group) {
+            object.group.remove(object);
+        }
+        else if (canvas) {
+            canvas.remove(object);
+        }
+        // Clear caches after removal
+        object.matrixCache = undefined;
+        object.ownMatrixCache = undefined;
+        // ── 4. Block premature setCoords inside _enterGroup ──
+        // Fabric's _enterGroup calls: this._shouldSetNestedCoords() && object.setCoords()
+        // At that point, object.group and object.canvas are NOT yet set, producing
+        // wrong coords. We patch object.setCoords to a no-op during frame.add().
+        // This is safer than patching frame._shouldSetNestedCoords which breaks
+        // the frame's prototype chain (Group.setCoords won't propagate to children).
+        object.setCoords = function () { }; // no-op during frame.add
+        // ── 5. Use frame.add() — handles coordinate conversion, events, layout ──
+        frame.add(object);
+        // ── 6. Restore object.setCoords from prototype ──
+        // Remove own property so it falls back to InteractiveObject.prototype.setCoords
+        delete object.setCoords;
+        // ── 7. Safety: ensure object.canvas is set ──
+        // _enterGroup should have set it, but verify as a safety net
+        if (!object.canvas && frame.canvas) {
+            canvasWarn('addObjectToFrame: canvas not set by _enterGroup, fixing manually');
+            object._set('canvas', frame.canvas);
+        }
+        // ── 8. Safety: ensure object.group is set ──
+        if (object.group !== frame) {
+            canvasWarn('addObjectToFrame: group not set by _enterGroup, fixing manually');
+            object._set('group', frame);
+        }
+        // ── 9. Restore frame dimensions if layout changed them ──
+        if (frame.width !== savedFrameWidth || frame.height !== savedFrameHeight ||
+            frame.left !== savedFrameLeft || frame.top !== savedFrameTop) {
+            frame.set({
+                width: savedFrameWidth,
+                height: savedFrameHeight,
+                left: savedFrameLeft,
+                top: savedFrameTop,
+            });
+        }
+        // ── 10. Clear stale matrix caches after group membership change ──
+        object.matrixCache = undefined;
+        object.ownMatrixCache = undefined;
+        frame.matrixCache = undefined;
+        frame.ownMatrixCache = undefined;
+        // ── 11. Clear stale _activeObjects ──
+        if (frame._activeObjects && frame._activeObjects.length > 0) {
+            frame._activeObjects = [];
+        }
+        // ── 12. NOW call setCoords — with object.group and object.canvas properly set ──
+        // This produces correct aCoords (corners in absolute space via
+        // calcTransformMatrix = frameMatrix * ownMatrix) and correct oCoords
+        // (control positions in viewport space, requires this.canvas).
+        object.setCoords();
+        // frame.setCoords() propagates to ALL children via _shouldSetNestedCoords()
+        // which returns this.subTargetCheck (true for our frame).
+        frame.setCoords();
+        frame.dirty = true;
+        // ── 13. Update clip path ──
+        updateClipPath(frame);
+        // ── 14. Track parent frame ID on child for orphan-repair on reload ──
+        // If the child is somehow not inside the frame group after a save/load cycle,
+        // loadCanvas will use _parentFrameId to re-attach it to the correct frame.
+        object._parentFrameId = frame._objectId || null;
+        // Debug: verify all state is correct
+        const hasGroup = object.group === frame;
+        const hasCanvas = !!object.canvas;
+        const hasOCoords = !!object.oCoords;
+        const nestedCoordsWorks = frame._shouldSetNestedCoords();
+        const isInObjects = frame._objects.includes(object);
+        canvasLog('addObjectToFrame: Object added to frame', {
+            objectType: object.type || object._customType,
+            frameLabel: frame._labelText,
+            hasGroup,
+            hasCanvas,
+            hasOCoords,
+            nestedCoordsWorks,
+            isInObjects,
+        });
+    }
+    catch (error) {
+        console.error('addObjectToFrame: Failed to add object', error);
+    }
+}
+// ─────────────────────────────────────────────
+// Remove an object from the frame
+// Manual coordinate conversion that converts group-relative → canvas-absolute
+// ─────────────────────────────────────────────
+export function removeObjectFromFrame(frame, object, canvas) {
+    try {
+        // Skip if object is not in this frame
+        if (object.group !== frame) {
+            canvasLog('removeObjectFromFrame: Object not in this frame');
+            return;
+        }
+        // Skip the background rect
+        if (object._isFrameBackground) {
+            canvasLog('removeObjectFromFrame: Cannot remove frame background');
+            return;
+        }
+        const { applyTransformToObject } = util;
+        // Calculate absolute transform BEFORE any removal
+        // (calcTransformMatrix chains through the parent group)
+        const absMatrix = object.calcTransformMatrix();
+        // Use Fabric's own Group.remove() for thorough internal cleanup.
+        // This handles _objects removal, _watchObject, canvas refs, events, etc.
+        frame.remove(object);
+        // Apply absolute coordinates (Group.remove may reset them)
+        applyTransformToObject(object, absMatrix);
+        // Explicitly clear any lingering group/parent references
+        object._set('group', undefined);
+        object._set('parent', undefined);
+        // Clear parent frame tracking — object is no longer in any frame
+        object._parentFrameId = undefined;
+        // Clear stale matrix caches
+        object.matrixCache = undefined;
+        object.ownMatrixCache = undefined;
+        frame.setCoords();
+        frame.dirty = true;
+        // Add back to canvas as a free-standing object with absolute coordinates
+        if (canvas) {
+            canvas.add(object);
+            object.setCoords();
+        }
+        canvasLog('removeObjectFromFrame: Object removed from frame', {
+            objectType: object.type || object._customType,
+            frameLabel: frame._labelText,
+        });
+    }
+    catch (error) {
+        console.error('removeObjectFromFrame: Failed to remove object', error);
+    }
+}
+// ─────────────────────────────────────────────
+// Check if a canvas-space point is inside a frame's label area
+// Used for extending the clickable/draggable area to include the label
+// ─────────────────────────────────────────────
+export function isPointInFrameLabel(frame, point) {
+    try {
+        // Use full transform to get visual dimensions (including parent groups)
+        const m = frame.calcTransformMatrix();
+        const totalScaleX = Math.sqrt(m[0] * m[0] + m[1] * m[1]);
+        const totalScaleY = Math.sqrt(m[2] * m[2] + m[3] * m[3]);
+        const frameW = (frame.width || 100) * totalScaleX;
+        const frameH = (frame.height || 100) * totalScaleY;
+        const center = frame.getCenterPoint();
+        // Label sits above the top of the frame
+        const fontSize = frame._labelFontSize || DEFAULT_LABEL_FONT_SIZE;
+        const lineHeight = fontSize * 1.2;
+        const padding = 6;
+        const gap = 4;
+        const labelHeight = lineHeight + padding * 2;
+        const frameLeft = center.x - frameW / 2;
+        const frameTop = center.y - frameH / 2;
+        const labelBgX = frameLeft;
+        const labelBgY = frameTop - labelHeight - gap;
+        return (point.x >= labelBgX && point.x <= labelBgX + frameW &&
+            point.y >= labelBgY && point.y <= frameTop);
+    }
+    catch {
+        return false;
+    }
+}
+// ─────────────────────────────────────────────
+// Check if a canvas-absolute point is inside a frame's boundaries
+// Used for containment detection during drag
+// ─────────────────────────────────────────────
+export function isPointInsideFrame(frame, point) {
+    try {
+        const frameCenter = frame.getCenterPoint();
+        // Use visual (scaled) dimensions for the hit-test
+        const halfW = ((frame.width || 0) * (frame.scaleX || 1)) / 2;
+        const halfH = ((frame.height || 0) * (frame.scaleY || 1)) / 2;
+        // Simple AABB check (ignoring rotation for now - frames have lockRotation)
+        return (point.x >= frameCenter.x - halfW &&
+            point.x <= frameCenter.x + halfW &&
+            point.y >= frameCenter.y - halfH &&
+            point.y <= frameCenter.y + halfH);
+    }
+    catch {
+        return false;
+    }
+}
+// ─────────────────────────────────────────────
+// Check if a canvas-space point is on a frame's border/stroke area.
+// Returns true only for points near the frame edge (within hit thickness),
+// not for points in the interior.
+// ─────────────────────────────────────────────
+export function isPointOnFrameBorder(frame, point) {
+    try {
+        const m = frame.calcTransformMatrix();
+        const totalScaleX = Math.sqrt(m[0] * m[0] + m[1] * m[1]);
+        const totalScaleY = Math.sqrt(m[2] * m[2] + m[3] * m[3]);
+        const frameW = (frame.width || 100) * totalScaleX;
+        const frameH = (frame.height || 100) * totalScaleY;
+        const center = frame.getCenterPoint();
+        const left = center.x - frameW / 2;
+        const right = center.x + frameW / 2;
+        const top = center.y - frameH / 2;
+        const bottom = center.y + frameH / 2;
+        // Hit zone: half the stroke width + a generous pointer buffer for easy grabbing
+        const strokeW = frame._frameStrokeWidth || DEFAULT_STROKE_WIDTH;
+        const hitZone = Math.max(strokeW / 2 + 4, 6);
+        // Must be within outer bounds (with tolerance)
+        if (point.x < left - hitZone || point.x > right + hitZone ||
+            point.y < top - hitZone || point.y > bottom + hitZone) {
+            return false;
+        }
+        // If well inside the inner bounds, it's the interior — not the border
+        if (point.x > left + hitZone && point.x < right - hitZone &&
+            point.y > top + hitZone && point.y < bottom - hitZone) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─────────────────────────────────────────────
+// Apply border-only hit test to a frame instance.
+// Frame is selectable only by clicking its border/stroke or label area —
+// clicking the interior is a click-through so rubber-band selection can start there.
+// Must be called from both createFrameShape and reapplyFrameRender.
+// ─────────────────────────────────────────────
+export function applyFrameHitTest(frame) {
+    frame.containsPoint = function (point) {
+        const canvasRef = this.canvas;
+        if (!canvasRef)
+            return false;
+        // Convert viewport-space point to canvas (scene) space
+        const vpt = canvasRef.viewportTransform || [1, 0, 0, 1, 0, 0];
+        const inv = util.invertTransform(vpt);
+        const canvasX = inv[0] * point.x + inv[2] * point.y + inv[4];
+        const canvasY = inv[1] * point.x + inv[3] * point.y + inv[5];
+        const canvasPoint = { x: canvasX, y: canvasY };
+        // 1. Label area (above the frame) → selectable
+        if (isPointInFrameLabel(this, canvasPoint))
+            return true;
+        // 2. Border/stroke area → selectable
+        if (isPointOnFrameBorder(this, canvasPoint))
+            return true;
+        // 3. Interior → click-through (Fabric will start rubber-band selection)
+        return false;
+    };
+}
+// ─────────────────────────────────────────────
+// Get all non-background children of a frame
+// (Excludes the background rect)
+// ─────────────────────────────────────────────
+export function getFrameChildren(frame) {
+    return frame.getObjects().filter((obj) => !obj._isFrameBackground);
+}
+// ─────────────────────────────────────────────
+// Get the background rect of a frame
+// ─────────────────────────────────────────────
+export function getFrameBackground(frame) {
+    const bg = frame.getObjects().find((obj) => obj._isFrameBackground);
+    if (bg)
+        return bg;
+    // Fallback: when _isFrameBackground flag is missing (e.g. after JSON round-trip with
+    // incomplete custom props), the first Rect in the group is the background rect.
+    const fallbackRect = frame.getObjects().find((obj) => (obj.type === 'rect' || obj.type === 'Rect') && !obj._isFrame);
+    if (fallbackRect) {
+        fallbackRect._isFrameBackground = true; // Re-mark so future calls skip this path
+        canvasLog('FrameShape: getFrameBackground — fallback, re-marked rect as background for frame', frame._labelText);
+        return fallbackRect;
+    }
+    return null;
+}
+// ─────────────────────────────────────────────
+// Update the frame's background rect visual properties
+// (fill, stroke, strokeWidth)
+// ─────────────────────────────────────────────
+export function updateFrameBackground(frame, props) {
+    const bg = getFrameBackground(frame);
+    if (bg) {
+        bg.set(props);
+        bg.dirty = true;
+    }
+    // Also store on frame custom props
+    const frameAny = frame;
+    if (props.fill !== undefined)
+        frameAny._frameFill = props.fill;
+    if (props.stroke !== undefined)
+        frameAny._frameStroke = props.stroke;
+    if (props.strokeWidth !== undefined)
+        frameAny._frameStrokeWidth = props.strokeWidth;
+    frame.dirty = true;
+}
+// ─────────────────────────────────────────────
+// Normalize frame after scaling
+// Converts scaleX/scaleY back to width/height so the label stays consistent.
+// preserveChildren = false (default): children scale with frame
+// preserveChildren = true (Option key): only frame resizes, children stay at position/size
+// ─────────────────────────────────────────────
+export function normalizeFrameAfterScaling(frame, preserveChildren = false) {
+    const scaleX = frame.scaleX || 1;
+    const scaleY = frame.scaleY || 1;
+    if (scaleX === 1 && scaleY === 1)
+        return;
+    let newWidth = (frame.width || 0) * scaleX;
+    let newHeight = (frame.height || 0) * scaleY;
+    // Enforce minimums
+    newWidth = Math.max(newWidth, MIN_FRAME_WIDTH);
+    newHeight = Math.max(newHeight, MIN_FRAME_HEIGHT);
+    // Also scale the background rect dimensions and reset its scale
+    const bg = getFrameBackground(frame);
+    if (bg) {
+        bg.set({
+            width: newWidth,
+            height: newHeight,
+            scaleX: 1,
+            scaleY: 1,
+        });
+    }
+    // Adjust children based on mode
+    const children = getFrameChildren(frame);
+    if (!preserveChildren) {
+        // DEFAULT: Scale children's positions and sizes so they appear at the same
+        // visual position/size as during the scaling drag
+        for (const child of children) {
+            child.set({
+                left: (child.left || 0) * scaleX,
+                top: (child.top || 0) * scaleY,
+                scaleX: (child.scaleX || 1) * scaleX,
+                scaleY: (child.scaleY || 1) * scaleY,
+            });
+            child.setCoords();
+        }
+    }
+    // When preserveChildren = true: don't adjust children at all.
+    // After normalization (frame scaleX/Y → 1), children remain at their
+    // original group-relative positions and sizes. The frame's viewport expands
+    // but children stay put.
+    // Reset frame scale and set new dimensions
+    frame.set({
+        width: newWidth,
+        height: newHeight,
+        scaleX: 1,
+        scaleY: 1,
+    });
+    // Update clip path for new dimensions
+    updateClipPath(frame);
+    // Recalculate corner radius from percentage after resize
+    // (percentage stays constant, pixel value adapts to new dimensions)
+    const cornerRoundness = frame._cornerRoundness || 0;
+    if (cornerRoundness > 0) {
+        const minDim = Math.min(newWidth, newHeight);
+        const newRadius = (cornerRoundness / 100) * (minDim / 2);
+        updateFrameCornerRadius(frame, newRadius);
+    }
+    frame.setCoords();
+    frame.dirty = true;
+}
+// ─────────────────────────────────────────────
+// Enforce minimum size during scaling (call from object:scaling event)
+// ─────────────────────────────────────────────
+export function enforceFrameMinSize(frame) {
+    const currentWidth = (frame.width || 0) * (frame.scaleX || 1);
+    const currentHeight = (frame.height || 0) * (frame.scaleY || 1);
+    if (currentWidth < MIN_FRAME_WIDTH) {
+        frame.scaleX = MIN_FRAME_WIDTH / (frame.width || 1);
+    }
+    if (currentHeight < MIN_FRAME_HEIGHT) {
+        frame.scaleY = MIN_FRAME_HEIGHT / (frame.height || 1);
+    }
+}
+// ─────────────────────────────────────────────
+// List of custom properties for copy/paste serialization
+// ─────────────────────────────────────────────
+export const FRAME_CUSTOM_PROPS = [
+    '_customType', '_isFrame', '_isFrameBackground',
+    '_labelText', '_labelFontSize', '_labelFontFamily', '_labelColor',
+    '_labelBackgroundColor', '_labelTextAlign', '_labelFontWeight',
+    '_labelFontStyle', '_labelUnderline',
+    '_frameFill', '_frameStroke', '_frameStrokeWidth', '_frameStrokeDashArray',
+    '_cornerRoundness', '_frameCornerRadius',
+    // Tracks which frame a child belongs to; used to repair orphaned children on reload
+    '_parentFrameId',
+];
+// ─────────────────────────────────────────────
+// Helper: Check if a Fabric object is a FrameShape
+// ─────────────────────────────────────────────
+export function isFrameShape(obj) {
+    return obj && (obj._isFrame === true || obj._customType === 'frame');
+}
+// ─────────────────────────────────────────────
+// Reapply custom render to a cloned/deserialized frame
+// Call this after copy/paste or JSON load to restore the label rendering
+// ─────────────────────────────────────────────
+export function reapplyFrameRender(frame) {
+    // ── Upgrade to FrameShape prototype if needed ──────────────────────────────
+    // Called on: (a) newly deserialized objects via FrameShape.fromObject (already upgraded),
+    //            (b) old-format saves (type:'Group' + _isFrame:true) via loadCanvas reviver,
+    //            (c) any backward-compat path that still passes plain Groups here.
+    // Fabric's type getter reads this.constructor.type.toLowerCase(), so after setPrototypeOf:
+    //   frame.constructor === FrameShape  →  frame.type === 'frameshape'
+    //   frame.toObject() calls FrameShape.prototype.toObject()  →  serializes type:'FrameShape'
+    if (Object.getPrototypeOf(frame) !== FrameShape.prototype) {
+        Object.setPrototypeOf(frame, FrameShape.prototype);
+        canvasLog('FrameShape: reapplyFrameRender — upgraded Group to FrameShape prototype for', frame._labelText || '(unlabelled)');
+    }
+    // Ensure backward-compat flags are always present
+    if (!frame._isFrame)
+        frame._isFrame = true;
+    if (!frame._customType)
+        frame._customType = 'frame';
+    const originalRender = Group.prototype.render.bind(frame);
+    frame.render = function (ctx) {
+        originalRender(ctx);
+        // Draw label using Fabric's this.transform() which automatically handles
+        // the parent chain (_transformDone flag), then counter-scale to 1:1.
+        // This approach works identically for top-level and nested frames.
+        ctx.save();
+        this.transform(ctx);
+        const scaling = this.getObjectScaling();
+        ctx.scale(1 / scaling.x, 1 / scaling.y);
+        renderFrameLabel(ctx, this);
+        ctx.restore();
+    };
+    // Remove rotation control if it exists
+    if (frame.controls && frame.controls.mtr) {
+        delete frame.controls.mtr;
+    }
+    // Restore interactive Group properties lost during clone/fromObject
+    // (Group.fromObject creates a plain Group without these)
+    frame.interactive = true;
+    frame.subTargetCheck = true;
+    frame.objectCaching = false;
+    frame.lockRotation = true;
+    frame.hoverCursor = 'move';
+    frame.moveCursor = 'move';
+    // Unsubscribe old LayoutManager from children before replacing it.
+    // Group.fromObject subscribes a FitContentLayout (or the saved one) to all
+    // children — if we just overwrite layoutManager without cleaning up, those
+    // event handlers keep pointing to the old manager and can cause stale layouts.
+    if (frame.layoutManager) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            frame.layoutManager.unsubscribeTargets({ target: frame, targets: frame.getObjects() });
+        }
+        catch {
+            // Ignore errors if old manager has no subscriptions
+        }
+    }
+    frame.layoutManager = new LayoutManager(new FixedLayout());
+    // Restore background rect's non-interactive flags (not serialized by Fabric)
+    // Without this, the cloned background becomes selectable and "breaks" the Frame:
+    // clicking the frame selects the rect child instead of the Group.
+    const bg = getFrameBackground(frame);
+    if (bg) {
+        bg.selectable = false;
+        bg.evented = false;
+    }
+    // Ensure clip path is set
+    if (!frame.clipPath) {
+        setupClipPath(frame);
+    }
+    // Restore corner radius on background rect and clip path
+    // (after clipPath is ensured, so we can set rx/ry on it)
+    const cornerRadius = frame._frameCornerRadius || 0;
+    if (cornerRadius > 0) {
+        updateFrameCornerRadius(frame, cornerRadius);
+    }
+    // Restore border-only hit test (lost during clone/fromObject)
+    applyFrameHitTest(frame);
+    frame.dirty = true;
+}