@mathscan/math-exercise-engine 1.0.13 → 1.0.14

package/dist/index.d.ts

@@ -45,6 +45,12 @@ export declare const AST_TYPES: {
     readonly NUMBER_LINE_COUNTER: "NumberLineCounter";
     /** A highlighted range on the number line axis */
     readonly NUMBER_LINE_HIGHLIGHT: "NumberLineHighlight";
+    /** Matcher layout block */
+    readonly MATCHER_BLOCK: "MatcherBlock";
+    /** Row within a matcher */
+    readonly MATCHER_ROW: "MatcherRow";
+    /** Item within a matcher row */
+    readonly MATCHER_ITEM: "MatcherItem";
     /** Drag-and-drop options tool */
     readonly DRAG_OPTIONS: "DragOptions";
     /** Radio button options tool */
@@ -355,6 +361,44 @@ export declare function compileWithAST(dsl: string): {
             options: string[];
             name: string;
             answer: string;
+        } | {
+            type: "MatcherBlock";
+            name: string;
+            rows: {
+                type: "MatcherRow";
+                items: {
+                    type: "MatcherItem";
+                    inlines: ({
+                        value: string;
+                        type: "FreeText";
+                    } | {
+                        type: "Space";
+                    } | {
+                        value: string;
+                        type: "HighlightedText";
+                        highlight?: [number, number] | undefined;
+                    } | {
+                        value: string;
+                        type: "ColorText";
+                        color: string;
+                        highlight?: [number, number] | undefined;
+                    } | {
+                        value: string;
+                        type: "BoldText";
+                        highlight?: [number, number] | undefined;
+                    } | {
+                        type: "Fraction";
+                        name: string;
+                        simplified: boolean;
+                        answer?: string | undefined;
+                        numerator?: number | undefined;
+                        denominator?: number | undefined;
+                    })[];
+                    itemId: string;
+                }[];
+            }[];
+            answers: string[][];
+            colors?: string[] | undefined;
         })[];
         question?: {
             value: string;
@@ -401,11 +445,25 @@ export declare function compileWithAST(dsl: string): {
             numerator: number | null;
             denominator: number | null;
             simplified: boolean;
+        } | {
+            type: "matcher";
+            rows: {
+                type: "matcher-row";
+                items: {
+                    type: "matcher-item";
+                    itemId: string;
+                    id: string;
+                    content: any[];
+                }[];
+                id: string;
+            }[];
+            groupCount: number;
+            colors?: string[] | undefined;
         }>;
         validation?: {
             mode: "simple" | "expression";
             expression?: string | undefined;
-            answers?: Record<string, string | number> | undefined;
+            answers?: Record<string, string | number | string[][]> | undefined;
             variables?: string[] | undefined;
         } | undefined;
         id?: string | undefined;
@@ -1669,343 +1727,818 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
         color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
         label?: string | undefined;
     }[] | undefined;
