@editframe/elements 0.30.1-beta.0 → 0.31.0-beta.0

package/dist/canvas/api/CanvasAPI.js

@@ -0,0 +1,182 @@
+//#region src/canvas/api/CanvasAPI.ts
+/**
+* Programmatic API/SDK for canvas operations.
+*/
+var CanvasAPI = class {
+	constructor(canvas) {
+		this.canvas = canvas;
+	}
+	/**
+	* Register an existing element for canvas management.
+	* @param element - The HTML element to register
+	* @param id - Optional custom ID, otherwise auto-generated
+	* @returns The element ID
+	*/
+	registerElement(element, id) {
+		return this.canvas.registerElement(element, id);
+	}
+	/**
+	* Unregister an element from canvas management.
+	* @param id - Element ID or element itself
+	*/
+	unregisterElement(id) {
+		this.canvas.unregisterElement(id);
+	}
+	/**
+	* Update element position/transform in canvas coordinates.
+	* @param id - Element ID
+	* @param updates - Partial element data to update
+	*/
+	updateElement(id, updates) {
+		const current = this.getElement(id);
+		if (!current) throw new Error(`Element ${id} not found`);
+		if (updates.x !== void 0 || updates.y !== void 0) {
+			const x = updates.x !== void 0 ? updates.x : current.x;
+			const y = updates.y !== void 0 ? updates.y : current.y;
+			this.canvas.updateElementPosition(id, x, y);
+		}
+		if (updates.width !== void 0 || updates.height !== void 0) {
+			const element = current.element;
+			const width = updates.width !== void 0 ? updates.width : current.width;
+			const height = updates.height !== void 0 ? updates.height : current.height;
+			element.style.width = `${width}px`;
+			element.style.height = `${height}px`;
+		}
+		if (updates.rotation !== void 0) {
+			const element = current.element;
+			element.style.transform = `rotate(${updates.rotation}deg)`;
+		}
+	}
+	/**
+	* Get element data by ID.
+	* @param id - Element ID
+	* @returns Element data or null if not found
+	*/
+	getElement(id) {
+		return this.canvas.getElementData(id);
+	}
+	/**
+	* Get all registered elements.
+	* @returns Array of all element data
+	*/
+	getAllElements() {
+		return this.canvas.getAllElementsData();
+	}
+	/**
+	* Get the number of registered elements.
+	* @returns The count of registered elements
+	*/
+	get elementCount() {
+		return this.getAllElements().length;
+	}
+	/**
+	* Get all registered elements (getter alias for getAllElements).
+	* @returns Array of all element data
+	*/
+	get elements() {
+		return this.getAllElements();
+	}
+	/**
+	* Convert screen coordinates to canvas coordinates.
+	* @param screenX - X coordinate in screen space
+	* @param screenY - Y coordinate in screen space
+	* @returns Canvas coordinates
+	*/
+	screenToCanvas(screenX, screenY) {
+		return this.canvas.screenToCanvasCoords(screenX, screenY);
+	}
+	/**
+	* Convert canvas coordinates to screen coordinates.
+	* @param canvasX - X coordinate in canvas space
+	* @param canvasY - Y coordinate in canvas space
+	* @returns Screen coordinates
+	*/
+	canvasToScreen(canvasX, canvasY) {
+		return this.canvas.canvasToScreenCoords(canvasX, canvasY);
+	}
+	/**
+	* Select an element.
+	* @param id - Element ID
+	*/
+	select(id) {
+		this.canvas.selectionController.getModel().select(id);
+	}
+	/**
+	* Select multiple elements.
+	* @param ids - Array of element IDs
+	*/
+	selectMultiple(ids) {
+		this.canvas.selectionController.getModel().selectMultiple(ids);
+	}
+	/**
+	* Deselect an element.
+	* @param id - Element ID
+	*/
+	deselect(id) {
+		this.canvas.selectionController.getModel().deselect(id);
+	}
+	/**
+	* Get currently selected element IDs.
+	* @returns Set of selected IDs
+	*/
+	getSelectedIds() {
+		const controller = this.canvas.selectionController;
+		return Array.from(controller.getModel().selectedIds);
+	}
+	/**
+	* Create a group from element IDs.
+	* @param ids - Array of element IDs to group
+	* @returns Group ID
+	*/
+	group(ids) {
+		return this.canvas.selectionController.getModel().createGroup(ids);
+	}
+	/**
+	* Ungroup a group.
+	* @param groupId - Group ID
+	*/
+	ungroup(groupId) {
+		this.canvas.selectionController.getModel().ungroup(groupId);
+	}
+	/**
+	* Export canvas data.
+	* @returns Canvas data structure
+	*/
+	export() {
+		const model = this.canvas.selectionController.getModel();
+		const groups = [];
+		const processedGroups = /* @__PURE__ */ new Set();
+		for (const elementId of this.getAllElements().map((e) => e.id)) {
+			const groupId = model.getGroupId(elementId);
+			if (groupId && !processedGroups.has(groupId)) {
+				processedGroups.add(groupId);
+				groups.push({
+					id: groupId,
+					elementIds: model.getGroupElements(groupId)
+				});
+			}
+		}
+		return {
+			elements: this.getAllElements(),
+			groups
+		};
+	}
+	/**
+	* Import canvas data.
+	* @param data - Canvas data structure
+	*/
+	import(data) {
+		for (const element of this.getAllElements()) this.unregisterElement(element.id);
+		for (const elementData of data.elements) {
+			const element = elementData.element;
+			this.registerElement(element, elementData.id);
+			this.updateElement(elementData.id, elementData);
+		}
+		const controller = this.canvas.selectionController;
+		for (const group of data.groups) controller.getModel().createGroup(group.elementIds);
+	}
+};
+
+//#endregion
+export { CanvasAPI };
+//# sourceMappingURL=CanvasAPI.js.map

