@mathscan/math-exercise-engine 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2030 @@
+import { CstNode } from 'chevrotain';
+import { default as default_2 } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { ILexingError } from 'chevrotain';
+import { IRecognitionException } from 'chevrotain';
+import { IToken } from 'chevrotain';
+import { RefAttributes } from 'react';
+import { z } from 'zod';
+
+/**
+ * Compile DSL text directly to JSON (convenience function)
+ *
+ * This combines tokenize → parse → toAST → toJSON in one call.
+ *
+ * @param dsl - The DSL text to compile
+ * @returns The exercise JSON
+ * @throws LexerError if tokenization fails
+ * @throws ParseError if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const json = compile(`
+ *   QUESTION_TEXT["Solve"]
+ *   25 + W_S_I[name="x", length=2, answer="5"] = 30
+ *   WIDGET_ANSWER[type="simple"]
+ * `);
+ * ```
+ */
+export declare function compile(dsl: string): ExerciseJSON;
+
+/**
+ * Compile DSL and return both AST and JSON
+ *
+ * Useful when you need access to both representations.
+ *
+ * @param dsl - The DSL text to compile
+ * @returns Object containing both ast and json
+ */
+export declare function compileWithAST(dsl: string): {
+    ast: {
+        validation: {
+            type: "SimpleValidation";
+        } | {
+            type: "ExpressionValidation";
+            expression: string;
+        };
+        type: "ExerciseDocument";
+        lines: {
+            type: "LineBlock";
+            inlines: ({
+                value: string;
+                type: "FreeText";
+            } | {
+                type: "Space";
+            } | {
+                value: string;
+                type: "NumberText";
+                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;
+            })[];
+        }[];
+        question?: {
+            value: string;
+            type: "TextBlock";
+        } | undefined;
+        tools?: ({
+            type: "DragOptions";
+            options: string[];
+        } | {
+            type: "NumericKeypad";
+            includeDecimal: boolean;
+            includeNegative: boolean;
+        })[] | undefined;
+    };
+    json: {
+        validation: {
+            mode: "expression" | "simple";
+            expression?: string | undefined;
+            answers?: Record<string, string | number> | undefined;
+            variables?: string[] | undefined;
+        };
+        version: "2.0";
+        layout: any[];
+        widgets: Record<string, {
+            length: number;
+            type: "inline-input";
+            inputType: "string";
+        } | {
+            type: "inline-input";
+            inputType: "numeric";
+            digits: number;
+        } | {
+            type: "drag-options";
+            options: string[];
+        } | {
+            type: "numeric-keypad";
+            includeDecimal: boolean;
+        }>;
+        id?: string | undefined;
+        meta?: {
+            createdAt?: string | undefined;
+            author?: string | undefined;
+            tags?: string[] | undefined;
+            difficulty?: number | undefined;
+        } | undefined;
+    };
+};
+
+/**
+ * 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: z.infer<typeof LineBlockSchema>[], 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 free text inline element
+ */
+export declare function createFreeText(value: string): FreeTextInline;
+
+/**
+ * @deprecated Use createStringInput or createNumericInput instead
+ */
+export declare function createInlineInput(name: string, inputType: "string" | "numeric", lengthOrDigits: number, answer?: string | number): InlineInputWidget;
+
+/**
+ * Create a line block
+ */
+export declare function createLineBlock(inlines: any[]): LineBlock;
+
+/**
+ * Create a number text inline element
+ */
+export declare function createNumberText(value: string, highlight?: [number, number]): NumberTextInline;
+
+/**
+ * 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(includeDecimal?: boolean, includeNegative?: 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: "NumberText", value: "151 000", highlight: [0, 3] },
+ *         { type: "InlineInput", name: "x", length: 1 },
+ *         { type: "NumberText", 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.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<"NumberText">;
+            value: z.ZodString;
+            highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            type: "NumberText";
+            highlight?: [number, number] | undefined;
+        }, {
+            value: string;
+            type: "NumberText";
+            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;
+        }>]>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "LineBlock";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "NumberText";
+            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: "LineBlock";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "NumberText";
+            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;
+        })[];
+    }>, "many">;
+    tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"DragOptions">;
+        options: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "DragOptions";
+        options: string[];
+    }, {
+        type: "DragOptions";
+        options: string[];
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"NumericKeypad">;
+        includeDecimal: z.ZodDefault<z.ZodBoolean>;
+        includeNegative: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "NumericKeypad";
+        includeDecimal: boolean;
+        includeNegative: boolean;
+    }, {
+        type: "NumericKeypad";
+        includeDecimal?: boolean | undefined;
+        includeNegative?: boolean | undefined;
+    }>]>, "many">>;
+    validation: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"SimpleValidation">;
+    }, "strip", z.ZodTypeAny, {
+        type: "SimpleValidation";
+    }, {
+        type: "SimpleValidation";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ExpressionValidation">;
+        expression: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "ExpressionValidation";
+        expression: string;
+    }, {
+        type: "ExpressionValidation";
+        expression: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    validation: {
+        type: "SimpleValidation";
+    } | {
+        type: "ExpressionValidation";
+        expression: string;
+    };
+    type: "ExerciseDocument";
+    lines: {
+        type: "LineBlock";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "NumberText";
+            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;
+        })[];
+    }[];
+    question?: {
+        value: string;
+        type: "TextBlock";
+    } | undefined;
+    tools?: ({
+        type: "DragOptions";
+        options: string[];
+    } | {
+        type: "NumericKeypad";
+        includeDecimal: boolean;
+        includeNegative: boolean;
+    })[] | undefined;
+}, {
+    validation: {
+        type: "SimpleValidation";
+    } | {
+        type: "ExpressionValidation";
+        expression: string;
+    };
+    type: "ExerciseDocument";
+    lines: {
+        type: "LineBlock";
+        inlines: ({
+            value: string;
+            type: "FreeText";
+        } | {
+            type: "Space";
+        } | {
+            value: string;
+            type: "NumberText";
+            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;
+        })[];
+    }[];
+    question?: {
+        value: string;
+        type: "TextBlock";
+    } | undefined;
+    tools?: ({
+        type: "DragOptions";
+        options: string[];
+    } | {
+        type: "NumericKeypad";
+        includeDecimal?: boolean | undefined;
+        includeNegative?: boolean | undefined;
+    })[] | undefined;
+}>;
+
+export declare type ExerciseJSON = z.infer<typeof ExerciseJSONSchema>;
+
+export declare const ExerciseJSONSchema: z.ZodObject<{
+    version: z.ZodLiteral<"2.0">;
+    id: z.ZodOptional<z.ZodString>;
+    layout: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
+    widgets: z.ZodRecord<z.ZodString, z.ZodUnion<[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;
+    }>]>, 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[];
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"numeric-keypad">;
+        includeDecimal: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }, {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>]>>;
+    validation: z.ZodObject<{
+        mode: z.ZodEnum<["simple", "expression"]>;
+        answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>>;
+        expression: z.ZodOptional<z.ZodString>;
+        variables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    }, {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    }>;
+    meta: z.ZodOptional<z.ZodObject<{
+        createdAt: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        difficulty: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    }, {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    validation: {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    };
+    version: "2.0";
+    layout: any[];
+    widgets: Record<string, {
+        length: number;
+        type: "inline-input";
+        inputType: "string";
+    } | {
+        type: "inline-input";
+        inputType: "numeric";
+        digits: number;
+    } | {
+        type: "drag-options";
+        options: string[];
+    } | {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>;
+    id?: string | undefined;
+    meta?: {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    } | undefined;
+}, {
+    validation: {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    };
+    version: "2.0";
+    layout: any[];
+    widgets: Record<string, {
+        length: number;
+        type: "inline-input";
+        inputType: "string";
+    } | {
+        type: "inline-input";
+        inputType: "numeric";
+        digits: number;
+    } | {
+        type: "drag-options";
+        options: string[];
+    } | {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>;
+    id?: string | undefined;
+    meta?: {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    } | undefined;
+}>;
+
+export declare type ExerciseMeta = z.infer<typeof ExerciseMetaSchema>;
+
+export declare const ExerciseMetaSchema: z.ZodObject<{
+    createdAt: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    difficulty: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    createdAt?: string | undefined;
+    author?: string | undefined;
+    tags?: string[] | undefined;
+    difficulty?: number | undefined;
+}, {
+    createdAt?: string | undefined;
+    author?: string | undefined;
+    tags?: string[] | undefined;
+    difficulty?: number | undefined;
+}>;
+
+/**
+ * Main renderer component - the contract for rendering exercises.
+ *
+ * This component is DUMB - it only collects values and passes them up.
+ * The parent decides correctness via validation.
+ */
+export declare const ExerciseRenderer: ForwardRefExoticComponent<ExerciseRendererProps & RefAttributes<ExerciseRendererRef>>;
+
+export declare interface ExerciseRendererProps {
+    json: ExerciseJSON;
+    onSubmit?: (values: Record<string, string>) => void;
+    onChange?: (values: Record<string, string>) => void;
+    showSubmitButton?: boolean;
+    className?: string;
+}
+
+export declare interface ExerciseRendererRef {
+    submit: () => ValidationResult;
+    getValues: () => Record<string, string>;
+    reset: () => void;
+    focusFirstInput: () => void;
+}
+
+export declare type ExpressionValidation = z.infer<typeof ExpressionValidationSchema>;
+
+/**
+ * Expression validation schema - validates using a boolean expression
+ *
+ * The expression can reference widget values by name.
+ * Example: "a + b === 10"
+ *
+ * @example
+ * {
+ *   type: "ExpressionValidation",
+ *   expression: "a + b === 10"
+ * }
+ */
+export declare const ExpressionValidationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ExpressionValidation">;
+    expression: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ExpressionValidation";
+    expression: string;
+}, {
+    type: "ExpressionValidation";
+    expression: string;
+}>;
+
+/**
+ * Extract variable names from an expression
+ *
+ * @param expression - The expression to analyze
+ * @param validVariables - Optional list of valid variable names to filter by (e.g., from exercise widgets)
+ * @returns Array of variable names
+ */
+export declare function extractExpressionVariables(expression: string, validVariables?: string[]): string[];
+
+/**
+ * Check if any combination of values can satisfy the expression
+ * (useful for debugging/testing exercises)
+ *
+ * @param expression - The expression to check
+ * @param ranges - Value ranges for each variable
+ * @returns First valid combination found, or null
+ */
+export declare function findValidCombination(expression: string, ranges: Record<string, {
+    min: number;
+    max: number;
+    step?: number;
+}>): Record<string, number> | null;
+
+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";
+}>;
+
+/**
+ * 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";
+    id: string;
+    items: any[];
+}, {
+    type: "group";
+    id: string;
+    items: any[];
+}>;
+
+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>;
+
+/**
+ * Union of all inline element types
+ */
+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<"NumberText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "NumberText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "NumberText";
+    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;
+}>]>]>;
+
+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 isFreeText(value: unknown): value is FreeTextInline;
+
+/**
+ * Type guard for GroupItem
+ */
+export declare function isGroupItem(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'group';
+}>;
+
+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';
+}>;
+
+/**
+ * Type guard for NumberText
+ */
+export declare function isNumberText(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'number-text';
+}>;
+
+/**
+ * @deprecated Use isInlineInputJSON instead
+ */
+export declare function isNumericInputJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'inline-input';
+}>;
+
+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';
+}>;
+
+export declare function isSimpleValidation(value: unknown): value is SimpleValidation;
+
+export declare function isSpace(value: unknown): value is SpaceInline;
+
+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;
+
+/**
+ * @deprecated Use isWidgetRef instead
+ */
+export declare function isWidgetPlaceholder(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'widget-ref';
+}>;
+
+/**
+ * Type guard for WidgetRef
+ */
+export declare function isWidgetRef(item: LayoutItem): item is Extract<LayoutItem, {
+    type: 'widget-ref';
+}>;
+
+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>;
+    onChange: (widgetId: string, value: string, fromDrop?: boolean) => 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>;
+
+/**
+ * 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: "NumberText", value: "151 000", highlight: [0, 3] },
+ *     { type: "InlineInput", name: "x", length: 1 },
+ *     { type: "NumberText", value: "54 000", highlight: [0, 3] }
+ *   ]
+ * }
+ */
+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<"NumberText">;
+        value: z.ZodString;
+        highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "NumberText";
+        highlight?: [number, number] | undefined;
+    }, {
+        value: string;
+        type: "NumberText";
+        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;
+    }>]>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "LineBlock";
+    inlines: ({
+        value: string;
+        type: "FreeText";
+    } | {
+        type: "Space";
+    } | {
+        value: string;
+        type: "NumberText";
+        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: "LineBlock";
+    inlines: ({
+        value: string;
+        type: "FreeText";
+    } | {
+        type: "Space";
+    } | {
+        value: string;
+        type: "NumberText";
+        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;
+    })[];
+}>;
+
+export declare type Linebreak = z.infer<typeof LinebreakSchema>;
+
+export declare const LinebreakSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"linebreak">;
+}, "strip", z.ZodTypeAny, {
+    type: "linebreak";
+    id: string;
+}, {
+    type: "linebreak";
+    id: string;
+}>;
+
+export declare type NumberText = z.infer<typeof NumberTextSchema>;
+
+export declare type NumberTextInline = z.infer<typeof NumberTextInlineSchema>;
+
+/**
+ * Number text inline schema - styled numbers with optional highlighting
+ *
+ * highlight: [start, end] character positions for visual emphasis
+ *
+ * @example
+ * {
+ *   type: "NumberText",
+ *   value: "151 000",
+ *   highlight: [0, 3]  // Highlights "151"
+ * }
+ */
+export declare const NumberTextInlineSchema: z.ZodObject<{
+    type: z.ZodLiteral<"NumberText">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "NumberText";
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "NumberText";
+    highlight?: [number, number] | undefined;
+}>;
+
+export declare const NumberTextSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"number-text">;
+    value: z.ZodString;
+    highlight: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "number-text";
+    id: string;
+    highlight?: [number, number] | undefined;
+}, {
+    value: string;
+    type: "number-text";
+    id: string;
+    highlight?: [number, number] | undefined;
+}>;
+
+export declare type NumericKeypadJSON = z.infer<typeof NumericKeypadJSONSchema>;
+
+export declare const NumericKeypadJSONSchema: z.ZodObject<{
+    type: z.ZodLiteral<"numeric-keypad">;
+    includeDecimal: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}, {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}>;
+
+export declare type NumericKeypadTool = z.infer<typeof NumericKeypadToolSchema>;
+
+/**
+ * Numeric keypad tool schema - on-screen number pad
+ *
+ * Use cases:
+ * - Touch-friendly number entry
+ * - Restricting input to numbers only
+ * - Consistent cross-device experience
+ *
+ * @example
+ * {
+ *   type: "NumericKeypad",
+ *   includeDecimal: false,
+ *   includeNegative: true
+ * }
+ */
+export declare const NumericKeypadToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"NumericKeypad">;
+    includeDecimal: z.ZodDefault<z.ZodBoolean>;
+    includeNegative: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "NumericKeypad";
+    includeDecimal: boolean;
+    includeNegative: boolean;
+}, {
+    type: "NumericKeypad";
+    includeDecimal?: boolean | undefined;
+    includeNegative?: boolean | undefined;
+}>;
+
+export declare type OperatorItem = z.infer<typeof OperatorItemSchema>;
+
+export declare const OperatorItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"operator">;
+    operator: z.ZodEnum<["+", "-", "×", "÷", "=", "<", ">", "?"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "operator";
+    id: string;
+    operator: "+" | "-" | "×" | "÷" | "=" | "<" | ">" | "?";
+}, {
+    type: "operator";
+    id: string;
+    operator: "+" | "-" | "×" | "÷" | "=" | "<" | ">" | "?";
+}>;
+
+export declare const OperatorSchema: z.ZodEnum<["+", "-", "×", "÷", "=", "<", ">", "?"]>;
+
+/**
+ * Parse DSL tokens into CST
+ */
+export declare function parse(tokens: IToken[]): CstNode;
+
+/**
+ * Error thrown when parser fails to parse tokens
+ */
+export declare class ParseError extends EngineError {
+    readonly parseErrors: IRecognitionException[];
+    readonly positions: SourcePosition[];
+    constructor(errors: IRecognitionException[]);
+}
+
+/**
+ * Parse DSL tokens into CST (safe version - returns errors instead of throwing)
+ */
+export declare function parseSafe(tokens: IToken[]): {
+    success: true;
+    cst: CstNode;
+    error?: undefined;
+} | {
+    success: false;
+    error: unknown;
+    cst?: undefined;
+};
+
+export declare type QuestionText = z.infer<typeof QuestionTextSchema>;
+
+export declare const QuestionTextSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"question-text">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "question-text";
+    id: string;
+}, {
+    value: string;
+    type: "question-text";
+    id: string;
+}>;
+
+/**
+ * DOM helper for quick usage / demos.
+ *
+ * This couples the engine to DOM + React root creation.
+ * For production use, prefer <ExerciseRenderer /> directly in your React tree.
+ *
+ * @example
+ * ```typescript
+ * import { compile, renderExercise } from 'math-exercise-engine';
+ *
+ * const json = compile(dsl);
+ * const unmount = renderExercise({
+ *   container: '#app',
+ *   json,
+ *   onSubmit: (values) => {
+ *     // Parent decides correctness
+ *     const result = validate(json, values);
+ *     console.log(result.isCorrect);
+ *   }
+ * });
+ *
+ * // Later: unmount()
+ * ```
+ */
+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;
+    showSubmitButton?: boolean;
+    className?: string;
+}
+
+export declare type SimpleValidation = z.infer<typeof SimpleValidationSchema>;
+
+/**
+ * Simple validation schema - direct answer matching
+ *
+ * Each input has a predetermined correct answer.
+ * No complex expressions or calculations.
+ *
+ * @example
+ * {
+ *   type: "SimpleValidation"
+ * }
+ *
+ * Note: Actual answer values are stored separately (in widget definitions)
+ */
+export declare const SimpleValidationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SimpleValidation">;
+}, "strip", z.ZodTypeAny, {
+    type: "SimpleValidation";
+}, {
+    type: "SimpleValidation";
+}>;
+
+/**
+ * Source position information for error reporting
+ */
+export declare interface SourcePosition {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+}
+
+export declare type SpaceInline = z.infer<typeof SpaceInlineSchema>;
+
+/**
+ * Space inline schema - explicit spacing element
+ *
+ * Represents one or more consecutive spaces as a single space element.
+ * This allows for deterministic and explicit control over spacing in the layout.
+ *
+ * @example
+ * { type: "Space" }
+ */
+export declare const SpaceInlineSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Space">;
+}, "strip", z.ZodTypeAny, {
+    type: "Space";
+}, {
+    type: "Space";
+}>;
+
+export declare type TextBlock = z.infer<typeof TextBlockSchema>;
+
+/**
+ * Text block schema - represents the question/instruction
+ *
+ * @example
+ * {
+ *   type: "TextBlock",
+ *   value: "أقارن كل عددين باستعمال الرمر المناسب"
+ * }
+ */
+export declare const TextBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"TextBlock">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "TextBlock";
+}, {
+    value: string;
+    type: "TextBlock";
+}>;
+
+export declare type TextItem = z.infer<typeof TextItemSchema>;
+
+export declare const TextItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"text">;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "text";
+    id: string;
+}, {
+    value: string;
+    type: "text";
+    id: string;
+}>;
+
+/**
+ * Transform CST to AST
+ */
+export declare function toAST(cst: any): ExerciseDocument;
+
+/**
+ * Transform AST to JSON
+ *
+ * The JSON format is what gets consumed by renderers and validators
+ */
+export declare function toJSON(ast: ExerciseDocument): ExerciseJSON;
+
+/**
+ * Tokenize a DSL input string
+ *
+ * @param input - The DSL text to tokenize
+ * @returns Array of tokens
+ * @throws LexerError if tokenization fails
+ */
+export declare function tokenize(input: string): IToken[];
+
+/**
+ * Result of tokenization
+ */
+declare interface TokenizeResult {
+    tokens: IToken[];
+    errors: ILexingError[];
+}
+
+/**
+ * Tokenize without throwing - returns both tokens and errors
+ * Useful for error-tolerant parsing (e.g., in editors)
+ */
+export declare function tokenizeSafe(input: string): TokenizeResult;
+
+export declare type ToolNode = z.infer<typeof ToolNodeSchema>;
+
+/**
+ * Union of all tool types
+ */
+export declare const ToolNodeSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"DragOptions">;
+    options: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "DragOptions";
+    options: string[];
+}, {
+    type: "DragOptions";
+    options: string[];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"NumericKeypad">;
+    includeDecimal: z.ZodDefault<z.ZodBoolean>;
+    includeNegative: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "NumericKeypad";
+    includeDecimal: boolean;
+    includeNegative: boolean;
+}, {
+    type: "NumericKeypad";
+    includeDecimal?: boolean | undefined;
+    includeNegative?: boolean | undefined;
+}>]>;
+
+/**
+ * Error thrown during AST transformation
+ */
+export declare class TransformError extends EngineError {
+    readonly position?: SourcePosition;
+    constructor(message: string, position?: SourcePosition);
+}
+
+/**
+ * Validate user inputs against an exercise
+ *
+ * This is the main entry point for validation. It automatically
+ * dispatches to the correct validation mode based on the exercise.
+ *
+ * @param exercise - The exercise JSON
+ * @param userInputs - User's answers keyed by widget ID
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validate(exercise, { a: 10, b: 20 });
+ * if (result.isCorrect) {
+ *   console.log('Correct!');
+ * } else {
+ *   console.log('Try again');
+ * }
+ * ```
+ */
+export declare function validate(exercise: ExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+
+/**
+ * Validate that an expression will return a boolean
+ *
+ * @param expression - The expression to check
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validateBooleanExpression(expression: string): string | null;
+
+/**
+ * Validate an exercise JSON object at runtime
+ *
+ * @param data - The data to validate
+ * @returns Parsed and validated exercise JSON
+ * @throws ZodError if validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const validated = validateExerciseJSON(unknownData);
+ *   console.log('Valid exercise:', validated);
+ * } catch (error) {
+ *   console.error('Validation failed:', error);
+ * }
+ * ```
+ */
+export declare function validateExerciseJSON(data: unknown): {
+    validation: {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    };
+    version: "2.0";
+    layout: any[];
+    widgets: Record<string, {
+        length: number;
+        type: "inline-input";
+        inputType: "string";
+    } | {
+        type: "inline-input";
+        inputType: "numeric";
+        digits: number;
+    } | {
+        type: "drag-options";
+        options: string[];
+    } | {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>;
+    id?: string | undefined;
+    meta?: {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    } | undefined;
+};
+
+/**
+ * Safely validate an exercise JSON object at runtime
+ *
+ * @param data - The data to validate
+ * @returns Success result with data or error result
+ *
+ * @example
+ * ```typescript
+ * const result = validateExerciseJSONSafe(unknownData);
+ * if (result.success) {
+ *   console.log('Valid exercise:', result.data);
+ * } else {
+ *   console.error('Validation errors:', result.error.errors);
+ * }
+ * ```
+ */
+export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseReturnType<{
+    validation: {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    };
+    version: "2.0";
+    layout: any[];
+    widgets: Record<string, {
+        length: number;
+        type: "inline-input";
+        inputType: "string";
+    } | {
+        type: "inline-input";
+        inputType: "numeric";
+        digits: number;
+    } | {
+        type: "drag-options";
+        options: string[];
+    } | {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>;
+    id?: string | undefined;
+    meta?: {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    } | undefined;
+}, {
+    validation: {
+        mode: "expression" | "simple";
+        expression?: string | undefined;
+        answers?: Record<string, string | number> | undefined;
+        variables?: string[] | undefined;
+    };
+    version: "2.0";
+    layout: any[];
+    widgets: Record<string, {
+        length: number;
+        type: "inline-input";
+        inputType: "string";
+    } | {
+        type: "inline-input";
+        inputType: "numeric";
+        digits: number;
+    } | {
+        type: "drag-options";
+        options: string[];
+    } | {
+        type: "numeric-keypad";
+        includeDecimal: boolean;
+    }>;
+    id?: string | undefined;
+    meta?: {
+        createdAt?: string | undefined;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+        difficulty?: number | undefined;
+    } | undefined;
+}>;
+
+/**
+ * Validate using expression mode
+ *
+ * @param exercise - The exercise JSON
+ * @param userInputs - User's answers keyed by widget ID (variable names)
+ * @returns Validation result
+ */
+export declare function validateExpression(exercise: ExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+
+/**
+ * Check if user inputs are valid (proper format, etc.)
+ * without checking correctness
+ *
+ * @param exercise - The exercise JSON
+ * @param userInputs - User's answers
+ * @returns Object with widgetId -> error message (empty if all valid)
+ */
+export declare function validateInputFormats(exercise: ExerciseJSON, userInputs: Record<string, string | number>): Record<string, string>;
+
+/**
+ * Validate using simple mode (predetermined answers)
+ *
+ * @param exercise - The exercise JSON
+ * @param userInputs - User's answers keyed by widget ID
+ * @returns Validation result
+ */
+export declare function validateSimple(exercise: ExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+
+/**
+ * Validate a widget JSON object at runtime
+ *
+ * @param data - The data to validate
+ * @returns Parsed and validated widget JSON
+ * @throws ZodError if validation fails
+ */
+export declare function validateWidgetJSON(data: unknown): {
+    length: number;
+    type: "inline-input";
+    inputType: "string";
+} | {
+    type: "inline-input";
+    inputType: "numeric";
+    digits: number;
+} | {
+    type: "drag-options";
+    options: string[];
+} | {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+};
+
+/**
+ * Safely validate a widget JSON object at runtime
+ *
+ * @param data - The data to validate
+ * @returns Success result with data or error result
+ */
+export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturnType<{
+    length: number;
+    type: "inline-input";
+    inputType: "string";
+} | {
+    type: "inline-input";
+    inputType: "numeric";
+    digits: number;
+} | {
+    type: "drag-options";
+    options: string[];
+} | {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}, {
+    length: number;
+    type: "inline-input";
+    inputType: "string";
+} | {
+    type: "inline-input";
+    inputType: "numeric";
+    digits: number;
+} | {
+    type: "drag-options";
+    options: string[];
+} | {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}>;
+
+/**
+ * Error thrown during validation
+ */
+export declare class ValidationError extends EngineError {
+    readonly details: Record<string, string>;
+    constructor(message: string, details?: Record<string, string>);
+}
+
+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]>>>;
+    expression: z.ZodOptional<z.ZodString>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    mode: "expression" | "simple";
+    expression?: string | undefined;
+    answers?: Record<string, string | number> | undefined;
+    variables?: string[] | undefined;
+}, {
+    mode: "expression" | "simple";
+    expression?: string | undefined;
+    answers?: Record<string, string | number> | undefined;
+    variables?: string[] | undefined;
+}>;
+
+export declare type ValidationNode = z.infer<typeof ValidationNodeSchema>;
+
+/**
+ * Union of all validation types
+ */
+export declare const ValidationNodeSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"SimpleValidation">;
+}, "strip", z.ZodTypeAny, {
+    type: "SimpleValidation";
+}, {
+    type: "SimpleValidation";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ExpressionValidation">;
+    expression: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ExpressionValidation";
+    expression: string;
+}, {
+    type: "ExpressionValidation";
+    expression: string;
+}>]>;
+
+/**
+ * Complete validation result
+ */
+export declare interface ValidationResult {
+    /** Whether all inputs are correct */
+    isCorrect: boolean;
+    /** Per-widget validation details */
+    details: Record<string, WidgetValidation>;
+    /** Numeric score (0-1) for partial grading */
+    score?: number;
+    /** The expression that was evaluated (expression mode only) */
+    expression?: string;
+    /** The scope used for evaluation (expression mode only, debugging) */
+    scope?: Record<string, number>;
+    /** Error message if validation failed */
+    error?: string;
+}
+
+export declare type WidgetJSON = z.infer<typeof WidgetJSONSchema>;
+
+export declare const WidgetJSONSchema: z.ZodUnion<[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;
+}>]>, 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[];
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"numeric-keypad">;
+    includeDecimal: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}, {
+    type: "numeric-keypad";
+    includeDecimal: boolean;
+}>]>;
+
+declare type WidgetRef = z.infer<typeof WidgetRefSchema>;
+export { WidgetRef as WidgetPlaceholder }
+export { WidgetRef }
+
+export declare const WidgetRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"widget-ref">;
+    widgetId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "widget-ref";
+    id: string;
+    widgetId: string;
+}, {
+    type: "widget-ref";
+    id: string;
+    widgetId: string;
+}>;
+
+/**
+ * WidgetRenderer - Router component that delegates to specific widget components
+ * This is a thin layer that just switches between different widget types
+ * Each widget handles its own behavior (DnD, buttons, input, etc.)
+ */
+export declare const WidgetRenderer: default_2.FC<WidgetRendererProps>;
+
+export declare interface WidgetRendererProps {
+    widget: WidgetJSON;
+    widgetId: string;
+    value: string;
+    isDropped?: boolean;
+    onChange: (widgetId: string, value: string, fromDrop?: boolean) => void;
+}
+
+/**
+ * Validation Result Types
+ *
+ * These define the output of validation operations.
+ */
+/**
+ * Result of validating a single widget
+ */
+export declare interface WidgetValidation {
+    /** The widget ID */
+    widgetId: string;
+    /** The user's input value */
+    userValue: string | number | undefined;
+    /** Whether the input is correct */
+    isCorrect: boolean;
+    /** Optional error message (for debugging) */
+    error?: string;
+}
+
+export { }