@kritzel/engine 0.4.31

package/dist/collection/helpers/color.helper.js

@@ -0,0 +1,106 @@
+import { resolveColor } from "../constants/color-palette.constants";
+import { KritzelThemeManager } from "../classes/managers/theme.manager";
+export class KritzelColorHelper {
+    /**
+     * Resolves a color value based on the current theme.
+     * Handles both simple string colors and theme-aware color objects.
+     * @param color - The color to resolve (string or ThemeAwareColor)
+     * @param theme - Optional theme to use. If not provided, uses current theme from ThemeManager
+     * @returns The resolved hex color string, or empty string if color is undefined
+     */
+    static resolveThemeColor(color, theme) {
+        if (!color) {
+            return '';
+        }
+        const currentTheme = theme ?? KritzelThemeManager.getStoredTheme();
+        return resolveColor(color, currentTheme);
+    }
+    /**
+     * Applies opacity to a theme-aware color and returns an rgba string.
+     * @param color - The theme-aware color object or a hex color string
+     * @param opacity - The opacity value between 0 and 1
+     * @param theme - Optional theme to use. If not provided, uses current theme from ThemeManager
+     * @returns The color as an rgba string, or the resolved hex if opacity is 1
+     */
+    static applyOpacity(color, opacity, theme) {
+        const hexColor = typeof color === 'string' ? color : this.resolveThemeColor(color, theme);
+        if (!hexColor || opacity >= 1)
+            return hexColor;
+        const sanitizedHex = hexColor.startsWith('#') ? hexColor.slice(1) : hexColor;
+        let r, g, b;
+        if (sanitizedHex.length === 3) {
+            r = parseInt(sanitizedHex[0] + sanitizedHex[0], 16);
+            g = parseInt(sanitizedHex[1] + sanitizedHex[1], 16);
+            b = parseInt(sanitizedHex[2] + sanitizedHex[2], 16);
+        }
+        else if (sanitizedHex.length === 6) {
+            r = parseInt(sanitizedHex.substring(0, 2), 16);
+            g = parseInt(sanitizedHex.substring(2, 4), 16);
+            b = parseInt(sanitizedHex.substring(4, 6), 16);
+        }
+        else {
+            return hexColor;
+        }
+        if (isNaN(r) || isNaN(g) || isNaN(b)) {
+            return hexColor;
+        }
+        return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+    }
+    /**
+     * Determines the appropriate contrast color (black or white) based on the luminance of the given hex color.
+     * Uses the relative luminance formula: 0.299*R + 0.587*G + 0.114*B
+     * @param hexColor - The hex color string (with or without #)
+     * @returns '#000000' for light backgrounds, '#ffffff' for dark backgrounds
+     */
+    static getContrastColor(hexColor) {
+        const sanitizedHex = hexColor.startsWith('#') ? hexColor.slice(1) : hexColor;
+        let r, g, b;
+        if (sanitizedHex.length === 3) {
+            r = parseInt(sanitizedHex[0] + sanitizedHex[0], 16);
+            g = parseInt(sanitizedHex[1] + sanitizedHex[1], 16);
+            b = parseInt(sanitizedHex[2] + sanitizedHex[2], 16);
+        }
+        else if (sanitizedHex.length === 6) {
+            r = parseInt(sanitizedHex.substring(0, 2), 16);
+            g = parseInt(sanitizedHex.substring(2, 4), 16);
+            b = parseInt(sanitizedHex.substring(4, 6), 16);
+        }
+        else {
+            // Default to black for invalid colors
+            return '#000000';
+        }
+        if (isNaN(r) || isNaN(g) || isNaN(b)) {
+            return '#000000';
+        }
+        // Calculate relative luminance
+        const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
+        // Use threshold of 150 (midpoint) for balanced contrast
+        return luminance > 150 ? '#000000' : '#ffffff';
+    }
+    /**
+     * Determines the appropriate text color for both light and dark themes based on the fill color.
+     * Returns default theme-appropriate colors if the fill is transparent.
+     * @param fillColor - The theme-aware fill color
+     * @returns A theme-aware color object with appropriate text colors for both themes
+     */
+    static determineTextColor(fillColor) {
+        // Check if fillColor is transparent for both themes
+        const isTransparentLight = fillColor.light === 'transparent';
+        const isTransparentDark = fillColor.dark === 'transparent';
+        if (isTransparentLight && isTransparentDark) {
+            // Return default theme-appropriate colors for transparent fills
+            return { light: '#000000', dark: '#ffffff' };
+        }
+        // Determine text color for each theme based on fill brightness
+        const lightThemeTextColor = isTransparentLight
+            ? '#000000'
+            : this.getContrastColor(fillColor.light);
+        const darkThemeTextColor = isTransparentDark
+            ? '#ffffff'
+            : this.getContrastColor(fillColor.dark);
+        return {
+            light: lightThemeTextColor,
+            dark: darkThemeTextColor,
+        };
+    }
+}