package/dist/canvas/api/CanvasAPI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasAPI.js","names":["canvas: EFCanvas","groups: Array<{ id: string; elementIds: string[] }>"],"sources":["../../../src/canvas/api/CanvasAPI.ts"],"sourcesContent":["import type { EFCanvas } from \"../EFCanvas.js\";\nimport type { CanvasElementData, CanvasData } from \"./types.js\";\nimport { SelectionModel } from \"../selection/SelectionModel.js\";\n\n/**\n * Programmatic API/SDK for canvas operations.\n */\nexport class CanvasAPI {\n  constructor(private canvas: EFCanvas) {}\n\n  /**\n   * Register an existing element for canvas management.\n   * @param element - The HTML element to register\n   * @param id - Optional custom ID, otherwise auto-generated\n   * @returns The element ID\n   */\n  registerElement(element: HTMLElement, id?: string): string {\n    return (this.canvas as any).registerElement(element, id);\n  }\n\n  /**\n   * Unregister an element from canvas management.\n   * @param id - Element ID or element itself\n   */\n  unregisterElement(id: string | HTMLElement): void {\n    (this.canvas as any).unregisterElement(id);\n  }\n\n  /**\n   * Update element position/transform in canvas coordinates.\n   * @param id - Element ID\n   * @param updates - Partial element data to update\n   */\n  updateElement(id: string, updates: Partial<CanvasElementData>): void {\n    const current = this.getElement(id);\n    if (!current) {\n      throw new Error(`Element ${id} not found`);\n    }\n\n    if (updates.x !== undefined || updates.y !== undefined) {\n      const x = updates.x !== undefined ? updates.x : current.x;\n      const y = updates.y !== undefined ? updates.y : current.y;\n      (this.canvas as any).updateElementPosition(id, x, y);\n    }\n\n    if (updates.width !== undefined || updates.height !== undefined) {\n      const element = current.element;\n      const width = updates.width !== undefined ? updates.width : current.width;\n      const height =\n        updates.height !== undefined ? updates.height : current.height;\n      // Set size in canvas coordinates (parent transform handles scaling)\n      element.style.width = `${width}px`;\n      element.style.height = `${height}px`;\n    }\n\n    if (updates.rotation !== undefined) {\n      const element = current.element;\n      element.style.transform = `rotate(${updates.rotation}deg)`;\n    }\n  }\n\n  /**\n   * Get element data by ID.\n   * @param id - Element ID\n   * @returns Element data or null if not found\n   */\n  getElement(id: string): CanvasElementData | null {\n    return (this.canvas as any).getElementData(id);\n  }\n\n  /**\n   * Get all registered elements.\n   * @returns Array of all element data\n   */\n  getAllElements(): CanvasElementData[] {\n    return (this.canvas as any).getAllElementsData();\n  }\n\n  /**\n   * Get the number of registered elements.\n   * @returns The count of registered elements\n   */\n  get elementCount(): number {\n    return this.getAllElements().length;\n  }\n\n  /**\n   * Get all registered elements (getter alias for getAllElements).\n   * @returns Array of all element data\n   */\n  get elements(): CanvasElementData[] {\n    return this.getAllElements();\n  }\n\n  /**\n   * Convert screen coordinates to canvas coordinates.\n   * @param screenX - X coordinate in screen space\n   * @param screenY - Y coordinate in screen space\n   * @returns Canvas coordinates\n   */\n  screenToCanvas(screenX: number, screenY: number): { x: number; y: number } {\n    return (this.canvas as any).screenToCanvasCoords(screenX, screenY);\n  }\n\n  /**\n   * Convert canvas coordinates to screen coordinates.\n   * @param canvasX - X coordinate in canvas space\n   * @param canvasY - Y coordinate in canvas space\n   * @returns Screen coordinates\n   */\n  canvasToScreen(canvasX: number, canvasY: number): { x: number; y: number } {\n    return (this.canvas as any).canvasToScreenCoords(canvasX, canvasY);\n  }\n\n  /**\n   * Select an element.\n   * @param id - Element ID\n   */\n  select(id: string): void {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    controller.getModel().select(id);\n    // Update is deferred via selectionchange event listener\n  }\n\n  /**\n   * Select multiple elements.\n   * @param ids - Array of element IDs\n   */\n  selectMultiple(ids: string[]): void {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    controller.getModel().selectMultiple(ids);\n    // Update is deferred via selectionchange event listener\n  }\n\n  /**\n   * Deselect an element.\n   * @param id - Element ID\n   */\n  deselect(id: string): void {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    controller.getModel().deselect(id);\n    // Update is deferred via selectionchange event listener\n  }\n\n  /**\n   * Get currently selected element IDs.\n   * @returns Set of selected IDs\n   */\n  getSelectedIds(): string[] {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    return Array.from(controller.getModel().selectedIds);\n  }\n\n  /**\n   * Create a group from element IDs.\n   * @param ids - Array of element IDs to group\n   * @returns Group ID\n   */\n  group(ids: string[]): string {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    const groupId = controller.getModel().createGroup(ids);\n    // Update is deferred via selectionchange event listener\n    return groupId;\n  }\n\n  /**\n   * Ungroup a group.\n   * @param groupId - Group ID\n   */\n  ungroup(groupId: string): void {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    controller.getModel().ungroup(groupId);\n    // Update is deferred via selectionchange event listener\n  }\n\n  /**\n   * Export canvas data.\n   * @returns Canvas data structure\n   */\n  export(): CanvasData {\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    const model = controller.getModel();\n    const groups: Array<{ id: string; elementIds: string[] }> = [];\n\n    // Collect all groups\n    const processedGroups = new Set<string>();\n    for (const elementId of this.getAllElements().map((e) => e.id)) {\n      const groupId = model.getGroupId(elementId);\n      if (groupId && !processedGroups.has(groupId)) {\n        processedGroups.add(groupId);\n        groups.push({\n          id: groupId,\n          elementIds: model.getGroupElements(groupId),\n        });\n      }\n    }\n\n    return {\n      elements: this.getAllElements(),\n      groups,\n    };\n  }\n\n  /**\n   * Import canvas data.\n   * @param data - Canvas data structure\n   */\n  import(data: CanvasData): void {\n    // Clear existing\n    for (const element of this.getAllElements()) {\n      this.unregisterElement(element.id);\n    }\n\n    // Import elements\n    for (const elementData of data.elements) {\n      const element = elementData.element;\n      this.registerElement(element, elementData.id);\n      this.updateElement(elementData.id, elementData);\n    }\n\n    // Import groups\n    const controller = (this.canvas as any).selectionController as {\n      getModel(): SelectionModel;\n    };\n    for (const group of data.groups) {\n      controller.getModel().createGroup(group.elementIds);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/canvas/api/types.d.ts

