Shopify product configurator print-ready artwork: client-side pre-flight, DPI validation, and vector export

import assert from "node:assert/strict";

export interface PhysicalPrintSpec {
  widthInches: number;
  heightInches: number;
  bleedInches: number; // typically 0.125 inches (3mm)
  targetDpi: number; // typically 300 DPI for high-end giclée or laser engraving
}

export interface CustomerUploadInput {
  intrinsicWidthPx: number;
  intrinsicHeightPx: number;
  mimeType: "image/png" | "image/jpeg" | "image/tiff" | "image/svg+xml";
  fileSizeBytes: number;
  userTransform?: {
    scale: number; // 1.0 = 100%
    rotationDegrees: number; // 0, 90, 180, 270
    panOffsetX: number; // CSS canvas pixels
    panOffsetY: number; // CSS canvas pixels
  };
}

export interface PrintPreflightResult {
  isPrintReady: boolean;
  effectiveDpi: number;
  requiredWidthPx: number;
  requiredHeightPx: number;
  bleedWidthPx: number;
  bleedHeightPx: number;
  aspectRatioMismatchPercent: number;
  errors: string[];
  warnings: string[];
  productionPayload?: {
    normalizedMatrix: {
      scaleFactor: number;
      rotation: number;
      cropBox: { x: number; y: number; width: number; height: number };
      bleedBox: { x: number; y: number; width: number; height: number };
    };
    lineItemProperties: Record<string, string>;
  };
}

const MINIMUM_PERMISSIBLE_DPI = 150; // Warn between 150 and 299; block below 150
const MAX_ASPECT_RATIO_TOLERANCE_PERCENT = 5.0; // Above 5% distortion requires letterboxing or user crop clamp

export function validateAndGeneratePrintArtifact(
  spec: PhysicalPrintSpec,
  upload: CustomerUploadInput
): PrintPreflightResult {
  const errors: string[] = [];
  const warnings: string[] = [];

  const totalPhysicalWidthInches = spec.widthInches + spec.bleedInches * 2;
  const totalPhysicalHeightInches = spec.heightInches + spec.bleedInches * 2;

  const requiredWidthPx = Math.round(spec.widthInches * spec.targetDpi);
  const requiredHeightPx = Math.round(spec.heightInches * spec.targetDpi);

  const bleedWidthPx = Math.round(totalPhysicalWidthInches * spec.targetDpi);
  const bleedHeightPx = Math.round(totalPhysicalHeightInches * spec.targetDpi);

  const isVector = upload.mimeType === "image/svg+xml";

  const transformScale = upload.userTransform?.scale ?? 1.0;
  const effectiveWidthPx = isVector ? requiredWidthPx : upload.intrinsicWidthPx * transformScale;
  const effectiveHeightPx = isVector ? requiredHeightPx : upload.intrinsicHeightPx * transformScale;

  const effectiveDpiX = isVector ? spec.targetDpi : effectiveWidthPx / spec.widthInches;
  const effectiveDpiY = isVector ? spec.targetDpi : effectiveHeightPx / spec.heightInches;
  const effectiveDpi = Math.round(Math.min(effectiveDpiX, effectiveDpiY));

  if (!isVector) {
    if (effectiveDpi < MINIMUM_PERMISSIBLE_DPI) {
      errors.push(
        `Resolution too low: file produces ${effectiveDpi} DPI for a ${spec.widthInches}"×${spec.heightInches}" print. Minimum required is ${MINIMUM_PERMISSIBLE_DPI} DPI (target: ${spec.targetDpi} DPI). Upload at least ${requiredWidthPx}×${requiredHeightPx}px.`
      );
    } else if (effectiveDpi < spec.targetDpi) {
      warnings.push(
        `Resolution sub-optimal: file provides ${effectiveDpi} DPI. Target commercial standard is ${spec.targetDpi} DPI. Minor pixelation may be visible on high-contrast edges.`
      );
    }
  }

  const targetAspect = spec.widthInches / spec.heightInches;
  const sourceAspect = upload.intrinsicWidthPx / upload.intrinsicHeightPx;
  const aspectDeviation = Math.abs((sourceAspect - targetAspect) / targetAspect) * 100;

  if (aspectDeviation > MAX_ASPECT_RATIO_TOLERANCE_PERCENT && !isVector) {
    warnings.push(
      `Aspect ratio mismatch: uploaded artwork is ${sourceAspect.toFixed(3)}, while print target is ${targetAspect.toFixed(3)} (${aspectDeviation.toFixed(1)}% variance). Image must be cropped or padded to avoid stretching.`
    );
  }

  const MAX_FILE_SIZE = 100 * 1024 * 1024;
  if (upload.fileSizeBytes > MAX_FILE_SIZE) {
    errors.push(`File size ${(upload.fileSizeBytes / (1024 * 1024)).toFixed(1)}MB exceeds maximum 100MB threshold.`);
  }

  const isPrintReady = errors.length === 0;

  if (!isPrintReady) {
    return {
      isPrintReady: false,
      effectiveDpi,
      requiredWidthPx,
      requiredHeightPx,
      bleedWidthPx,
      bleedHeightPx,
      aspectRatioMismatchPercent: Number(aspectDeviation.toFixed(2)),
      errors,
      warnings,
    };
  }

  const bleedPaddingXPx = Math.round(spec.bleedInches * spec.targetDpi);
  const bleedPaddingYPx = Math.round(spec.bleedInches * spec.targetDpi);

  const normalizedMatrix = {
    scaleFactor: Number(transformScale.toFixed(4)),
    rotation: upload.userTransform?.rotationDegrees ?? 0,
    cropBox: {
      x: bleedPaddingXPx,
      y: bleedPaddingYPx,
      width: requiredWidthPx,
      height: requiredHeightPx,
    },
    bleedBox: {
      x: 0,
      y: 0,
      width: bleedWidthPx,
      height: bleedHeightPx,
    },
  };

  const lineItemProperties: Record<string, string> = {
    _print_dimensions: `${spec.widthInches}x${spec.heightInches}in`,
    _print_target_dpi: String(spec.targetDpi),
    _print_effective_dpi: String(effectiveDpi),
    _print_bleed_inches: String(spec.bleedInches),
    _print_matrix_json: JSON.stringify(normalizedMatrix),
    _print_preflight_passed: "true",
  };

  return {
    isPrintReady: true,
    effectiveDpi,
    requiredWidthPx,
    requiredHeightPx,
    bleedWidthPx,
    bleedHeightPx,
    aspectRatioMismatchPercent: Number(aspectDeviation.toFixed(2)),
    errors,
    warnings,
    productionPayload: {
      normalizedMatrix,
      lineItemProperties,
    },
  };
}