package/dist/collection/helpers/cursor.helper.js

@@ -0,0 +1,57 @@
+import { KritzelIconRegistry } from "../classes/registries/icon-registry.class";
+export class KritzelCursorHelper {
+    static _pointerCursor = null;
+    /**
+     * Returns the custom pointer cursor CSS value.
+     * This can be used instead of `cursor: pointer` for consistent styling.
+     */
+    static getPointerCursor() {
+        if (!this._pointerCursor) {
+            this._pointerCursor = this.getCursor({ iconName: 'pointer' });
+        }
+        return this._pointerCursor;
+    }
+    /**
+     * Returns a custom cursor CSS value with support for rotation.
+     * The icon is retrieved from the KritzelIconRegistry.
+     */
+    static getCursor(options) {
+        const iconName = options.iconName === 'default' ? 'mouse-pointer' : options.iconName;
+        const iconSvg = KritzelIconRegistry.get(iconName);
+        if (!iconSvg) {
+            console.warn(`Icon "${iconName}" not found in registry.`);
+            return 'auto';
+        }
+        const size = options.size || 24;
+        const rotation = options.rotation || 0;
+        const color = options.color || 'black';
+        // Default cursor (mouse-pointer) has hotspot at (4, 4), others at center
+        const hotspot = options.hotspot || (options.iconName === 'default' ? { x: 4, y: 4 } : { x: size / 2, y: size / 2 });
+        // Modify the SVG string to set size and color
+        // We replace width and height to match the requested size
+        // We replace currentColor with the requested color
+        let content = iconSvg
+            .replace(/width="\d+"/, `width="${size}"`)
+            .replace(/height="\d+"/, `height="${size}"`)
+            .replace(/currentColor/g, color);
+        // Create the SVG string
+        // We rotate around the center of the SVG canvas
+        const center = size / 2;
+        // We use a group to apply the rotation
+        const svg = `
+      <svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">
+        <g transform="rotate(${rotation} ${center} ${center})">
+          ${content}
+        </g>
+      </svg>
+    `;
+        // Encode the SVG for use in a data URI
+        // We need to be careful with encoding to ensure it works across browsers
+        const encodedSvg = encodeURIComponent(svg.replace(/\s+/g, ' ').trim())
+            .replace(/'/g, '%27')
+            .replace(/"/g, '%22');
+        const dataUri = `data:image/svg+xml;charset=utf-8,${encodedSvg}`;
+        // Return the cursor style string
+        return `url('${dataUri}') ${hotspot.x} ${hotspot.y}, auto`;
+    }
+}

package/dist/collection/helpers/devices.helper.js

@@ -0,0 +1,28 @@
+export class KritzelDevicesHelper {
+    static isTouchDevice() {
+        return window.matchMedia('(any-pointer: coarse)').matches;
+    }
+    static isAndroid() {
+        return /android/i.test(navigator.userAgent);
+    }
+    static isIOS() {
+        return /iPad|iPhone|iPod/.test(navigator.userAgent);
+    }
+    static detectOS() {
+        if (this.isIOS()) {
+            return 'iOS';
+        }
+        else if (this.isAndroid()) {
+            return 'Android';
+        }
+        else {
+            return 'Other';
+        }
+    }
+    static isMobile() {
+        return this.isIOS() || this.isAndroid();
+    }
+    static isFirefox() {
+        return /firefox/i.test(navigator.userAgent);
+    }
+}

package/dist/collection/helpers/event.helper.js

@@ -0,0 +1,58 @@
+import { KritzelMouseButton } from "../enums/event-button.enum";
+export class KritzelEventHelper {
+    static isRightClick(ev) {
+        return ev.button === KritzelMouseButton.Right;
+    }
+    static isLeftClick(ev) {
+        return ev.button === KritzelMouseButton.Left;
+    }
+    static isPointerEventOnContextMenu(event) {
+        const path = event.composedPath();
+        const contextMenu = path.find(element => element.classList && element.classList.contains('context-menu'));
+        return !!contextMenu;
+    }
+    static onLongPress(event, onSuccess, onCancel) {
+        if (event.pointerType !== 'touch') {
+            onCancel?.();
+            return () => { };
+        }
+        const startX = event.clientX;
+        const startY = event.clientY;
+        const target = event.target;
+        if (!target) {
+            onCancel?.();
+            return () => { };
+        }
+        const longPressTimeout = 400;
+        const moveThreshold = 10;
+        const timer = setTimeout(() => {
+            removeListeners();
+            onSuccess(event);
+        }, longPressTimeout);
+        const cancel = () => {
+            clearTimeout(timer);
+            removeListeners();
+            onCancel?.();
+        };
+        const onPointerMove = (e) => {
+            if (Math.abs(e.clientX - startX) > moveThreshold || Math.abs(e.clientY - startY) > moveThreshold) {
+                cancel();
+            }
+        };
+        const onPointerUp = () => {
+            cancel();
+        };
+        const onPointerCancel = () => {
+            cancel();
+        };
+        const removeListeners = () => {
+            target.removeEventListener('pointermove', onPointerMove);
+            target.removeEventListener('pointerup', onPointerUp);
+            target.removeEventListener('pointercancel', onPointerCancel);
+        };
+        target.addEventListener('pointermove', onPointerMove, { passive: true });
+        target.addEventListener('pointerup', onPointerUp, { once: true });
+        target.addEventListener('pointercancel', onPointerCancel, { once: true });
+        return cancel;
+    }
+}

package/dist/collection/helpers/geometry.helper.js

@@ -0,0 +1,149 @@
+export class KritzelGeometryHelper {
+    static doPolygonsIntersect(polygon1, polygon2) {
+        // 1. Convert polygons to array of points for easier processing
+        const points1 = [polygon1.bottomLeft, polygon1.bottomRight, polygon1.topRight, polygon1.topLeft];
+        const points2 = [polygon2.bottomLeft, polygon2.bottomRight, polygon2.topRight, polygon2.topLeft];
+        // 2. Check if any point of polygon1 is inside polygon2
+        for (const point of points1) {
+            if (this.isPointInPolygon(point, points2)) {
+                return true;
+            }
+        }
+        // 3. Check if any point of polygon2 is inside polygon1
+        for (const point of points2) {
+            if (this.isPointInPolygon(point, points1)) {
+                return true;
+            }
+        }
+        // 4. Check for edge intersections (more complex)
+        for (let i = 0; i < points1.length; i++) {
+            const p1a = points1[i];
+            const p1b = points1[(i + 1) % points1.length]; // Wrap around to the first point
+            for (let j = 0; j < points2.length; j++) {
+                const p2a = points2[j];
+                const p2b = points2[(j + 1) % points2.length];
+                if (this.intersectLines(p1a, p1b, p2a, p2b)) {
+                    return true;
+                }
+            }
+        }
+        return false; // No intersection found
+    }
+    static isPointInPolygon(point, polygon) {
+        let inside = false;
+        for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+            const xi = polygon[i].x, yi = polygon[i].y;
+            const xj = polygon[j].x, yj = polygon[j].y;
+            const intersect = yi > point.y !== yj > point.y && point.x < ((xj - xi) * (point.y - yi)) / (yj - yi) + xi;
+            if (intersect)
+                inside = !inside;
+        }
+        return inside;
+    }
+    static intersectLines(p1a, p1b, p2a, p2b) {
+        const det = (p1b.x - p1a.x) * (p2b.y - p2a.y) - (p1b.y - p1a.y) * (p2b.x - p2a.x);
+        if (det === 0) {
+            return false; // Lines are parallel
+        }
+        const t = ((p2a.x - p1a.x) * (p2b.y - p2a.y) - (p2a.y - p1a.y) * (p2b.x - p2a.x)) / det;
+        const u = -((p1a.x - p2a.x) * (p1b.y - p1a.y) - (p1a.y - p2a.y) * (p1b.x - p1a.x)) / det;
+        return t >= 0 && t <= 1 && u >= 0 && u <= 1;
+    }
+    /**
+     * Finds the intersection point between a line segment and a line segment.
+     * Returns the intersection point or null if no intersection.
+     */
+    static getLineIntersectionPoint(p1a, p1b, p2a, p2b) {
+        const det = (p1b.x - p1a.x) * (p2b.y - p2a.y) - (p1b.y - p1a.y) * (p2b.x - p2a.x);
+        if (det === 0) {
+            return null; // Lines are parallel
+        }
+        const t = ((p2a.x - p1a.x) * (p2b.y - p2a.y) - (p2a.y - p1a.y) * (p2b.x - p2a.x)) / det;
+        const u = -((p1a.x - p2a.x) * (p1b.y - p1a.y) - (p1a.y - p2a.y) * (p1b.x - p1a.x)) / det;
+        if (t >= 0 && t <= 1 && u >= 0 && u <= 1) {
+            return {
+                x: p1a.x + t * (p1b.x - p1a.x),
+                y: p1a.y + t * (p1b.y - p1a.y)
+            };
+        }
+        return null;
+    }
+    /**
+     * Finds the closest intersection point between a line segment (from lineStart to lineEnd)
+     * and a polygon. Returns the intersection point closest to lineStart, or null if no intersection.
+     */
+    static getLinePolygonIntersection(lineStart, lineEnd, polygon) {
+        const points = [polygon.topLeft, polygon.topRight, polygon.bottomRight, polygon.bottomLeft];
+        let closestIntersection = null;
+        let closestDistance = Infinity;
+        for (let i = 0; i < points.length; i++) {
+            const edgeStart = points[i];
+            const edgeEnd = points[(i + 1) % points.length];
+            const intersection = this.getLineIntersectionPoint(lineStart, lineEnd, edgeStart, edgeEnd);
+            if (intersection) {
+                const distance = Math.sqrt(Math.pow(intersection.x - lineStart.x, 2) +
+                    Math.pow(intersection.y - lineStart.y, 2));
+                if (distance < closestDistance) {
+                    closestDistance = distance;
+                    closestIntersection = intersection;
+                }
+            }
+        }
+        return closestIntersection;
+    }
+    /**
+     * Generates a polygon approximation of an ellipse.
+     * @param centerX - X coordinate of ellipse center
+     * @param centerY - Y coordinate of ellipse center
+     * @param rx - Horizontal radius
+     * @param ry - Vertical radius
+     * @param segments - Number of segments (more = smoother approximation)
+     * @param rotation - Optional rotation angle in radians
+     */
+    static getEllipsePolygonApproximation(centerX, centerY, rx, ry, segments = 32, rotation = 0) {
+        const points = [];
+        const cos = Math.cos(rotation);
+        const sin = Math.sin(rotation);
+        for (let i = 0; i < segments; i++) {
+            const angle = (2 * Math.PI * i) / segments;
+            // Point on unrotated ellipse
+            const px = rx * Math.cos(angle);
+            const py = ry * Math.sin(angle);
+            // Apply rotation around center
+            const rotatedX = centerX + px * cos - py * sin;
+            const rotatedY = centerY + px * sin + py * cos;
+            points.push({ x: rotatedX, y: rotatedY });
+        }
+        return points;
+    }
+    /**
+     * Finds the closest intersection point between a line segment and a polygon
+     * defined as an array of points. Returns the intersection closest to lineStart,
+     * or null if no intersection.
+     */
+    static getLinePointsArrayIntersection(lineStart, lineEnd, polygonPoints) {
+        let closestIntersection = null;
+        let closestDistance = Infinity;
+        for (let i = 0; i < polygonPoints.length; i++) {
+            const edgeStart = polygonPoints[i];
+            const edgeEnd = polygonPoints[(i + 1) % polygonPoints.length];
+            const intersection = this.getLineIntersectionPoint(lineStart, lineEnd, edgeStart, edgeEnd);
+            if (intersection) {
+                const distance = Math.sqrt(Math.pow(intersection.x - lineStart.x, 2) +
+                    Math.pow(intersection.y - lineStart.y, 2));
+                if (distance < closestDistance) {
+                    closestDistance = distance;
+                    closestIntersection = intersection;
+                }
+            }
+        }
+        return closestIntersection;
+    }
+    /**
+     * Checks if a point is inside a polygon defined as an array of points.
+     * This is a convenience wrapper that works with arbitrary polygon point arrays.
+     */
+    static isPointInPolygonPoints(point, polygonPoints) {
+        return this.isPointInPolygon(point, polygonPoints);
+    }
+}

package/dist/collection/helpers/html.helper.js

@@ -0,0 +1,116 @@
+export class KritzelHTMLHelper {
+    static getNumericValueFromStyle(element, property) {
+        const value = window.getComputedStyle(element).getPropertyValue(property);
+        return parseFloat(value) || 0;
+    }
+    static isScrollableElement(element) {
+        if (!(element instanceof HTMLElement)) {
+            return false;
+        }
+        const style = window.getComputedStyle(element);
+        const overflowX = style.overflowX;
+        const overflowY = style.overflowY;
+        const overflow = style.overflow;
+        const canScrollX = (overflowX === 'auto' || overflowX === 'scroll' || overflowX === 'overlay') && element.scrollWidth > element.clientWidth;
+        const canScrollY = (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') && element.scrollHeight > element.clientHeight;
+        const canScroll = overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay';
+        return canScrollX || canScrollY || (canScroll && (element.scrollWidth > element.clientWidth || element.scrollHeight > element.clientHeight));
+    }
+    static findScrollableElement(root) {
+        if (!root) {
+            return null;
+        }
+        const visited = new Set();
+        const walk = (element) => {
+            if (visited.has(element)) {
+                return null;
+            }
+            visited.add(element);
+            if (this.isScrollableElement(element)) {
+                return element;
+            }
+            if (element.shadowRoot) {
+                for (const child of Array.from(element.shadowRoot.children)) {
+                    const scrollable = walk(child);
+                    if (scrollable) {
+                        return scrollable;
+                    }
+                }
+            }
+            if (element.tagName === 'SLOT') {
+                for (const assignedElement of element.assignedElements({ flatten: true })) {
+                    const scrollable = walk(assignedElement);
+                    if (scrollable) {
+                        return scrollable;
+                    }
+                }
+            }
+            for (const child of Array.from(element.children)) {
+                const scrollable = walk(child);
+                if (scrollable) {
+                    return scrollable;
+                }
+            }
+            return null;
+        };
+        return walk(root);
+    }
+    static getScrollableParent(element) {
+        if (!element) {
+            return window;
+        }
+        const parent = element.parentNode?.host ?? element.parentElement;
+        if (!parent || parent.tagName === 'BODY') {
+            return window;
+        }
+        const style = window.getComputedStyle(parent);
+        if (style.overflow === 'auto' || style.overflowY === 'auto' || style.overflow === 'scroll' || style.overflowY === 'scroll') {
+            return parent;
+        }
+        return this.getScrollableParent(parent);
+    }
+    static isElementInViewport(element) {
+        if (!element) {
+            return false;
+        }
+        const scrollableParent = this.getScrollableParent(element);
+        const rect = element.getBoundingClientRect();
+        if (scrollableParent === window) {
+            const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+            const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+            return rect.top >= 0 && rect.left >= 0 && rect.bottom <= viewportHeight && rect.right <= viewportWidth;
+        }
+        const parentRect = scrollableParent.getBoundingClientRect();
+        return rect.top >= parentRect.top && rect.left >= parentRect.left && rect.bottom <= parentRect.bottom && rect.right <= parentRect.right;
+    }
+    static getFocusableElements(root) {
+        if (!root)
+            return [];
+        const focusableElements = [];
+        const focusableSelector = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), details, [tabindex]:not([tabindex="-1"])';
+        const isVisible = (el) => {
+            const style = window.getComputedStyle(el);
+            return style.display !== 'none' && style.visibility !== 'hidden';
+        };
+        const find = (element) => {
+            // Check if the element itself is focusable
+            if (element instanceof HTMLElement && element.matches(focusableSelector) && !element.hasAttribute('disabled') && isVisible(element)) {
+                focusableElements.push(element);
+            }
+            // Traverse shadow DOM
+            if (element.shadowRoot) {
+                Array.from(element.shadowRoot.children).forEach(find);
+            }
+            // Traverse slotted content
+            if (element.tagName === 'SLOT') {
+                element.assignedElements({ flatten: true }).forEach(find);
+            }
+            // Traverse light DOM children if there is no shadow root
+            if (!element.shadowRoot) {
+                Array.from(element.children).forEach(find);
+            }
+        };
+        find(root);
+        return focusableElements;
+    }
+}

package/dist/collection/helpers/image-file.helper.js

@@ -0,0 +1,6 @@
+export class KritzelImageFileHelper {
+    static isGifFile(file) {
+        const mimeType = file.type.trim().toLowerCase();
+        return mimeType === 'image/gif' || (mimeType === '' && file.name.toLowerCase().endsWith('.gif'));
+    }
+}

package/dist/collection/helpers/keyboard.helper.js

@@ -0,0 +1,55 @@
+import { KritzelDevicesHelper } from "./devices.helper";
+export class KritzelKeyboardHelper {
+    static forceHideKeyboard() {
+        if (document.activeElement instanceof HTMLElement) {
+            document.activeElement.blur();
+        }
+    }
+    static enableInteractiveWidget() {
+        const meta = document.querySelector('meta[name="viewport"][content*="interactive-widget=resizes-content"]');
+        if (meta) {
+            let currentContent = meta.getAttribute('content');
+            if (!currentContent?.includes('interactive-widget=resizes-content')) {
+                currentContent += ', interactive-widget=resizes-content';
+            }
+            if (currentContent) {
+                meta.setAttribute('content', currentContent);
+            }
+        }
+    }
+    static disableInteractiveWidget() {
+        const meta = document.querySelector('meta[name="viewport"][content*="interactive-widget=resizes-content"]');
+        if (meta) {
+            let currentContent = meta.getAttribute('content');
+            let newContent = currentContent?.replace(/\s*interactive-widget=resizes-content\s*[,;]?/g, '');
+            if (newContent !== undefined) {
+                newContent = newContent
+                    .replace(/,(\s*,)+/g, ',')
+                    .replace(/^,/, '')
+                    .replace(/,$/, '')
+                    .trim();
+                meta.setAttribute('content', newContent);
+            }
+        }
+    }
+    static onKeyboardVisibleChanged(callback) {
+        if ('visualViewport' in window) {
+            const VIEWPORT_VS_CLIENT_HEIGHT_RATIO = 0.75;
+            const onResize = (event) => {
+                const target = event.target;
+                const isMobileDevice = KritzelDevicesHelper.isMobile();
+                const isViewportReduced = (target.height * target.scale) / window.screen.height < VIEWPORT_VS_CLIENT_HEIGHT_RATIO;
+                const isOpen = isMobileDevice && isViewportReduced;
+                callback(isOpen);
+            };
+            window.visualViewport?.addEventListener('resize', onResize);
+            return () => window.visualViewport?.removeEventListener('resize', onResize);
+        }
+        else {
+            // Fallback for older browsers does not provide a reliable event-based mechanism.
+            console.warn('Listening for keyboard visibility changes is not reliably supported in this browser.');
+            // Return a no-op cleanup function.
+            return () => { };
+        }
+    }
+}

package/dist/collection/helpers/localization.helper.js

@@ -0,0 +1,25 @@
+/**
+ * Pure static utilities for localization term resolution.
+ */
+export class LocalizationHelper {
+    /**
+     * Interpolates `{placeholder}` tokens in a term template with the provided
+     * variables. Tokens without a matching variable are left untouched.
+     *
+     * @param template - The raw term string, e.g. `'Expires {date}'`
+     * @param vars - Map of placeholder names to replacement values
+     * @returns The interpolated string
+     *
+     * @example
+     * LocalizationHelper.interpolate('Hello {name}', { name: 'Ada' }); // 'Hello Ada'
+     */
+    static interpolate(template, vars) {
+        if (!vars) {
+            return template;
+        }
+        return template.replace(/\{(\w+)\}/g, (match, key) => {
+            const value = vars[key];
+            return value === undefined || value === null ? match : String(value);
+        });
+    }
+}

package/dist/collection/helpers/math.helper.js

@@ -0,0 +1,8 @@
+export class KritzelMathHelper {
+    static average(a, b) {
+        return (a + b) / 2;
+    }
+    static degreesToRadians(degrees) {
+        return degrees * (Math.PI / 180);
+    }
+}

package/dist/collection/helpers/migration.helper.js

@@ -0,0 +1,45 @@
+/**
+ * Runs pending schema migrations on a Y.Doc.
+ *
+ * Reads the current `schemaVersion` from the metadata map (defaults to 0 for
+ * documents that predate the migration system), filters and sorts pending
+ * migrations, and executes them in a single `'migration'`-origin transaction.
+ *
+ * The `'migration'` origin is:
+ * - NOT tracked by the UndoManager (which only tracks `'local'` and `'temporary'`)
+ * - Distinguishable in observers so they can skip re-processing migration writes
+ *
+ * @param ydoc - The Y.Doc to migrate
+ * @param metadataMap - The metadata Y.Map that stores the schemaVersion
+ * @param maps - Named Y.Maps available for migration logic (e.g. `{ workspaces }` or `{ objects }`)
+ * @param migrations - The ordered array of migration definitions
+ * @param currentVersion - The target schema version defined in code
+ * @param options - Optional configuration (e.g. `{ quiet: true }` to suppress console logs)
+ * @returns A result object indicating whether migrations ran and the version range
+ */
+export function runMigrations(ydoc, metadataMap, maps, migrations, currentVersion, options) {
+    const quiet = options?.quiet ?? true;
+    const docVersion = metadataMap.get('schemaVersion') ?? 0;
+    if (docVersion >= currentVersion) {
+        return { migrated: false, fromVersion: docVersion, toVersion: docVersion };
+    }
+    const pending = migrations
+        .filter(m => m.fromVersion >= docVersion && m.toVersion <= currentVersion)
+        .sort((a, b) => a.fromVersion - b.fromVersion);
+    if (!quiet) {
+        console.log(`[Kritzel] Running ${pending.length} migration(s) from v${docVersion} to v${currentVersion}`);
+    }
+    ydoc.transact(() => {
+        for (const migration of pending) {
+            if (!quiet) {
+                console.log(`[Kritzel] Migrating v${migration.fromVersion} → v${migration.toVersion}`);
+            }
+            migration.migrate(ydoc, maps);
+        }
+        metadataMap.set('schemaVersion', currentVersion);
+    }, 'migration');
+    if (!quiet) {
+        console.log(`[Kritzel] Migrations complete. Schema now at v${currentVersion}`);
+    }
+    return { migrated: true, fromVersion: docVersion, toVersion: currentVersion };
+}