@mathscan/math-exercise-engine 1.1.17 → 1.2.1

package/dist/index.d.ts

@@ -875,7 +875,7 @@ export declare function compileWithAST(dsl: string): {
             type: "PairMatcherBlock";
             name: string;
             answers: [string, string][];
-            topItems: {
+            groups: [{
                 type: "MatcherItem";
                 inlines: ({
                     value: string;
@@ -923,8 +923,7 @@ export declare function compileWithAST(dsl: string): {
                     size?: number | undefined;
                 })[];
                 itemId: string;
-            }[];
-            bottomItems: {
+            }[], {
                 type: "MatcherItem";
                 inlines: ({
                     value: string;
@@ -972,7 +971,8 @@ export declare function compileWithAST(dsl: string): {
                     size?: number | undefined;
                 })[];
                 itemId: string;
-            }[];
+            }[]];
+            layout?: "rows" | "columns" | undefined;
         })[];
         validation?: {
             type: "SimpleValidation";
@@ -1007,8 +1007,8 @@ export declare function compileWithAST(dsl: string): {
         })[] | undefined;
     };
     json: {
-        version: "2.0";
         layout: any[];
+        version: "2.0";
         widgets: Record<string, {
             length: number;
             type: "inline-input";
@@ -1055,18 +1055,18 @@ export declare function compileWithAST(dsl: string): {
             colors?: string[] | undefined;
         } | {
             type: "pair-matcher";
-            topItems: {
+            groups: [{
                 type: "matcher-item";
                 itemId: string;
                 id: string;
                 content: any[];
-            }[];
-            bottomItems: {
+            }[], {
                 type: "matcher-item";
                 itemId: string;
                 id: string;
                 content: any[];
-            }[];
+            }[]];
+            layout?: "rows" | "columns" | undefined;
         } | {
             type: "visual-fraction";
             shape: "bar" | "circle" | "triangle" | "grid";
@@ -5268,7 +5268,8 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
 }>, z.ZodEffects<z.ZodObject<{
     type: z.ZodLiteral<"PairMatcherBlock">;
     name: z.ZodString;
-    topItems: z.ZodArray<z.ZodObject<{
+    layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+    groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"MatcherItem">;
         itemId: z.ZodString;
         inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -5556,8 +5557,7 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }>, "many">;
-    bottomItems: z.ZodArray<z.ZodObject<{
+    }>, "many">, z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"MatcherItem">;
         itemId: z.ZodString;
         inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -5845,13 +5845,13 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }>, "many">;
+    }>, "many">], null>;
     answers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -5899,8 +5899,7 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -5948,12 +5947,13 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6001,8 +6001,7 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6050,12 +6049,13 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6103,8 +6103,7 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6152,12 +6151,13 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6205,8 +6205,7 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -6254,7 +6253,8 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"VerticalOperationBlock">;
     op: z.ZodOptional<z.ZodEnum<["+", "-", "×", "÷", "="]>>;
@@ -6883,7 +6883,7 @@ export declare function createNumericInput(name: string, digits: number, answer?
  */
 export declare function createNumericKeypad(includeOperators?: boolean, includeDecimal?: boolean, style?: 'diamond' | 'classic'): NumericKeypadTool;
 
-export declare function createPairMatcherBlock(name: string, topItems: MatcherItem[], bottomItems: MatcherItem[], answers: [string, string][]): PairMatcherBlock;
+export declare function createPairMatcherBlock(name: string, groups: [MatcherItem[], MatcherItem[]], answers: [string, string][], layout?: 'rows' | 'columns'): PairMatcherBlock;
 
 export declare function createProtractorTool(size?: number): ProtractorTool;
 
@@ -11383,7 +11383,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
     }>, z.ZodEffects<z.ZodObject<{
         type: z.ZodLiteral<"PairMatcherBlock">;
         name: z.ZodString;
-        topItems: z.ZodArray<z.ZodObject<{
+        layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+        groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"MatcherItem">;
             itemId: z.ZodString;
             inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -11671,8 +11672,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }>, "many">;
-        bottomItems: z.ZodArray<z.ZodObject<{
+        }>, "many">, z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"MatcherItem">;
             itemId: z.ZodString;
             inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -11960,13 +11960,13 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }>, "many">;
