@mathscan/math-exercise-engine 1.1.17 → 1.2.0

package/dist/index.mjs

@@ -15449,13 +15449,18 @@ function applyDropToInput(targetId, item, onChange) {
 function isUndoDrop(event, dragId) {
   return event.active.id === dragId && !event.over;
 }
+const LockContext = createContext(false);
+const ExerciseLockProvider = ({ locked, children }) => /* @__PURE__ */ jsx(LockContext.Provider, { value: locked, children });
+const useExerciseLocked = () => useContext(LockContext);
 const PlacedInputChip = ({ widgetId, value, className = "", onRemove }) => {
   const { droppedSources } = useExerciseDnd();
+  const locked = useExerciseLocked();
   const sourceOptionId = droppedSources.get(widgetId);
   const dragId = `${widgetId}__chip`;
   const { attributes, listeners, setNodeRef, isDragging } = useDraggable({
     id: dragId,
-    data: { type: "placed-chip", widgetId, label: value, sourceOptionId }
+    data: { type: "placed-chip", widgetId, label: value, sourceOptionId },
+    disabled: locked
   });
   useDndMonitor({
     onDragEnd(event) {
@@ -15468,10 +15473,10 @@ const PlacedInputChip = ({ widgetId, value, className = "", onRemove }) => {
       ref: setNodeRef,
       className: `inline-input-chip ${className}${isDragging ? " dragging" : ""}`.trim(),
       onClick: (e) => {
-        if (e.detail !== 0) onRemove();
+        if (!locked && e.detail !== 0) onRemove();
       },
-      title: "Drag to move, or click to remove",
-      style: { touchAction: "none", cursor: "grab" },
+      title: locked ? void 0 : "Drag to move, or click to remove",
+      style: { touchAction: "none", cursor: locked ? "default" : "grab" },
       ...listeners,
       ...attributes,
       children: value
@@ -15491,6 +15496,7 @@ const InlineInput = ({
   onFocus
 }) => {
   const playSound = useSound();
+  const locked = useExerciseLocked();
   const handleChange = useCallback((newValue, fromDrop = false, sourceOptionId) => {
     onChange(widgetId, newValue, fromDrop, sourceOptionId);
   }, [onChange, widgetId]);
@@ -15506,6 +15512,7 @@ const InlineInput = ({
       id: widgetId,
       accepts: ["drag-option", "placed-chip"],
       onDrop: handleDrop,
+      disabled: locked,
       className: "inline-widget inline-input-droppable",
       children: isDropped && value !== "" ? (
         // Show as chip only when value came from drag-drop
@@ -15528,8 +15535,11 @@ const InlineInput = ({
             className: `inline-input${statusClass}`,
             value,
             onChange: (e) => handleChange(e.target.value, false),
-            onMouseDown: () => playSound("input-select"),
+            onMouseDown: () => {
+              if (!locked) playSound("input-select");
+            },
             onFocus: () => onFocus?.(widgetId),
+            readOnly: locked,
             maxLength: expectedLength,
             style: { width: dynamicWidth },
             placeholder
@@ -15546,6 +15556,7 @@ const SingleDragOption = ({
   className = ""
 }) => {
   const { usedOptionIds } = useExerciseDnd();
+  const locked = useExerciseLocked();
   const isUsed = usedOptionIds.has(optionId);
   return /* @__PURE__ */ jsx("div", { className: `drag-option-slot ${className}`.trim(), children: isUsed ? /* @__PURE__ */ jsx("div", { className: "drag-option-empty", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(
     Draggable,
@@ -15553,12 +15564,16 @@ const SingleDragOption = ({
       id: optionId,
       type: "drag-option",
       data: { value, label: value },
+      disabled: locked,
       className: "drag-option-wrapper",
       children: /* @__PURE__ */ jsx(
         "button",
         {
           className: "drag-option",
-          onClick: () => onOptionClick?.(value),
+          onClick: () => {
+            if (!locked) onOptionClick?.(value);
+          },
+          "aria-disabled": locked ? "true" : void 0,
           children: value
         }
       )
@@ -15672,31 +15687,34 @@ const NumericKeypad = ({
   onChange
 }) => {
   const playSound = useSound();
+  const locked = useExerciseLocked();
   const handleDigit = (digit) => {
+    if (locked) return;
     playSound("keypad-press");
     onChange(value + digit);
   };
   const handleBackspace = () => {
+    if (locked) return;
     playSound("keypad-press");
     onChange(value.slice(0, -1));
   };
   return /* @__PURE__ */ jsxs("div", { className: `numeric-keypad ${includeOperators ? "numeric-keypad-with-operators" : ""}`, children: [
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("1"), children: "1" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("2"), children: "2" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("3"), children: "3" }),
-    includeOperators && /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("+"), children: "+" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("4"), children: "4" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("5"), children: "5" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("6"), children: "6" }),
-    includeOperators && /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("-"), children: "-" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("7"), children: "7" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("8"), children: "8" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("9"), children: "9" }),
-    includeOperators && /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("×"), children: "×" }),
-    includeDecimal ? /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-decimal", onClick: () => handleDigit(","), children: "," }) : /* @__PURE__ */ jsx("div", {}),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("0"), children: "0" }),
-    /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-backspace", onClick: handleBackspace, children: "⌫" }),
-    includeOperators && /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("÷"), children: "÷" })
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("1"), children: "1" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("2"), children: "2" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("3"), children: "3" }),
+    includeOperators && /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("+"), children: "+" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("4"), children: "4" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("5"), children: "5" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("6"), children: "6" }),
+    includeOperators && /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("-"), children: "-" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("7"), children: "7" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("8"), children: "8" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("9"), children: "9" }),
+    includeOperators && /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("×"), children: "×" }),
+    includeDecimal ? /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-decimal", onClick: () => handleDigit(","), children: "," }) : /* @__PURE__ */ jsx("div", {}),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-digit", onClick: () => handleDigit("0"), children: "0" }),
+    /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-backspace", onClick: handleBackspace, children: "⌫" }),
+    includeOperators && /* @__PURE__ */ jsx("button", { disabled: locked, className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("÷"), children: "÷" })
   ] });
 };
 const FractionInput = ({
@@ -15713,6 +15731,7 @@ const FractionInput = ({
   placeholder
 }) => {
   const playSound = useSound();
+  const locked = useExerciseLocked();
   const numKey = getFractionKey(widgetId, "num");
   const denKey = getFractionKey(widgetId, "den");
   const numValue = values[numKey] ?? "";
@@ -15733,6 +15752,7 @@ const FractionInput = ({
         id: subKey,
         accepts: ["drag-option", "placed-chip"],
         onDrop: handleDrop(subKey),
+        disabled: locked,
         className: "fraction-slot-droppable",
         children: isDroppedHere && currentValue !== "" ? /* @__PURE__ */ jsx(
           PlacedInputChip,
@@ -15750,8 +15770,11 @@ const FractionInput = ({
             className: `inline-input fraction-input${slotClass}`,
             value: currentValue,
             onChange: (e) => onChange(subKey, e.target.value, false),
-            onMouseDown: () => playSound("input-select"),
+            onMouseDown: () => {
+              if (!locked) playSound("input-select");
+            },
             onFocus: () => onFocus?.(subKey),
+            readOnly: locked,
             maxLength: placeholder ? Math.max(20, placeholder.length) : 4,
             size: placeholder ? placeholder.length : void 0,
             "aria-label": label,
@@ -15982,12 +16005,13 @@ function getEqualTrianglePartPath(index, divisions) {
 function getGridColumnCount(divisions) {
   return Math.ceil(Math.sqrt(divisions));
 }
-function getInteractiveProps(part, onPartClick) {
+function getInteractiveProps(part, onPartClick, locked = false) {
   if (!part.isInteractiveSlot) return {};
   return {
     onClick: () => onPartClick(part.index),
     role: "button",
     "aria-pressed": part.isSelected,
+    "aria-disabled": locked ? "true" : void 0,
     "aria-label": getPartAriaLabel(part),
     tabIndex: 0,
     onKeyDown: (event) => {
@@ -16007,6 +16031,7 @@ const BarShape = ({
   orientation,
   onPartClick
 }) => {
+  const locked = useExerciseLocked();
   const renderedParts = orientation === "vertical" ? [...parts].reverse() : parts;
   return /* @__PURE__ */ jsx(
     "div",
@@ -16018,7 +16043,7 @@ const BarShape = ({
         {
           className: part.className,
           style: part.style,
-          ...getInteractiveProps(part, onPartClick)
+          ...getInteractiveProps(part, onPartClick, locked)
         },
         part.index
       ))
@@ -16030,87 +16055,96 @@ const GridShape = ({
   parts,
   divisions,
   onPartClick
-}) => /* @__PURE__ */ jsx(
-  "div",
-  {
-    className: "visual-fraction-widget__parts visual-fraction-widget__parts--horizontal",
-    style: {
-      "--visual-fraction-divisions": divisions,
-      "--visual-fraction-grid-cols": getGridColumnCount(divisions),
-      // Safe integer division: zod schema enforces divisions = perfect square.
-      "--visual-fraction-grid-rows": divisions / getGridColumnCount(divisions)
-    },
-    children: parts.map((part) => /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: part.className,
-        style: part.style,
-        ...getInteractiveProps(part, onPartClick)
+}) => {
+  const locked = useExerciseLocked();
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "visual-fraction-widget__parts visual-fraction-widget__parts--horizontal",
+      style: {
+        "--visual-fraction-divisions": divisions,
+        "--visual-fraction-grid-cols": getGridColumnCount(divisions),
+        // Safe integer division: zod schema enforces divisions = perfect square.
+        "--visual-fraction-grid-rows": divisions / getGridColumnCount(divisions)
       },
-      part.index
-    ))
-  }
-);
+      children: parts.map((part) => /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: part.className,
+          style: part.style,
+          ...getInteractiveProps(part, onPartClick, locked)
+        },
+        part.index
+      ))
+    }
+  );
+};
 GridShape.displayName = "GridShape";
 const CircleShape = ({
   parts,
   divisions,
   onPartClick
-}) => /* @__PURE__ */ jsx(
-  "svg",
-  {
-    className: "visual-fraction-widget__shape visual-fraction-widget__circle",
-    viewBox: "0 0 100 100",
-    children: parts.map((part) => {
-      const sectorProps = getCircleSectorProps(part.index, divisions);
-      const className = `${part.className} visual-fraction-widget__sector`;
-      const interactiveProps = getInteractiveProps(part, onPartClick);
-      return sectorProps.kind === "circle" ? /* @__PURE__ */ jsx(
-        "circle",
-        {
-          className,
-          style: part.style,
-          cx: "50",
-          cy: "50",
-          r: "48",
-          ...interactiveProps
-        },
-        part.index
-      ) : /* @__PURE__ */ jsx(
-        "path",
-        {
-          className,
-          style: part.style,
-          d: sectorProps.d,
-          ...interactiveProps
-        },
-        part.index
-      );
-    })
-  }
-);
+}) => {
+  const locked = useExerciseLocked();
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      className: "visual-fraction-widget__shape visual-fraction-widget__circle",
+      viewBox: "0 0 100 100",
+      children: parts.map((part) => {
+        const sectorProps = getCircleSectorProps(part.index, divisions);
+        const className = `${part.className} visual-fraction-widget__sector`;
+        const interactiveProps = getInteractiveProps(part, onPartClick, locked);
+        return sectorProps.kind === "circle" ? /* @__PURE__ */ jsx(
+          "circle",
+          {
+            className,
+            style: part.style,
+            cx: "50",
+            cy: "50",
+            r: "48",
+            ...interactiveProps
+          },
+          part.index
+        ) : /* @__PURE__ */ jsx(
+          "path",
+          {
+            className,
+            style: part.style,
+            d: sectorProps.d,
+            ...interactiveProps
+          },
+          part.index
+        );
+      })
+    }
+  );
+};
 CircleShape.displayName = "CircleShape";
 const TriangleShape = ({
   parts,
   divisions,
   onPartClick
-}) => /* @__PURE__ */ jsx(
-  "svg",
-  {
-    className: "visual-fraction-widget__shape visual-fraction-widget__triangle",
-    viewBox: "0 0 100 100",
-    children: parts.map((part) => /* @__PURE__ */ jsx(
-      "path",
-      {
-        className: `${part.className} visual-fraction-widget__sector`,
-        style: part.style,
-        d: getEqualTrianglePartPath(part.index, divisions),
-        ...getInteractiveProps(part, onPartClick)
-      },
-      part.index
-    ))
-  }
-);
+}) => {
+  const locked = useExerciseLocked();
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      className: "visual-fraction-widget__shape visual-fraction-widget__triangle",
+      viewBox: "0 0 100 100",
+      children: parts.map((part) => /* @__PURE__ */ jsx(
+        "path",
+        {
+          className: `${part.className} visual-fraction-widget__sector`,
+          style: part.style,
+          d: getEqualTrianglePartPath(part.index, divisions),
+          ...getInteractiveProps(part, onPartClick, locked)
+        },
+        part.index
+      ))
+    }
+  );
+};
 TriangleShape.displayName = "TriangleShape";
 const ShapeBar = ({ parts, divisions, orientation, onPartClick }) => /* @__PURE__ */ jsx(BarShape, { parts, divisions, orientation, onPartClick });
 const ShapeCircle = ({ parts, divisions, onPartClick }) => /* @__PURE__ */ jsx(CircleShape, { parts, divisions, onPartClick });