-}>]>;
-
-/**
- * Create a bold text inline element
- */
-export declare function createBoldText(value: string, highlight?: [number, number]): BoldTextInline;
-
-/**
- * Create a color text inline element
- */
-export declare function createColorText(value: string, color: string, highlight?: [number, number]): ColorTextInline;
-
-/**
- * Create a drag options tool
- */
-export declare function createDragOptions(options: string[]): DragOptionsTool;
-
-/**
- * Create an exercise document
- */
-export declare function createExerciseDocument(question: z.infer<typeof TextBlockSchema> | undefined, lines: ContentBlock[], validation?: z.infer<typeof ValidationNodeSchema>, tools?: z.infer<typeof ToolNodeSchema>[]): ExerciseDocument;
-
-/**
- * Create an expression validation node
- */
-export declare function createExpressionValidation(expression: string): ExpressionValidation;
-
-/**
- * Create a fraction inline widget
- */
-export declare function createFraction(name: string, options?: {
-    numerator?: number;
-    denominator?: number;
-    answer?: string;
-    simplified?: boolean;
-}): FractionInline;
-
-/**
- * Create a free text inline element
- */
-export declare function createFreeText(value: string): FreeTextInline;
-
-/**
- * Create a highlighted text inline element
- */
-export declare function createHighlightedText(value: string, highlight?: [number, number]): HighlightedTextInline;
-
-/**
- * Create a line block
- */
-export declare function createLineBlock(inlines: InlineNode[]): LineBlock;
-
-/**
- * Create a numeric inline input widget (W_N_I)
- */
-export declare function createNumericInput(name: string, digits: number, answer?: string | number): InlineInputWidget;
-
-/**
- * Create a numeric keypad tool
- */
-export declare function createNumericKeypad(includeOperators?: boolean, includeDecimal?: boolean): NumericKeypadTool;
-
-/**
- * Create a simple validation node
- */
-export declare function createSimpleValidation(): SimpleValidation;
-
-/**
- * Create a space inline element
- */
-export declare function createSpace(): SpaceInline;
-
-/**
- * Create a string inline input widget (W_S_I)
- */
-export declare function createStringInput(name: string, length: number, answer?: string | number): InlineInputWidget;
-
-/**
- * Create a text block (question)
- */
-export declare function createTextBlock(value: string): TextBlock;
-
-export declare type DragOptionsJSON = z.infer<typeof DragOptionsJSONSchema>;
-
-export declare const DragOptionsJSONSchema: z.ZodObject<{
-    type: z.ZodLiteral<"drag-options">;
-    options: z.ZodArray<z.ZodString, "many">;
-}, "strip", z.ZodTypeAny, {
-    type: "drag-options";
-    options: string[];
-}, {
-    type: "drag-options";
-    options: string[];
-}>;
-
-export declare type DragOptionsTool = z.infer<typeof DragOptionsToolSchema>;
-
-/**
- * Drag options tool schema - draggable buttons/options
- *
- * Common use cases:
- * - Comparison symbols: ["<", ">", "="]
- * - Yes/No: ["نعم", "لا"]
- * - Multiple choice: ["A", "B", "C", "D"]
- *
- * @example
- * {
- *   type: "DragOptions",
- *   options: ["<", ">", "="]
- * }
- */
-export declare const DragOptionsToolSchema: z.ZodObject<{
-    type: z.ZodLiteral<"DragOptions">;
-    options: z.ZodArray<z.ZodString, "many">;
-}, "strip", z.ZodTypeAny, {
-    type: "DragOptions";
-    options: string[];
-}, {
-    type: "DragOptions";
-    options: string[];
-}>;
-
-/**
- * Base error class for all engine errors
- */
-export declare class EngineError extends Error {
-    constructor(message: string);
-}
-
-/**
- * Evaluate a mathematical expression with the given variable scope
- *
- * @param expression - The expression to evaluate (e.g., "(a * b) + (c * d) == 1200")
- * @param scope - Variable bindings (e.g., { a: 10, b: 5, c: 20, d: 30 })
- * @returns The boolean result of the expression
- * @throws Error if evaluation fails
- */
-export declare function evaluate(expression: string, scope: Record<string, number>): boolean;
-
-export declare type ExerciseDocument = z.infer<typeof ExerciseDocumentSchema>;
-
-/**
- * Exercise document schema - the complete exercise structure
- *
- * Structure:
- * 1. Question: What the student should do
- * 2. Lines: Visual rows with inline elements
- * 3. Tools: Standalone interactive elements (optional)
- * 4. Validation: How to check answers
- *
- * @example
- * {
- *   type: "ExerciseDocument",
- *   question: {
- *     type: "TextBlock",
- *     value: "أقارن كل عددين باستعمال الرمر المناسب"
- *   },
- *   lines: [
- *     {
- *       type: "LineBlock",
- *       inlines: [
- *         { type: "HighlightedText", value: "151 000", highlight: [0, 3] },
- *         { type: "InlineInput", name: "x", length: 1 },
- *         { type: "HighlightedText", value: "54 000", highlight: [0, 3] }
- *       ]
- *     }
- *   ],
- *   tools: [
- *     { type: "DragOptions", options: ["<", ">", "="] }
- *   ],
- *   validation: {
- *     type: "SimpleValidation"
- *   }
- * }
- */
-export declare const ExerciseDocumentSchema: z.ZodObject<{
-    type: z.ZodLiteral<"ExerciseDocument">;
-    question: z.ZodOptional<z.ZodObject<{
-        type: z.ZodLiteral<"TextBlock">;
-        value: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        value: string;
-        type: "TextBlock";
-    }, {
-        value: string;
-        type: "TextBlock";
-    }>>;
-    lines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
-        type: z.ZodLiteral<"LineBlock">;
-        inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
-            type: z.ZodLiteral<"FreeText">;
-            value: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            value: string;
-            type: "FreeText";
-        }, {
-            value: string;
-            type: "FreeText";
-        }>, z.ZodObject<{
-            type: z.ZodLiteral<"Space">;
-        }, "strip", z.ZodTypeAny, {
-            type: "Space";
-        }, {
-            type: "Space";
-        }>, z.ZodObject<{
-            type: z.ZodLiteral<"HighlightedText">;
-            value: z.ZodString;
-            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-        }, "strip", z.ZodTypeAny, {
-            value: string;
-            type: "HighlightedText";
-            highlight?: [number, number] | undefined;
-        }, {
-            value: string;
-            type: "HighlightedText";
-            highlight?: [number, number] | undefined;
-        }>, z.ZodObject<{
-            type: z.ZodLiteral<"ColorText">;
-            value: z.ZodString;
-            color: z.ZodString;
-            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-        }, "strip", z.ZodTypeAny, {
-            value: string;
-            type: "ColorText";
-            color: string;
-            highlight?: [number, number] | undefined;
-        }, {
-            value: string;
-            type: "ColorText";
-            color: string;
-            highlight?: [number, number] | undefined;
-        }>, z.ZodObject<{
-            type: z.ZodLiteral<"BoldText">;
-            value: z.ZodString;
-            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-        }, "strip", z.ZodTypeAny, {
-            value: string;
-            type: "BoldText";
-            highlight?: [number, number] | undefined;
-        }, {
-            value: string;
-            type: "BoldText";
-            highlight?: [number, number] | undefined;
-        }>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
-            type: z.ZodLiteral<"InlineInput">;
-            name: z.ZodString;
-            inputType: z.ZodLiteral<"string">;
-            length: z.ZodNumber;
-            answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-        }, "strip", z.ZodTypeAny, {
-            length: number;
-            type: "InlineInput";
-            inputType: "string";
-            name: string;
-            answer?: string | number | undefined;
-        }, {
-            length: number;
-            type: "InlineInput";
-            inputType: "string";
-            name: string;
-            answer?: string | number | undefined;
-        }>, z.ZodObject<{
-            type: z.ZodLiteral<"InlineInput">;
-            name: z.ZodString;
-            inputType: z.ZodLiteral<"numeric">;
-            digits: z.ZodNumber;
-            answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-        }, "strip", z.ZodTypeAny, {
-            type: "InlineInput";
-            inputType: "numeric";
-            name: string;
-            digits: number;
-            answer?: string | number | undefined;
-        }, {
-            type: "InlineInput";
-            inputType: "numeric";
-            name: string;
-            digits: number;
-            answer?: string | number | undefined;
-        }>]>, z.ZodObject<{
-            type: z.ZodLiteral<"Fraction">;
-            name: z.ZodString;
-            numerator: z.ZodOptional<z.ZodNumber>;
-            denominator: z.ZodOptional<z.ZodNumber>;
-            answer: z.ZodOptional<z.ZodString>;
-            simplified: z.ZodDefault<z.ZodBoolean>;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"MatcherBlock">;
+    name: z.ZodString;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    rows: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"MatcherRow">;
+        items: z.ZodArray<z.ZodObject<{
+            type: z.ZodLiteral<"MatcherItem">;
+            itemId: z.ZodString;
+            inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"FreeText">;
+                value: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "FreeText";
+            }, {
+                value: string;
+                type: "FreeText";
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"Space">;
+            }, "strip", z.ZodTypeAny, {
+                type: "Space";
+            }, {
+                type: "Space";
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"HighlightedText">;
+                value: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"ColorText">;
+                value: z.ZodString;
+                color: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"BoldText">;
+                value: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            }>, z.ZodEffects<z.ZodObject<{
+                type: z.ZodLiteral<"Fraction">;
+                name: z.ZodString;
+                numerator: z.ZodOptional<z.ZodNumber>;
+                denominator: z.ZodOptional<z.ZodNumber>;
+                answer: z.ZodOptional<z.ZodString>;
+                simplified: z.ZodDefault<z.ZodBoolean>;
+            }, "strip", z.ZodTypeAny, {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            }, {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            }>, {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            }, {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            }>]>, "many">;
         }, "strip", z.ZodTypeAny, {
-            type: "Fraction";
-            name: string;
-            simplified: boolean;
-            answer?: string | undefined;
-            numerator?: number | undefined;
-            denominator?: number | undefined;
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
         }, {
-            type: "Fraction";
-            name: string;
-            answer?: string | undefined;
-            numerator?: number | undefined;
-            denominator?: number | undefined;
-            simplified?: boolean | undefined;
-        }>]>, "many">;
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        type: "LineBlock";
-        inlines: ({
-            value: string;
-            type: "FreeText";
-        } | {
-            type: "Space";
-        } | {
-            value: string;
-            type: "HighlightedText";
-            highlight?: [number, number] | undefined;
-        } | {
-            value: string;
-            type: "ColorText";
-            color: string;
-            highlight?: [number, number] | undefined;
-        } | {
-            value: string;
-            type: "BoldText";
-            highlight?: [number, number] | undefined;
-        } | {
-            length: number;
-            type: "InlineInput";
-            inputType: "string";
-            name: string;
-            answer?: string | number | undefined;
-        } | {
-            type: "InlineInput";
-            inputType: "numeric";
-            name: string;
-            digits: number;
-            answer?: string | number | undefined;
-        } | {
-            type: "Fraction";
-            name: string;
-            simplified: boolean;
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }, {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }>, "many">;
+    answers: z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "MatcherBlock";
+    name: string;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}, {
+    type: "MatcherBlock";
+    name: string;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}>, {
+    type: "MatcherBlock";
+    name: string;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}, {
+    type: "MatcherBlock";
+    name: string;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}>]>;
+
+/**
+ * Create a bold text inline element
+ */
+export declare function createBoldText(value: string, highlight?: [number, number]): BoldTextInline;
+
+/**
+ * Create a color text inline element
+ */
+export declare function createColorText(value: string, color: string, highlight?: [number, number]): ColorTextInline;
+
+/**
+ * Create a drag options tool
+ */
+export declare function createDragOptions(options: string[]): DragOptionsTool;
+
+/**
+ * Create an exercise document
+ */
+export declare function createExerciseDocument(question: z.infer<typeof TextBlockSchema> | undefined, lines: ContentBlock[], validation?: z.infer<typeof ValidationNodeSchema>, tools?: z.infer<typeof ToolNodeSchema>[]): ExerciseDocument;
+
+/**
+ * Create an expression validation node
+ */
+export declare function createExpressionValidation(expression: string): ExpressionValidation;
+
+/**
+ * Create a fraction inline widget
+ */
+export declare function createFraction(name: string, options?: {
+    numerator?: number;
+    denominator?: number;
+    answer?: string;
+    simplified?: boolean;
+}): FractionInline;
+
+/**
+ * Create a free text inline element
+ */
+export declare function createFreeText(value: string): FreeTextInline;
+
+/**
+ * Create a highlighted text inline element
+ */
+export declare function createHighlightedText(value: string, highlight?: [number, number]): HighlightedTextInline;
+
+/**
+ * Create a line block
+ */
+export declare function createLineBlock(inlines: InlineNode[]): LineBlock;
+
+export declare function createMatcherBlock(name: string, rows: MatcherRow[], answers: string[][], colors?: string[]): MatcherBlock;
+
+export declare function createMatcherItem(itemId: string, inlines: DisplayInlineNode[]): MatcherItem;
+
+export declare function createMatcherRow(items: MatcherItem[]): MatcherRow;
+
+/**
+ * Create a numeric inline input widget (W_N_I)
+ */
+export declare function createNumericInput(name: string, digits: number, answer?: string | number): InlineInputWidget;
+
+/**
+ * Create a numeric keypad tool
+ */
+export declare function createNumericKeypad(includeOperators?: boolean, includeDecimal?: boolean): NumericKeypadTool;
+
+/**
+ * Create a simple validation node
+ */
+export declare function createSimpleValidation(): SimpleValidation;
+
+/**
+ * Create a space inline element
+ */
+export declare function createSpace(): SpaceInline;
+
+/**
+ * Create a string inline input widget (W_S_I)
+ */
+export declare function createStringInput(name: string, length: number, answer?: string | number): InlineInputWidget;
+
+/**
+ * Create a text block (question)
+ */
+export declare function createTextBlock(value: string): TextBlock;
+
+export declare type DisplayInlineNode = z.infer<typeof DisplayInlineNodeSchema>;
+
+export declare const DisplayInlineNodeSchema: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"FreeText">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "FreeText";
+}, {
+    value: string;
+    type: "FreeText";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"Space">;
+}, "strip", z.ZodTypeAny, {
+    type: "Space";
+}, {
+    type: "Space";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"HighlightedText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ColorText">;
+    value: z.ZodString;
+    color: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "ColorText";
+    color: string;
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "ColorText";
+    color: string;
+    highlight?: [number, number] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"BoldText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "BoldText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "BoldText";
+    highlight?: [number, number] | undefined;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"Fraction">;
+    name: z.ZodString;
+    numerator: z.ZodOptional<z.ZodNumber>;
+    denominator: z.ZodOptional<z.ZodNumber>;
+    answer: z.ZodOptional<z.ZodString>;
+    simplified: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "Fraction";
+    name: string;
+    simplified: boolean;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+}, {
+    type: "Fraction";
+    name: string;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+    simplified?: boolean | undefined;
+}>, {
+    type: "Fraction";
+    name: string;
+    simplified: boolean;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+}, {
+    type: "Fraction";
+    name: string;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+    simplified?: boolean | undefined;
+}>]>;
+
+export declare type DragOptionsJSON = z.infer<typeof DragOptionsJSONSchema>;
+
+export declare const DragOptionsJSONSchema: z.ZodObject<{
+    type: z.ZodLiteral<"drag-options">;
+    options: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "drag-options";
+    options: string[];
+}, {
+    type: "drag-options";
+    options: string[];
+}>;
+
+export declare type DragOptionsTool = z.infer<typeof DragOptionsToolSchema>;
+
+/**
+ * Drag options tool schema - draggable buttons/options
+ *
+ * Common use cases:
+ * - Comparison symbols: ["<", ">", "="]
+ * - Yes/No: ["نعم", "لا"]
+ * - Multiple choice: ["A", "B", "C", "D"]
+ *
+ * @example
+ * {
+ *   type: "DragOptions",
+ *   options: ["<", ">", "="]
+ * }
+ */
+export declare const DragOptionsToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"DragOptions">;
+    options: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "DragOptions";
+    options: string[];
+}, {
+    type: "DragOptions";
+    options: string[];
+}>;
+
+/**
+ * Base error class for all engine errors
+ */
+export declare class EngineError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Evaluate a mathematical expression with the given variable scope
+ *
+ * @param expression - The expression to evaluate (e.g., "(a * b) + (c * d) == 1200")
+ * @param scope - Variable bindings (e.g., { a: 10, b: 5, c: 20, d: 30 })
+ * @returns The boolean result of the expression
+ * @throws Error if evaluation fails
+ */
+export declare function evaluate(expression: string, scope: Record<string, number>): boolean;
+
+export declare type ExerciseDocument = z.infer<typeof ExerciseDocumentSchema>;
+
+/**
+ * Exercise document schema - the complete exercise structure
+ *
+ * Structure:
+ * 1. Question: What the student should do
+ * 2. Lines: Visual rows with inline elements
+ * 3. Tools: Standalone interactive elements (optional)
+ * 4. Validation: How to check answers
+ *
+ * @example
+ * {
+ *   type: "ExerciseDocument",
+ *   question: {
+ *     type: "TextBlock",
+ *     value: "أقارن كل عددين باستعمال الرمر المناسب"
+ *   },
+ *   lines: [
+ *     {
+ *       type: "LineBlock",
+ *       inlines: [
+ *         { type: "HighlightedText", value: "151 000", highlight: [0, 3] },
+ *         { type: "InlineInput", name: "x", length: 1 },
+ *         { type: "HighlightedText", value: "54 000", highlight: [0, 3] }
+ *       ]
+ *     }
+ *   ],
+ *   tools: [
+ *     { type: "DragOptions", options: ["<", ">", "="] }
+ *   ],
+ *   validation: {
+ *     type: "SimpleValidation"
+ *   }
+ * }
+ */
+export declare const ExerciseDocumentSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ExerciseDocument">;
+    question: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"TextBlock">;
+        value: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "TextBlock";
+    }, {
+        value: string;
+        type: "TextBlock";
+    }>>;
+    lines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"LineBlock">;
+        inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"FreeText">;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "FreeText";
+        }, {
+            value: string;
+            type: "FreeText";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"Space">;
+        }, "strip", z.ZodTypeAny, {
+            type: "Space";
+        }, {
+            type: "Space";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"HighlightedText">;
+            value: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"ColorText">;
+            value: z.ZodString;
+            color: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"BoldText">;
+            value: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        }>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
+            type: z.ZodLiteral<"InlineInput">;
+            name: z.ZodString;
+            inputType: z.ZodLiteral<"string">;
+            length: z.ZodNumber;
+            answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+        }, "strip", z.ZodTypeAny, {
+            length: number;
+            type: "InlineInput";
+            inputType: "string";
+            name: string;
+            answer?: string | number | undefined;
+        }, {
+            length: number;
+            type: "InlineInput";
+            inputType: "string";
+            name: string;
+            answer?: string | number | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"InlineInput">;
+            name: z.ZodString;
+            inputType: z.ZodLiteral<"numeric">;
+            digits: z.ZodNumber;
+            answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "InlineInput";
+            inputType: "numeric";
+            name: string;
+            digits: number;
+            answer?: string | number | undefined;
+        }, {
+            type: "InlineInput";
+            inputType: "numeric";
+            name: string;
+            digits: number;
+            answer?: string | number | undefined;
+        }>]>, z.ZodObject<{
+            type: z.ZodLiteral<"Fraction">;
+            name: z.ZodString;
+            numerator: z.ZodOptional<z.ZodNumber>;
+            denominator: z.ZodOptional<z.ZodNumber>;
+            answer: z.ZodOptional<z.ZodString>;
+            simplified: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+        }, {
+            type: "Fraction";
+            name: string;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+            simplified?: boolean | undefined;
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "LineBlock";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        } | {
+            length: number;
+            type: "InlineInput";
+            inputType: "string";
+            name: string;
+            answer?: string | number | undefined;
+        } | {
+            type: "InlineInput";
+            inputType: "numeric";
+            name: string;
+            digits: number;
+            answer?: string | number | undefined;
+        } | {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
             answer?: string | undefined;
             numerator?: number | undefined;
             denominator?: number | undefined;
@@ -2626,19 +3159,107 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
             }, "strip", z.ZodTypeAny, {
                 type: "Fraction";
                 name: string;
-                simplified: boolean;
-                answer?: string | undefined;
-                numerator?: number | undefined;
-                denominator?: number | undefined;
-            }, {
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            }, {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            }>]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            value: number;
+            type: "NumberLinePosition";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                length: number;
+                type: "InlineInput";
+                inputType: "string";
+                name: string;
+                answer?: string | number | undefined;
+            } | {
+                type: "InlineInput";
+                inputType: "numeric";
+                name: string;
+                digits: number;
+                answer?: string | number | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+        }, {
+            value: number;
+            type: "NumberLinePosition";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                length: number;
+                type: "InlineInput";
+                inputType: "string";
+                name: string;
+                answer?: string | number | undefined;
+            } | {
+                type: "InlineInput";
+                inputType: "numeric";
+                name: string;
+                digits: number;
+                answer?: string | number | undefined;
+            } | {
                 type: "Fraction";
                 name: string;
                 answer?: string | undefined;
                 numerator?: number | undefined;
                 denominator?: number | undefined;
                 simplified?: boolean | undefined;
-            }>]>, "many">;
-        }, "strip", z.ZodTypeAny, {
+            })[];
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "NumberLineBlock";
+        min: number;
+        max: number;
+        step: number;
+        positions: {
             value: number;
             type: "NumberLinePosition";
             inlines: ({
@@ -2679,7 +3300,29 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
                 numerator?: number | undefined;
                 denominator?: number | undefined;
             })[];
-        }, {
+        }[];
+        counter?: {
+            type: "NumberLineCounter";
+            min: number;
+            max: number;
+            name?: string | undefined;
+            default?: number | undefined;
+        } | undefined;
+        minorTicks?: number | undefined;
+        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
+        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
+        highlights?: {
+            type: "NumberLineHighlight";
+            from: number;
+            to: number;
+            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
+            label?: string | undefined;
+        }[] | undefined;
+    }, {
+        type: "NumberLineBlock";
+        min: number;
+        max: number;
+        positions: {
             value: number;
             type: "NumberLinePosition";
             inlines: ({
@@ -2720,8 +3363,26 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
                 denominator?: number | undefined;
                 simplified?: boolean | undefined;
             })[];
-        }>, "many">;
-    }, "strip", z.ZodTypeAny, {
+        }[];
+        counter?: {
+            type: "NumberLineCounter";
+            min: number;
+            max: number;
+            name?: string | undefined;
+            default?: number | undefined;
+        } | undefined;
+        step?: number | undefined;
+        minorTicks?: number | undefined;
+        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
+        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
+        highlights?: {
+            type: "NumberLineHighlight";
+            from: number;
+            to: number;
+            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
+            label?: string | undefined;
+        }[] | undefined;
+    }>, {
         type: "NumberLineBlock";
         min: number;
         max: number;
@@ -2896,215 +3557,463 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
                 denominator?: number | undefined;
             })[];
         }[];