+        }>, "many">], null>;
         answers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
     }, "strip", z.ZodTypeAny, {
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12014,8 +12014,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12063,12 +12062,13 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }, {
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12116,8 +12116,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12165,12 +12164,13 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }>, {
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12218,8 +12218,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12267,12 +12266,13 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }, {
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12320,8 +12320,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -12369,7 +12368,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"VerticalOperationBlock">;
         op: z.ZodOptional<z.ZodEnum<["+", "-", "×", "÷", "="]>>;
@@ -13483,7 +13483,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -13531,8 +13531,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -13580,7 +13579,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     })[];
     validation?: {
         type: "SimpleValidation";
@@ -14131,7 +14131,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -14179,8 +14179,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -14228,7 +14227,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     })[];
     validation?: {
         type: "SimpleValidation";
@@ -14779,7 +14779,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -14827,8 +14827,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -14876,7 +14875,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     })[];
     validation?: {
         type: "SimpleValidation";
@@ -15427,7 +15427,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         type: "PairMatcherBlock";
         name: string;
         answers: [string, string][];
-        topItems: {
+        groups: [{
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -15475,8 +15475,7 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
-        bottomItems: {
+        }[], {
             type: "MatcherItem";
             inlines: ({
                 value: string;
@@ -15524,7 +15523,8 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 size?: number | undefined;
             })[];
             itemId: string;
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     })[];
     validation?: {
         type: "SimpleValidation";
@@ -15731,7 +15731,9 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         colors?: string[] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"pair-matcher">;
-        topItems: z.ZodArray<z.ZodObject<{
+        /** Row layout (top/bottom, default) or column layout (left/right). */
+        layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+        groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             type: z.ZodLiteral<"matcher-item">;
             /** Item identifier (no pipe allowed) */
@@ -15748,8 +15750,7 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
             itemId: string;
             id: string;
             content: any[];
-        }>, "many">;
-        bottomItems: z.ZodArray<z.ZodObject<{
+        }>, "many">, z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             type: z.ZodLiteral<"matcher-item">;
             /** Item identifier (no pipe allowed) */
@@ -15766,35 +15767,35 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
             itemId: string;
             id: string;
             content: any[];
-        }>, "many">;
+        }>, "many">], null>;
     }, "strip", z.ZodTypeAny, {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }, {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     }>, z.ZodEffects<z.ZodObject<{
         type: z.ZodLiteral<"visual-fraction">;
         shape: z.ZodDefault<z.ZodEnum<["bar", "circle", "triangle", "grid"]>>;
@@ -15946,8 +15947,8 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         difficulty?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    version: "2.0";
     layout: any[];
+    version: "2.0";
     widgets: Record<string, {
         length: number;
         type: "inline-input";
@@ -15994,18 +15995,18 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         colors?: string[] | undefined;
     } | {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     } | {
         type: "visual-fraction";
         shape: "bar" | "circle" | "triangle" | "grid";
@@ -16047,8 +16048,8 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         difficulty?: number | undefined;
     } | undefined;
 }, {
-    version: "2.0";
     layout: any[];
+    version: "2.0";
     widgets: Record<string, {
         length: number;
         type: "inline-input";
@@ -16095,18 +16096,18 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         colors?: string[] | undefined;
     } | {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     } | {
         type: "visual-fraction";
         answer: number[];
@@ -16149,6 +16150,20 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
     } | undefined;
 }>;
 
