web-to-print 0.1.0

package/dist/collection/utils/canvas-helpers.js

@@ -0,0 +1,380 @@
+import { FabricImage } from "fabric";
+export function generateObjectId() {
+    return crypto.randomUUID();
+}
+const IMAGE_PROXY_BASE = 'http://localhost:3001';
+/** Load a FabricImage from a URL, trying CORS → local proxy → plain load (tainted). */
+async function loadFabricImage(url) {
+    // Data URLs and blob URLs are always same-origin
+    if (url.startsWith('data:') || url.startsWith('blob:')) {
+        return FabricImage.fromURL(url);
+    }
+    // Try direct CORS
+    try {
+        return await FabricImage.fromURL(url, { crossOrigin: 'anonymous' });
+    }
+    catch { /* CORS rejected */ }
+    // Try local image proxy
+    try {
+        const proxyUrl = `${IMAGE_PROXY_BASE}/?url=${encodeURIComponent(url)}`;
+        return await FabricImage.fromURL(proxyUrl, { crossOrigin: 'anonymous' });
+    }
+    catch { /* proxy not available */ }
+    // Fallback: load without CORS (canvas will be tainted, export blocked)
+    return FabricImage.fromURL(url);
+}
+export async function setCanvasBackground(canvas, imageUrl, fitMode = 'contain') {
+    const img = await loadFabricImage(imageUrl);
+    const canvasWidth = canvas.getWidth();
+    const canvasHeight = canvas.getHeight();
+    let scaleX;
+    let scaleY;
+    if (fitMode === 'fill') {
+        scaleX = canvasWidth / (img.width ?? canvasWidth);
+        scaleY = canvasHeight / (img.height ?? canvasHeight);
+    }
+    else {
+        const imgWidth = img.width ?? canvasWidth;
+        const imgHeight = img.height ?? canvasHeight;
+        const scale = fitMode === 'contain'
+            ? Math.min(canvasWidth / imgWidth, canvasHeight / imgHeight)
+            : Math.max(canvasWidth / imgWidth, canvasHeight / imgHeight);
+        scaleX = scale;
+        scaleY = scale;
+        // In contain mode, resize canvas to match scaled image so there's no letterboxing
+        if (fitMode === 'contain') {
+            const fittedWidth = imgWidth * scale;
+            const fittedHeight = imgHeight * scale;
+            canvas.setDimensions({ width: fittedWidth, height: fittedHeight });
+        }
+    }
+    const finalWidth = canvas.getWidth();
+    const finalHeight = canvas.getHeight();
+    img.set({
+        scaleX,
+        scaleY,
+        originX: 'center',
+        originY: 'center',
+        left: finalWidth / 2,
+        top: finalHeight / 2,
+        selectable: false,
+        evented: false,
+        excludeFromExport: true,
+    });
+    // Remove existing background image if any
+    const objects = canvas.getObjects();
+    const existingBg = objects.find(o => o._isBackground === true);
+    if (existingBg !== undefined)
+        canvas.remove(existingBg);
+    img._isBackground = true;
+    canvas.insertAt(0, img);
+    canvas.renderAll();
+}
+/** Convert PrintArea corner coordinates (0-1) to absolute pixel positions. */
+export function printAreaToPixelCorners(pa, canvasW, canvasH) {
+    return [
+        { x: pa.topLeft.x * canvasW, y: pa.topLeft.y * canvasH },
+        { x: pa.topRight.x * canvasW, y: pa.topRight.y * canvasH },
+        { x: pa.bottomRight.x * canvasW, y: pa.bottomRight.y * canvasH },
+        { x: pa.bottomLeft.x * canvasW, y: pa.bottomLeft.y * canvasH },
+    ];
+}
+/** Convert absolute pixel corner positions back to 0-1 relative PrintArea. */
+export function pixelCornersToPrintArea(corners, canvasW, canvasH, bulge = 0) {
+    return {
+        topLeft: { x: corners[0].x / canvasW, y: corners[0].y / canvasH },
+        topRight: { x: corners[1].x / canvasW, y: corners[1].y / canvasH },
+        bottomRight: { x: corners[2].x / canvasW, y: corners[2].y / canvasH },
+        bottomLeft: { x: corners[3].x / canvasW, y: corners[3].y / canvasH },
+        ...(bulge !== 0 ? { bulge } : {}),
+    };
+}
+/**
+ * Convert a legacy center+dimensions print area to the 4-corner format.
+ * Applies taper, skew, and rotation in 0-1 coordinate space.
+ */
+export function legacyToPrintArea(legacy) {
+    const { x, y, width, height, angle = 0, skewX = 0, skewY = 0, taper = 0, bulge = 0 } = legacy;
+    const halfW = width / 2;
+    const halfH = height / 2;
+    const topHalfW = halfW * (1 - taper);
+    // Local corners (relative to center, in 0-1 coords)
+    let corners = [
+        { x: -topHalfW, y: -halfH }, // TL
+        { x: topHalfW, y: -halfH }, // TR
+        { x: halfW, y: halfH }, // BR
+        { x: -halfW, y: halfH }, // BL
+    ];
+    // Apply skew
+    if (skewX !== 0 || skewY !== 0) {
+        const tanSkX = Math.tan(skewX * Math.PI / 180);
+        const tanSkY = Math.tan(skewY * Math.PI / 180);
+        corners = corners.map(c => ({
+            x: c.x + c.y * tanSkX,
+            y: c.y + c.x * tanSkY,
+        }));
+    }
+    // Apply rotation
+    if (angle !== 0) {
+        const rad = angle * Math.PI / 180;
+        const cos = Math.cos(rad);
+        const sin = Math.sin(rad);
+        corners = corners.map(c => ({
+            x: c.x * cos - c.y * sin,
+            y: c.x * sin + c.y * cos,
+        }));
+    }
+    // Translate to center
+    return {
+        topLeft: { x: x + corners[0].x, y: y + corners[0].y },
+        topRight: { x: x + corners[1].x, y: y + corners[1].y },
+        bottomRight: { x: x + corners[2].x, y: y + corners[2].y },
+        bottomLeft: { x: x + corners[3].x, y: y + corners[3].y },
+        ...(bulge !== 0 ? { bulge } : {}),
+    };
+}
+/** Detect whether a PrintArea uses pixel coordinates (at least one value > 1). */
+export function isPixelPrintArea(pa) {
+    return [pa.topLeft, pa.topRight, pa.bottomRight, pa.bottomLeft].some(p => p.x > 1 || p.y > 1);
+}
+/** Normalize a PrintArea from pixel coordinates to 0–1 relative values. Already-normalized areas are returned unchanged. */
+export function normalizePrintArea(pa, imageWidth, imageHeight) {
+    if (!isPixelPrintArea(pa))
+        return pa;
+    return pixelCornersToPrintArea([pa.topLeft, pa.topRight, pa.bottomRight, pa.bottomLeft], imageWidth, imageHeight, pa.bulge ?? 0);
+}
+/** Returns a default centered print area (30% width x 35% height rectangle). */
+export function defaultPrintArea() {
+    return {
+        topLeft: { x: 0.35, y: 0.325 },
+        topRight: { x: 0.65, y: 0.325 },
+        bottomRight: { x: 0.65, y: 0.675 },
+        bottomLeft: { x: 0.35, y: 0.675 },
+    };
+}
+/**
+ * Compute a CanvasTransform to fit a logo within a 4-corner print area.
+ * Uses the centroid for position, average edge lengths for dimensions,
+ * and the bottom edge angle for rotation.
+ */
+export function fitLogoToPrintArea(logoWidth, logoHeight, printArea, canvasWidth, canvasHeight) {
+    const [tl, tr, br, bl] = printAreaToPixelCorners(printArea, canvasWidth, canvasHeight);
+    // Centroid
+    const cx = (tl.x + tr.x + br.x + bl.x) / 4;
+    const cy = (tl.y + tr.y + br.y + bl.y) / 4;
+    // Average edge lengths for effective width/height
+    const topLen = Math.hypot(tr.x - tl.x, tr.y - tl.y);
+    const botLen = Math.hypot(br.x - bl.x, br.y - bl.y);
+    const leftLen = Math.hypot(bl.x - tl.x, bl.y - tl.y);
+    const rightLen = Math.hypot(br.x - tr.x, br.y - tr.y);
+    const avgWidth = (topLen + botLen) / 2;
+    const avgHeight = (leftLen + rightLen) / 2;
+    // Angle from bottom edge
+    const angle = Math.atan2(br.y - bl.y, br.x - bl.x) * 180 / Math.PI;
+    const scale = Math.min(avgWidth / logoWidth, avgHeight / logoHeight);
+    return {
+        x: cx,
+        y: cy,
+        scaleX: scale,
+        scaleY: scale,
+        angle,
+    };
+}
+/**
+ * Warp a logo image to follow the bulge curvature of a print area.
+ * Slices the image into vertical strips and displaces each vertically
+ * according to the same quadratic Bezier curve used by the print area outline.
+ */
+export function warpImageForBulge(sourceImg, bulge, areaHeight, logoScale) {
+    const w = sourceImg.width;
+    const h = sourceImg.height;
+    // Max displacement at center (t=0.5): 0.5 * |bulge| * areaHeight / logoScale
+    const maxAbsDy = Math.ceil(Math.abs(0.5 * bulge * areaHeight / logoScale)) + 1;
+    const canvas = document.createElement('canvas');
+    canvas.width = w;
+    canvas.height = h + maxAbsDy * 2;
+    const ctx = canvas.getContext('2d');
+    for (let x = 0; x < w; x++) {
+        const t = w > 1 ? x / (w - 1) : 0.5;
+        // Displacement matching the quadratic Bezier control-point shift in PrintAreaQuad._render:
+        // control point is at midY - bulge * areaHeight, Bezier weight at parameter t is 2t(1-t)
+        const dy = -2 * t * (1 - t) * bulge * areaHeight / logoScale;
+        ctx.drawImage(sourceImg, x, 0, 1, h, x, maxAbsDy + dy, 1, h);
+    }
+    return canvas;
+}
+/** Decode SVG text from a data URL. Returns null for non-SVG URLs. */
+function decodeSvgDataUrl(svgDataUrl) {
+    if (!svgDataUrl.startsWith('data:image/svg+xml'))
+        return null;
+    const base64Idx = svgDataUrl.indexOf(';base64,');
+    if (base64Idx !== -1) {
+        return atob(svgDataUrl.slice(base64Idx + 8));
+    }
+    const commaIdx = svgDataUrl.indexOf(',');
+    if (commaIdx === -1)
+        return null;
+    return decodeURIComponent(svgDataUrl.slice(commaIdx + 1));
+}
+/**
+ * Extract width/height from an SVG data URL by parsing viewBox or width/height attributes.
+ * Returns null for non-SVG data URLs or when dimensions cannot be determined.
+ */
+export function parseSvgDimensions(svgDataUrl) {
+    const svgText = decodeSvgDataUrl(svgDataUrl);
+    if (svgText === null)
+        return null;
+    const widthMatch = svgText.match(/\bwidth=["']([.\d]+)/);
+    const heightMatch = svgText.match(/\bheight=["']([.\d]+)/);
+    if (widthMatch !== null && heightMatch !== null) {
+        return { width: Math.round(parseFloat(widthMatch[1])), height: Math.round(parseFloat(heightMatch[1])) };
+    }
+    const viewBoxMatch = svgText.match(/viewBox=["']\s*[\d.]+\s+[\d.]+\s+([\d.]+)\s+([\d.]+)/);
+    if (viewBoxMatch !== null) {
+        return { width: Math.round(parseFloat(viewBoxMatch[1])), height: Math.round(parseFloat(viewBoxMatch[2])) };
+    }
+    return null;
+}
+/**
+ * Upscale an SVG data URL so the browser rasterizes it at high resolution.
+ * SVGs loaded via `<img src>` are rasterized at their intrinsic dimensions
+ * (from viewBox or width/height attributes), which are often small. This
+ * function sets explicit width/height on the root `<svg>` element to ensure
+ * high-resolution rasterization when loaded into Fabric.js.
+ *
+ * Returns the (possibly modified) data URL and the uniform scale factor applied.
+ * For non-SVG data URLs, returns the input unchanged with scaleApplied = 1.
+ */
+export function upscaleSvgDataUrl(svgDataUrl, maxSize = 4000) {
+    const svgText = decodeSvgDataUrl(svgDataUrl);
+    if (svgText === null) {
+        return { dataUrl: svgDataUrl, scaleApplied: 1 };
+    }
+    // Parse SVG document
+    const doc = new DOMParser().parseFromString(svgText, 'image/svg+xml');
+    const svgEl = doc.documentElement;
+    if (svgEl.tagName !== 'svg')
+        return { dataUrl: svgDataUrl, scaleApplied: 1 };
+    // Determine intrinsic dimensions from viewBox or width/height attributes
+    const viewBox = svgEl.getAttribute('viewBox');
+    let intrinsicW;
+    let intrinsicH;
+    if (viewBox !== null) {
+        const parts = viewBox.trim().split(/[\s,]+/);
+        intrinsicW = parseFloat(parts[2]) || 0;
+        intrinsicH = parseFloat(parts[3]) || 0;
+    }
+    else {
+        intrinsicW = parseFloat(svgEl.getAttribute('width') || '') || 0;
+        intrinsicH = parseFloat(svgEl.getAttribute('height') || '') || 0;
+    }
+    if (intrinsicW <= 0 || intrinsicH <= 0)
+        return { dataUrl: svgDataUrl, scaleApplied: 1 };
+    // Skip if already large enough
+    const maxDim = Math.max(intrinsicW, intrinsicH);
+    if (maxDim >= maxSize)
+        return { dataUrl: svgDataUrl, scaleApplied: 1 };
+    // Compute scale factor and target dimensions
+    const scale = maxSize / maxDim;
+    const targetW = Math.round(intrinsicW * scale);
+    const targetH = Math.round(intrinsicH * scale);
+    // Set explicit width/height and ensure viewBox is present for proper scaling
+    svgEl.setAttribute('width', String(targetW));
+    svgEl.setAttribute('height', String(targetH));
+    if (viewBox === null) {
+        svgEl.setAttribute('viewBox', `0 0 ${intrinsicW} ${intrinsicH}`);
+    }
+    // Serialize and re-encode as base64 data URL
+    const newSvgText = new XMLSerializer().serializeToString(doc);
+    const bytes = new TextEncoder().encode(newSvgText);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return { dataUrl: 'data:image/svg+xml;base64,' + btoa(binary), scaleApplied: scale };
+}
+/**
+ * Trim excess whitespace from an SVG by adjusting its viewBox to the actual content bounds.
+ * Uses `getBBox()` which requires the SVG to be temporarily inserted into the DOM.
+ * Returns the input unchanged for non-SVG data URLs or when trimming is not possible.
+ */
+export async function trimSvgWhitespace(svgDataUrl, padding = 1) {
+    const svgText = decodeSvgDataUrl(svgDataUrl);
+    if (svgText === null) {
+        return svgDataUrl;
+    }
+    // Parse SVG document
+    const doc = new DOMParser().parseFromString(svgText, 'image/svg+xml');
+    const svgEl = doc.documentElement;
+    if (svgEl.tagName !== 'svg')
+        return svgDataUrl;
+    // Insert SVG offscreen to enable getBBox()
+    const container = document.createElement('div');
+    container.style.cssText = 'visibility:hidden;position:absolute;left:-9999px;top:-9999px;width:0;height:0;overflow:hidden';
+    container.appendChild(svgEl);
+    document.body.appendChild(container);
+    let bbox;
+    try {
+        bbox = svgEl.getBBox();
+    }
+    catch {
+        container.remove();
+        return svgDataUrl;
+    }
+    container.remove();
+    // Graceful fallback: if getBBox returned zeros (e.g. JSDOM), skip trimming
+    if (bbox.width <= 0 || bbox.height <= 0) {
+        return svgDataUrl;
+    }
+    // Check if trimming is needed by comparing to existing viewBox
+    const existingVB = svgEl.getAttribute('viewBox');
+    if (existingVB !== null) {
+        const parts = existingVB.trim().split(/[\s,]+/).map(Number);
+        if (parts.length === 4 &&
+            Math.abs(parts[0] - bbox.x) < 1 &&
+            Math.abs(parts[1] - bbox.y) < 1 &&
+            Math.abs(parts[2] - bbox.width) < 1 &&
+            Math.abs(parts[3] - bbox.height) < 1) {
+            return svgDataUrl;
+        }
+    }
+    // Apply trimmed viewBox with padding
+    const newVB = `${bbox.x - padding} ${bbox.y - padding} ${bbox.width + 2 * padding} ${bbox.height + 2 * padding}`;
+    svgEl.setAttribute('viewBox', newVB);
+    // Update width/height to match new aspect ratio
+    const newW = bbox.width + 2 * padding;
+    const newH = bbox.height + 2 * padding;
+    svgEl.setAttribute('width', String(newW));
+    svgEl.setAttribute('height', String(newH));
+    // Re-attach svgEl to doc for serialization (it was moved to container)
+    if (svgEl.parentNode !== doc) {
+        doc.appendChild(svgEl);
+    }
+    // Serialize and re-encode as base64 data URL
+    const newSvgText = new XMLSerializer().serializeToString(doc);
+    const bytes = new TextEncoder().encode(newSvgText);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return 'data:image/svg+xml;base64,' + btoa(binary);
+}
+export async function addLogoToCanvas(canvas, logoDataUrl, transform, id) {
+    const { dataUrl, scaleApplied } = upscaleSvgDataUrl(logoDataUrl);
+    const img = await FabricImage.fromURL(dataUrl);
+    img.set({
+        left: transform.x,
+        top: transform.y,
+        scaleX: transform.scaleX / scaleApplied,
+        scaleY: transform.scaleY / scaleApplied,
+        angle: transform.angle,
+        skewX: transform.skewX ?? 0,
+        skewY: transform.skewY ?? 0,
+        originX: 'center',
+        originY: 'center',
+    });
+    img._objectId = id;
+    canvas.add(img);
+    canvas.renderAll();
+    return img;
+}

package/dist/collection/utils/format-detection.js

@@ -0,0 +1,48 @@
+const MAGIC_BYTES = [
+    { format: 'png', bytes: [0x89, 0x50, 0x4e, 0x47] },
+    { format: 'jpeg', bytes: [0xff, 0xd8, 0xff] },
+    { format: 'tiff', bytes: [0x49, 0x49, 0x2a, 0x00] }, // Little-endian
+    { format: 'tiff', bytes: [0x4d, 0x4d, 0x00, 0x2a] }, // Big-endian
+    { format: 'avif', bytes: [0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66], offset: 4 }, // ISO BMFF "ftypavif"
+];
+export function mimeToFormat(mime) {
+    const map = {
+        'image/png': 'png',
+        'image/jpeg': 'jpeg',
+        'image/svg+xml': 'svg',
+        'image/tiff': 'tiff',
+        'image/avif': 'avif',
+    };
+    return map[mime] ?? 'unknown';
+}
+export function isSvgContent(text) {
+    const trimmed = text.trim();
+    return trimmed.startsWith('<?xml') || trimmed.startsWith('<svg');
+}
+function matchMagicBytes(bytes) {
+    for (const entry of MAGIC_BYTES) {
+        const offset = entry.offset ?? 0;
+        if (bytes.length < offset + entry.bytes.length)
+            continue;
+        const match = entry.bytes.every((b, i) => bytes[offset + i] === b);
+        if (match)
+            return entry.format;
+    }
+    return null;
+}
+export async function detectFileFormat(file) {
+    // Try magic bytes first (most reliable)
+    const buffer = await file.slice(0, 16).arrayBuffer();
+    const bytes = new Uint8Array(buffer);
+    const magicFormat = matchMagicBytes(bytes);
+    if (magicFormat !== null)
+        return magicFormat;
+    // Check for SVG by reading text content
+    if (file.type === 'image/svg+xml' || file.name.endsWith('.svg')) {
+        const text = await file.text();
+        if (isSvgContent(text))
+            return 'svg';
+    }
+    // Fallback to MIME type
+    return mimeToFormat(file.type);
+}

package/dist/collection/utils/html-render-helpers.js

@@ -0,0 +1,106 @@
+/** Utility functions for the HTML/CSS-based logo renderer and Canvas 2D export. */
+/** Load an image from a URL/data-URL and return the HTMLImageElement once loaded. */
+export function loadImage(src) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error(`Failed to load image: ${src.slice(0, 80)}`));
+        img.src = src;
+    });
+}
+/** Compute contain-fit dimensions (uniform scale to fit inside container). */
+export function computeContainFit(containerW, containerH, imgW, imgH) {
+    const scale = Math.min(containerW / imgW, containerH / imgH);
+    return { fittedW: imgW * scale, fittedH: imgH * scale };
+}
+/**
+ * Convert a Fabric.js center-origin transform to CSS top-left positioning.
+ * Fabric.js stores x/y as the center of the object. CSS `transform-origin: center`
+ * means the origin is at the center of the unscaled element box, so left/top are
+ * computed by subtracting half the *natural* (unscaled) dimensions.
+ */
+export function centerOriginToTopLeft(transform, naturalW, naturalH) {
+    return {
+        left: transform.x - naturalW / 2,
+        top: transform.y - naturalH / 2,
+    };
+}
+/**
+ * Parse an SVG data URL to extract intrinsic dimensions from viewBox or width/height attributes.
+ * Returns null if the data URL is not SVG or dimensions cannot be determined.
+ */
+export function getSvgIntrinsicSize(svgDataUrl) {
+    if (!svgDataUrl.startsWith('data:image/svg+xml'))
+        return null;
+    let svgText;
+    const base64Idx = svgDataUrl.indexOf(';base64,');
+    if (base64Idx !== -1) {
+        svgText = atob(svgDataUrl.slice(base64Idx + 8));
+    }
+    else {
+        const commaIdx = svgDataUrl.indexOf(',');
+        if (commaIdx === -1)
+            return null;
+        svgText = decodeURIComponent(svgDataUrl.slice(commaIdx + 1));
+    }
+    // Use regex instead of DOMParser to avoid JSDOM/mock-doc XML parsing limitations
+    const svgMatch = svgText.match(/<svg[^>]*>/i);
+    if (svgMatch === null)
+        return null;
+    const svgTag = svgMatch[0];
+    const viewBoxMatch = svgTag.match(/viewBox=["']([^"']+)["']/);
+    if (viewBoxMatch !== null) {
+        const parts = viewBoxMatch[1].trim().split(/[\s,]+/);
+        const vbW = parseFloat(parts[2]);
+        const vbH = parseFloat(parts[3]);
+        if (vbW > 0 && vbH > 0)
+            return { width: vbW, height: vbH };
+    }
+    const widthMatch = svgTag.match(/\bwidth=["']([^"']+)["']/);
+    const heightMatch = svgTag.match(/\bheight=["']([^"']+)["']/);
+    if (widthMatch !== null && heightMatch !== null) {
+        const svgW = parseFloat(widthMatch[1]);
+        const svgH = parseFloat(heightMatch[1]);
+        if (svgW > 0 && svgH > 0)
+            return { width: svgW, height: svgH };
+    }
+    return null;
+}
+/**
+ * Canvas 2D export: draw product background + logo layers onto a plain canvas.
+ * Returns a data URL string.
+ */
+export function renderToCanvas(containerW, containerH, bgColor, productImg, layers, format = 'png', quality = 1) {
+    const canvas = document.createElement('canvas');
+    canvas.width = containerW;
+    canvas.height = containerH;
+    const ctx = canvas.getContext('2d');
+    // Background color
+    ctx.fillStyle = bgColor;
+    ctx.fillRect(0, 0, containerW, containerH);
+    // Product image (contain-fit, centered)
+    if (productImg !== undefined) {
+        const { fittedW, fittedH } = computeContainFit(containerW, containerH, productImg.naturalWidth, productImg.naturalHeight);
+        const ox = (containerW - fittedW) / 2;
+        const oy = (containerH - fittedH) / 2;
+        ctx.drawImage(productImg, ox, oy, fittedW, fittedH);
+    }
+    // Logo layers
+    for (const layer of layers) {
+        ctx.save();
+        // Move to the center of the object (top-left + half natural size, matching CSS transform-origin: center)
+        const cx = layer.left + layer.naturalWidth / 2;
+        const cy = layer.top + layer.naturalHeight / 2;
+        ctx.translate(cx, cy);
+        // Apply transforms in Fabric.js order: rotate → skew → scale
+        ctx.rotate((layer.angle * Math.PI) / 180);
+        const tanSkX = Math.tan((layer.skewX * Math.PI) / 180);
+        const tanSkY = Math.tan((layer.skewY * Math.PI) / 180);
+        ctx.transform(1, tanSkY, tanSkX, 1, 0, 0);
+        ctx.scale(layer.scaleX, layer.scaleY);
+        // Draw image centered at origin
+        ctx.drawImage(layer.img, -layer.naturalWidth / 2, -layer.naturalHeight / 2, layer.naturalWidth, layer.naturalHeight);
+        ctx.restore();
+    }
+    return canvas.toDataURL(`image/${format}`, quality);
+}

package/dist/collection/utils/image-preview.js

@@ -0,0 +1,54 @@
+const DEFAULT_MAX_SIZE = 800;
+/**
+ * Returns true if the data URL contains an SVG image (image/svg+xml).
+ */
+function isSvgDataUrl(dataUrl) {
+    return dataUrl.startsWith('data:image/svg+xml');
+}
+/**
+ * Generate a downscaled preview data URL from a full-resolution data URL.
+ *
+ * - SVG data URLs are returned unchanged (vectors are compact and scale-independent).
+ * - Raster images are downscaled so the longest side is at most `maxSize` pixels.
+ *   If the image is already smaller, the original is returned unchanged.
+ * - Output is PNG to preserve transparency.
+ *
+ * @param dataUrl  Full-resolution data URL
+ * @param maxSize  Maximum pixel dimension for the longest side (default: 800)
+ * @returns  Downscaled PNG data URL, or the original for SVGs / small images
+ */
+export async function generatePreviewDataUrl(dataUrl, maxSize = DEFAULT_MAX_SIZE) {
+    if (isSvgDataUrl(dataUrl)) {
+        return dataUrl;
+    }
+    // Browser-only: requires Image and canvas
+    if (typeof globalThis.Image === 'undefined' || typeof document === 'undefined') {
+        return dataUrl;
+    }
+    const img = await loadImageElement(dataUrl);
+    const { width, height } = img;
+    // Already within bounds — no scaling needed
+    if (width <= maxSize && height <= maxSize) {
+        return dataUrl;
+    }
+    const scale = maxSize / Math.max(width, height);
+    const targetW = Math.round(width * scale);
+    const targetH = Math.round(height * scale);
+    const canvas = document.createElement('canvas');
+    canvas.width = targetW;
+    canvas.height = targetH;
+    const ctx = canvas.getContext('2d');
+    if (ctx === null) {
+        return dataUrl;
+    }
+    ctx.drawImage(img, 0, 0, targetW, targetH);
+    return canvas.toDataURL('image/png');
+}
+function loadImageElement(src) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error('Failed to load image for preview generation'));
+        img.src = src;
+    });
+}