@@ -0,0 +1,42 @@
+//#region src/canvas/api/types.d.ts
+/**
+ * Core types for the canvas system.
+ */
+/**
+ * Selection state enumeration.
+ */
+type SelectionState = "none" | "single" | "multiple" | "box-selecting";
+/**
+ * Element bounds interface - elements can implement this to override default bounding rect.
+ * This allows elements to provide custom hit testing areas or account for visual bounds
+ * that differ from DOM bounds.
+ */
+interface CanvasElementBounds {
+  getCanvasBounds(): DOMRect;
+}
+/**
+ * Canvas element metadata for API/manipulation.
+ * Positions and dimensions are in canvas coordinate space.
+ */
+interface CanvasElementData {
+  id: string;
+  element: HTMLElement;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rotation?: number;
+}
+/**
+ * Canvas data structure for export/import.
+ */
+interface CanvasData {
+  elements: CanvasElementData[];
+  groups: Array<{
+    id: string;
+    elementIds: string[];
+  }>;
+}
+//#endregion
+export { CanvasData, CanvasElementBounds, CanvasElementData, SelectionState };
+//# sourceMappingURL=types.d.ts.map

package/dist/canvas/coordinateTransform.js

@@ -0,0 +1,90 @@
+//#region src/canvas/coordinateTransform.ts
+/**
+* =============================================================================
+* COORDINATE SPACES
+* =============================================================================
+*
+* This module provides utilities for converting between two coordinate spaces:
+*
+* 1. SCREEN SPACE (viewport coordinates)
+*    - Origin: Top-left of browser viewport
+*    - Units: Physical screen pixels
+*    - Used by: getBoundingClientRect(), mouse events (clientX/clientY)
+*    - AFFECTED by: zoom/scale transforms
+*
+* 2. CANVAS SPACE (logical coordinates)
+*    - Origin: Top-left of the canvas content area
+*    - Units: CSS pixels at 1:1 scale (unaffected by zoom)
+*    - Used by: Element positioning (style.left/top), metadata storage
+*    - NOT AFFECTED by: zoom/scale transforms
+*
+* KEY RELATIONSHIP:
+*   screenPosition = canvasRect.origin + (canvasPosition * scale)
+*   canvasPosition = (screenPosition - canvasRect.origin) / scale
+*
+* IMPORTANT: These functions convert POSITIONS, not DIMENSIONS.
+*
+* For positions (like element center or mouse coordinates):
+*   - Use screenToCanvas() / canvasToScreen() for conversion
+*
+* For dimensions (like element width/height):
+*   - Screen dimensions = canvas dimensions * scale
+*   - Canvas dimensions = screen dimensions / scale
+*   - OR better: use offsetWidth/offsetHeight which are already in canvas space
+*
+* =============================================================================
+*/
+/**
+* Convert screen coordinates to canvas coordinates.
+*
+* Use this for converting POSITIONS from screen space (getBoundingClientRect,
+* mouse events) to canvas space (element positioning, metadata).
+*
+* Example: Converting a click position to canvas coordinates for hit testing.
+* Example: Converting element center from screen to canvas for metadata.
+*
+* @param screenX - X coordinate in screen space (e.g., event.clientX, rect.left)
+* @param screenY - Y coordinate in screen space (e.g., event.clientY, rect.top)
+* @param canvasRect - Canvas content element's bounding rect (.canvas-content, not <ef-canvas>)
+* @param panZoomTransform - Optional PanZoom transform from context
+* @returns Object with x, y in canvas coordinate space
+*/
+function screenToCanvas(screenX, screenY, canvasRect, panZoomTransform) {
+	if (!panZoomTransform) return {
+		x: screenX - canvasRect.left,
+		y: screenY - canvasRect.top
+	};
+	return {
+		x: (screenX - canvasRect.left) / panZoomTransform.scale,
+		y: (screenY - canvasRect.top) / panZoomTransform.scale
+	};
+}
+/**
+* Convert canvas coordinates to screen coordinates.
+*
+* Use this for converting POSITIONS from canvas space (element positioning,
+* metadata) to screen space (overlay positioning, visual display).
+*
+* Example: Converting element top-left from metadata to screen position for overlays.
+* Example: Converting a canvas point to screen coordinates for rendering guides.
+*
+* @param canvasX - X coordinate in canvas space (from metadata or style.left)
+* @param canvasY - Y coordinate in canvas space (from metadata or style.top)
+* @param canvasRect - Canvas content element's bounding rect (.canvas-content, not <ef-canvas>)
+* @param panZoomTransform - Optional PanZoom transform from context
+* @returns Object with x, y in screen coordinate space
+*/
+function canvasToScreen(canvasX, canvasY, canvasRect, panZoomTransform) {
+	if (!panZoomTransform) return {
+		x: canvasRect.left + canvasX,
+		y: canvasRect.top + canvasY
+	};
+	return {
+		x: canvasRect.left + canvasX * panZoomTransform.scale,
+		y: canvasRect.top + canvasY * panZoomTransform.scale
+	};
+}
+
+//#endregion
+export { canvasToScreen, screenToCanvas };
+//# sourceMappingURL=coordinateTransform.js.map