+/**
+ * Broadcasts the exercise lock to every widget.
+ *
+ * A context (rather than a prop threaded through LayoutRenderer → WidgetRenderer)
+ * because interactive elements sit 3–4 levels deep (number-line arcs, matcher
+ * cards, DnD chips rendered into a body portal).
+ */
+export declare const ExerciseLockProvider: default_2.FC<ExerciseLockProviderProps>;
+
+export declare interface ExerciseLockProviderProps {
+    locked: boolean;
+    children: default_2.ReactNode;
+}
+
 export declare type ExerciseMeta = z.infer<typeof ExerciseMetaSchema>;
 
 export declare const ExerciseMetaSchema: z.ZodObject<{
@@ -23223,8 +23238,10 @@ export declare type PairMatcherBlock = z.infer<typeof PairMatcherBlockSchema>;
 export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
     type: z.ZodLiteral<"PairMatcherBlock">;
     name: z.ZodString;
-    /** Items in the top row — at least one required */
-    topItems: z.ZodArray<z.ZodObject<{
+    /** Row layout (top/bottom, default) or column layout (left/right). */
+    layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+    /** Exactly two groups, in declaration order — neither more nor fewer. */
+    groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"MatcherItem">;
         itemId: z.ZodString;
         inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -23512,9 +23529,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }>, "many">;
-    /** Items in the bottom row — at least one required */
-    bottomItems: z.ZodArray<z.ZodObject<{
+    }>, "many">, z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"MatcherItem">;
         itemId: z.ZodString;
         inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -23802,9 +23817,9 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }>, "many">;
+    }>, "many">], null>;
     /**
-     * Each answer pair is [topId, bottomId].
+     * Each answer pair is [groups[0] id, groups[1] id].
      * At least one pair is required.
      */
     answers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
@@ -23812,7 +23827,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -23860,8 +23875,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -23909,12 +23923,13 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -23962,8 +23977,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -24011,12 +24025,13 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -24064,8 +24079,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -24113,12 +24127,13 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "PairMatcherBlock";
     name: string;
     answers: [string, string][];