-        counter?: {
-            type: "NumberLineCounter";
-            min: number;
-            max: number;
-            name?: string | undefined;
-            default?: number | undefined;
-        } | undefined;
-        minorTicks?: number | undefined;
-        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
-        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
-        highlights?: {
-            type: "NumberLineHighlight";
-            from: number;
-            to: number;
-            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
-            label?: string | undefined;
-        }[] | undefined;
+        counter?: {
+            type: "NumberLineCounter";
+            min: number;
+            max: number;
+            name?: string | undefined;
+            default?: number | undefined;
+        } | undefined;
+        minorTicks?: number | undefined;
+        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
+        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
+        highlights?: {
+            type: "NumberLineHighlight";
+            from: number;
+            to: number;
+            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
+            label?: string | undefined;
+        }[] | undefined;
+    }, {
+        type: "NumberLineBlock";
+        min: number;
+        max: number;
+        positions: {
+            value: number;
+            type: "NumberLinePosition";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                length: number;
+                type: "InlineInput";
+                inputType: "string";
+                name: string;
+                answer?: string | number | undefined;
+            } | {
+                type: "InlineInput";
+                inputType: "numeric";
+                name: string;
+                digits: number;
+                answer?: string | number | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+        }[];
+        counter?: {
+            type: "NumberLineCounter";
+            min: number;
+            max: number;
+            name?: string | undefined;
+            default?: number | undefined;
+        } | undefined;
+        step?: number | undefined;
+        minorTicks?: number | undefined;
+        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
+        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
+        highlights?: {
+            type: "NumberLineHighlight";
+            from: number;
+            to: number;
+            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
+            label?: string | undefined;
+        }[] | undefined;
+    }>, z.ZodEffects<z.ZodObject<{
+        type: z.ZodLiteral<"MatcherBlock">;
+        name: z.ZodString;
+        colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        rows: z.ZodArray<z.ZodObject<{
+            type: z.ZodLiteral<"MatcherRow">;
+            items: z.ZodArray<z.ZodObject<{
+                type: z.ZodLiteral<"MatcherItem">;
+                itemId: z.ZodString;
+                inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                    type: z.ZodLiteral<"FreeText">;
+                    value: z.ZodString;
+                }, "strip", z.ZodTypeAny, {
+                    value: string;
+                    type: "FreeText";
+                }, {
+                    value: string;
+                    type: "FreeText";
+                }>, z.ZodObject<{
+                    type: z.ZodLiteral<"Space">;
+                }, "strip", z.ZodTypeAny, {
+                    type: "Space";
+                }, {
+                    type: "Space";
+                }>, z.ZodObject<{
+                    type: z.ZodLiteral<"HighlightedText">;
+                    value: z.ZodString;
+                    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, "strip", z.ZodTypeAny, {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                }, {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                }>, z.ZodObject<{
+                    type: z.ZodLiteral<"ColorText">;
+                    value: z.ZodString;
+                    color: z.ZodString;
+                    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, "strip", z.ZodTypeAny, {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                }, {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                }>, z.ZodObject<{
+                    type: z.ZodLiteral<"BoldText">;
+                    value: z.ZodString;
+                    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, "strip", z.ZodTypeAny, {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                }, {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                }>, z.ZodEffects<z.ZodObject<{
+                    type: z.ZodLiteral<"Fraction">;
+                    name: z.ZodString;
+                    numerator: z.ZodOptional<z.ZodNumber>;
+                    denominator: z.ZodOptional<z.ZodNumber>;
+                    answer: z.ZodOptional<z.ZodString>;
+                    simplified: z.ZodDefault<z.ZodBoolean>;
+                }, "strip", z.ZodTypeAny, {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                }, {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                }>, {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                }, {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                }>]>, "many">;
+            }, "strip", z.ZodTypeAny, {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                })[];
+                itemId: string;
+            }, {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                })[];
+                itemId: string;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }, {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }>, "many">;
+        answers: z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }[];
+        answers: string[][];
+        colors?: string[] | undefined;
     }, {
-        type: "NumberLineBlock";
-        min: number;
-        max: number;
-        positions: {
-            value: number;
-            type: "NumberLinePosition";
-            inlines: ({
-                value: string;
-                type: "FreeText";
-            } | {
-                type: "Space";
-            } | {
-                value: string;
-                type: "HighlightedText";
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "ColorText";
-                color: string;
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "BoldText";
-                highlight?: [number, number] | undefined;
-            } | {
-                length: number;
-                type: "InlineInput";
-                inputType: "string";
-                name: string;
-                answer?: string | number | undefined;
-            } | {
-                type: "InlineInput";
-                inputType: "numeric";
-                name: string;
-                digits: number;
-                answer?: string | number | undefined;
-            } | {
-                type: "Fraction";
-                name: string;
-                answer?: string | undefined;
-                numerator?: number | undefined;
-                denominator?: number | undefined;
-                simplified?: boolean | undefined;
-            })[];
-        }[];
-        counter?: {
-            type: "NumberLineCounter";
-            min: number;
-            max: number;
-            name?: string | undefined;
-            default?: number | undefined;
-        } | undefined;
-        step?: number | undefined;
-        minorTicks?: number | undefined;
-        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
-        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
-        highlights?: {
-            type: "NumberLineHighlight";
-            from: number;
-            to: number;
-            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
-            label?: string | undefined;
-        }[] | undefined;
-    }>, {
-        type: "NumberLineBlock";
-        min: number;
-        max: number;
-        step: number;
-        positions: {
-            value: number;
-            type: "NumberLinePosition";
-            inlines: ({
-                value: string;
-                type: "FreeText";
-            } | {
-                type: "Space";
-            } | {
-                value: string;
-                type: "HighlightedText";
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "ColorText";
-                color: string;
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "BoldText";
-                highlight?: [number, number] | undefined;
-            } | {
-                length: number;
-                type: "InlineInput";
-                inputType: "string";
-                name: string;
-                answer?: string | number | undefined;
-            } | {
-                type: "InlineInput";
-                inputType: "numeric";
-                name: string;
-                digits: number;
-                answer?: string | number | undefined;
-            } | {
-                type: "Fraction";
-                name: string;
-                simplified: boolean;
-                answer?: string | undefined;
-                numerator?: number | undefined;
-                denominator?: number | undefined;
-            })[];
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                })[];
+                itemId: string;
+            }[];
         }[];
-        counter?: {
-            type: "NumberLineCounter";
-            min: number;
-            max: number;
-            name?: string | undefined;
-            default?: number | undefined;
-        } | undefined;
-        minorTicks?: number | undefined;
-        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
-        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
-        highlights?: {
-            type: "NumberLineHighlight";
-            from: number;
-            to: number;
-            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
-            label?: string | undefined;
-        }[] | undefined;
+        answers: string[][];
+        colors?: string[] | undefined;
+    }>, {
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }[];
+        answers: string[][];
+        colors?: string[] | undefined;
     }, {
-        type: "NumberLineBlock";
-        min: number;
-        max: number;
-        positions: {
-            value: number;
-            type: "NumberLinePosition";
-            inlines: ({
-                value: string;
-                type: "FreeText";
-            } | {
-                type: "Space";
-            } | {
-                value: string;
-                type: "HighlightedText";
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "ColorText";
-                color: string;
-                highlight?: [number, number] | undefined;
-            } | {
-                value: string;
-                type: "BoldText";
-                highlight?: [number, number] | undefined;
-            } | {
-                length: number;
-                type: "InlineInput";
-                inputType: "string";
-                name: string;
-                answer?: string | number | undefined;
-            } | {
-                type: "InlineInput";
-                inputType: "numeric";
-                name: string;
-                digits: number;
-                answer?: string | number | undefined;
-            } | {
-                type: "Fraction";
-                name: string;
-                answer?: string | undefined;
-                numerator?: number | undefined;
-                denominator?: number | undefined;
-                simplified?: boolean | undefined;
-            })[];
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                })[];
+                itemId: string;
+            }[];
         }[];
-        counter?: {
-            type: "NumberLineCounter";
-            min: number;
-            max: number;
-            name?: string | undefined;
-            default?: number | undefined;
-        } | undefined;
-        step?: number | undefined;
-        minorTicks?: number | undefined;
-        style?: "arrow-right" | "arrow-left" | "arrow-both" | "line" | undefined;
-        labelVisibility?: "all" | "extremes" | "min-only" | "max-only" | "none" | undefined;
-        highlights?: {
-            type: "NumberLineHighlight";
-            from: number;
-            to: number;
-            color?: "blue" | "red" | "green" | "orange" | "purple" | "yellow" | undefined;
-            label?: string | undefined;
-        }[] | undefined;
+        answers: string[][];
+        colors?: string[] | undefined;
     }>]>, "many">;
     tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"DragOptions">;