package/dist/canvas/coordinateTransform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateTransform.js","names":[],"sources":["../../src/canvas/coordinateTransform.ts"],"sourcesContent":["import type { PanZoomTransform } from \"../elements/EFPanZoom.js\";\n\n/**\n * =============================================================================\n * COORDINATE SPACES\n * =============================================================================\n *\n * This module provides utilities for converting between two coordinate spaces:\n *\n * 1. SCREEN SPACE (viewport coordinates)\n *    - Origin: Top-left of browser viewport\n *    - Units: Physical screen pixels\n *    - Used by: getBoundingClientRect(), mouse events (clientX/clientY)\n *    - AFFECTED by: zoom/scale transforms\n *\n * 2. CANVAS SPACE (logical coordinates)\n *    - Origin: Top-left of the canvas content area\n *    - Units: CSS pixels at 1:1 scale (unaffected by zoom)\n *    - Used by: Element positioning (style.left/top), metadata storage\n *    - NOT AFFECTED by: zoom/scale transforms\n *\n * KEY RELATIONSHIP:\n *   screenPosition = canvasRect.origin + (canvasPosition * scale)\n *   canvasPosition = (screenPosition - canvasRect.origin) / scale\n *\n * IMPORTANT: These functions convert POSITIONS, not DIMENSIONS.\n *\n * For positions (like element center or mouse coordinates):\n *   - Use screenToCanvas() / canvasToScreen() for conversion\n *\n * For dimensions (like element width/height):\n *   - Screen dimensions = canvas dimensions * scale\n *   - Canvas dimensions = screen dimensions / scale\n *   - OR better: use offsetWidth/offsetHeight which are already in canvas space\n *\n * =============================================================================\n */\n\n/**\n * Convert screen coordinates to canvas coordinates.\n *\n * Use this for converting POSITIONS from screen space (getBoundingClientRect,\n * mouse events) to canvas space (element positioning, metadata).\n *\n * Example: Converting a click position to canvas coordinates for hit testing.\n * Example: Converting element center from screen to canvas for metadata.\n *\n * @param screenX - X coordinate in screen space (e.g., event.clientX, rect.left)\n * @param screenY - Y coordinate in screen space (e.g., event.clientY, rect.top)\n * @param canvasRect - Canvas content element's bounding rect (.canvas-content, not <ef-canvas>)\n * @param panZoomTransform - Optional PanZoom transform from context\n * @returns Object with x, y in canvas coordinate space\n */\nexport function screenToCanvas(\n  screenX: number,\n  screenY: number,\n  canvasRect: DOMRect,\n  panZoomTransform?: PanZoomTransform,\n): { x: number; y: number } {\n  if (!panZoomTransform) {\n    return {\n      x: screenX - canvasRect.left,\n      y: screenY - canvasRect.top,\n    };\n  }\n  // canvasRect already includes the panzoom transform (since canvas is inside .content-wrapper)\n  // So we only need to:\n  // 1. Get position relative to canvas in screen space: screenX - canvasRect.left\n  // 2. Divide by scale to get canvas coordinates\n  // We don't need to subtract panZoomTransform.x/y because it's already accounted for in canvasRect\n  return {\n    x: (screenX - canvasRect.left) / panZoomTransform.scale,\n    y: (screenY - canvasRect.top) / panZoomTransform.scale,\n  };\n}\n\n/**\n * Convert canvas coordinates to screen coordinates.\n *\n * Use this for converting POSITIONS from canvas space (element positioning,\n * metadata) to screen space (overlay positioning, visual display).\n *\n * Example: Converting element top-left from metadata to screen position for overlays.\n * Example: Converting a canvas point to screen coordinates for rendering guides.\n *\n * @param canvasX - X coordinate in canvas space (from metadata or style.left)\n * @param canvasY - Y coordinate in canvas space (from metadata or style.top)\n * @param canvasRect - Canvas content element's bounding rect (.canvas-content, not <ef-canvas>)\n * @param panZoomTransform - Optional PanZoom transform from context\n * @returns Object with x, y in screen coordinate space\n */\nexport function canvasToScreen(\n  canvasX: number,\n  canvasY: number,\n  canvasRect: DOMRect,\n  panZoomTransform?: PanZoomTransform,\n): { x: number; y: number } {\n  if (!panZoomTransform) {\n    return {\n      x: canvasRect.left + canvasX,\n      y: canvasRect.top + canvasY,\n    };\n  }\n  // canvasRect already includes the panzoom transform (since canvas is inside .content-wrapper)\n  // So we only need to:\n  // 1. Multiply canvas coordinates by scale to get screen-space offset\n  // 2. Add to canvasRect.left/top (which already includes pan)\n  // We don't need to add panZoomTransform.x/y because it's already accounted for in canvasRect\n  return {\n    x: canvasRect.left + canvasX * panZoomTransform.scale,\n    y: canvasRect.top + canvasY * panZoomTransform.scale,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,eACd,SACA,SACA,YACA,kBAC0B;AAC1B,KAAI,CAAC,iBACH,QAAO;EACL,GAAG,UAAU,WAAW;EACxB,GAAG,UAAU,WAAW;EACzB;AAOH,QAAO;EACL,IAAI,UAAU,WAAW,QAAQ,iBAAiB;EAClD,IAAI,UAAU,WAAW,OAAO,iBAAiB;EAClD;;;;;;;;;;;;;;;;;AAkBH,SAAgB,eACd,SACA,SACA,YACA,kBAC0B;AAC1B,KAAI,CAAC,iBACH,QAAO;EACL,GAAG,WAAW,OAAO;EACrB,GAAG,WAAW,MAAM;EACrB;AAOH,QAAO;EACL,GAAG,WAAW,OAAO,UAAU,iBAAiB;EAChD,GAAG,WAAW,MAAM,UAAU,iBAAiB;EAChD"}

