@mathscan/math-exercise-engine 1.1.1 → 1.1.2

package/dist/index.mjs

@@ -52,6 +52,8 @@ const AST_TYPES = {
   MATCHER_ROW: "MatcherRow",
   /** Item within a matcher row */
   MATCHER_ITEM: "MatcherItem",
+  /** Pair-matcher layout block (top-row ↔ bottom-row pairing) */
+  PAIR_MATCHER_BLOCK: "PairMatcherBlock",
   /** Visual fraction inline widget */
   VISUAL_FRACTION: "VisualFraction",
   // ═══════════════════════════════════════════════════════════════════════════
@@ -70,6 +72,8 @@ const AST_TYPES = {
   SIMPLE_VALIDATION: "SimpleValidation",
   /** Expression-based validation */
   EXPRESSION_VALIDATION: "ExpressionValidation",
+  /** Mixed validation: per-widget simple answers + expression over free variables */
+  MIXED_VALIDATION: "MixedValidation",
   // ═══════════════════════════════════════════════════════════════════════════
   // Document
   // ═══════════════════════════════════════════════════════════════════════════
@@ -122,6 +126,8 @@ const JSON_TYPES = {
   MATCHER_ROW: "matcher-row",
   /** Item within a matcher row */
   MATCHER_ITEM: "matcher-item",
+  /** Pair-matcher widget (top-row ↔ bottom-row pairing) */
+  PAIR_MATCHER: "pair-matcher",
   // ═══════════════════════════════════════════════════════════════════════════
   // Widget Types
   // ═══════════════════════════════════════════════════════════════════════════
@@ -139,11 +145,18 @@ const JSON_TYPES = {
   VISUAL_FRACTION: "visual-fraction"
 };
 const DRAG_OPTIONS_WIDGET_ID = "_drag_options";
+const STATEFUL_WIDGET_TYPES = /* @__PURE__ */ new Set([
+  JSON_TYPES.MATCHER,
+  JSON_TYPES.PAIR_MATCHER,
+  JSON_TYPES.VISUAL_FRACTION
+]);
 const VALIDATION_MODES = {
   /** Simple answer matching validation */
   SIMPLE: "simple",
   /** Expression-based validation using JavaScript expressions */
-  EXPRESSION: "expression"
+  EXPRESSION: "expression",
+  /** Mixed: simple per-widget answers AND a boolean expression over free variables */
+  MIXED: "mixed"
 };
 const INPUT_TYPES = {
   /** String/text input */
@@ -279,10 +292,22 @@ const FRACTION = createToken({
   name: "FRACTION",
   pattern: /FRACTION/
 });
+const PAIR_MATCHER = createToken({
+  name: "PAIR_MATCHER",
+  pattern: /PAIR_MATCHER/
+});
 const MATCHER = createToken({
   name: "MATCHER",
   pattern: /MATCHER/
 });
+const TOP_ROW = createToken({
+  name: "TOP_ROW",
+  pattern: /TOP_ROW/
+});
+const BOTTOM_ROW = createToken({
+  name: "BOTTOM_ROW",
+  pattern: /BOTTOM_ROW/
+});
 const ITEM = createToken({
   name: "ITEM",
   pattern: /ITEM/
@@ -401,11 +426,14 @@ const allTokens = [
   POSITION,
   TABLE,
   ROW,
+  TOP_ROW,
+  BOTTOM_ROW,
   CELL,
   COUNTER,
   HIGHLIGHT,
   VISUAL_FRACTION,
   FRACTION,
+  PAIR_MATCHER,
   MATCHER,
   ITEM,
   ANSWERS,
@@ -559,6 +587,10 @@ class MathExerciseParser extends CstParser {
           GATE: this.BACKTRACK(this.numberLine),
           ALT: () => this.SUBRULE(this.numberLine)
         },
+        {
+          GATE: this.BACKTRACK(this.pairMatcher),
+          ALT: () => this.SUBRULE(this.pairMatcher)
+        },
         {
           GATE: this.BACKTRACK(this.matcher),
           ALT: () => this.SUBRULE(this.matcher)
@@ -820,6 +852,69 @@ class MathExerciseParser extends CstParser {
       });
       this.CONSUME(RBracket);
     });
+    this.pairMatcher = this.RULE("pairMatcher", () => {
+      this.MANY(() => {
+        this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
+      });
+      this.CONSUME(PAIR_MATCHER);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+      this.MANY2(() => {
+        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
+      });
+      this.CONSUME(LBrace);
+      this.MANY3(() => {
+        this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
+      });
+      this.SUBRULE(this.pairMatcherTopSection);
+      this.SUBRULE(this.pairMatcherBottomSection);
+      this.SUBRULE(this.matcherAnswers);
+      this.CONSUME(RBrace);
+      this.MANY4(() => {
+        this.OR4([{ ALT: () => this.CONSUME4(Newline) }, { ALT: () => this.CONSUME4(Space) }]);
+      });
+    });
+    this.pairMatcherTopSection = this.RULE("pairMatcherTopSection", () => {
+      this.MANY(() => {
+        this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
+      });
+      this.CONSUME(TOP_ROW);
+      this.MANY2(() => {
+        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
+      });
+      this.CONSUME(LBrace);
+      this.MANY3(() => {
+        this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
+      });
+      this.AT_LEAST_ONE(() => {
+        this.SUBRULE(this.matcherItem);
+      });
+      this.CONSUME(RBrace);
+      this.MANY4(() => {
+        this.OR4([{ ALT: () => this.CONSUME4(Space) }, { ALT: () => this.CONSUME4(Newline) }]);
+      });
+    });
+    this.pairMatcherBottomSection = this.RULE("pairMatcherBottomSection", () => {
+      this.MANY(() => {
+        this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
+      });
+      this.CONSUME(BOTTOM_ROW);
+      this.MANY2(() => {
+        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
+      });
+      this.CONSUME(LBrace);
+      this.MANY3(() => {
+        this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
+      });
+      this.AT_LEAST_ONE(() => {
+        this.SUBRULE(this.matcherItem);
+      });
+      this.CONSUME(RBrace);
+      this.MANY4(() => {
+        this.OR4([{ ALT: () => this.CONSUME4(Space) }, { ALT: () => this.CONSUME4(Newline) }]);
+      });
+    });
     this.line = this.RULE("line", () => {
       this.MANY(() => {
         this.CONSUME(Space);
@@ -1634,6 +1729,91 @@ function createMatcherBlock(name, rows, answers, colors) {
 function isMatcherBlock(value) {
   return MatcherBlockSchema.safeParse(value).success;
 }
+const PairMatcherBlockSchema = z.object({
+  type: z.literal(AST_TYPES.PAIR_MATCHER_BLOCK),
+  name: z.string().min(1),
+  /** Items in the top row — at least one required */
+  topItems: z.array(MatcherItemSchema).min(1),
+  /** Items in the bottom row — at least one required */
+  bottomItems: z.array(MatcherItemSchema).min(1),
+  /**
+   * Each answer pair is [topId, bottomId].
+   * At least one pair is required.
+   */
+  answers: z.array(z.tuple([z.string().min(1), z.string().min(1)])).min(1)
+}).superRefine((data, ctx) => {
+  const idRegistry = /* @__PURE__ */ new Map();
+  const sections = [
+    { key: "topItems", items: data.topItems },
+    { key: "bottomItems", items: data.bottomItems }
+  ];
+  for (const { key: key2, items } of sections) {
+    for (let i = 0; i < items.length; i++) {
+      const { itemId } = items[i];
+      const existing = idRegistry.get(itemId);
+      if (existing) {
+        const isCrossSection = existing.section !== key2;
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: isCrossSection ? `itemId "${itemId}" appears in both TOP and BOTTOM — ids must be globally unique` : `Duplicate itemId "${itemId}" in ${key2 === "topItems" ? "TOP" : "BOTTOM"} section`,
+          path: [key2, i, "itemId"]
+        });
+      } else {
+        idRegistry.set(itemId, { section: key2, index: i });
+      }
+    }
+  }
+  const topIds = new Set(data.topItems.map((it) => it.itemId));
+  const bottomIds = new Set(data.bottomItems.map((it) => it.itemId));
+  const usedTopIds = /* @__PURE__ */ new Set();
+  const usedBottomIds = /* @__PURE__ */ new Set();
+  data.answers.forEach(([topId, bottomId], i) => {
+    if (!topIds.has(topId)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Answer pair [${topId}, ${bottomId}]: "${topId}" is not declared in TOP section`,
+        path: ["answers", i, 0]
+      });
+    }
+    if (!bottomIds.has(bottomId)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Answer pair [${topId}, ${bottomId}]: "${bottomId}" is not declared in BOTTOM section`,
+        path: ["answers", i, 1]
+      });
+    }
+    if (usedTopIds.has(topId)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `topId "${topId}" appears in more than one answer pair`,
+        path: ["answers", i, 0]
+      });
+    } else {
+      usedTopIds.add(topId);
+    }
+    if (usedBottomIds.has(bottomId)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `bottomId "${bottomId}" appears in more than one answer pair`,
+        path: ["answers", i, 1]
+      });
+    } else {
+      usedBottomIds.add(bottomId);
+    }
+  });
+});
+function createPairMatcherBlock(name, topItems, bottomItems, answers) {
+  return PairMatcherBlockSchema.parse({
+    type: AST_TYPES.PAIR_MATCHER_BLOCK,
+    name,
+    topItems,
+    bottomItems,
+    answers
+  });
+}
+function isPairMatcherBlock(value) {
+  return PairMatcherBlockSchema.safeParse(value).success;
+}
 const DragOptionsToolSchema = z.object({
   type: z.literal(AST_TYPES.DRAG_OPTIONS),
   options: z.array(z.string()).min(1)
@@ -1692,9 +1872,14 @@ const ExpressionValidationSchema = z.object({
   type: z.literal(AST_TYPES.EXPRESSION_VALIDATION),
   expression: z.string()
 });
+const MixedValidationSchema = z.object({
+  type: z.literal(AST_TYPES.MIXED_VALIDATION),
+  expression: z.string().min(1)
+});
 const ValidationNodeSchema = z.discriminatedUnion("type", [
   SimpleValidationSchema,
-  ExpressionValidationSchema
+  ExpressionValidationSchema,
+  MixedValidationSchema
 ]);
 function createSimpleValidation() {
   return SimpleValidationSchema.parse({
@@ -1707,16 +1892,25 @@ function createExpressionValidation(expression) {
     expression
   });
 }
+function createMixedValidation(expression) {
+  return MixedValidationSchema.parse({
+    type: AST_TYPES.MIXED_VALIDATION,
+    expression
+  });
+}
 function isSimpleValidation(value) {
   return SimpleValidationSchema.safeParse(value).success;
 }
 function isExpressionValidation(value) {
   return ExpressionValidationSchema.safeParse(value).success;
 }
+function isMixedValidation(value) {
+  return MixedValidationSchema.safeParse(value).success;
+}
 function isValidationNode(value) {
   return ValidationNodeSchema.safeParse(value).success;
 }
-const ContentBlockSchema = z.union([LineBlockSchema, TableBlockSchema, RadioOptionsBlockSchema, NumberLineBlockSchema, MatcherBlockSchema]);
+const ContentBlockSchema = z.union([LineBlockSchema, TableBlockSchema, RadioOptionsBlockSchema, NumberLineBlockSchema, MatcherBlockSchema, PairMatcherBlockSchema]);
 const ExerciseDocumentSchema = z.object({
   type: z.literal(AST_TYPES.EXERCISE_DOCUMENT),
   question: TextBlockSchema.optional(),
@@ -1764,6 +1958,12 @@ const ExerciseDocumentSchema = z.object({
           visitInlines(item.inlines, ["lines", bi, "rows", ri, "items", ii, "inlines"]);
         });
       });
+    } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
+      const pm = block;
+      record(pm.name, ["lines", bi, "name"]);
+      [...pm.topItems, ...pm.bottomItems].forEach((item, ii) => {
+        visitInlines(item.inlines, ["lines", bi, "items", ii, "inlines"]);
+      });
     } else if (block.type === AST_TYPES.RADIO_OPTIONS) {
       record(block.name, ["lines", bi, "name"]);
     }
@@ -1812,6 +2012,7 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     if (ctx.table) return this.visit(ctx.table);
     if (ctx.radioButtons) return this.visit(ctx.radioButtons);
     if (ctx.numberLine) return this.visit(ctx.numberLine);
+    if (ctx.pairMatcher) return this.visit(ctx.pairMatcher);
     if (ctx.matcher) return this.visit(ctx.matcher);
     if (ctx.line) return this.visit(ctx.line);
     throw new Error("Unknown content block");
@@ -1925,6 +2126,32 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     return ctx.ids ? ctx.ids.map((t) => t.image) : [];
   }
   // ═══════════════════════════════════════════════════════════════════════════
+  // Pair Matcher Block
+  // ═══════════════════════════════════════════════════════════════════════════
+  pairMatcher(ctx) {
+    const params = this.visit(ctx.parameterList);
+    const name = params.name;
+    const topItems = this.visit(ctx.pairMatcherTopSection);
+    const bottomItems = this.visit(ctx.pairMatcherBottomSection);
+    const rawAnswers = this.visit(ctx.matcherAnswers);
+    return createPairMatcherBlock(name, topItems, bottomItems, rawAnswers);
+  }
+  pairMatcherTopSection(ctx) {
+    return this.visitMatcherItemList(ctx);
+  }
+  pairMatcherBottomSection(ctx) {
+    return this.visitMatcherItemList(ctx);
+  }
+  /**
+   * Maps `ctx.matcherItem` CST nodes to MatcherItem AST nodes.
+   * Shared by pairMatcherTopSection and pairMatcherBottomSection because their
+   * grammar rules are structurally identical — both are `matcherItem+` lists
+   * wrapped in a labelled section keyword.
+   */
+  visitMatcherItemList(ctx) {
+    return ctx.matcherItem ? ctx.matcherItem.map((i) => this.visit(i)) : [];
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
   // Line Block
   // ═══════════════════════════════════════════════════════════════════════════
   line(ctx) {
@@ -2130,6 +2357,12 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     } else if (type === "expression") {
       const expression = params.expression;
       return createExpressionValidation(expression);
+    } else if (type === "mixed") {
+      const expression = params.expression;
+      if (!expression || expression.trim() === "") {
+        throw new Error("Mixed validation requires a non-empty expression");
+      }
+      return createMixedValidation(expression);
     }
     throw new Error(`Unknown validation type: ${type}`);
   }
@@ -2403,6 +2636,11 @@ const MatcherWidgetJSONSchema = z.object({
   /** Number of answer groups — equals answers.length, stored here to avoid prop-drilling. */
   groupCount: z.number().int().min(1)
 });
+const PairMatcherWidgetJSONSchema = z.object({
+  type: z.literal(JSON_TYPES.PAIR_MATCHER),
+  topItems: z.array(MatcherItemContentSchema).min(1),
+  bottomItems: z.array(MatcherItemContentSchema).min(1)
+});
 const VisualFractionJSONSchema = z.object({
   type: z.literal(JSON_TYPES.VISUAL_FRACTION),
   shape: z.enum(["bar", "circle", "triangle", "grid"]).default("bar"),
@@ -2427,10 +2665,11 @@ const WidgetJSONSchema = z.union([
   NumericKeypadJSONSchema,
   FractionJSONSchema,
   MatcherWidgetJSONSchema,
+  PairMatcherWidgetJSONSchema,
   VisualFractionJSONSchema
 ]);
 const ValidationJSONSchema = z.object({
-  mode: z.enum([VALIDATION_MODES.SIMPLE, VALIDATION_MODES.EXPRESSION]),
+  mode: z.enum([VALIDATION_MODES.SIMPLE, VALIDATION_MODES.EXPRESSION, VALIDATION_MODES.MIXED]),
   // Simple answers: string|number per widget id.
   // Matcher answers: string[][] keyed by matcher name. Outer/inner min(1)
   // mirrors MatcherBlockSchema invariants in src/ast/matcher.ts.
@@ -2566,6 +2805,17 @@ function toJSON(ast) {
         id: idGenerator.generate(JSON_TYPES.LINEBREAK),
         type: JSON_TYPES.LINEBREAK
       });
+    } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
+      const pmBlock = block;
+      layout.push({
+        id: idGenerator.generate(JSON_TYPES.WIDGET_REF),
+        type: JSON_TYPES.WIDGET_REF,
+        widgetId: pmBlock.name
+      });
+      layout.push({
+        id: idGenerator.generate(JSON_TYPES.LINEBREAK),
+        type: JSON_TYPES.LINEBREAK
+      });
     } else if (block.type === AST_TYPES.RADIO_OPTIONS) {
       const radioBlock = block;
       layout.push({
@@ -2647,6 +2897,10 @@ function toJSON(ast) {
       const matcherBlock = block;
       widgets[matcherBlock.name] = buildMatcherWidget(matcherBlock, idGenerator);
       answers[matcherBlock.name] = matcherBlock.answers;
+    } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
+      const pmBlock = block;
+      widgets[pmBlock.name] = buildPairMatcherWidget(pmBlock, idGenerator);
+      answers[pmBlock.name] = pmBlock.answers;
     }
   }
   if (ast.tools) {
@@ -2695,6 +2949,11 @@ function collectAllInlines(blocks) {
           result.push(...item.inlines);
         }
       }
+    } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
+      const pm = block;
+      for (const item of [...pm.topItems, ...pm.bottomItems]) {
+        result.push(...item.inlines);
+      }
     }
   }
   return result;
@@ -2748,20 +3007,20 @@ function transformNumberLine(numberLine, idGenerator) {
   };
   return item;
 }