@@ -3303,6 +4212,44 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
         options: string[];
         name: string;
         answer: string;
+    } | {
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    simplified: boolean;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }[];
+        answers: string[][];
+        colors?: string[] | undefined;
     })[];
     question?: {
         value: string;
@@ -3481,6 +4428,44 @@ export declare const ExerciseDocumentSchema: z.ZodObject<{
         options: string[];
         name: string;
         answer: string;
+    } | {
+        type: "MatcherBlock";
+        name: string;
+        rows: {
+            type: "MatcherRow";
+            items: {
+                type: "MatcherItem";
+                inlines: ({
+                    value: string;
+                    type: "FreeText";
+                } | {
+                    type: "Space";
+                } | {
+                    value: string;
+                    type: "HighlightedText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "ColorText";
+                    color: string;
+                    highlight?: [number, number] | undefined;
+                } | {
+                    value: string;
+                    type: "BoldText";
+                    highlight?: [number, number] | undefined;
+                } | {
+                    type: "Fraction";
+                    name: string;
+                    answer?: string | undefined;
+                    numerator?: number | undefined;
+                    denominator?: number | undefined;
+                    simplified?: boolean | undefined;
+                })[];
+                itemId: string;
+            }[];
+        }[];
+        answers: string[][];
+        colors?: string[] | undefined;
     })[];
     question?: {
         value: string;
@@ -3577,21 +4562,95 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"matcher">;
+        rows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"matcher-row">;
+            items: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodLiteral<"matcher-item">;
+                /** Item identifier (no pipe allowed) */
+                itemId: z.ZodString;
+                /** Display-only inline content */
+                content: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
+            }, "strip", z.ZodTypeAny, {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }, {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }, {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }>, "many">;
+        /** Optional color palette for the renderer (one color per answer group) */
+        colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Number of answer groups — equals answers.length, stored here to avoid prop-drilling. */
+        groupCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
+    }, {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>]>>;
     validation: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<["simple", "expression"]>;
-        answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>>;
+        answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">]>>>;
         expression: z.ZodOptional<z.ZodString>;
         variables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     }, {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     }>>;
     meta: z.ZodOptional<z.ZodObject<{
@@ -3636,11 +4695,25 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    } | {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     } | undefined;
     id?: string | undefined;
@@ -3676,11 +4749,25 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    } | {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     } | undefined;
     id?: string | undefined;
@@ -3721,15 +4808,15 @@ export declare const ExerciseRenderer: ForwardRefExoticComponent<ExerciseRendere
 
 export declare interface ExerciseRendererProps {
     json: ExerciseJSON;
-    onSubmit?: (values: Record<string, string>) => void;
-    onChange?: (values: Record<string, string>) => void;
+    onSubmit?: (values: Record<string, UserAnswerValue>) => void;
+    onChange?: (values: Record<string, UserAnswerValue>) => void;
     showSubmitButton?: boolean;
     className?: string;
 }
 
 export declare interface ExerciseRendererRef {
     submit: () => ValidationResult;
-    getValues: () => Record<string, string>;
+    getValues: () => Record<string, UserAnswerValue>;
     reset: () => void;
     focusFirstInput: () => void;
 }
@@ -3782,22 +4869,356 @@ export declare function findValidCombination(expression: string, ranges: Record<
     step?: number;
 }>): Record<string, number> | null;
 
-export declare type FractionInline = z.infer<typeof FractionInlineSchema>;
+export declare type FractionInline = z.infer<typeof FractionInlineSchema>;
+
+/**
+ * Fraction inline widget schema
+ *
+ * Modes determined by presence of numerator/denominator:
+ * - both provided → readonly display
+ * - only numerator → denominator input
+ * - only denominator → numerator input
+ * - neither → both are inputs
+ *
+ * @example Readonly: { type: "Fraction", name: "x", numerator: 5, denominator: 3 }
+ * @example Denominator input: { type: "Fraction", name: "y", numerator: 5, answer: "5/3" }
+ * @example Both inputs: { type: "Fraction", name: "z", answer: "5/3" }
+ */
+export declare const FractionInlineSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Fraction">;
+    name: z.ZodString;
+    numerator: z.ZodOptional<z.ZodNumber>;
+    denominator: z.ZodOptional<z.ZodNumber>;
+    answer: z.ZodOptional<z.ZodString>;
+    simplified: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "Fraction";
+    name: string;
+    simplified: boolean;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+}, {
+    type: "Fraction";
+    name: string;
+    answer?: string | undefined;
+    numerator?: number | undefined;
+    denominator?: number | undefined;
+    simplified?: boolean | undefined;
+}>;
+
+export declare type FractionJSON = z.infer<typeof FractionJSONSchema>;
+
+export declare const FractionJSONSchema: z.ZodObject<{
+    type: z.ZodLiteral<"fraction">;
+    numerator: z.ZodNullable<z.ZodNumber>;
+    denominator: z.ZodNullable<z.ZodNumber>;
+    simplified: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "fraction";
+    numerator: number | null;
+    denominator: number | null;
+    simplified: boolean;
+}, {
+    type: "fraction";
+    numerator: number | null;
+    denominator: number | null;
+    simplified: boolean;
+}>;
+
+/**
+ * Centralized fraction compound key utilities.
+ *
+ * Fraction widgets use compound keys (e.g., "x__num", "x__den") in the
+ * UI values map for sub-inputs. These keys are UI-only — they never appear
+ * in the widgets map or validation answers.
+ */
+export declare type FractionPart = 'num' | 'den';
+
+export declare type FreeTextInline = z.infer<typeof FreeTextInlineSchema>;
+
+/**
+ * Free text inline schema - plain text/numbers WITHOUT special formatting
+ *
+ * Use this for normal text. Only use NUMBER_TEXT when you need highlighting!
+ *
+ * @example
+ * { type: "FreeText", value: "25 + " }
+ * { type: "FreeText", value: " = 30" }
+ */
+export declare const FreeTextInlineSchema: z.ZodObject<{
+    type: z.ZodLiteral<"FreeText">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "FreeText";
+}, {
+    value: string;
+    type: "FreeText";
+}>;
+
+export declare function getFractionKey(widgetId: string, part: FractionPart): string;
+
+/**
+ * Check if all required inputs are provided
+ *
+ * @param exercise - The exercise JSON
+ * @param userInputs - User's answers
+ * @returns Array of missing widget IDs
+ */
+export declare function getMissingInputs(exercise: ExerciseJSON, userInputs: Record<string, string | number>): string[];
+
+export declare type GroupItem = z.infer<typeof GroupItemSchema>;
+
+export declare const GroupItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"group">;
+    items: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "group";
+    items: any[];
+    id: string;
+}, {
+    type: "group";
+    items: any[];
+    id: string;
+}>;
+
+export declare type HighlightedText = z.infer<typeof HighlightedTextSchema>;
+
+export declare type HighlightedTextInline = z.infer<typeof HighlightedTextInlineSchema>;
+
+/**
+ * Highlighted text inline schema - text with optional highlighting
+ *
+ * highlight: [start, end] character positions for visual emphasis
+ *
+ * @example
+ * {
+ *   type: "HighlightedText",
+ *   value: "151 000",
+ *   highlight: [0, 3]  // Highlights "151"
+ * }
+ */
+export declare const HighlightedTextInlineSchema: z.ZodObject<{
+    type: z.ZodLiteral<"HighlightedText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}>;
+
+export declare const HighlightedTextSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"highlighted-text">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "highlighted-text";
+    id: string;
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "highlighted-text";
+    id: string;
+    highlight?: [number, number] | undefined;
+}>;
+
+export declare type InlineInputJSON = z.infer<typeof InlineInputJSONSchema>;
+
+export declare const InlineInputJSONSchema: z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
+    type: z.ZodLiteral<"inline-input">;
+    inputType: z.ZodLiteral<"string">;
+    length: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    length: number;
+    type: "inline-input";
+    inputType: "string";
+}, {
+    length: number;
+    type: "inline-input";
+    inputType: "string";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"inline-input">;
+    inputType: z.ZodLiteral<"numeric">;
+    digits: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "inline-input";
+    inputType: "numeric";
+    digits: number;
+}, {
+    type: "inline-input";
+    inputType: "numeric";
+    digits: number;
+}>]>;
+
+export declare type InlineInputWidget = z.infer<typeof InlineInputWidgetSchema>;
+
+/**
+ * Inline input widget schema - small input that appears within a line
+ *
+ * This is for SHORT inputs (1-5 characters) that flow with text
+ * For longer inputs, consider a standalone tool
+ *
+ * @example String input (W_S_I):
+ * {
+ *   type: "InlineInput",
+ *   name: "x",
+ *   inputType: "string",
+ *   length: 5,        // Visual width in characters
+ *   answer: "hello"
+ * }
+ *
+ * @example Numeric input (W_N_I):
+ * {
+ *   type: "InlineInput",
+ *   name: "x",
+ *   inputType: "numeric",
+ *   digits: 2,        // Maximum number of digits
+ *   answer: 42
+ * }
+ */
+export declare const InlineInputWidgetSchema: z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
+    type: z.ZodLiteral<"InlineInput">;
+    name: z.ZodString;
+    inputType: z.ZodLiteral<"string">;
+    length: z.ZodNumber;
+    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    length: number;
+    type: "InlineInput";
+    inputType: "string";
+    name: string;
+    answer?: string | number | undefined;
+}, {
+    length: number;
+    type: "InlineInput";
+    inputType: "string";
+    name: string;
+    answer?: string | number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"InlineInput">;
+    name: z.ZodString;
+    inputType: z.ZodLiteral<"numeric">;
+    digits: z.ZodNumber;
+    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "InlineInput";
+    inputType: "numeric";
+    name: string;
+    digits: number;
+    answer?: string | number | undefined;
+}, {
+    type: "InlineInput";
+    inputType: "numeric";
+    name: string;
+    digits: number;
+    answer?: string | number | undefined;
+}>]>;
+
+export declare type InlineNode = z.infer<typeof InlineNodeSchema>;
 
 /**
- * Fraction inline widget schema
- *
- * Modes determined by presence of numerator/denominator:
- * - both provided → readonly display
- * - only numerator → denominator input
- * - only denominator → numerator input
- * - neither → both are inputs
- *
- * @example Readonly: { type: "Fraction", name: "x", numerator: 5, denominator: 3 }
- * @example Denominator input: { type: "Fraction", name: "y", numerator: 5, answer: "5/3" }
- * @example Both inputs: { type: "Fraction", name: "z", answer: "5/3" }
+ * Union of all inline element types
  */
-export declare const FractionInlineSchema: z.ZodObject<{
+export declare const InlineNodeSchema: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"FreeText">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "FreeText";
+}, {
+    value: string;
+    type: "FreeText";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"Space">;
+}, "strip", z.ZodTypeAny, {
+    type: "Space";
+}, {
+    type: "Space";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"HighlightedText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "HighlightedText";
+    highlight?: [number, number] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ColorText">;
+    value: z.ZodString;
+    color: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "ColorText";
+    color: string;
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "ColorText";
+    color: string;
+    highlight?: [number, number] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"BoldText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "BoldText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "BoldText";
+    highlight?: [number, number] | undefined;
+}>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
+    type: z.ZodLiteral<"InlineInput">;
+    name: z.ZodString;
+    inputType: z.ZodLiteral<"string">;
+    length: z.ZodNumber;
+    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    length: number;
+    type: "InlineInput";
+    inputType: "string";
+    name: string;
+    answer?: string | number | undefined;
+}, {
+    length: number;
+    type: "InlineInput";
+    inputType: "string";
+    name: string;
+    answer?: string | number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"InlineInput">;
+    name: z.ZodString;
+    inputType: z.ZodLiteral<"numeric">;
+    digits: z.ZodNumber;
+    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "InlineInput";
+    inputType: "numeric";
+    name: string;
+    digits: number;
+    answer?: string | number | undefined;
+}, {
+    type: "InlineInput";
+    inputType: "numeric";
+    name: string;
+    digits: number;
+    answer?: string | number | undefined;
+}>]>, z.ZodObject<{
     type: z.ZodLiteral<"Fraction">;
     name: z.ZodString;
     numerator: z.ZodOptional<z.ZodNumber>;
@@ -3818,609 +5239,884 @@ export declare const FractionInlineSchema: z.ZodObject<{
     numerator?: number | undefined;
     denominator?: number | undefined;
     simplified?: boolean | undefined;
+}>]>;
+
+/**
+ * Type guard for BoldText
+ */
+export declare function isBoldText(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'bold-text';
 }>;
 