package/dist/canvas/getElementBounds.js

@@ -0,0 +1,40 @@
+//#region src/canvas/getElementBounds.ts
+/**
+* Get element bounds using the CanvasElementBounds protocol if available,
+* otherwise fall back to getBoundingClientRect().
+*
+* This allows elements to provide custom hit testing areas or account for
+* visual bounds that differ from DOM bounds.
+*
+* IMPORTANT: This returns a DOMRect in SCREEN SPACE (like getBoundingClientRect).
+*
+* For ROTATED elements, the returned rect is the AXIS-ALIGNED BOUNDING BOX:
+* - rect.width/height are the bounding box dimensions, NOT the element's actual dimensions
+* - rect.left/top are the bounding box corner, NOT the element's visual top-left
+*
+* CORRECT USAGE:
+*
+* ✅ Getting element CENTER (rotation-invariant):
+*    const rect = getElementBounds(element);
+*    const centerX = rect.left + rect.width / 2;
+*    const centerY = rect.top + rect.height / 2;
+*
+* ✅ Hit testing (checking if a point is inside the bounding box):
+*    const rect = getElementBounds(element);
+*    if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) { ... }
+*
+* ❌ Getting element DIMENSIONS (wrong for rotated elements):
+*    const rect = getElementBounds(element);
+*    const width = rect.width;  // WRONG! This is bounding box width, not element width
+*
+* For actual dimensions, use element.offsetWidth / element.offsetHeight instead.
+* These return layout dimensions unaffected by CSS transforms.
+*/
+function getElementBounds(element) {
+	if ("getCanvasBounds" in element && typeof element.getCanvasBounds === "function") return element.getCanvasBounds();
+	return element.getBoundingClientRect();
+}
+
+//#endregion
+export { getElementBounds };
+//# sourceMappingURL=getElementBounds.js.map