+function mapMatcherItemList(items, idGenerator) {
+  return items.map((item) => ({
+    id: idGenerator.generate(JSON_TYPES.MATCHER_ITEM),
+    type: JSON_TYPES.MATCHER_ITEM,
+    itemId: item.itemId,
+    content: item.inlines.map((inline) => transformInline(inline, idGenerator))
+  }));
+}
 function buildMatcherWidget(matcher, idGenerator) {
-  const rows = matcher.rows.map((row) => {
-    const items = row.items.map((item) => ({
-      id: idGenerator.generate(JSON_TYPES.MATCHER_ITEM),
-      type: JSON_TYPES.MATCHER_ITEM,
-      itemId: item.itemId,
-      content: item.inlines.map((inline) => transformInline(inline, idGenerator))
-    }));
-    return {
-      id: idGenerator.generate(JSON_TYPES.MATCHER_ROW),
-      type: JSON_TYPES.MATCHER_ROW,
-      items
-    };
-  });
+  const rows = matcher.rows.map((row) => ({
+    id: idGenerator.generate(JSON_TYPES.MATCHER_ROW),
+    type: JSON_TYPES.MATCHER_ROW,
+    items: mapMatcherItemList(row.items, idGenerator)
+  }));
   const result = {
     type: JSON_TYPES.MATCHER,
     rows,
@@ -2772,6 +3031,13 @@ function buildMatcherWidget(matcher, idGenerator) {
   }
   return result;
 }
+function buildPairMatcherWidget(pm, idGenerator) {
+  return {
+    type: JSON_TYPES.PAIR_MATCHER,
+    topItems: mapMatcherItemList(pm.topItems, idGenerator),
+    bottomItems: mapMatcherItemList(pm.bottomItems, idGenerator)
+  };
+}
 function transformTable(table, idGenerator) {
   const rows = table.rows.map((row) => {
     const cells = row.cells.map((cell) => {
@@ -2900,6 +3166,32 @@ function transformValidation(validation, answers, widgets) {
       expression: validation.expression,
       variables
     };
+  } else if (validation.type === AST_TYPES.MIXED_VALIDATION) {
+    const validVariableNames = Object.keys(widgets);
+    const variables = extractVariables$1(validation.expression, validVariableNames);
+    const inExpression = new Set(variables);
+    for (const [name, widget] of Object.entries(widgets)) {
+      if (name.startsWith("_")) continue;
+      if (name in answers) continue;
+      if (inExpression.has(name)) continue;
+      if (widget.type === JSON_TYPES.FRACTION) {
+        const w = widget;
+        if (w.numerator !== null && w.denominator !== null) continue;
+      }
+      if (widget.type === JSON_TYPES.VISUAL_FRACTION) {
+        const w = widget;
+        if (Array.isArray(w.filled) && w.filled.length > 0) continue;
+      }
+      throw new Error(
+        `Mixed validation: widget "${name}" has no \`answer\` and is not referenced in expression "${validation.expression}"`
+      );
+    }
+    return {
+      mode: VALIDATION_MODES.MIXED,
+      expression: validation.expression,
+      answers,
+      variables
+    };
   }
   throw new Error(`Unknown validation type: ${validation.type}`);
 }
@@ -8424,6 +8716,19 @@ function areMatcherEqual(expected, result) {
   const normalize2 = (groups) => lodashExports.sortBy(groups.map((g) => lodashExports.sortBy(g)), (g) => g.join("|"));
   return lodashExports.isEqual(normalize2(expected), normalize2(result));
 }
+function getPairMatcherGroupResults(expected, result) {
+  if (!Array.isArray(result)) return [];
+  const normalizeGroup = (g) => lodashExports.sortBy(g).join("|");
+  const expectedKeys = new Set(expected.map(normalizeGroup));
+  return result.map((group) => {
+    const key2 = normalizeGroup(group);
+    if (expectedKeys.has(key2)) {
+      expectedKeys.delete(key2);
+      return { group, isCorrect: true };
+    }
+    return { group, isCorrect: false };
+  });
+}
 function areVisualFractionCountsEqual(expected, result) {
   if (!Array.isArray(result)) return false;
   if (expected.length !== result.length) return false;
@@ -8462,7 +8767,8 @@ function validateSimple(exercise, userInputs) {
     return {
       isCorrect: false,
       details: {},
-      score: 0
+      score: 0,
+      error: "No answers defined for simple validation"
     };
   }
   const positionMap = buildPositionMap(exercise);
@@ -8477,6 +8783,21 @@ function validateSimple(exercise, userInputs) {
       else allCorrect = false;
       continue;
     }
+    if (widget?.type === JSON_TYPES.PAIR_MATCHER) {
+      const userValue2 = userInputs[widgetId];
+      const groupResults = getPairMatcherGroupResults(expected, userValue2);
+      const isCorrect2 = groupResults.length === expected.length && groupResults.every((r) => r.isCorrect);
+      details[widgetId] = {
+        widgetId,
+        userValue: userValue2,
+        isCorrect: isCorrect2,
+        groupResults
+      };
+      totalCount++;
+      if (isCorrect2) correctCount++;
+      else allCorrect = false;
+      continue;
+    }
     if (widget?.type === JSON_TYPES.VISUAL_FRACTION) {
       const userValue2 = userInputs[widgetId];
       const isCorrect2 = areVisualFractionCountsEqual(expected, userValue2);
@@ -8795,6 +9116,55 @@ function parseFractionOrNumber(s) {
   }
   return parseFloat(s);
 }
+function validateMixed(exercise, userInputs) {
+  const answers = exercise.validation.answers ?? {};
+  const simpleResult = validateSimple(exercise, userInputs);
+  const scalarInputs = {};
+  for (const [k, v] of Object.entries(userInputs)) {
+    if (typeof v === "string" || typeof v === "number") scalarInputs[k] = v;
+  }
+  const exprResult = validateExpression(exercise, scalarInputs);
+  const details = {};
+  const answerKeys = new Set(Object.keys(answers));
+  for (const k of answerKeys) {
+    const simpleDetail = simpleResult.details[k];
+    if (!simpleDetail) continue;
+    const inExpr = k in exprResult.details;
+    details[k] = {
+      ...simpleDetail,
+      simpleCorrect: simpleDetail.isCorrect,
+      ...inExpr && { expressionCorrect: exprResult.isCorrect },
+      isCorrect: inExpr ? simpleDetail.isCorrect && exprResult.isCorrect : simpleDetail.isCorrect
+    };
+  }
+  for (const [k, detail] of Object.entries(exprResult.details)) {
+    if (!(k in details)) {
+      details[k] = {
+        ...detail,
+        expressionCorrect: exprResult.isCorrect
+      };
+    }
+  }
+  const simpleCount = Object.keys(answers).length;
+  let simpleCorrect = 0;
+  for (const k of Object.keys(answers)) {
+    if (simpleResult.details[k]?.isCorrect) simpleCorrect++;
+  }
+  const score = (simpleCorrect + (exprResult.isCorrect ? 1 : 0)) / (simpleCount + 1);
+  const isCorrect = simpleResult.isCorrect && exprResult.isCorrect;
+  const result = {
+    isCorrect,
+    details,
+    score,
+    expression: exercise.validation.expression,
+    scope: exprResult.scope
+  };
+  const propagatedError = exprResult.error ?? simpleResult.error;
+  if (!isCorrect && propagatedError) {
+    result.error = propagatedError;
+  }
+  return result;
+}
 function preprocessFractionValues(exercise, userInputs) {
   const result = { ...userInputs };
   for (const [widgetId, widget] of Object.entries(exercise.widgets)) {
@@ -8837,6 +9207,8 @@ function validate(exercise, userInputs) {
       }
       return validateExpression(validatedExercise, scalar);
     }
+    case VALIDATION_MODES.MIXED:
+      return validateMixed(validatedExercise, processedInputs);
     default:
       return {
         isCorrect: false,
@@ -8850,18 +9222,27 @@ function getMissingInputs(exercise, userInputs) {
   if (!exercise.validation) {
     return missing;
   }
+  const isEmpty = (v) => v === void 0 || v === null || v === "" || Array.isArray(v) && v.length === 0;
   if (exercise.validation.mode === VALIDATION_MODES.SIMPLE && exercise.validation.answers) {
     for (const widgetId of Object.keys(exercise.validation.answers)) {
-      if (!(widgetId in userInputs) || userInputs[widgetId] === "") {
+      if (!(widgetId in userInputs) || isEmpty(userInputs[widgetId])) {
         missing.push(widgetId);
       }
     }
   } else if (exercise.validation.mode === VALIDATION_MODES.EXPRESSION && exercise.validation.variables) {
     for (const varName of exercise.validation.variables) {
-      if (!(varName in userInputs) || userInputs[varName] === "") {
+      if (!(varName in userInputs) || isEmpty(userInputs[varName])) {
         missing.push(varName);
       }
     }
+  } else if (exercise.validation.mode === VALIDATION_MODES.MIXED) {
+    const keys = /* @__PURE__ */ new Set([
+      ...Object.keys(exercise.validation.answers ?? {}),
+      ...exercise.validation.variables ?? []
+    ]);
+    for (const k of keys) {
+      if (!(k in userInputs) || isEmpty(userInputs[k])) missing.push(k);
+    }
   }
   return missing;
 }
@@ -13695,10 +14076,10 @@ function buildGroups(assignments) {
   }
   return Array.from(map.values());
 }
-const EMPTY_WIDGETS = {};
-const EMPTY_VALUES = {};
-const EMPTY_DROPPED = /* @__PURE__ */ new Set();
-const NOOP = () => {
+const EMPTY_WIDGETS$1 = {};
+const EMPTY_VALUES$1 = {};
+const EMPTY_DROPPED$1 = /* @__PURE__ */ new Set();
+const NOOP$1 = () => {
 };
 const MatcherWidget = ({
   widgetId,
@@ -13709,7 +14090,7 @@ const MatcherWidget = ({
   widgets
 }) => {
   const { rows, colors: userColors, groupCount } = widget;
-  const widgetsMap = widgets ?? EMPTY_WIDGETS;
+  const widgetsMap = widgets ?? EMPTY_WIDGETS$1;
   const palette = useMemo(
     () => resolveGroupPalette(userColors, groupCount),
     [userColors, groupCount]
@@ -13774,9 +14155,9 @@ const MatcherWidget = ({
               {
                 item: layoutItem,
                 widgets: widgetsMap,
-                values: EMPTY_VALUES,
-                droppedInputs: EMPTY_DROPPED,
-                onChange: NOOP
+                values: EMPTY_VALUES$1,
+                droppedInputs: EMPTY_DROPPED$1,
+                onChange: NOOP$1
               },
               layoutItem.id
             ))
@@ -13788,6 +14169,424 @@ const MatcherWidget = ({
   );
 };
 MatcherWidget.displayName = "MatcherWidget";
+function isArabic(text) {
+  return /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/.test(text);
+}
+function hasLatinChars(text) {
+  return /[A-Za-z]/.test(text);
+}
+function itemContainsArabic(item) {
+  if (item.type === JSON_TYPES.TEXT && "value" in item) {
+    return isArabic(item.value);
+  }
+  if (item.type === JSON_TYPES.HIGHLIGHTED_TEXT && "value" in item) {
+    return isArabic(item.value);
+  }
+  if (item.type === JSON_TYPES.GROUP && "items" in item) {
+    return item.items.some((subItem) => itemContainsArabic(subItem));
+  }
+  return false;
+}
+function itemContainsLatin(item) {
+  if (item.type === JSON_TYPES.TEXT && "value" in item) {
+    return hasLatinChars(item.value);
+  }
+  if (item.type === JSON_TYPES.HIGHLIGHTED_TEXT && "value" in item) {
+    return hasLatinChars(item.value);
+  }
+  if (item.type === JSON_TYPES.GROUP && "items" in item) {
+    return item.items.some((subItem) => itemContainsLatin(subItem));
+  }
+  return false;
+}
+function shouldItemsUseRTL(items) {
+  const hasArabic = items.some(itemContainsArabic);
+  const hasLatin = items.some(itemContainsLatin);
+  return hasArabic && !hasLatin;
+}
+function usePairLines({
+  containerRef,
+  pairs,
+  lineDirections,
+  validationStatus,
+  pairStatusByTopId
+}) {
+  const dotRefs = useRef(/* @__PURE__ */ new Map());
+  const [lines, setLines] = useState([]);
+  const recalcLines = useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const cr = container.getBoundingClientRect();
+    const newLines = [];
+    for (const [topId, bottomId] of Object.entries(pairs)) {
+      const topDot = dotRefs.current.get(`top:${topId}`);
+      const bottomDot = dotRefs.current.get(`bottom:${bottomId}`);
+      if (!topDot || !bottomDot) continue;
+      const tr = topDot.getBoundingClientRect();
+      const br = bottomDot.getBoundingClientRect();
+      const status = validationStatus ? pairStatusByTopId[topId] ?? (validationStatus === "correct" ? "correct" : "incorrect") : "idle";
+      const direction = lineDirections[topId] ?? "top-to-bottom";
+      const startRect = direction === "top-to-bottom" ? tr : br;
+      const endRect = direction === "top-to-bottom" ? br : tr;
+      newLines.push({
+        topId,
+        x1: startRect.left - cr.left + startRect.width / 2,
+        y1: startRect.top - cr.top + startRect.height / 2,
+        x2: endRect.left - cr.left + endRect.width / 2,
+        y2: endRect.top - cr.top + endRect.height / 2,
+        status
+      });
+    }
+    setLines(newLines);
+  }, [pairs, lineDirections, validationStatus, pairStatusByTopId]);
+  useLayoutEffect(() => {
+    recalcLines();
+  }, [recalcLines]);
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver(recalcLines);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [containerRef, recalcLines]);
+  return { dotRefs, lines };
+}
+const EMPTY_WIDGETS = {};
+const EMPTY_VALUES = {};
+const EMPTY_DROPPED = /* @__PURE__ */ new Set();
+const NOOP = () => {
+};
+function buildInitialState(defaultValue2, topIds, bottomIds) {
+  if (!defaultValue2?.length) return { pairs: {}, lineDirections: {} };
+  const pairs = {};
+  const lineDirections = {};
+  for (const pair of defaultValue2) {
+    if (!Array.isArray(pair) || pair.length !== 2 || pair[0] == null || pair[1] == null) continue;
+    const [first, second] = pair;
+    if (topIds.has(first) && bottomIds.has(second)) {
+      pairs[first] = second;
+      lineDirections[first] = "top-to-bottom";
+    } else if (bottomIds.has(first) && topIds.has(second)) {
+      pairs[second] = first;
+      lineDirections[second] = "bottom-to-top";
+    }
+  }
+  return { pairs, lineDirections };
+}
+function findTopForBottom(pairs, bottomId) {
+  return Object.keys(pairs).find((topId) => pairs[topId] === bottomId);
+}
+function withLineDirection(lineDirections, pairs, topId, bottomId, direction) {
+  const next = { ...lineDirections };
+  delete next[topId];
+  const existingTop = findTopForBottom(pairs, bottomId);
+  if (existingTop !== void 0) delete next[existingTop];
+  next[topId] = direction;
+  return next;
+}
+function getPairIds(pair, topIds, bottomIds) {
+  if (pair.length !== 2) return null;
+  const first = pair[0];
+  const second = pair[1];
+  if (first === void 0 || second === void 0) return null;
+  if (topIds.has(first) && bottomIds.has(second)) return { topId: first, bottomId: second };
+  if (bottomIds.has(first) && topIds.has(second)) return { topId: second, bottomId: first };
+  return null;
+}
+function withPair(pairs, topId, bottomId) {
+  const next = { ...pairs };
+  delete next[topId];
+  const existingTop = findTopForBottom(next, bottomId);
+  if (existingTop !== void 0) delete next[existingTop];
+  next[topId] = bottomId;
+  return next;
+}
+function resolveCardStatus(ownId, isTop, pairs, pending, validationStatus, pairStatus) {
+  if (validationStatus) {
+    const topId2 = isTop ? ownId : findTopForBottom(pairs, ownId);
+    if (topId2 === void 0 || pairs[topId2] === void 0) return "idle";
+    return pairStatus ?? (validationStatus === "correct" ? "correct" : "incorrect");
+  }
+  if (pending?.side === (isTop ? "top" : "bottom") && pending.id === ownId) return "pending";
+  const topId = isTop ? ownId : findTopForBottom(pairs, ownId);
+  if (topId !== void 0 && pairs[topId] !== void 0) return "paired";
+  return "idle";
+}
+function buildDotClass(status, position) {
+  const cls = ["pair-matcher-dot", `pair-matcher-dot--${position}`];
+  if (status !== "idle") {
+    cls.push("pair-matcher-dot--active");
+    if (status !== "paired") cls.push(`pair-matcher-dot--${status}`);
+  }
+  return cls.join(" ");
+}
+function buildCardClass(status, isFlashing) {
+  const cls = ["pair-matcher-card"];
+  if (status !== "idle") cls.push(`pair-matcher-card--${status}`);
+  if (isFlashing) cls.push("pair-matcher-card--flash");
+  return cls.join(" ");
+}
+function lineStrokeVar(status) {
+  if (status === "correct") return "var(--pm-line-color-correct)";
+  if (status === "incorrect") return "var(--pm-line-color-incorrect)";
+  return "var(--pm-line-color)";
+}
+function renderPairMatcherItemContent(item, widgets) {
+  if (item.type === JSON_TYPES.SPACE) {
+    return /* @__PURE__ */ jsx("span", { className: "space", children: " " }, item.id);
+  }
+  if (item.type === JSON_TYPES.GROUP) {
+    return /* @__PURE__ */ jsx("span", { className: "group", children: item.items.map((subItem) => renderPairMatcherItemContent(subItem, widgets)) }, item.id);
+  }
+  return /* @__PURE__ */ jsx(
+    LayoutRenderer,
+    {
+      item,
+      widgets,
+      values: EMPTY_VALUES,
+      droppedInputs: EMPTY_DROPPED,
+      onChange: NOOP
+    },
+    item.id
+  );
+}
+const PairMatcherWidget = ({
+  widgetId,
+  widget,
+  onChange,
+  validationStatus = null,
+  validationDetail,
+  defaultValue: defaultValue2,
+  widgets,
+  shuffleItems = true
+}) => {
+  const { topItems, bottomItems } = widget;
+  const [shuffledTop] = useState(
+    () => shuffleItems ? lodashExports.shuffle([...topItems]) : [...topItems]
+  );
+  const [shuffledBottom] = useState(
+    () => shuffleItems ? lodashExports.shuffle([...bottomItems]) : [...bottomItems]
+  );
+  const widgetsMap = widgets ?? EMPTY_WIDGETS;
+  const topIds = useMemo(() => new Set(topItems.map((item) => item.itemId)), [topItems]);
+  const bottomIds = useMemo(() => new Set(bottomItems.map((item) => item.itemId)), [bottomItems]);
+  const pairStatusByTopId = useMemo(() => {
+    const statuses = {};
+    for (const result of validationDetail?.groupResults ?? []) {
+      const ids2 = getPairIds(result.group, topIds, bottomIds);
+      if (ids2) statuses[ids2.topId] = result.isCorrect ? "correct" : "incorrect";
+    }
+    return statuses;
+  }, [validationDetail?.groupResults, topIds, bottomIds]);
+  const [state, setState] = useState(() => ({
+    ...buildInitialState(defaultValue2, topIds, bottomIds),
+    pending: null,
+    flashTopId: null,
+    flashBottomId: null
+  }));
+  const flashTimerRef = useRef(null);
+  const handleTopClick = useCallback((topId) => {
+    if (validationStatus) return;
+    if (flashTimerRef.current) {
+      clearTimeout(flashTimerRef.current);
+      flashTimerRef.current = null;
+    }
+    setState((prev) => {
+      if (prev.pairs[topId] !== void 0) {
+        const { [topId]: _, ...rest } = prev.pairs;
+        const { [topId]: __, ...restDirections } = prev.lineDirections;
+        if (prev.pending?.side === "bottom") {
+          return {
+            pairs: withPair(rest, topId, prev.pending.id),
+            lineDirections: withLineDirection(restDirections, rest, topId, prev.pending.id, "bottom-to-top"),
+            pending: null,
+            flashTopId: topId,
+            flashBottomId: prev.pending.id
+          };
+        }
+        return {
+          pairs: rest,
+          lineDirections: restDirections,
+          pending: { side: "top", id: topId },
+          flashTopId: null,
+          flashBottomId: null
+        };
+      }
+      if (prev.pending?.side === "bottom") {
+        return {
+          pairs: withPair(prev.pairs, topId, prev.pending.id),
+          lineDirections: withLineDirection(prev.lineDirections, prev.pairs, topId, prev.pending.id, "bottom-to-top"),
+          pending: null,
+          flashTopId: topId,
+          flashBottomId: prev.pending.id
+        };
+      }
+      return {
+        ...prev,
+        pending: prev.pending?.side === "top" && prev.pending.id === topId ? null : { side: "top", id: topId },
+        flashTopId: null,
+        flashBottomId: null
+      };
+    });
+  }, [validationStatus]);
+  const handleBottomClick = useCallback((bottomId) => {
+    if (validationStatus) return;
+    if (flashTimerRef.current) {
+      clearTimeout(flashTimerRef.current);
+      flashTimerRef.current = null;
+    }
+    setState((prev) => {
+      const existingTop = findTopForBottom(prev.pairs, bottomId);
+      if (existingTop !== void 0) {
+        const { [existingTop]: _, ...rest } = prev.pairs;
+        const { [existingTop]: __, ...restDirections } = prev.lineDirections;
+        if (prev.pending?.side === "top" && prev.pending.id !== existingTop) {
+          return {
+            pairs: withPair(rest, prev.pending.id, bottomId),
+            lineDirections: withLineDirection(restDirections, rest, prev.pending.id, bottomId, "top-to-bottom"),
+            pending: null,
+            flashTopId: prev.pending.id,
+            flashBottomId: bottomId
+          };
+        }
+        return {
+          pairs: rest,
+          lineDirections: restDirections,
+          pending: { side: "bottom", id: bottomId },
+          flashTopId: null,
+          flashBottomId: null
+        };
+      }
+      if (prev.pending?.side === "top") {
+        return {
+          pairs: withPair(prev.pairs, prev.pending.id, bottomId),
+          lineDirections: withLineDirection(prev.lineDirections, prev.pairs, prev.pending.id, bottomId, "top-to-bottom"),
+          pending: null,
+          flashTopId: prev.pending.id,
+          flashBottomId: bottomId
+        };
+      }
+      return {
+        ...prev,
+        pending: prev.pending?.side === "bottom" && prev.pending.id === bottomId ? null : { side: "bottom", id: bottomId },
+        flashTopId: null,
+        flashBottomId: null
+      };
+    });
+  }, [validationStatus]);
+  useEffect(() => {
+    if (validationStatus || state.flashTopId === null || state.flashBottomId === null) return;
+    flashTimerRef.current = setTimeout(() => {
+      flashTimerRef.current = null;
+      setState((current) => {
+        if (current.flashTopId === null && current.flashBottomId === null) return current;
+        return { ...current, flashTopId: null, flashBottomId: null };
+      });
+    }, 650);
+    return () => {
+      if (flashTimerRef.current) {
+        clearTimeout(flashTimerRef.current);
+        flashTimerRef.current = null;
+      }
+    };
+  }, [state.flashTopId, state.flashBottomId, validationStatus]);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const isMounted = useRef(false);
+  useEffect(() => {
+    if (!isMounted.current) {
+      isMounted.current = true;
+      return;
+    }
+    const value = Object.entries(state.pairs).map(
+      ([topId, bottomId]) => state.lineDirections[topId] === "bottom-to-top" ? [bottomId, topId] : [topId, bottomId]
+    );
+    onChangeRef.current(widgetId, value);
+  }, [state.pairs, state.lineDirections, widgetId]);
+  const containerRef = useRef(null);
+  const { dotRefs, lines } = usePairLines({
+    containerRef,
+    pairs: state.pairs,
+    lineDirections: state.lineDirections,
+    validationStatus,
+    pairStatusByTopId
+  });
+  const cols = useMemo(
+    () => Math.max(topItems.length, bottomItems.length, 1),
+    [topItems.length, bottomItems.length]
+  );
+  const renderCard = (item, isTop) => {
+    const isRtl = shouldItemsUseRTL(item.content);
+    const pairedTopId = isTop ? item.itemId : findTopForBottom(state.pairs, item.itemId);
+    const pairStatus = pairedTopId ? pairStatusByTopId[pairedTopId] ?? null : null;
+    const status = resolveCardStatus(
+      item.itemId,
+      isTop,
+      state.pairs,
+      state.pending,
+      validationStatus,
+      pairStatus
+    );
+    const isFlashing = isTop ? state.flashTopId === item.itemId : state.flashBottomId === item.itemId;
+    const dotKey = isTop ? `top:${item.itemId}` : `bottom:${item.itemId}`;
+    const dot = /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: buildDotClass(status, isTop ? "south" : "north"),
+        ref: (el) => {
+          if (el) dotRefs.current.set(dotKey, el);
+          else dotRefs.current.delete(dotKey);
+        }
+      }
+    );
+    return /* @__PURE__ */ jsxs("div", { className: "pair-matcher-cell", children: [
+      !isTop && dot,
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          className: `${buildCardClass(status, isFlashing)}${isRtl ? " pair-matcher-card--rtl" : ""}`,
+          dir: isRtl ? "rtl" : void 0,
+          onClick: () => isTop ? handleTopClick(item.itemId) : handleBottomClick(item.itemId),
+          "aria-pressed": status !== "idle",
+          "aria-disabled": validationStatus ? "true" : void 0,
+          children: /* @__PURE__ */ jsx("span", { className: "pair-matcher-card-content", children: item.content.map((li) => renderPairMatcherItemContent(li, widgetsMap)) })
+        }
+      ),
+      isTop && dot
+    ] }, item.id);
+  };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `pair-matcher-widget${validationStatus ? ` pair-matcher-widget--${validationStatus}` : ""}`,
+      style: { "--pm-cols": cols },
+      ref: containerRef,
+      role: "group",
+      "aria-label": "Pair matcher exercise",
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "pair-matcher-row pair-matcher-row--top", children: shuffledTop.map((item) => renderCard(item, true)) }),
+        /* @__PURE__ */ jsx("svg", { className: "pair-matcher-lines", "aria-hidden": "true", children: lines.map((line) => /* @__PURE__ */ jsx(
+          "line",
+          {
+            x1: line.x1,
+            y1: line.y1,
+            x2: line.x2,
+            y2: line.y2,
+            stroke: lineStrokeVar(line.status),
+            strokeWidth: "var(--pm-line-width, 4)",
+            strokeLinecap: "round",
+            pathLength: 1,
+            className: "pair-matcher-line"
+          },
+          line.topId
+        )) }),
+        /* @__PURE__ */ jsx("div", { className: "pair-matcher-row pair-matcher-row--bottom", children: shuffledBottom.map((item) => renderCard(item, false)) })
+      ]
+    }
+  );
+};
+PairMatcherWidget.displayName = "PairMatcherWidget";
 function isInlineInputWidget(widget) {
   return widget.type === "inline-input";
 }
@@ -13806,6 +14605,9 @@ function isFractionWidget(widget) {
 function isMatcherWidget(widget) {
   return widget.type === "matcher";
 }
+function isPairMatcherWidget(widget) {
+  return widget.type === "pair-matcher";
+}
 function isVisualFractionWidget(widget) {
   return widget.type === "visual-fraction";
 }
@@ -13818,6 +14620,7 @@ const WidgetRenderer = ({
   validationStatus = null,
   numValidationStatus = null,
   denValidationStatus = null,
+  validationDetail,
   droppedInputs = /* @__PURE__ */ new Set(),
   widgets,
   onChange,
@@ -13917,6 +14720,20 @@ const WidgetRenderer = ({
       }
     );
   }
+  if (isPairMatcherWidget(widget)) {
+    return /* @__PURE__ */ jsx(
+      PairMatcherWidget,
+      {
+        widgetId,
+        widget,
+        onChange,
+        validationStatus,
+        validationDetail,
+        defaultValue: Array.isArray(value) ? value : void 0,
+        widgets
+      }
+    );
+  }
   if (isVisualFractionWidget(widget)) {
     return /* @__PURE__ */ jsx(
       VisualFraction,
@@ -14673,36 +15490,6 @@ const NumberLineRenderer = ({
     }
   );
 };
-function isArabic(text) {
-  return /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/.test(text);
-}
-function hasLatinChars(text) {
-  return /[A-Za-z]/.test(text);
-}
-function itemContainsArabic(item) {
-  if (item.type === JSON_TYPES.TEXT && "value" in item) {
-    return isArabic(item.value);
-  }
-  if (item.type === JSON_TYPES.HIGHLIGHTED_TEXT && "value" in item) {
-    return isArabic(item.value);
-  }
-  if (item.type === JSON_TYPES.GROUP && "items" in item) {
-    return item.items.some((subItem) => itemContainsArabic(subItem));
-  }
-  return false;
-}
-function itemContainsLatin(item) {
-  if (item.type === JSON_TYPES.TEXT && "value" in item) {
-    return hasLatinChars(item.value);
-  }
-  if (item.type === JSON_TYPES.HIGHLIGHTED_TEXT && "value" in item) {
-    return hasLatinChars(item.value);
-  }
-  if (item.type === JSON_TYPES.GROUP && "items" in item) {
-    return item.items.some((subItem) => itemContainsLatin(subItem));
-  }
-  return false;
-}
 function isTextItem(item) {
   return item.type === JSON_TYPES.TEXT || item.type === JSON_TYPES.HIGHLIGHTED_TEXT || item.type === JSON_TYPES.BOLD_TEXT || item.type === JSON_TYPES.COLOR_TEXT || item.type === JSON_TYPES.OPERATOR || item.type === JSON_TYPES.SPACE || item.type === JSON_TYPES.GROUP;
 }
@@ -14805,9 +15592,10 @@ const LayoutRenderer = ({
     case JSON_TYPES.WIDGET_REF: {
       const widget = widgets[item.widgetId];
       if (!widget) return null;
-      const isCorrect = validationDetails?.[item.widgetId];
+      const validationDetail = validationDetails?.[item.widgetId];
+      const isCorrect = validationDetail?.isCorrect;
       const validationStatus = isCorrect === true ? "correct" : isCorrect === false ? "incorrect" : null;
-      const widgetKey = widget.type === JSON_TYPES.MATCHER || widget.type === JSON_TYPES.VISUAL_FRACTION ? `${item.widgetId}-${resetKey}` : item.widgetId;
+      const widgetKey = STATEFUL_WIDGET_TYPES.has(widget.type) ? `${item.widgetId}-${resetKey}` : item.widgetId;
       return /* @__PURE__ */ jsx(
         WidgetRenderer,
         {
@@ -14817,8 +15605,9 @@ const LayoutRenderer = ({
           values,
           isDropped: droppedInputs.has(item.widgetId),
           validationStatus,
-          numValidationStatus: toValidationStatus(validationDetails?.[`${item.widgetId}__num`]),
-          denValidationStatus: toValidationStatus(validationDetails?.[`${item.widgetId}__den`]),
+          numValidationStatus: toValidationStatus(validationDetails?.[`${item.widgetId}__num`]?.isCorrect),
+          denValidationStatus: toValidationStatus(validationDetails?.[`${item.widgetId}__den`]?.isCorrect),
+          validationDetail,
           droppedInputs,
           widgets,
           onChange,
@@ -14901,7 +15690,7 @@ const DEFAULT_RULER_TOOL = {
 function buildInitialValues(json) {
   const initial = {};
   for (const [id, widget] of Object.entries(json.widgets)) {
-    if (widget.type === JSON_TYPES.MATCHER) initial[id] = [];
+    if (widget.type === JSON_TYPES.MATCHER || widget.type === JSON_TYPES.PAIR_MATCHER) initial[id] = [];
   }
   return initial;
 }
@@ -14920,10 +15709,12 @@ const ExerciseRenderer = forwardRef(({
   useImperativeHandle(ref, () => ({
     submit: () => {
       const result = validate(json, values);
-      const details = {};
-      for (const [id, v] of Object.entries(result.details)) {
-        details[id] = v.isCorrect;
-      }
+      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;
@@ -14931,18 +15722,12 @@ const ExerciseRenderer = forwardRef(({
         if (!answer) continue;
         const [expectedNum, expectedDen] = answer.split("/", 2);
         if (!expectedNum || !expectedDen) continue;
-        if (details[widgetId]) {
-          if (widget.numerator === null) details[`${widgetId}__num`] = true;
-          if (widget.denominator === null) details[`${widgetId}__den`] = true;
+        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) {
-            const u = values[`${widgetId}__num`];
-            details[`${widgetId}__num`] = typeof u === "string" && u !== "" && normalize(u) === normalize(expectedNum);
-          }
-          if (widget.denominator === null) {
-            const u = values[`${widgetId}__den`];
-            details[`${widgetId}__den`] = typeof u === "string" && u !== "" && normalize(u) === normalize(expectedDen);
-          }
+          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);
@@ -15214,6 +15999,8 @@ export {
   MatcherBlockSchema,
   MatcherItemSchema,
   MatcherRowSchema,
+  MatcherWidgetJSONSchema,
+  MixedValidationSchema,
   NumberLineCounterItemSchema,
   NumberLineHighlightItemSchema,
   NumberLineItemSchema,
@@ -15222,6 +16009,8 @@ export {
   NumericKeypadToolSchema,
   OperatorItemSchema,
   OperatorSchema,
+  PairMatcherBlockSchema,
+  PairMatcherWidgetJSONSchema,
   ParseError,
   QuestionTextSchema,
   RadioOptionsJSONSchema,
@@ -15261,8 +16050,10 @@ export {
   createMatcherBlock,
   createMatcherItem,
   createMatcherRow,
+  createMixedValidation,
   createNumericInput,
   createNumericKeypad,
+  createPairMatcherBlock,
   createSimpleValidation,
   createSpace,
   createStringInput,
@@ -15295,9 +16086,13 @@ export {
   isMatcherBlock,
   isMatcherItem,
   isMatcherRow,
+  isMatcherWidget,
+  isMixedValidation,
   isNumericKeypad,
   isNumericKeypadJSON,
   isOperatorItem,
+  isPairMatcherBlock,
+  isPairMatcherWidget,
   isQuestionText,
   isRadioOptionsJSON,
   isSimpleValidation,
@@ -15327,6 +16122,7 @@ export {
   validateExerciseJSONSafe,
   validateExpression,
   validateInputFormats,
+  validateMixed,
   validateSimple,
   validateVisualFractionCapacity,
   validateWidgetJSON,