-export declare type FractionJSON = z.infer<typeof FractionJSONSchema>;
+/**
+ * Type guard for ColorText
+ */
+export declare function isColorText(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'color-text';
+}>;
 
-export declare const FractionJSONSchema: z.ZodObject<{
-    type: z.ZodLiteral<"fraction">;
-    numerator: z.ZodNullable<z.ZodNumber>;
-    denominator: z.ZodNullable<z.ZodNumber>;
-    simplified: z.ZodBoolean;
-}, "strip", z.ZodTypeAny, {
-    type: "fraction";
-    numerator: number | null;
-    denominator: number | null;
-    simplified: boolean;
-}, {
-    type: "fraction";
-    numerator: number | null;
-    denominator: number | null;
-    simplified: boolean;
+export declare function isDragOptions(value: unknown): value is DragOptionsTool;
+
+/**
+ * Type guard for DragOptionsJSON
+ */
+export declare function isDragOptionsJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'drag-options';
 }>;
 
+export declare function isExerciseDocument(value: unknown): value is ExerciseDocument;
+
+export declare function isExpressionValidation(value: unknown): value is ExpressionValidation;
+
+export declare function isFraction(value: unknown): value is FractionInline;
+
 /**
- * Centralized fraction compound key utilities.
- *
- * Fraction widgets use compound keys (e.g., "x__num", "x__den") in the
- * UI values map for sub-inputs. These keys are UI-only — they never appear
- * in the widgets map or validation answers.
+ * Type guard for FractionJSON
  */
-export declare type FractionPart = 'num' | 'den';
+export declare function isFractionJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'fraction';
+}>;
 
-export declare type FreeTextInline = z.infer<typeof FreeTextInlineSchema>;
+export declare function isFractionKey(key: string): boolean;
+
+export declare function isFreeText(value: unknown): value is FreeTextInline;
 
 /**
- * Free text inline schema - plain text/numbers WITHOUT special formatting
- *
- * Use this for normal text. Only use NUMBER_TEXT when you need highlighting!
- *
- * @example
- * { type: "FreeText", value: "25 + " }
- * { type: "FreeText", value: " = 30" }
+ * Type guard for GroupItem
  */
-export declare const FreeTextInlineSchema: z.ZodObject<{
-    type: z.ZodLiteral<"FreeText">;
-    value: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "FreeText";
-}, {
-    value: string;
-    type: "FreeText";
+export declare function isGroupItem(item: LayoutItem): item is GroupItem;
+
+/**
+ * Type guard for HighlightedText
+ */
+export declare function isHighlightedText(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'highlighted-text';
+}>;
+
+export declare function isInlineInput(value: unknown): value is InlineInputWidget;
+
+/**
+ * Type guard for InlineInputJSON
+ */
+export declare function isInlineInputJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'inline-input';
+}>;
+
+export declare function isInlineNode(value: unknown): value is InlineNode;
+
+export declare function isLineBlock(value: unknown): value is LineBlock;
+
+/**
+ * Type guard for Linebreak
+ */
+export declare function isLinebreak(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'linebreak';
+}>;
+
+export declare function isMatcherBlock(value: unknown): value is MatcherBlock;
+
+export declare function isMatcherItem(value: unknown): value is MatcherItem;
+
+export declare function isMatcherRow(value: unknown): value is MatcherRow;
+
+export declare function isNumericKeypad(value: unknown): value is NumericKeypadTool;
+
+/**
+ * Type guard for NumericKeypadJSON
+ */
+export declare function isNumericKeypadJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'numeric-keypad';
+}>;
+
+/**
+ * Type guard for OperatorItem
+ */
+export declare function isOperatorItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'operator';
+}>;
+
+/**
+ * Type guard for QuestionText
+ */
+export declare function isQuestionText(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'question-text';
+}>;
+
+/**
+ * Type guard for RadioOptionsJSON
+ */
+export declare function isRadioOptionsJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'radio-options';
+}>;
+
+export declare function isSimpleValidation(value: unknown): value is SimpleValidation;
+
+export declare function isSpace(value: unknown): value is SpaceInline;
+
+/**
+ * Type guard for SpaceItem
+ */
+export declare function isSpaceItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'space';
+}>;
+
+/**
+ * Type guard for TableCellItem
+ */
+export declare function isTableCellItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'table-cell';
 }>;
 
-export declare function getFractionKey(widgetId: string, part: FractionPart): string;
+/**
+ * Type guard for TableItem
+ */
+export declare function isTableItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'table';
+}>;
 
 /**
- * Check if all required inputs are provided
- *
- * @param exercise - The exercise JSON
- * @param userInputs - User's answers
- * @returns Array of missing widget IDs
+ * Type guard for TableRowItem
  */
-export declare function getMissingInputs(exercise: ExerciseJSON, userInputs: Record<string, string | number>): string[];
+export declare function isTableRowItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'table-row';
+}>;
 
-export declare type GroupItem = z.infer<typeof GroupItemSchema>;
+export declare function isTextBlock(value: unknown): value is TextBlock;
 
-export declare const GroupItemSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"group">;
-    items: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strip", z.ZodTypeAny, {
-    type: "group";
-    id: string;
-    items: any[];
-}, {
-    type: "group";
-    id: string;
-    items: any[];
+/**
+ * Type guard for TextItem
+ */
+export declare function isTextItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'text';
 }>;
 
-export declare type HighlightedText = z.infer<typeof HighlightedTextSchema>;
+export declare function isToolNode(value: unknown): value is ToolNode;
 
-export declare type HighlightedTextInline = z.infer<typeof HighlightedTextInlineSchema>;
+export declare function isValidationNode(value: unknown): value is ValidationNode;
 
 /**
- * Highlighted text inline schema - text with optional highlighting
- *
- * highlight: [start, end] character positions for visual emphasis
+ * Check if an expression is syntactically valid
  *
- * @example
- * {
- *   type: "HighlightedText",
- *   value: "151 000",
- *   highlight: [0, 3]  // Highlights "151"
- * }
+ * @param expression - The expression to check
+ * @returns true if valid, false otherwise
  */
-export declare const HighlightedTextInlineSchema: z.ZodObject<{
-    type: z.ZodLiteral<"HighlightedText">;
-    value: z.ZodString;
-    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "HighlightedText";
-    highlight?: [number, number] | undefined;
-}, {
-    value: string;
-    type: "HighlightedText";
-    highlight?: [number, number] | undefined;
-}>;
+export declare function isValidExpression(expression: string): boolean;
 
-export declare const HighlightedTextSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"highlighted-text">;
-    value: z.ZodString;
-    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "highlighted-text";
-    id: string;
-    highlight?: [number, number] | undefined;
-}, {
-    value: string;
-    type: "highlighted-text";
-    id: string;
-    highlight?: [number, number] | undefined;
+/**
+ * Type guard for WidgetRef
+ */
+export declare function isWidgetRef(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'widget-ref';
 }>;
 
-export declare type InlineInputJSON = z.infer<typeof InlineInputJSONSchema>;
+/**
+ * JSON Layout Item Types
+ *
+ * These are the types used in the JSON output format.
+ */
+export declare const JSON_TYPES: {
+    /** Question/instruction text */
+    readonly QUESTION_TEXT: "question-text";
+    /** Regular text element */
+    readonly TEXT: "text";
+    /** Spacing element */
+    readonly SPACE: "space";
+    /** Text with optional highlighting */
+    readonly HIGHLIGHTED_TEXT: "highlighted-text";
+    /** Text with color styling */
+    readonly COLOR_TEXT: "color-text";
+    /** Bold text */
+    readonly BOLD_TEXT: "bold-text";
+    /** Reference to a widget */
+    readonly WIDGET_REF: "widget-ref";
+    /** Line break element */
+    readonly LINEBREAK: "linebreak";
+    /** Grouped layout items */
+    readonly GROUP: "group";
+    /** Operator symbol */
+    readonly OPERATOR: "operator";
+    /** Table layout block */
+    readonly TABLE: "table";
+    /** Row within a table */
+    readonly TABLE_ROW: "table-row";
+    /** Cell within a table */
+    readonly TABLE_CELL: "table-cell";
+    /** Number line layout block */
+    readonly NUMBER_LINE: "number-line";
+    /** Position marker within a number line */
+    readonly NUMBER_LINE_POSITION: "number-line-position";
+    /** Dynamic subdivision counter embedded in a number line */
+    readonly NUMBER_LINE_COUNTER: "number-line-counter";
+    /** Highlighted range within a number line */
+    readonly NUMBER_LINE_HIGHLIGHT: "number-line-highlight";
+    /** Matcher layout block */
+    readonly MATCHER: "matcher";
+    /** Row within a matcher */
+    readonly MATCHER_ROW: "matcher-row";
+    /** Item within a matcher row */
+    readonly MATCHER_ITEM: "matcher-item";
+    /** Inline input widget (string or numeric) */
+    readonly INLINE_INPUT: "inline-input";
+    /** Drag-and-drop options widget */
+    readonly DRAG_OPTIONS: "drag-options";
+    /** Radio button options widget */
+    readonly RADIO_OPTIONS: "radio-options";
+    /** Numeric keypad widget */
+    readonly NUMERIC_KEYPAD: "numeric-keypad";
+    /** Inline fraction widget */
+    readonly FRACTION: "fraction";
+};
 
-export declare const InlineInputJSONSchema: z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
-    type: z.ZodLiteral<"inline-input">;
-    inputType: z.ZodLiteral<"string">;
-    length: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    length: number;
-    type: "inline-input";
-    inputType: "string";
-}, {
-    length: number;
-    type: "inline-input";
-    inputType: "string";
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"inline-input">;
-    inputType: z.ZodLiteral<"numeric">;
-    digits: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "inline-input";
-    inputType: "numeric";
-    digits: number;
-}, {
-    type: "inline-input";
-    inputType: "numeric";
-    digits: number;
-}>]>;
+/**
+ * Type helper to get all JSON type values as a union type
+ */
+export declare type JSONType = typeof JSON_TYPES[keyof typeof JSON_TYPES];
 
-export declare type InlineInputWidget = z.infer<typeof InlineInputWidgetSchema>;
+export declare type LayoutItem = z.infer<typeof LayoutItemSchema>;
+
+export declare const LayoutItemSchema: z.ZodType<any>;
 
 /**
- * Inline input widget schema - small input that appears within a line
- *
- * This is for SHORT inputs (1-5 characters) that flow with text
- * For longer inputs, consider a standalone tool
- *
- * @example String input (W_S_I):
- * {
- *   type: "InlineInput",
- *   name: "x",
- *   inputType: "string",
- *   length: 5,        // Visual width in characters
- *   answer: "hello"
- * }
- *
- * @example Numeric input (W_N_I):
- * {
- *   type: "InlineInput",
- *   name: "x",
- *   inputType: "numeric",
- *   digits: 2,        // Maximum number of digits
- *   answer: 42
- * }
+ * DUMB layout renderer - no opinions about spacing or layout.
  */