package/dist/canvas/getElementBounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getElementBounds.js","names":[],"sources":["../../src/canvas/getElementBounds.ts"],"sourcesContent":["import type { CanvasElementBounds } from \"./api/types.js\";\n\n/**\n * Get element bounds using the CanvasElementBounds protocol if available,\n * otherwise fall back to getBoundingClientRect().\n *\n * This allows elements to provide custom hit testing areas or account for\n * visual bounds that differ from DOM bounds.\n *\n * IMPORTANT: This returns a DOMRect in SCREEN SPACE (like getBoundingClientRect).\n *\n * For ROTATED elements, the returned rect is the AXIS-ALIGNED BOUNDING BOX:\n * - rect.width/height are the bounding box dimensions, NOT the element's actual dimensions\n * - rect.left/top are the bounding box corner, NOT the element's visual top-left\n *\n * CORRECT USAGE:\n *\n * ✅ Getting element CENTER (rotation-invariant):\n *    const rect = getElementBounds(element);\n *    const centerX = rect.left + rect.width / 2;\n *    const centerY = rect.top + rect.height / 2;\n *\n * ✅ Hit testing (checking if a point is inside the bounding box):\n *    const rect = getElementBounds(element);\n *    if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) { ... }\n *\n * ❌ Getting element DIMENSIONS (wrong for rotated elements):\n *    const rect = getElementBounds(element);\n *    const width = rect.width;  // WRONG! This is bounding box width, not element width\n *\n * For actual dimensions, use element.offsetWidth / element.offsetHeight instead.\n * These return layout dimensions unaffected by CSS transforms.\n */\nexport function getElementBounds(element: HTMLElement): DOMRect {\n  if (\n    \"getCanvasBounds\" in element &&\n    typeof (element as any).getCanvasBounds === \"function\"\n  ) {\n    return (element as CanvasElementBounds).getCanvasBounds();\n  }\n  return element.getBoundingClientRect();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,iBAAiB,SAA+B;AAC9D,KACE,qBAAqB,WACrB,OAAQ,QAAgB,oBAAoB,WAE5C,QAAQ,QAAgC,iBAAiB;AAE3D,QAAO,QAAQ,uBAAuB"}

package/dist/canvas/overlays/SelectionOverlay.js