@@ -16154,12 +16188,14 @@ const VisualFraction = ({
     onChange
   });
   const playSound = useSound();
+  const locked = useExerciseLocked();
   const handlePartClickWithSound = useCallback(
     (index) => {
+      if (locked) return;
       if (answer.length > 0 && index >= filledCount) playSound("fraction-shade");
       handlePartClick(index);
     },
-    [answer.length, filledCount, playSound, handlePartClick]
+    [locked, answer.length, filledCount, playSound, handlePartClick]
   );
   const parts = useMemo(
     () => Array.from({ length: divisions }, (_, i) => {
@@ -16234,6 +16270,7 @@ const GridSymmetry = ({
   validationStatus = null,
   onChange
 }) => {
+  const exerciseLocked = useExerciseLocked();
   const initialKeys = useMemo(() => new Set(widget.cells.map(gridCellKey)), [widget.cells]);
   const initialInteractiveCells = useMemo(
     () => widget.cells.filter(
@@ -16244,6 +16281,7 @@ const GridSymmetry = ({
   const selectedCells = value ?? initialInteractiveCells;
   const selectedKeys = useMemo(() => new Set(selectedCells.map(gridCellKey)), [selectedCells]);
   const toggleCell = (cell) => {
+    if (exerciseLocked) return;
     const key2 = gridCellKey(cell);
     if (initialKeys.has(key2)) return;
     const next = selectedKeys.has(key2) ? selectedCells.filter((candidate) => gridCellKey(candidate) !== key2) : [...selectedCells, cell];
@@ -16284,6 +16322,7 @@ const GridSymmetry = ({
             className,
             "aria-label": label,
             "aria-pressed": selected,
+            "aria-disabled": exerciseLocked ? "true" : void 0,
             onClick: () => toggleCell(cell)
           },
           key2
@@ -16323,6 +16362,7 @@ const RadioOptions = ({
   onChange
 }) => {
   const playSound = useSound();
+  const locked = useExerciseLocked();
   return /* @__PURE__ */ jsx("div", { className: "radio-options", children: options.map((option, idx) => {
     const isSelected = value === option;
     const statusClass = isSelected && validationStatus ? ` widget--${validationStatus}` : "";
@@ -16331,9 +16371,11 @@ const RadioOptions = ({
       {
         className: `radio-option${isSelected ? " selected" : ""}${statusClass}`,
         onClick: () => {
+          if (locked) return;
           playSound("radio-select");
           onChange(name, option);
         },
+        "aria-disabled": locked ? "true" : void 0,
         type: "button",
         children: option
       },
@@ -16345,7 +16387,10 @@ const Btn = ({
   label,
   extraClass = "keypad-btn-digit",
   onClick
-}) => /* @__PURE__ */ jsx("button", { className: `keypad-btn ${extraClass}`, onClick, children: /* @__PURE__ */ jsx("span", { children: label }) });
+}) => {
+  const locked = useExerciseLocked();
+  return /* @__PURE__ */ jsx("button", { className: `keypad-btn ${extraClass}`, disabled: locked, onClick, children: /* @__PURE__ */ jsx("span", { children: label }) });
+};
 const DiamondKeypad = ({ value, onChange }) => {
   const playSound = useSound();
   const append = (ch) => {
@@ -16432,8 +16477,10 @@ const MatcherWidget = ({
     () => defaultValue2 && defaultValue2.length > 0 ? assignmentsFromValue(defaultValue2, itemIds, groupCount) : initialAssignments(itemIds)
   );
   const playSound = useSound();
+  const locked = useExerciseLocked();
   const handleCardClick = useCallback(
     (itemId) => {
+      if (locked) return;
       playSound("matcher-select");
       setAssignments((prev) => {
         const current = prev[itemId] ?? null;
@@ -16441,7 +16488,7 @@ const MatcherWidget = ({
         return { ...prev, [itemId]: next };
       });
     },
-    [groupCount, playSound]
+    [groupCount, playSound, locked]
   );
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
@@ -16478,6 +16525,7 @@ const MatcherWidget = ({
               "--matcher-card-text-color": `var(--matcher-group-${colorIdx + 1}-text-color, ${textColors[colorIdx]})`
             } : void 0,
             onClick: () => handleCardClick(item.itemId),
+            "aria-disabled": locked ? "true" : void 0,
             "aria-pressed": isSelected,
             "aria-label": isSelected ? `Assigned to group ${colorIdx + 1}` : "Not assigned",
             children: item.content.map((layoutItem) => /* @__PURE__ */ jsx(
@@ -16691,6 +16739,7 @@ const PairMatcherWidget = ({
   shuffleItems = true
 }) => {
   const { topItems, bottomItems } = widget;
+  const exerciseLocked = useExerciseLocked();
   const [shuffledTop] = useState(
     () => shuffleItems ? lodashExports.shuffle([...topItems]) : [...topItems]
   );
@@ -16734,8 +16783,9 @@ const PairMatcherWidget = ({
     }
     soundPrevRef.current = { count, pendingId, flashId };
   }, [state.pairs, state.pending, state.flashTopId, playSound]);
+  const interactionLocked = validationStatus !== null || exerciseLocked;
   const handleTopClick = useCallback((topId) => {
-    if (validationStatus) return;
+    if (interactionLocked) return;
     if (flashTimerRef.current) {
       clearTimeout(flashTimerRef.current);
       flashTimerRef.current = null;
@@ -16777,9 +16827,9 @@ const PairMatcherWidget = ({
         flashBottomId: null
       };
     });
-  }, [validationStatus]);
+  }, [interactionLocked]);
   const handleBottomClick = useCallback((bottomId) => {
-    if (validationStatus) return;
+    if (interactionLocked) return;
     if (flashTimerRef.current) {
       clearTimeout(flashTimerRef.current);
       flashTimerRef.current = null;
@@ -16822,9 +16872,13 @@ const PairMatcherWidget = ({
         flashBottomId: null
       };
     });
-  }, [validationStatus]);
+  }, [interactionLocked]);
   useEffect(() => {
-    if (validationStatus || state.flashTopId === null || state.flashBottomId === null) return;
+    if (state.flashTopId === null || state.flashBottomId === null) return;
+    if (interactionLocked) {
+      setState((current) => ({ ...current, flashTopId: null, flashBottomId: null }));
+      return;
+    }
     flashTimerRef.current = setTimeout(() => {
       flashTimerRef.current = null;
       setState((current) => {
@@ -16838,7 +16892,7 @@ const PairMatcherWidget = ({
         flashTimerRef.current = null;
       }
     };
-  }, [state.flashTopId, state.flashBottomId, validationStatus]);
+  }, [state.flashTopId, state.flashBottomId, interactionLocked]);
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
   const isMounted = useRef(false);
@@ -16898,7 +16952,7 @@ const PairMatcherWidget = ({
           dir: isRtl ? "rtl" : void 0,
           onClick: () => isTop ? handleTopClick(item.itemId) : handleBottomClick(item.itemId),
           "aria-pressed": status !== "idle",
-          "aria-disabled": validationStatus ? "true" : void 0,
+          "aria-disabled": interactionLocked ? "true" : void 0,
           children: /* @__PURE__ */ jsx("span", { className: "pair-matcher-card-content", children: item.content.map((li) => renderPairMatcherItemContent(li, widgetsMap)) })
         }
       ),
@@ -17437,6 +17491,7 @@ const DraggableCursor = ({
   currentValue,
   validationStatus
 }) => {
+  const locked = useExerciseLocked();
   const [isDragging, setIsDragging] = useState(false);
   const isDraggingRef = useRef(false);
   const currentValueRef = useRef(currentValue);
@@ -17458,13 +17513,14 @@ const DraggableCursor = ({
     return snapTicks.length > 0 ? snapToNearest(raw, snapTicks) : cleanFloat(raw);
   }, [axisRowRef, min, max, snapTicks]);
   const handlePointerDown = useCallback((e) => {
+    if (locked) return;
     e.currentTarget.setPointerCapture(e.pointerId);
     e.stopPropagation();
     isDraggingRef.current = true;
     dragStartValueRef.current = currentValue;
     lastSoundValueRef.current = currentValue;
     setIsDragging(true);
-  }, [currentValue]);
+  }, [currentValue, locked]);
   const updateCursorValue = useCallback((clientX) => {
     const next = snap(clientX);
     if (!almostEqual(next, lastSoundValueRef.current)) {
@@ -17492,7 +17548,7 @@ const DraggableCursor = ({
     }
   }, [updateCursorValue, playSound]);
   const handleKeyDown = useCallback((e) => {
-    if (!snapTicks.length) return;
+    if (locked || !snapTicks.length) return;
     const sorted = [...snapTicks].sort((a, b) => a - b);
     const idx = sorted.findIndex((t) => t >= currentValue - 1e-9);
     const first = sorted[0] ?? currentValue;
@@ -17514,7 +17570,7 @@ const DraggableCursor = ({
       }
       onChange(cursor.id, String(next));
     }
-  }, [snapTicks, audibleTicks, currentValue, playSound, onChange, cursor.id]);
+  }, [locked, snapTicks, audibleTicks, currentValue, playSound, onChange, cursor.id]);
   const ballClass = [
     "number-line-cursor-ball",
     isDragging ? "number-line-cursor-ball--dragging" : "",
@@ -17563,6 +17619,7 @@ const DraggableCursor = ({
         "aria-valuemax": max,
         "aria-valuenow": currentValue,
         "aria-label": sliderAriaLabel,
+        "aria-disabled": locked ? "true" : void 0,
         tabIndex: 0
       }
     )
@@ -17603,9 +17660,11 @@ const CursorBalls = ({
   }) });
 };
 const PlacedChip = ({ widgetId, label, leftPercent, isLanding, onRemove }) => {
+  const locked = useExerciseLocked();
   const { attributes, listeners, setNodeRef, isDragging } = useDraggable({
     id: widgetId,
-    data: { type: "placed-chip", widgetId, label }
+    data: { type: "placed-chip", widgetId, label },
+    disabled: locked
   });
   return /* @__PURE__ */ jsx(
     "div",
@@ -17630,6 +17689,7 @@ const PlacedChip = ({ widgetId, label, leftPercent, isLanding, onRemove }) => {
             type: "button",
             className: "number-line-placed-chip-remove",
             "aria-label": "Remove",
+            disabled: locked,
             onClick: onRemove,
             children: "✕"
           }
@@ -17669,6 +17729,7 @@ const FreeDragAxis = ({
   cursorValidationStatuses,
   snapKey
 }) => {
+  const axisLocked = useExerciseLocked();
   const axisRef = useRef(null);
   const snapTicks = useMemo(
     () => getSnapTicks(majorTicks, minorTicks),
@@ -17724,7 +17785,7 @@ const FreeDragAxis = ({
       return changed ? next : prev;
     });
   }, [values]);
-  const { setNodeRef } = useDroppable({ id: axisDropId });
+  const { setNodeRef } = useDroppable({ id: axisDropId, disabled: axisLocked });
   const mergedRef = useCallback((node) => {
     axisRef.current = node;
     setNodeRef(node);
@@ -18038,6 +18099,7 @@ const CounterControls = ({
   onIncrement
 }) => {
   const playSound = useSound();
+  const locked = useExerciseLocked();
   return /* @__PURE__ */ jsxs("div", { className: "number-line-counter", "aria-label": counter.name ?? "Counter", children: [
     /* @__PURE__ */ jsxs("div", { className: "number-line-counter-controls", children: [
       /* @__PURE__ */ jsx(
@@ -18046,7 +18108,7 @@ const CounterControls = ({
           type: "button",
           className: "number-line-counter-btn",
           "aria-label": "Decrease",
-          disabled: count <= counter.min,
+          disabled: locked || count <= counter.min,
           onClick: () => {
             playSound("counter-step");
             onDecrement();
@@ -18061,7 +18123,7 @@ const CounterControls = ({
           type: "button",
           className: "number-line-counter-btn",
           "aria-label": "Increase",
-          disabled: count >= counter.max,
+          disabled: locked || count >= counter.max,
           onClick: () => {
             playSound("counter-step");
             onIncrement();
@@ -18645,6 +18707,7 @@ const ClockRenderer = ({
   validationStatus,
   onChange
 }) => {
+  const locked = useExerciseLocked();
   const format = item.format ?? "24h";
   const interactive = item.mode === "interactive";
   const snap = interactive && "snap" in item ? item.snap ?? 1 : 1;
@@ -18690,18 +18753,18 @@ const ClockRenderer = ({
     }
   }, [snap, hours, minutes, item.mode, item.name, onChange, playSound]);
   const onPointerDown = (hand) => (e) => {
-    if (!interactive) return;
+    if (!interactive || locked) return;
     e.preventDefault();
     e.target.setPointerCapture?.(e.pointerId);
     draggingRef.current = hand;
     updateFromPointer(e.clientX, e.clientY);
   };
   const onPointerMove = (e) => {
-    if (!interactive || !draggingRef.current) return;
+    if (!interactive || locked || !draggingRef.current) return;
     updateFromPointer(e.clientX, e.clientY);
   };
   const onPointerUp = (e) => {
-    if (!interactive) return;
+    if (!interactive || locked) return;
     e.target.releasePointerCapture?.(e.pointerId);
     draggingRef.current = null;
   };
@@ -19253,38 +19316,45 @@ const ExerciseRenderer = forwardRef(({
   const [droppedSources, setDroppedSources] = useState(/* @__PURE__ */ new Map());
   const [focusedInputId, setFocusedInputId] = useState(null);
   const [validationDetails, setValidationDetails] = useState(null);
+  const rootRef = useRef(null);
   const [resetKey, setResetKey] = useState(0);
   const [revealed, setRevealed] = useState(false);
   const playSound = useSoundPlayer(soundEnabled, sounds);
-  useImperativeHandle(ref, () => ({
-    submit: () => {
-      const result = validate(json, values);
-      playSound(result.isCorrect ? "answer-correct" : "answer-wrong");
-      const details = { ...result.details };
-      const slotValidation = (id, raw, expected) => ({
-        widgetId: id,
-        userValue: typeof raw === "string" ? raw : void 0,
-        isCorrect: typeof raw === "string" && raw !== "" && normalize(raw) === normalize(expected)
-      });
-      for (const [widgetId, widget] of Object.entries(json.widgets)) {
-        if (widget.type !== JSON_TYPES.FRACTION) continue;
-        if (!(widgetId in details)) continue;
-        const answer = json.validation?.answers?.[widgetId];
-        if (!answer) continue;
-        const [expectedNum, expectedDen] = answer.split("/", 2);
-        if (!expectedNum || !expectedDen) continue;
-        if (details[widgetId]?.isCorrect) {
-          if (widget.numerator === null) details[`${widgetId}__num`] = { widgetId: `${widgetId}__num`, userValue: void 0, isCorrect: true };
-          if (widget.denominator === null) details[`${widgetId}__den`] = { widgetId: `${widgetId}__den`, userValue: void 0, isCorrect: true };
-        } else {
-          if (widget.numerator === null) details[`${widgetId}__num`] = slotValidation(`${widgetId}__num`, values[`${widgetId}__num`], expectedNum);
-          if (widget.denominator === null) details[`${widgetId}__den`] = slotValidation(`${widgetId}__den`, values[`${widgetId}__den`], expectedDen);
-        }
+  const externallyLocked = useExerciseLocked();
+  const locked = validationDetails !== null || externallyLocked;
+  const lastResultRef = useRef(null);
+  const runSubmit = () => {
+    if (locked) return lastResultRef.current ?? validate(json, values);
+    const result = validate(json, values);
+    playSound(result.isCorrect ? "answer-correct" : "answer-wrong");
+    const details = { ...result.details };
+    const slotValidation = (id, raw, expected) => ({
+      widgetId: id,
+      userValue: typeof raw === "string" ? raw : void 0,
+      isCorrect: typeof raw === "string" && raw !== "" && normalize(raw) === normalize(expected)
+    });
+    for (const [widgetId, widget] of Object.entries(json.widgets)) {
+      if (widget.type !== JSON_TYPES.FRACTION) continue;
+      if (!(widgetId in details)) continue;
+      const answer = json.validation?.answers?.[widgetId];
+      if (!answer) continue;
+      const [expectedNum, expectedDen] = answer.split("/", 2);
+      if (!expectedNum || !expectedDen) continue;
+      if (details[widgetId]?.isCorrect) {
+        if (widget.numerator === null) details[`${widgetId}__num`] = { widgetId: `${widgetId}__num`, userValue: void 0, isCorrect: true };
+        if (widget.denominator === null) details[`${widgetId}__den`] = { widgetId: `${widgetId}__den`, userValue: void 0, isCorrect: true };
+      } else {
+        if (widget.numerator === null) details[`${widgetId}__num`] = slotValidation(`${widgetId}__num`, values[`${widgetId}__num`], expectedNum);
+        if (widget.denominator === null) details[`${widgetId}__den`] = slotValidation(`${widgetId}__den`, values[`${widgetId}__den`], expectedDen);
       }
-      setValidationDetails(details);
-      onSubmit?.(values);
-      return result;
-    },
+    }
+    setValidationDetails(details);
+    onSubmit?.(values);
+    lastResultRef.current = result;
+    return result;
+  };
+  useImperativeHandle(ref, () => ({
+    submit: runSubmit,
     getValues: () => values,
     getCompletion: () => {
       const answerable = getAnswerableInputs(json);
@@ -19327,14 +19397,20 @@ const ExerciseRenderer = forwardRef(({
       setResetKey((k) => k + 1);
     },
     focusFirstInput: () => {
-      const container = document.querySelector(".math-exercise-renderer");
-      const firstInput = container?.querySelector('input[type="text"], input[type="number"], textarea, select');
-      if (firstInput instanceof HTMLElement) {
-        firstInput.focus();
+      const container = rootRef.current;
+      if (!container) return;
+      const candidates = container.querySelectorAll(
+        'input[type="text"], input[type="number"], textarea, select'
+      );
+      for (const el of Array.from(candidates)) {
+        if (el.readOnly || el.disabled) continue;
+        el.focus();
+        return;
       }
     }
-  }), [json, values, onSubmit, playSound]);
+  }), [json, values, onSubmit, playSound, locked]);
   const handleChange = (widgetId, value, fromDrop = false, sourceOptionId) => {
+    if (locked) return;
     setRevealed(false);
     const next = { ...valuesRef.current, [widgetId]: value };
     valuesRef.current = next;
@@ -19351,7 +19427,7 @@ const ExerciseRenderer = forwardRef(({
     onChange?.(next);
   };
   const handleSubmit = () => {
-    onSubmit?.(values);
+    runSubmit();
   };
   const lineGroups = useMemo(() => {
     const isRTLInlineWidget = (item) => {
@@ -19466,7 +19542,7 @@ const ExerciseRenderer = forwardRef(({
     if (setSquareWidget) add2("set-square-1", "set-square", Math.round(getSize(setSquareWidget) * 160));
     return { tools: list, toolsMinHeight: maxH };
   }, [rulerWidget, protractorWidget, setSquareWidget]);
-  return /* @__PURE__ */ jsx(SoundPlayerProvider, { play: playSound, children: /* @__PURE__ */ jsx(ExerciseDndProvider, { droppedSources, children: /* @__PURE__ */ jsxs("div", { className: `math-exercise-renderer ${revealed ? "revealed" : ""} ${className}`, children: [
+  return /* @__PURE__ */ jsx(SoundPlayerProvider, { play: playSound, children: /* @__PURE__ */ jsx(ExerciseLockProvider, { locked, children: /* @__PURE__ */ jsx(ExerciseDndProvider, { droppedSources, children: /* @__PURE__ */ jsxs("div", { ref: rootRef, className: `math-exercise-renderer ${revealed ? "revealed" : ""} ${locked ? "locked" : ""} ${className}`, children: [
     /* @__PURE__ */ jsxs(
       "div",
       {
@@ -19562,8 +19638,8 @@ const ExerciseRenderer = forwardRef(({
         }
       }
     ) }),
-    showSubmitButton && /* @__PURE__ */ jsx("button", { className: "exercise-submit-btn", onClick: handleSubmit, children: "Check Answer" })
-  ] }) }) });
+    showSubmitButton && /* @__PURE__ */ jsx("button", { className: "exercise-submit-btn", disabled: locked, onClick: handleSubmit, children: "Check Answer" })
+  ] }) }) }) });
 });
 ExerciseRenderer.displayName = "ExerciseRenderer";
 function renderExercise(options) {
@@ -19620,6 +19696,7 @@ export {
   EngineError,
   ExerciseDocumentSchema,
   ExerciseJSONSchema,
+  ExerciseLockProvider,
   ExerciseMetaSchema,
   ExerciseRenderer,
   ExpressionValidationSchema,
@@ -19842,6 +19919,7 @@ export {
   toJSON,
   tokenize,
   tokenizeSafe,
+  useExerciseLocked,
   useSound,
   validate,
   validateBooleanExpression,