-export declare const InlineInputWidgetSchema: z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
-    type: z.ZodLiteral<"InlineInput">;
-    name: z.ZodString;
-    inputType: z.ZodLiteral<"string">;
-    length: z.ZodNumber;
-    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-}, "strip", z.ZodTypeAny, {
-    length: number;
-    type: "InlineInput";
-    inputType: "string";
-    name: string;
-    answer?: string | number | undefined;
-}, {
-    length: number;
-    type: "InlineInput";
-    inputType: "string";
-    name: string;
-    answer?: string | number | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"InlineInput">;
-    name: z.ZodString;
-    inputType: z.ZodLiteral<"numeric">;
-    digits: z.ZodNumber;
-    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-}, "strip", z.ZodTypeAny, {
-    type: "InlineInput";
-    inputType: "numeric";
-    name: string;
-    digits: number;
-    answer?: string | number | undefined;
-}, {
-    type: "InlineInput";
-    inputType: "numeric";
-    name: string;
-    digits: number;
-    answer?: string | number | undefined;
-}>]>;
+export declare const LayoutRenderer: default_2.FC<LayoutRendererProps>;
 
-export declare type InlineNode = z.infer<typeof InlineNodeSchema>;
+export declare interface LayoutRendererProps {
+    item: LayoutItem;
+    widgets: Record<string, WidgetJSON>;
+    values: Record<string, UserAnswerValue>;
+    droppedInputs: Set<string>;
+    validationDetails?: Record<string, boolean> | null;
+    onChange: (widgetId: string, value: UserAnswerValue, fromDrop?: boolean, sourceOptionId?: string) => void;
+    onInputFocus?: (widgetId: string) => void;
+    /** Incremented on reset. Drives remount of stateful items: NumberLine and MatcherWidget. */
+    resetKey?: number;
+}
 
 /**
- * Union of all inline element types
+ * Error thrown when lexer fails to tokenize input
+ */
+export declare class LexerError extends EngineError {
+    readonly lexerErrors: ILexingError[];
+    readonly positions: SourcePosition[];
+    constructor(errors: ILexingError[]);
+}
+
+export declare type LineBlock = z.infer<typeof LineBlockSchema>;
+
+/**
+ * Line block schema - represents a visual row of inline elements
+ *
+ * One line = one visual row in the UI
+ * Contains an ordered sequence of inline elements
+ *
+ * @example
+ * {
+ *   type: "LineBlock",
+ *   inlines: [
+ *     { type: "HighlightedText", value: "151 000", highlight: [0, 3] },
+ *     { type: "InlineInput", name: "x", length: 1 },
+ *     { type: "HighlightedText", value: "54 000", highlight: [0, 3] }
+ *   ]
+ * }
  */
-export declare const InlineNodeSchema: z.ZodUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"FreeText">;
-    value: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "FreeText";
-}, {
-    value: string;
-    type: "FreeText";
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"Space">;
-}, "strip", z.ZodTypeAny, {
-    type: "Space";
-}, {
-    type: "Space";
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"HighlightedText">;
-    value: z.ZodString;
-    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "HighlightedText";
-    highlight?: [number, number] | undefined;
-}, {
-    value: string;
-    type: "HighlightedText";
-    highlight?: [number, number] | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"ColorText">;
-    value: z.ZodString;
-    color: z.ZodString;
-    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
-}, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "ColorText";
-    color: string;
-    highlight?: [number, number] | undefined;
-}, {
-    value: string;
-    type: "ColorText";
-    color: string;
-    highlight?: [number, number] | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"BoldText">;
-    value: z.ZodString;
-    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+export declare const LineBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"LineBlock">;
+    inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"FreeText">;
+        value: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "FreeText";
+    }, {
+        value: string;
+        type: "FreeText";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"Space">;
+    }, "strip", z.ZodTypeAny, {
+        type: "Space";
+    }, {
+        type: "Space";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"HighlightedText">;
+        value: z.ZodString;
+        highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "HighlightedText";
+        highlight?: [number, number] | undefined;
+    }, {
+        value: string;
+        type: "HighlightedText";
+        highlight?: [number, number] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ColorText">;
+        value: z.ZodString;
+        color: z.ZodString;
+        highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "ColorText";
+        color: string;
+        highlight?: [number, number] | undefined;
+    }, {
+        value: string;
+        type: "ColorText";
+        color: string;
+        highlight?: [number, number] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"BoldText">;
+        value: z.ZodString;
+        highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "BoldText";
+        highlight?: [number, number] | undefined;
+    }, {
+        value: string;
+        type: "BoldText";
+        highlight?: [number, number] | undefined;
+    }>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
+        type: z.ZodLiteral<"InlineInput">;
+        name: z.ZodString;
+        inputType: z.ZodLiteral<"string">;
+        length: z.ZodNumber;
+        answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    }, "strip", z.ZodTypeAny, {
+        length: number;
+        type: "InlineInput";
+        inputType: "string";
+        name: string;
+        answer?: string | number | undefined;
+    }, {
+        length: number;
+        type: "InlineInput";
+        inputType: "string";
+        name: string;
+        answer?: string | number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"InlineInput">;
+        name: z.ZodString;
+        inputType: z.ZodLiteral<"numeric">;
+        digits: z.ZodNumber;
+        answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "InlineInput";
+        inputType: "numeric";
+        name: string;
+        digits: number;
+        answer?: string | number | undefined;
+    }, {
+        type: "InlineInput";
+        inputType: "numeric";
+        name: string;
+        digits: number;
+        answer?: string | number | undefined;
+    }>]>, z.ZodObject<{
+        type: z.ZodLiteral<"Fraction">;
+        name: z.ZodString;
+        numerator: z.ZodOptional<z.ZodNumber>;
+        denominator: z.ZodOptional<z.ZodNumber>;
+        answer: z.ZodOptional<z.ZodString>;
+        simplified: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "Fraction";
+        name: string;
+        simplified: boolean;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+    }, {
+        type: "Fraction";
+        name: string;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+        simplified?: boolean | undefined;
+    }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
-    value: string;
-    type: "BoldText";
-    highlight?: [number, number] | undefined;
+    type: "LineBlock";
+    inlines: ({
+        value: string;
+        type: "FreeText";
+    } | {
+        type: "Space";
+    } | {
+        value: string;
+        type: "HighlightedText";
+        highlight?: [number, number] | undefined;
+    } | {
+        value: string;
+        type: "ColorText";
+        color: string;
+        highlight?: [number, number] | undefined;
+    } | {
+        value: string;
+        type: "BoldText";
+        highlight?: [number, number] | undefined;
+    } | {
+        length: number;
+        type: "InlineInput";
+        inputType: "string";
+        name: string;
+        answer?: string | number | undefined;
+    } | {
+        type: "InlineInput";
+        inputType: "numeric";
+        name: string;
+        digits: number;
+        answer?: string | number | undefined;
+    } | {
+        type: "Fraction";
+        name: string;
+        simplified: boolean;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+    })[];
 }, {
-    value: string;
-    type: "BoldText";
-    highlight?: [number, number] | undefined;
-}>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
-    type: z.ZodLiteral<"InlineInput">;
-    name: z.ZodString;
-    inputType: z.ZodLiteral<"string">;
-    length: z.ZodNumber;
-    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    type: "LineBlock";
+    inlines: ({
+        value: string;
+        type: "FreeText";
+    } | {
+        type: "Space";
+    } | {
+        value: string;
+        type: "HighlightedText";
+        highlight?: [number, number] | undefined;
+    } | {
+        value: string;
+        type: "ColorText";
+        color: string;
+        highlight?: [number, number] | undefined;
+    } | {
+        value: string;
+        type: "BoldText";
+        highlight?: [number, number] | undefined;
+    } | {
+        length: number;
+        type: "InlineInput";
+        inputType: "string";
+        name: string;
+        answer?: string | number | undefined;
+    } | {
+        type: "InlineInput";
+        inputType: "numeric";
+        name: string;
+        digits: number;
+        answer?: string | number | undefined;
+    } | {
+        type: "Fraction";
+        name: string;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+        simplified?: boolean | undefined;
+    })[];
+}>;
+
+export declare type Linebreak = z.infer<typeof LinebreakSchema>;
+
+export declare const LinebreakSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"linebreak">;
 }, "strip", z.ZodTypeAny, {
-    length: number;
-    type: "InlineInput";
-    inputType: "string";
-    name: string;
-    answer?: string | number | undefined;
+    type: "linebreak";
+    id: string;
 }, {
-    length: number;
-    type: "InlineInput";
-    inputType: "string";
-    name: string;
-    answer?: string | number | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"InlineInput">;
+    type: "linebreak";
+    id: string;
+}>;
+
+export declare type MatcherBlock = z.infer<typeof MatcherBlockSchema>;
+
+export declare const MatcherBlockSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"MatcherBlock">;
     name: z.ZodString;