@@ -0,0 +1,265 @@
+import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.94.0/helpers/decorate.js";
+import { panZoomTransformContext } from "../../gui/panZoomTransformContext.js";
+import { selectionContext } from "../selection/selectionContext.js";
+import { calculateOverlayState, getOverlayTargets } from "./overlayState.js";
+import { consume } from "@lit/context";
+import { LitElement, css, html } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+
+//#region src/canvas/overlays/SelectionOverlay.ts
+let SelectionOverlay = class SelectionOverlay$1 extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.canvasElement = null;
+		this.overlayState = {
+			selection: null,
+			boxSelect: null,
+			highlight: null
+		};
+		this.lastSelectionMode = null;
+		this.rafLoopActive = false;
+		this.rafLoop = () => {
+			if (!this.rafLoopActive) return;
+			this.updateOverlayData();
+			this.animationFrame = requestAnimationFrame(this.rafLoop);
+		};
+	}
+	static {
+		this.styles = [css`
+      :host {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100vw;
+        height: 100vh;
+        pointer-events: none;
+        z-index: 1000;
+      }
+      .box-select {
+        position: absolute;
+        border: 2px dashed rgb(59, 130, 246);
+        background: rgba(59, 130, 246, 0.05);
+        pointer-events: none;
+      }
+      .highlight-box {
+        position: absolute;
+        border: 2px solid rgb(148, 163, 184);
+        background: rgba(148, 163, 184, 0.1);
+        pointer-events: none;
+        box-shadow: 0 0 0 2px rgba(148, 163, 184, 0.3);
+      }
+    `];
+	}
+	createRenderRoot() {
+		return this;
+	}
+	firstUpdated(changedProperties) {
+		super.firstUpdated?.(changedProperties);
+		const styleElement = this.querySelector("style");
+		if (!styleElement) {
+			if (!(this.closest("[data-test-container]") !== null || this.closest("#sandbox-container") !== null || window.location.pathname.includes("scenario-runner"))) console.warn("[SelectionOverlay] No style element found - styles may not be applied");
+		} else console.log("[SelectionOverlay] Style element found, content length:", styleElement.textContent?.length || 0);
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.style.position = "fixed";
+		this.style.top = "0";
+		this.style.left = "0";
+		this.style.width = "100vw";
+		this.style.height = "100vh";
+		this.style.pointerEvents = "none";
+		this.style.zIndex = "1000";
+		this.setAttribute("data-selection-overlay", "true");
+		requestAnimationFrame(() => {
+			if (this.canvas) this.canvasElement = this.canvas;
+			else this.findCanvasElement();
+			if (this.canvasElement) this.startRafLoop();
+		});
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.stopRafLoop();
+	}
+	/**
+	* React to selection context changes to ensure box selection visual updates.
+	* This is called whenever Lit detects a property change, including context updates.
+	* Note: We don't call requestUpdate() here to avoid the Lit warning about scheduling
+	* updates after an update completes. The RAF loop handles all updates.
+	*/
+	updated(changedProperties) {
+		super.updated?.(changedProperties);
+		const currentMode = this.effectiveSelection?.selectionMode ?? null;
+		if (currentMode !== this.lastSelectionMode) this.lastSelectionMode = currentMode;
+		if (currentMode === "box-selecting" && !this.rafLoopActive) this.startRafLoop();
+		if (changedProperties.has("canvas") && this.canvas) {
+			this.canvasElement = this.canvas;
+			if (!this.rafLoopActive) this.startRafLoop();
+		}
+		if (this.canvasElement && !this.rafLoopActive) this.startRafLoop();
+	}
+	/**
+	* Find the EFCanvas element.
+	* Handles both cases:
+	* 1. Overlay is inside EFCanvas's shadow DOM (old case)
+	* 2. Overlay is a sibling of ef-pan-zoom (new case - outside transform)
+	*/
+	findCanvasElement() {
+		const parent = this.parentElement;
+		if (parent) {
+			const panZoom$1 = parent.querySelector("ef-pan-zoom");
+			if (panZoom$1) {
+				const canvas = panZoom$1.querySelector("ef-canvas");
+				if (canvas) {
+					this.canvasElement = canvas;
+					return;
+				}
+			}
+		}
+		const panZoom = this.closest("ef-pan-zoom");
+		if (panZoom) {
+			const canvas = panZoom.querySelector("ef-canvas");
+			if (canvas) {
+				this.canvasElement = canvas;
+				return;
+			}
+		}
+		let current = this;
+		while (current) if (current instanceof ShadowRoot) current = current.host;
+		else if (current instanceof HTMLElement) {
+			if (current.tagName === "EF-CANVAS" || current.tagName.toLowerCase() === "ef-canvas") {
+				this.canvasElement = current;
+				return;
+			}
+			const rootNode = current.getRootNode();
+			if (rootNode instanceof ShadowRoot) current = rootNode.host;
+			else current = current.parentElement;
+		} else {
+			const rootNode = current.getRootNode();
+			if (rootNode instanceof ShadowRoot) current = rootNode.host;
+			else current = current.parentElement;
+		}
+	}
+	/**
+	* Start continuous RAF loop for smooth overlay updates.
+	*/
+	startRafLoop() {
+		if (this.rafLoopActive) return;
+		this.rafLoopActive = true;
+		this.rafLoop();
+	}
+	/**
+	* Stop RAF loop.
+	*/
+	stopRafLoop() {
+		this.rafLoopActive = false;
+		if (this.animationFrame) {
+			cancelAnimationFrame(this.animationFrame);
+			this.animationFrame = void 0;
+		}
+	}
+	/**
+	* Get the effective selection context (from context or property).
+	*/
+	get effectiveSelection() {
+		return this.selectionFromContext ?? this.selection;
+	}
+	/**
+	* Get the effective pan-zoom transform (from context or property).
+	*/
+	get effectivePanZoomTransform() {
+		return this.panZoomTransformFromContext ?? this.panZoomTransform;
+	}
+	/**
+	* Update overlay data state using the abstraction layer.
+	* 
+	* This method now uses the clean separation of:
+	* - SEMANTICS: getOverlayTargets() determines WHAT should be shown
+	* - MECHANISM: calculateOverlayState() determines HOW to show it
+	*/
+	updateOverlayData() {
+		if (this.canvas && this.canvas !== this.canvasElement) this.canvasElement = this.canvas;
+		const effectiveCanvas = this.canvasElement || this.canvas;
+		if (!effectiveCanvas) {
+			this.overlayState = {
+				selection: null,
+				boxSelect: null,
+				highlight: null
+			};
+			return;
+		}
+		let canvasRect = effectiveCanvas.getBoundingClientRect();
+		if (effectiveCanvas.shadowRoot) {
+			const canvasContent = effectiveCanvas.shadowRoot.querySelector(".canvas-content");
+			if (canvasContent) canvasRect = canvasContent.getBoundingClientRect();
+		}
+		const panZoomElement = effectiveCanvas.closest("ef-pan-zoom");
+		const canvas = effectiveCanvas;
+		const highlightedElement = canvas?.highlightedElement;
+		const targets = getOverlayTargets(this.effectiveSelection, highlightedElement);
+		const canvasWithMetadata = {
+			getElementData: (id) => canvas?.getElementData?.(id),
+			getElement: (id) => canvas?.elementRegistry?.get(id),
+			querySelector: (selector) => effectiveCanvas.querySelector(selector),
+			shadowRoot: effectiveCanvas.shadowRoot
+		};
+		const currentTransform = this.readCurrentTransform(panZoomElement);
+		this.overlayState = calculateOverlayState(targets, canvasWithMetadata, canvasRect, panZoomElement, currentTransform);
+	}
+	/**
+	* Read current transform directly from panzoom element.
+	* This ensures we always have fresh values instead of stale property/context.
+	*/
+	readCurrentTransform(panZoomElement) {
+		if (panZoomElement) {
+			const pz = panZoomElement;
+			if (typeof pz.x === "number" && typeof pz.y === "number" && typeof pz.scale === "number") return {
+				x: pz.x,
+				y: pz.y,
+				scale: pz.scale
+			};
+		}
+		return this.effectivePanZoomTransform;
+	}
+	render() {
+		if (!(this.canvasElement || this.canvas)) return html``;
+		const { boxSelect, highlight } = this.overlayState;
+		const selectionMode = this.effectiveSelection?.selectionMode;
+		return html`
+      ${boxSelect ? html`
+            <div
+              class="box-select"
+              style="left: ${boxSelect.x}px; top: ${boxSelect.y}px; width: ${boxSelect.width}px; height: ${boxSelect.height}px; position: absolute; border: 2px dashed rgb(59, 130, 246); background: rgba(59, 130, 246, 0.05); pointer-events: none;"
+            ></div>
+          ` : html``}
+      ${highlight ? html`
+            <div
+              class="highlight-box"
+              style="left: ${highlight.x}px; top: ${highlight.y}px; width: ${highlight.width}px; height: ${highlight.height}px; position: absolute; border: 2px solid rgb(148, 163, 184); background: rgba(148, 163, 184, 0.1); pointer-events: none; box-shadow: 0 0 0 2px rgba(148, 163, 184, 0.3);"
+            ></div>
+          ` : html``}
+      ${selectionMode === "box-selecting" && !boxSelect ? html`
+            <div style="position: fixed; top: 50px; right: 10px; background: orange; color: white; padding: 4px; z-index: 10000; font-size: 12px;">
+              Box selecting but no bounds! mode=${selectionMode} bounds=${this.effectiveSelection?.boxSelectBounds ? "exists" : "null"}
+            </div>
+          ` : html``}
+    `;
+	}
+};
+__decorate([consume({
+	context: selectionContext,
+	subscribe: true
+})], SelectionOverlay.prototype, "selectionFromContext", void 0);
+__decorate([consume({
+	context: panZoomTransformContext,
+	subscribe: true
+})], SelectionOverlay.prototype, "panZoomTransformFromContext", void 0);
+__decorate([property({ type: Object })], SelectionOverlay.prototype, "selection", void 0);
+__decorate([property({ type: Object })], SelectionOverlay.prototype, "panZoomTransform", void 0);
+__decorate([state()], SelectionOverlay.prototype, "canvasElement", void 0);
+__decorate([property({ type: Object })], SelectionOverlay.prototype, "canvas", void 0);
+__decorate([state()], SelectionOverlay.prototype, "overlayState", void 0);
+__decorate([state()], SelectionOverlay.prototype, "lastSelectionMode", void 0);
+SelectionOverlay = __decorate([customElement("ef-canvas-selection-overlay")], SelectionOverlay);
+
+//#endregion
+//# sourceMappingURL=SelectionOverlay.js.map