feat: toggle settings for background image in puzzle

assets/src/js/v3/entries/course-builder/components/curriculum/QuestionList.tsx

@@ -269,6 +269,7 @@ const QuestionList = ({ isEditing }: { isEditing: boolean }) => {
         }),
         ...(questionType === 'puzzle' && {
           puzzle_grid_size: 4,
+          enable_puzzle_answer_background: true,
         }),
         ...(questionType === 'coordinates' && {
           coordinates_axis_range: 10,

assets/src/js/v3/entries/course-builder/components/modals/QuestionPreviewModal.tsx

@@ -410,6 +410,7 @@ const renderQuestionPreview = (question: QuizQuestion) => {
           answers={question.question_answers}
           gridSize={question.question_settings.puzzle_grid_size}
           questionId={question.question_id}
+          showPuzzleAnswerBackground={question.question_settings?.enable_puzzle_answer_background ?? true}
         />
       );
     }

assets/src/js/v3/entries/course-builder/components/modals/question-previews/PuzzlePreview.tsx

@@ -17,13 +17,19 @@ interface PuzzlePreviewProps {
   gridSize?: number | string;
   /** Used for hidden input id parity with `puzzle.php` (`tutor-puzzle-state-{id}`). */
   questionId: ID;
+  showPuzzleAnswerBackground?: boolean;
 }
 
 /**
  * Course Builder puzzle preview — loads Tutor Pro `puzzle-question.js` in the preview iframe
  * (same pattern as {@link DrawImagePreview}, {@link PinImagePreview}, {@link ScalePreview}).
  */
-const PuzzlePreview = ({ answers, gridSize: gridSizeProp, questionId }: PuzzlePreviewProps) => {
+const PuzzlePreview = ({
+  answers,
+  gridSize: gridSizeProp,
+  questionId,
+  showPuzzleAnswerBackground = true,
+}: PuzzlePreviewProps) => {
   const answer = answers[0];
   const imageUrl = answer?.image_url || answer?.answer_two_gap_match || '';
   const gridSize = clampGridSize(gridSizeProp);
@@ -91,11 +97,17 @@ const PuzzlePreview = ({ answers, gridSize: gridSizeProp, questionId }: PuzzlePr
   const instructionId = `tutor-puzzle-instruction-${questionId}`;
   const statusId = `tutor-puzzle-status-${questionId}`;
   const describedByIds = `${instructionId} ${statusId}`;
+  const wrapperClassName = [
+    'quiz-question-ans-choice-area tutor-mt-40 tutor-puzzle-question question-type-puzzle',
+    showPuzzleAnswerBackground ? '' : 'tutor-puzzle-question--no-answer-background',
+  ]
+    .filter(Boolean)
+    .join(' ');
 
   return (
     <div
       ref={wrapperRef}
-      className="quiz-question-ans-choice-area tutor-mt-40 tutor-puzzle-question question-type-puzzle"
+      className={wrapperClassName}
       data-tutor-puzzle-defer-init="true"
       data-question-type="puzzle"
       data-question-id={String(questionId)}
@@ -113,12 +125,7 @@ const PuzzlePreview = ({ answers, gridSize: gridSizeProp, questionId }: PuzzlePr
           'tutor',
         )}
       >
-        <img
-          className="tutor-puzzle-reference-image"
-          src={imageUrl}
-          alt={__('Puzzle reference image', 'tutor')}
-          style={{ opacity: 0.3 }}
-        />
+        <img className="tutor-puzzle-reference-image" src={imageUrl} alt={__('Puzzle reference image', 'tutor')} />
         <div className="tutor-puzzle-slots" aria-hidden="true" />
       </div>
       <div

assets/src/js/v3/entries/course-builder/services/quiz.ts

@@ -46,6 +46,7 @@ interface QuizQuestionsForPayload extends Omit<QuizQuestion, 'question_settings'
     is_image_matching?: '0' | '1';
     draw_image_threshold_percent?: number;
     puzzle_grid_size?: number;
+    enable_puzzle_answer_background?: '0' | '1';
     coordinates_axis_range?: number;
   };
 }
@@ -335,6 +336,7 @@ export const convertQuizFormDataToPayload = (
             }),
             ...(question.question_type === 'puzzle' && {
               puzzle_grid_size: Number(question.question_settings.puzzle_grid_size ?? 4),
+              enable_puzzle_answer_background: question.question_settings.enable_puzzle_answer_background ? '1' : '0',
             }),
             ...(question.question_type === 'coordinates' && {
               coordinates_axis_range: Number(question.question_settings.coordinates_axis_range ?? 10),

assets/src/js/v3/shared/components/fields/quiz/questions/FormPuzzle.tsx

@@ -6,7 +6,9 @@ import { __ } from '@wordpress/i18n';
 import ImageInput from '@TutorShared/atoms/ImageInput';
 
 import FormSelectInput from '@TutorShared/components/fields/FormSelectInput';
+import FormSwitch from '@TutorShared/components/fields/FormSwitch';
 
+import { tutorConfig } from '@TutorShared/config/config';
 import { borderRadius, Breakpoint, colorTokens, spacing } from '@TutorShared/config/styles';
 import { typography } from '@TutorShared/config/typography';
 import Show from '@TutorShared/controls/Show';
@@ -36,13 +38,23 @@ interface FormPuzzleProps extends FormControllerProps<QuizQuestionOption> {
   >;
   gridSizeControllerProps?: FormControllerProps<number | null>;
   gridSizePath?: string;
+  backgroundControllerProps?: FormControllerProps<boolean | undefined>;
 }
 
-const FormPuzzle = ({ field, activeQuestionIndex = 0, gridSizeControllerProps, gridSizePath }: FormPuzzleProps) => {
+const FormPuzzle = ({
+  field,
+  activeQuestionIndex = 0,
+  gridSizeControllerProps,
+  gridSizePath,
+  backgroundControllerProps,
+}: FormPuzzleProps) => {
   const form = useFormContext();
   const option = field.value;
   const resolvedGridSizePath =
     gridSizePath ?? (`questions.${activeQuestionIndex}.question_settings.puzzle_grid_size` as const);
+  const resolvedBackgroundPath = Array.isArray(form?.getValues?.('questions'))
+    ? (`questions.${activeQuestionIndex}.question_settings.enable_puzzle_answer_background` as const)
+    : ('question_settings.enable_puzzle_answer_background' as const);
   const resolvedQuestionDataStatusPath = Array.isArray(form?.getValues?.('questions'))
     ? (`questions.${activeQuestionIndex}._data_status` as const)
     : ('_data_status' as const);
@@ -122,6 +134,22 @@ const FormPuzzle = ({ field, activeQuestionIndex = 0, gridSizeControllerProps, g
     return null;
   }
 
+  const renderBackgroundSwitch = (controllerProps: FormControllerProps<boolean | undefined>) => (
+    <FormSwitch
+      {...controllerProps}
+      label={__('Show puzzle answer background', __TUTOR_TEXT_DOMAIN__)}
+      helpText={__('Display a faded reference image behind the puzzle board during attempts.', __TUTOR_TEXT_DOMAIN__)}
+      onChange={() => {
+        if (form && calculateQuizDataStatus(activeQuestionDataStatus, QuizDataStatus.UPDATE)) {
+          form.setValue(
+            resolvedQuestionDataStatusPath,
+            calculateQuizDataStatus(activeQuestionDataStatus, QuizDataStatus.UPDATE) as QuizDataStatus,
+          );
+        }
+      }}
+    />
+  );
+
   return (
     <div css={styles.wrapper}>
       <div css={styles.card}>
@@ -158,7 +186,7 @@ const FormPuzzle = ({ field, activeQuestionIndex = 0, gridSizeControllerProps, g
               helpText={__('Larger grids create more pieces and a harder puzzle for learners.', __TUTOR_TEXT_DOMAIN__)}
               onChange={(selectedOption) => {
                 gridSizeControllerProps.field.onChange(selectedOption.value);
-                if (calculateQuizDataStatus(activeQuestionDataStatus, QuizDataStatus.UPDATE)) {
+                if (form && calculateQuizDataStatus(activeQuestionDataStatus, QuizDataStatus.UPDATE)) {
                   form.setValue(
                     resolvedQuestionDataStatusPath,
                     calculateQuizDataStatus(activeQuestionDataStatus, QuizDataStatus.UPDATE) as QuizDataStatus,
@@ -195,6 +223,19 @@ const FormPuzzle = ({ field, activeQuestionIndex = 0, gridSizeControllerProps, g
               )}
             />
           )}
+
+          <Show when={!!tutorConfig.tutor_pro_url && !tutorConfig.is_legacy_learning_mode}>
+            {backgroundControllerProps ? (
+              renderBackgroundSwitch(backgroundControllerProps)
+            ) : (
+              <Controller
+                control={form.control}
+                name={resolvedBackgroundPath}
+                defaultValue={true}
+                render={renderBackgroundSwitch}
+              />
+            )}
+          </Show>
         </div>
       </Show>
 

assets/src/js/v3/shared/utils/quiz.ts

@@ -235,6 +235,10 @@ export const convertedQuestion = (question: Omit<QuizQuestion, '_data_status'>):
       if (rawGridSize !== undefined && rawGridSize !== null && !Number.isNaN(Number(rawGridSize))) {
         question.question_settings.puzzle_grid_size = Number(rawGridSize);
       }
+      question.question_settings.enable_puzzle_answer_background =
+        question.question_settings.enable_puzzle_answer_background === undefined
+          ? true
+          : !!Number(question.question_settings.enable_puzzle_answer_background);
     }
     if (question.question_type === 'coordinates') {
       const rawCoordinatesAxisRange = question.question_settings.coordinates_axis_range;

assets/src/js/v3/shared/utils/types.ts

@@ -343,6 +343,7 @@ export interface QuizQuestion {
     is_image_matching: boolean;
     draw_image_threshold_percent?: number;
     puzzle_grid_size?: number;
+    enable_puzzle_answer_background?: boolean;
     coordinates_axis_range?: number;
   };
   question_answers: QuizQuestionOption[];
@@ -360,6 +361,7 @@ export interface QuizQuestionsForPayload extends Omit<QuizQuestion, 'question_se
     is_image_matching?: '0' | '1';
     draw_image_threshold_percent?: number;
     puzzle_grid_size?: number;
+    enable_puzzle_answer_background?: '0' | '1';
     coordinates_axis_range?: number;
   };
 }