-    inputType: z.ZodLiteral<"numeric">;
-    digits: z.ZodNumber;
-    answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    /** Optional palette of colors for the renderer (one per answer group) */
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** At least one row required */
+    rows: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"MatcherRow">;
+        /** At least one item per row */
+        items: z.ZodArray<z.ZodObject<{
+            type: z.ZodLiteral<"MatcherItem">;
+            itemId: z.ZodString;
+            inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"FreeText">;
+                value: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "FreeText";
+            }, {
+                value: string;
+                type: "FreeText";
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"Space">;
+            }, "strip", z.ZodTypeAny, {
+                type: "Space";
+            }, {
+                type: "Space";
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"HighlightedText">;
+                value: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"ColorText">;
+                value: z.ZodString;
+                color: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"BoldText">;
+                value: z.ZodString;
+                highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            }, {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            }>, z.ZodEffects<z.ZodObject<{
+                type: z.ZodLiteral<"Fraction">;
+                name: z.ZodString;
+                numerator: z.ZodOptional<z.ZodNumber>;
+                denominator: z.ZodOptional<z.ZodNumber>;
+                answer: z.ZodOptional<z.ZodString>;
+                simplified: z.ZodDefault<z.ZodBoolean>;
+            }, "strip", z.ZodTypeAny, {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            }, {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            }>, {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            }, {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            }>]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }, {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }, {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }>, "many">;
+    answers: z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">;
 }, "strip", z.ZodTypeAny, {
-    type: "InlineInput";
-    inputType: "numeric";
+    type: "MatcherBlock";
     name: string;
-    digits: number;
-    answer?: string | number | undefined;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
 }, {
-    type: "InlineInput";
-    inputType: "numeric";
+    type: "MatcherBlock";
     name: string;
-    digits: number;
-    answer?: string | number | undefined;
-}>]>, z.ZodObject<{
-    type: z.ZodLiteral<"Fraction">;
-    name: z.ZodString;
-    numerator: z.ZodOptional<z.ZodNumber>;
-    denominator: z.ZodOptional<z.ZodNumber>;
-    answer: z.ZodOptional<z.ZodString>;
-    simplified: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    type: "Fraction";
-    name: string;
-    simplified: boolean;
-    answer?: string | undefined;
-    numerator?: number | undefined;
-    denominator?: number | undefined;
-}, {
-    type: "Fraction";
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}>, {
+    type: "MatcherBlock";
     name: string;
-    answer?: string | undefined;
-    numerator?: number | undefined;
-    denominator?: number | undefined;
-    simplified?: boolean | undefined;
-}>]>;
-
-/**
- * Type guard for BoldText
- */
-export declare function isBoldText(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'bold-text';
-}>;
-
-/**
- * Type guard for ColorText
- */
-export declare function isColorText(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'color-text';
-}>;
-
-export declare function isDragOptions(value: unknown): value is DragOptionsTool;
-
-/**
- * Type guard for DragOptionsJSON
- */
-export declare function isDragOptionsJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'drag-options';
-}>;
-
-export declare function isExerciseDocument(value: unknown): value is ExerciseDocument;
-
-export declare function isExpressionValidation(value: unknown): value is ExpressionValidation;
-
-export declare function isFraction(value: unknown): value is FractionInline;
-
-/**
- * Type guard for FractionJSON
- */
-export declare function isFractionJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'fraction';
-}>;
-
-export declare function isFractionKey(key: string): boolean;
-
-export declare function isFreeText(value: unknown): value is FreeTextInline;
-
-/**
- * Type guard for GroupItem
- */
-export declare function isGroupItem(item: LayoutItem): item is GroupItem;
-
-/**
- * Type guard for HighlightedText
- */
-export declare function isHighlightedText(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'highlighted-text';
-}>;
-
-export declare function isInlineInput(value: unknown): value is InlineInputWidget;
-
-/**
- * Type guard for InlineInputJSON
- */
-export declare function isInlineInputJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'inline-input';
-}>;
-
-export declare function isInlineNode(value: unknown): value is InlineNode;
-
-export declare function isLineBlock(value: unknown): value is LineBlock;
-
-/**
- * Type guard for Linebreak
- */
-export declare function isLinebreak(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'linebreak';
-}>;
-
-export declare function isNumericKeypad(value: unknown): value is NumericKeypadTool;
-
-/**
- * Type guard for NumericKeypadJSON
- */
-export declare function isNumericKeypadJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'numeric-keypad';
-}>;
-
-/**
- * Type guard for OperatorItem
- */
-export declare function isOperatorItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'operator';
-}>;
-
-/**
- * Type guard for QuestionText
- */
-export declare function isQuestionText(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'question-text';
-}>;
-
-/**
- * Type guard for RadioOptionsJSON
- */
-export declare function isRadioOptionsJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'radio-options';
-}>;
-
-export declare function isSimpleValidation(value: unknown): value is SimpleValidation;
-
-export declare function isSpace(value: unknown): value is SpaceInline;
-
-/**
- * Type guard for SpaceItem
- */
-export declare function isSpaceItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'space';
-}>;
-
-/**
- * Type guard for TableCellItem
- */
-export declare function isTableCellItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'table-cell';
-}>;
-
-/**
- * Type guard for TableItem
- */
-export declare function isTableItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'table';
-}>;
-
-/**
- * Type guard for TableRowItem
- */
-export declare function isTableRowItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'table-row';
-}>;
-
-export declare function isTextBlock(value: unknown): value is TextBlock;
-
-/**
- * Type guard for TextItem
- */
-export declare function isTextItem(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'text';
-}>;
-
-export declare function isToolNode(value: unknown): value is ToolNode;
-
-export declare function isValidationNode(value: unknown): value is ValidationNode;
-
-/**
- * Check if an expression is syntactically valid
- *
- * @param expression - The expression to check
- * @returns true if valid, false otherwise
- */
-export declare function isValidExpression(expression: string): boolean;
-
-/**
- * Type guard for WidgetRef
- */
-export declare function isWidgetRef(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'widget-ref';
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                simplified: boolean;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
+}, {
+    type: "MatcherBlock";
+    name: string;
+    rows: {
+        type: "MatcherRow";
+        items: {
+            type: "MatcherItem";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "HighlightedText";
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "ColorText";
+                color: string;
+                highlight?: [number, number] | undefined;
+            } | {
+                value: string;
+                type: "BoldText";
+                highlight?: [number, number] | undefined;
+            } | {
+                type: "Fraction";
+                name: string;
+                answer?: string | undefined;
+                numerator?: number | undefined;
+                denominator?: number | undefined;
+                simplified?: boolean | undefined;
+            })[];
+            itemId: string;
+        }[];
+    }[];
+    answers: string[][];
+    colors?: string[] | undefined;
 }>;
 
-/**
- * JSON Layout Item Types
- *
- * These are the types used in the JSON output format.
- */
-export declare const JSON_TYPES: {
-    /** Question/instruction text */
-    readonly QUESTION_TEXT: "question-text";
-    /** Regular text element */
-    readonly TEXT: "text";
-    /** Spacing element */
-    readonly SPACE: "space";
-    /** Text with optional highlighting */
-    readonly HIGHLIGHTED_TEXT: "highlighted-text";
-    /** Text with color styling */
-    readonly COLOR_TEXT: "color-text";
-    /** Bold text */
-    readonly BOLD_TEXT: "bold-text";
-    /** Reference to a widget */
-    readonly WIDGET_REF: "widget-ref";
-    /** Line break element */
-    readonly LINEBREAK: "linebreak";
-    /** Grouped layout items */
-    readonly GROUP: "group";
-    /** Operator symbol */
-    readonly OPERATOR: "operator";
-    /** Table layout block */
-    readonly TABLE: "table";
-    /** Row within a table */
-    readonly TABLE_ROW: "table-row";
-    /** Cell within a table */
-    readonly TABLE_CELL: "table-cell";
-    /** Number line layout block */
-    readonly NUMBER_LINE: "number-line";
-    /** Position marker within a number line */
-    readonly NUMBER_LINE_POSITION: "number-line-position";
-    /** Dynamic subdivision counter embedded in a number line */
-    readonly NUMBER_LINE_COUNTER: "number-line-counter";
-    /** Highlighted range within a number line */
-    readonly NUMBER_LINE_HIGHLIGHT: "number-line-highlight";
-    /** Inline input widget (string or numeric) */
-    readonly INLINE_INPUT: "inline-input";
-    /** Drag-and-drop options widget */
-    readonly DRAG_OPTIONS: "drag-options";
-    /** Radio button options widget */
-    readonly RADIO_OPTIONS: "radio-options";
-    /** Numeric keypad widget */
-    readonly NUMERIC_KEYPAD: "numeric-keypad";
-    /** Inline fraction widget */
-    readonly FRACTION: "fraction";
-};
-
-/**
- * Type helper to get all JSON type values as a union type
- */
-export declare type JSONType = typeof JSON_TYPES[keyof typeof JSON_TYPES];
-
-export declare type LayoutItem = z.infer<typeof LayoutItemSchema>;
-
-export declare const LayoutItemSchema: z.ZodType<any>;
-
-/**
- * DUMB layout renderer - no opinions about spacing or layout.
- */
-export declare const LayoutRenderer: default_2.FC<LayoutRendererProps>;
-
-export declare interface LayoutRendererProps {
-    item: LayoutItem;
-    widgets: Record<string, WidgetJSON>;
-    values: Record<string, string>;
-    droppedInputs: Set<string>;
-    validationDetails?: Record<string, boolean> | null;
-    onChange: (widgetId: string, value: string, fromDrop?: boolean, sourceOptionId?: string) => void;
-    onInputFocus?: (widgetId: string) => void;
-}
-
-/**
- * Error thrown when lexer fails to tokenize input
- */
-export declare class LexerError extends EngineError {
-    readonly lexerErrors: ILexingError[];
-    readonly positions: SourcePosition[];
-    constructor(errors: ILexingError[]);
-}
-
-export declare type LineBlock = z.infer<typeof LineBlockSchema>;
+export declare type MatcherItem = z.infer<typeof MatcherItemSchema>;
 
-/**
- * Line block schema - represents a visual row of inline elements
- *
- * One line = one visual row in the UI
- * Contains an ordered sequence of inline elements
- *
- * @example
- * {
- *   type: "LineBlock",
- *   inlines: [
- *     { type: "HighlightedText", value: "151 000", highlight: [0, 3] },
- *     { type: "InlineInput", name: "x", length: 1 },
- *     { type: "HighlightedText", value: "54 000", highlight: [0, 3] }
- *   ]
- * }
- */
-export declare const LineBlockSchema: z.ZodObject<{
-    type: z.ZodLiteral<"LineBlock">;
+export declare const MatcherItemSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MatcherItem">;
+    itemId: z.ZodString;
     inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
         type: z.ZodLiteral<"FreeText">;
         value: z.ZodString;
@@ -4475,43 +6171,7 @@ export declare const LineBlockSchema: z.ZodObject<{
         value: string;
         type: "BoldText";
         highlight?: [number, number] | undefined;
-    }>, z.ZodDiscriminatedUnion<"inputType", [z.ZodObject<{
-        type: z.ZodLiteral<"InlineInput">;
-        name: z.ZodString;
-        inputType: z.ZodLiteral<"string">;
-        length: z.ZodNumber;
-        answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    }, "strip", z.ZodTypeAny, {
-        length: number;
-        type: "InlineInput";
-        inputType: "string";
-        name: string;
-        answer?: string | number | undefined;
-    }, {
-        length: number;
-        type: "InlineInput";
-        inputType: "string";
-        name: string;
-        answer?: string | number | undefined;
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"InlineInput">;
-        name: z.ZodString;
-        inputType: z.ZodLiteral<"numeric">;
-        digits: z.ZodNumber;
-        answer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    }, "strip", z.ZodTypeAny, {
-        type: "InlineInput";
-        inputType: "numeric";
-        name: string;
-        digits: number;
-        answer?: string | number | undefined;
-    }, {
-        type: "InlineInput";
-        inputType: "numeric";
-        name: string;
-        digits: number;
-        answer?: string | number | undefined;
-    }>]>, z.ZodObject<{
+    }>, z.ZodEffects<z.ZodObject<{
         type: z.ZodLiteral<"Fraction">;
         name: z.ZodString;
         numerator: z.ZodOptional<z.ZodNumber>;
@@ -4532,9 +6192,23 @@ export declare const LineBlockSchema: z.ZodObject<{
         numerator?: number | undefined;
         denominator?: number | undefined;
         simplified?: boolean | undefined;
+    }>, {
+        type: "Fraction";
+        name: string;
+        simplified: boolean;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+    }, {
+        type: "Fraction";
+        name: string;
+        answer?: string | undefined;
+        numerator?: number | undefined;
+        denominator?: number | undefined;
+        simplified?: boolean | undefined;
     }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
-    type: "LineBlock";
+    type: "MatcherItem";
     inlines: ({
         value: string;
         type: "FreeText";
@@ -4553,18 +6227,6 @@ export declare const LineBlockSchema: z.ZodObject<{
         value: string;
         type: "BoldText";
         highlight?: [number, number] | undefined;
-    } | {
-        length: number;
-        type: "InlineInput";
-        inputType: "string";
-        name: string;
-        answer?: string | number | undefined;
-    } | {
-        type: "InlineInput";
-        inputType: "numeric";
-        name: string;
-        digits: number;
-        answer?: string | number | undefined;
     } | {
         type: "Fraction";
         name: string;
@@ -4573,8 +6235,9 @@ export declare const LineBlockSchema: z.ZodObject<{
         numerator?: number | undefined;
         denominator?: number | undefined;
     })[];
+    itemId: string;
 }, {
-    type: "LineBlock";
+    type: "MatcherItem";
     inlines: ({
         value: string;
         type: "FreeText";
@@ -4593,18 +6256,6 @@ export declare const LineBlockSchema: z.ZodObject<{
         value: string;
         type: "BoldText";
         highlight?: [number, number] | undefined;
-    } | {
-        length: number;
-        type: "InlineInput";
-        inputType: "string";
-        name: string;
-        answer?: string | number | undefined;
-    } | {
-        type: "InlineInput";
-        inputType: "numeric";
-        name: string;
-        digits: number;
-        answer?: string | number | undefined;
     } | {
         type: "Fraction";
         name: string;
@@ -4613,19 +6264,230 @@ export declare const LineBlockSchema: z.ZodObject<{
         denominator?: number | undefined;
         simplified?: boolean | undefined;
     })[];
+    itemId: string;
 }>;
 
-export declare type Linebreak = z.infer<typeof LinebreakSchema>;
+export declare type MatcherRow = z.infer<typeof MatcherRowSchema>;
 
-export declare const LinebreakSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"linebreak">;
+export declare const MatcherRowSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MatcherRow">;
+    /** At least one item per row */
+    items: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"MatcherItem">;
+        itemId: z.ZodString;
+        inlines: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"FreeText">;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "FreeText";
+        }, {
+            value: string;
+            type: "FreeText";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"Space">;
+        }, "strip", z.ZodTypeAny, {
+            type: "Space";
+        }, {
+            type: "Space";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"HighlightedText">;
+            value: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"ColorText">;
+            value: z.ZodString;
+            color: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"BoldText">;
+            value: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        }>, z.ZodEffects<z.ZodObject<{
+            type: z.ZodLiteral<"Fraction">;
+            name: z.ZodString;
+            numerator: z.ZodOptional<z.ZodNumber>;
+            denominator: z.ZodOptional<z.ZodNumber>;
+            answer: z.ZodOptional<z.ZodString>;
+            simplified: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+        }, {
+            type: "Fraction";
+            name: string;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+            simplified?: boolean | undefined;
+        }>, {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+        }, {
+            type: "Fraction";
+            name: string;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+            simplified?: boolean | undefined;
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "MatcherItem";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        } | {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+        })[];
+        itemId: string;
+    }, {
+        type: "MatcherItem";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        } | {
+            type: "Fraction";
+            name: string;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+            simplified?: boolean | undefined;
+        })[];
+        itemId: string;
+    }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    type: "linebreak";
-    id: string;
+    type: "MatcherRow";
+    items: {
+        type: "MatcherItem";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        } | {
+            type: "Fraction";
+            name: string;
+            simplified: boolean;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+        })[];
+        itemId: string;
+    }[];
 }, {
-    type: "linebreak";
-    id: string;
+    type: "MatcherRow";
+    items: {
+        type: "MatcherItem";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "HighlightedText";
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "ColorText";
+            color: string;
+            highlight?: [number, number] | undefined;
+        } | {
+            value: string;
+            type: "BoldText";
+            highlight?: [number, number] | undefined;
+        } | {
+            type: "Fraction";
+            name: string;
+            answer?: string | undefined;
+            numerator?: number | undefined;
+            denominator?: number | undefined;
+            simplified?: boolean | undefined;
+        })[];
+        itemId: string;
+    }[];
 }>;
 
 export declare type NumberLineBlock = z.infer<typeof NumberLineBlockSchema>;