-    topItems: {
+    groups: [{
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -24166,8 +24181,7 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
-    bottomItems: {
+    }[], {
         type: "MatcherItem";
         inlines: ({
             value: string;
@@ -24215,18 +24229,23 @@ export declare const PairMatcherBlockSchema: z.ZodEffects<z.ZodObject<{
             size?: number | undefined;
         })[];
         itemId: string;
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>;
 
 export declare type PairMatcherWidgetJSON = z.infer<typeof PairMatcherWidgetJSONSchema>;
 
 /**
- * Pair-Matcher widget — top row ↔ bottom row pairing.
- * topItems / bottomItems carry IDs for React keys.
+ * Pair-Matcher widget — two-group item pairing.
+ * `groups` is a fixed 2-tuple, in declaration order; items carry IDs for
+ * React keys. Neither group has a spatial meaning — `layout` decides whether
+ * they render as rows or columns.
  */
 export declare const PairMatcherWidgetJSONSchema: z.ZodObject<{
     type: z.ZodLiteral<"pair-matcher">;
-    topItems: z.ZodArray<z.ZodObject<{
+    /** Row layout (top/bottom, default) or column layout (left/right). */
+    layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+    groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"matcher-item">;
         /** Item identifier (no pipe allowed) */
@@ -24243,8 +24262,7 @@ export declare const PairMatcherWidgetJSONSchema: z.ZodObject<{
         itemId: string;
         id: string;
         content: any[];
-    }>, "many">;
-    bottomItems: z.ZodArray<z.ZodObject<{
+    }>, "many">, z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"matcher-item">;
         /** Item identifier (no pipe allowed) */
@@ -24261,35 +24279,35 @@ export declare const PairMatcherWidgetJSONSchema: z.ZodObject<{
         itemId: string;
         id: string;
         content: any[];
-    }>, "many">;
+    }>, "many">], null>;
 }, "strip", z.ZodTypeAny, {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>;
 
 /**
@@ -26727,6 +26745,9 @@ export declare class TransformError extends EngineError {
     constructor(message: string, position?: SourcePosition);
 }
 
+/** true once the exercise was checked/revealed — widgets must refuse input until reset(). */
+export declare const useExerciseLocked: () => boolean;
+
 /** User answers keyed by widget ID. */
 export declare type UserAnswers = Record<string, UserAnswerValue>;
 
@@ -26791,8 +26812,8 @@ declare type ValidatedExerciseJSON = ExerciseJSON & {
  * ```
  */
 export declare function validateExerciseJSON(data: unknown): {
-    version: "2.0";
     layout: any[];
+    version: "2.0";
     widgets: Record<string, {
         length: number;
         type: "inline-input";
@@ -26839,18 +26860,18 @@ export declare function validateExerciseJSON(data: unknown): {
         colors?: string[] | undefined;
     } | {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     } | {
         type: "visual-fraction";
         shape: "bar" | "circle" | "triangle" | "grid";
@@ -26910,8 +26931,8 @@ export declare function validateExerciseJSON(data: unknown): {
  * ```
  */
 export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseReturnType<{
-    version: "2.0";
     layout: any[];
+    version: "2.0";
     widgets: Record<string, {
         length: number;
         type: "inline-input";
@@ -26958,18 +26979,18 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         colors?: string[] | undefined;
     } | {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     } | {
         type: "visual-fraction";
         answer: number[];
@@ -27011,8 +27032,8 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         difficulty?: number | undefined;
     } | undefined;
 }, {
-    version: "2.0";
     layout: any[];
+    version: "2.0";
     widgets: Record<string, {
         length: number;
         type: "inline-input";
@@ -27059,18 +27080,18 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         colors?: string[] | undefined;
     } | {
         type: "pair-matcher";
-        topItems: {
+        groups: [{
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
-        bottomItems: {
+        }[], {
             type: "matcher-item";
             itemId: string;
             id: string;
             content: any[];
-        }[];
+        }[]];
+        layout?: "rows" | "columns" | undefined;
     } | {
         type: "visual-fraction";
         shape: "bar" | "circle" | "triangle" | "grid";
@@ -27210,18 +27231,18 @@ export declare function validateWidgetJSON(data: unknown): {
     colors?: string[] | undefined;
 } | {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 } | {
     type: "visual-fraction";
     shape: "bar" | "circle" | "triangle" | "grid";
@@ -27302,18 +27323,18 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     colors?: string[] | undefined;
 } | {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 } | {
     type: "visual-fraction";
     answer: number[];
@@ -27386,18 +27407,18 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     colors?: string[] | undefined;
 } | {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 } | {
     type: "visual-fraction";
     shape: "bar" | "circle" | "triangle" | "grid";
@@ -30337,7 +30358,9 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
     colors?: string[] | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"pair-matcher">;
-    topItems: z.ZodArray<z.ZodObject<{
+    /** Row layout (top/bottom, default) or column layout (left/right). */
+    layout: z.ZodOptional<z.ZodEnum<["rows", "columns"]>>;
+    groups: z.ZodTuple<[z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"matcher-item">;
         /** Item identifier (no pipe allowed) */
@@ -30354,8 +30377,7 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
         itemId: string;
         id: string;
         content: any[];
-    }>, "many">;
-    bottomItems: z.ZodArray<z.ZodObject<{
+    }>, "many">, z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"matcher-item">;
         /** Item identifier (no pipe allowed) */
@@ -30372,35 +30394,35 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
         itemId: string;
         id: string;
         content: any[];
-    }>, "many">;
+    }>, "many">], null>;
 }, "strip", z.ZodTypeAny, {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }, {
     type: "pair-matcher";
-    topItems: {
+    groups: [{
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
-    bottomItems: {
+    }[], {
         type: "matcher-item";
         itemId: string;
         id: string;
         content: any[];
-    }[];
+    }[]];
+    layout?: "rows" | "columns" | undefined;
 }>, z.ZodEffects<z.ZodObject<{
     type: z.ZodLiteral<"visual-fraction">;
     shape: z.ZodDefault<z.ZodEnum<["bar", "circle", "triangle", "grid"]>>;