@@ -5978,8 +7840,8 @@ export declare function renderExercise(options: RenderOptions): () => void;
 export declare interface RenderOptions {
     container: HTMLElement | string;
     json: ExerciseJSON;
-    onSubmit?: (values: Record<string, string>) => void;
-    onChange?: (values: Record<string, string>) => void;
+    onSubmit?: (values: Record<string, UserAnswerValue>) => void;
+    onChange?: (values: Record<string, UserAnswerValue>) => void;
     showSubmitButton?: boolean;
     className?: string;
 }
@@ -6452,13 +8314,13 @@ export declare const TableCellItemSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "table-cell";
-    id: string;
     items: any[];
+    id: string;
     colspan?: number | undefined;
 }, {
     type: "table-cell";
-    id: string;
     items: any[];
+    id: string;
     colspan?: number | undefined;
 }>;
 
@@ -6677,21 +8539,21 @@ export declare const TableItemSchema: z.ZodObject<{
             items: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
         }, "strip", z.ZodTypeAny, {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }, {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         type: "table-row";
         cells: {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }[];
         id: string;
@@ -6699,8 +8561,8 @@ export declare const TableItemSchema: z.ZodObject<{
         type: "table-row";
         cells: {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }[];
         id: string;
@@ -6712,8 +8574,8 @@ export declare const TableItemSchema: z.ZodObject<{
         type: "table-row";
         cells: {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }[];
         id: string;
@@ -6726,8 +8588,8 @@ export declare const TableItemSchema: z.ZodObject<{
         type: "table-row";
         cells: {
             type: "table-cell";
-            id: string;
             items: any[];
+            id: string;
             colspan?: number | undefined;
         }[];
         id: string;
@@ -6749,21 +8611,21 @@ export declare const TableRowItemSchema: z.ZodObject<{
         items: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
     }, "strip", z.ZodTypeAny, {
         type: "table-cell";
-        id: string;
         items: any[];
+        id: string;
         colspan?: number | undefined;
     }, {
         type: "table-cell";
-        id: string;
         items: any[];
+        id: string;
         colspan?: number | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "table-row";
     cells: {
         type: "table-cell";
-        id: string;
         items: any[];
+        id: string;
         colspan?: number | undefined;
     }[];
     id: string;
@@ -6771,8 +8633,8 @@ export declare const TableRowItemSchema: z.ZodObject<{
     type: "table-row";
     cells: {
         type: "table-cell";
-        id: string;
         items: any[];
+        id: string;
         colspan?: number | undefined;
     }[];
     id: string;
@@ -7182,6 +9044,18 @@ export declare class TransformError extends EngineError {
     constructor(message: string, position?: SourcePosition);
 }
 
+/**
+ * Shared value types for the renderer layer.
+ *
+ * `UserAnswerValue` is the runtime type of any answer collected by the renderer:
+ * - `string`    — all scalar widgets (inline-input, radio-options, drag-options, number-line inputs…)
+ * - `string[][]` — matcher widget (groups of item IDs, no JSON serialisation needed)
+ *
+ * This union matches the type accepted by `validate()` and avoids any
+ * JSON.stringify / JSON.parse round-trips for structured widget values.
+ */
+declare type UserAnswerValue = string | string[][];
+
 /**
  * Validate user inputs against an exercise
  *
@@ -7202,7 +9076,7 @@ export declare class TransformError extends EngineError {
  * }
  * ```
  */
-export declare function validate(exercise: ExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+export declare function validate(exercise: ExerciseJSON, userInputs: Record<string, string | number | string[][]>): ValidationResult;
 
 /**
  * Validate that an expression will return a boolean
@@ -7259,11 +9133,25 @@ export declare function validateExerciseJSON(data: unknown): {
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    } | {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     } | undefined;
     id?: string | undefined;
@@ -7317,11 +9205,25 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    } | {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     } | undefined;
     id?: string | undefined;
@@ -7357,11 +9259,25 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         numerator: number | null;
         denominator: number | null;
         simplified: boolean;
+    } | {
+        type: "matcher";
+        rows: {
+            type: "matcher-row";
+            items: {
+                type: "matcher-item";
+                itemId: string;
+                id: string;
+                content: any[];
+            }[];
+            id: string;
+        }[];
+        groupCount: number;
+        colors?: string[] | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression";
         expression?: string | undefined;
-        answers?: Record<string, string | number> | undefined;
+        answers?: Record<string, string | number | string[][]> | undefined;
         variables?: string[] | undefined;
     } | undefined;
     id?: string | undefined;
@@ -7399,7 +9315,7 @@ export declare function validateInputFormats(exercise: ExerciseJSON, userInputs:
  * @param userInputs - User's answers keyed by widget ID
  * @returns Validation result
  */
-export declare function validateSimple(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+export declare function validateSimple(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number | string[][]>): ValidationResult;
 
 /**
  * Validate a widget JSON object at runtime
@@ -7431,6 +9347,20 @@ export declare function validateWidgetJSON(data: unknown): {
     numerator: number | null;
     denominator: number | null;
     simplified: boolean;
+} | {
+    type: "matcher";
+    rows: {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }[];
+    groupCount: number;
+    colors?: string[] | undefined;
 };
 
 /**
@@ -7462,6 +9392,20 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     numerator: number | null;
     denominator: number | null;
     simplified: boolean;
+} | {
+    type: "matcher";
+    rows: {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }[];
+    groupCount: number;
+    colors?: string[] | undefined;
 }, {
     length: number;
     type: "inline-input";
@@ -7485,6 +9429,20 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     numerator: number | null;
     denominator: number | null;
     simplified: boolean;
+} | {
+    type: "matcher";
+    rows: {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }[];
+    groupCount: number;
+    colors?: string[] | undefined;
 }>;
 
 /**
@@ -7499,18 +9457,18 @@ export declare type ValidationJSON = z.infer<typeof ValidationJSONSchema>;
 
 export declare const ValidationJSONSchema: z.ZodObject<{
     mode: z.ZodEnum<["simple", "expression"]>;
-    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>>;
+    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">]>>>;
     expression: z.ZodOptional<z.ZodString>;
     variables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     mode: "simple" | "expression";
     expression?: string | undefined;
-    answers?: Record<string, string | number> | undefined;
+    answers?: Record<string, string | number | string[][]> | undefined;
     variables?: string[] | undefined;
 }, {
     mode: "simple" | "expression";
     expression?: string | undefined;
-    answers?: Record<string, string | number> | undefined;
+    answers?: Record<string, string | number | string[][]> | undefined;
     variables?: string[] | undefined;
 }>;
 
@@ -7627,6 +9585,80 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
     numerator: number | null;
     denominator: number | null;
     simplified: boolean;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"matcher">;
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"matcher-row">;
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"matcher-item">;
+            /** Item identifier (no pipe allowed) */
+            itemId: z.ZodString;
+            /** Display-only inline content */
+            content: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }, {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }, {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }>, "many">;
+    /** Optional color palette for the renderer (one color per answer group) */
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Number of answer groups — equals answers.length, stored here to avoid prop-drilling. */
+    groupCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "matcher";
+    rows: {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }[];
+    groupCount: number;
+    colors?: string[] | undefined;
+}, {
+    type: "matcher";
+    rows: {
+        type: "matcher-row";
+        items: {
+            type: "matcher-item";
+            itemId: string;
+            id: string;
+            content: any[];
+        }[];
+        id: string;
+    }[];
+    groupCount: number;
+    colors?: string[] | undefined;
 }>]>;
 
 export declare type WidgetRef = z.infer<typeof WidgetRefSchema>;
@@ -7655,12 +9687,14 @@ export declare const WidgetRenderer: default_2.FC<WidgetRendererProps>;
 export declare interface WidgetRendererProps {
     widget: WidgetJSON;
     widgetId: string;
-    value: string;
+    value: UserAnswerValue | undefined;
     values?: Record<string, string>;
     isDropped?: boolean;
     validationStatus?: ValidationStatus;
     droppedInputs?: Set<string>;
-    onChange: (widgetId: string, value: string, fromDrop?: boolean, sourceOptionId?: string) => void;
+    /** All widgets in the exercise — needed so MatcherWidget can resolve refs in its items. */
+    widgets?: Record<string, WidgetJSON>;
+    onChange: (widgetId: string, value: UserAnswerValue, fromDrop?: boolean, sourceOptionId?: string) => void;
     onInputFocus?: (widgetId: string) => void;
     onKeypadChange?: (value: string) => void;
 }
@@ -7677,7 +9711,7 @@ export declare interface WidgetValidation {
     /** The widget ID */
     widgetId: string;
     /** The user's input value */
-    userValue: string | number | undefined;
+    userValue: string | number | string[][] | undefined;
     /** Whether the input is correct */
     isCorrect: boolean;
     /** Optional error message (for debugging) */