@mathscan/math-exercise-engine 1.1.6 → 1.1.8

package/dist/index.d.ts

@@ -77,6 +77,12 @@ export declare const AST_TYPES: {
     readonly RADIO_OPTIONS: "RadioOptions";
     /** Numeric keypad input tool */
     readonly NUMERIC_KEYPAD: "NumericKeypad";
+    /** Geometry ruler tool */
+    readonly GEOMETRY_RULER: "GeometryRuler";
+    /** Geometry protractor tool */
+    readonly GEOMETRY_PROTRACTOR: "GeometryProtractor";
+    /** Geometry set square tool */
+    readonly GEOMETRY_SET_SQUARE: "GeometrySetSquare";
     /** Simple answer matching validation */
     readonly SIMPLE_VALIDATION: "SimpleValidation";
     /** Expression-based validation */
@@ -874,6 +880,15 @@ export declare function compileWithAST(dsl: string): {
             style?: "diamond" | "classic" | undefined;
             includeOperators?: boolean | undefined;
             includeDecimal?: boolean | undefined;
+        } | {
+            type: "GeometryRuler";
+            size: number;
+        } | {
+            type: "GeometryProtractor";
+            size: number;
+        } | {
+            type: "GeometrySetSquare";
+            size: number;
         })[] | undefined;
     };
     json: {
@@ -946,6 +961,15 @@ export declare function compileWithAST(dsl: string): {
             orientation?: "horizontal" | "vertical" | undefined;
             label?: string | undefined;
             size?: number | undefined;
+        } | {
+            type: "ruler";
+            size?: number | undefined;
+        } | {
+            type: "protractor";
+            size?: number | undefined;
+        } | {
+            type: "set-square";
+            size?: number | undefined;
         }>;
         validation?: {
             mode: "simple" | "expression" | "mixed";
@@ -5442,6 +5466,12 @@ export declare function createNumericKeypad(includeOperators?: boolean, includeD
 
 export declare function createPairMatcherBlock(name: string, topItems: MatcherItem[], bottomItems: MatcherItem[], answers: [string, string][]): PairMatcherBlock;
 
+export declare function createProtractorTool(size?: number): ProtractorTool;
+
+export declare function createRulerTool(size?: number): RulerTool;
+
+export declare function createSetSquareTool(size?: number): SetSquareTool;
+
 /**
  * Create a simple validation node
  */
@@ -10183,6 +10213,33 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         style?: "diamond" | "classic" | undefined;
         includeOperators?: boolean | undefined;
         includeDecimal?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"GeometryRuler">;
+        size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "GeometryRuler";
+        size: number;
+    }, {
+        type: "GeometryRuler";
+        size?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"GeometryProtractor">;
+        size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "GeometryProtractor";
+        size: number;
+    }, {
+        type: "GeometryProtractor";
+        size?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"GeometrySetSquare">;
+        size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "GeometrySetSquare";
+        size: number;
+    }, {
+        type: "GeometrySetSquare";
+        size?: number | undefined;
     }>]>, "many">>;
     validation: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"SimpleValidation">;
@@ -10738,6 +10795,15 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         style?: "diamond" | "classic" | undefined;
         includeOperators?: boolean | undefined;
         includeDecimal?: boolean | undefined;
+    } | {
+        type: "GeometryRuler";
+        size: number;
+    } | {
+        type: "GeometryProtractor";
+        size: number;
+    } | {
+        type: "GeometrySetSquare";
+        size: number;
     })[] | undefined;
 }, {
     type: "ExerciseDocument";
@@ -11268,6 +11334,15 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         style?: "diamond" | "classic" | undefined;
         includeOperators?: boolean | undefined;
         includeDecimal?: boolean | undefined;
+    } | {
+        type: "GeometryRuler";
+        size?: number | undefined;
+    } | {
+        type: "GeometryProtractor";
+        size?: number | undefined;
+    } | {
+        type: "GeometrySetSquare";
+        size?: number | undefined;
     })[] | undefined;
 }>, {
     type: "ExerciseDocument";
@@ -11798,6 +11873,15 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         style?: "diamond" | "classic" | undefined;
         includeOperators?: boolean | undefined;
         includeDecimal?: boolean | undefined;
+    } | {
+        type: "GeometryRuler";
+        size: number;
+    } | {
+        type: "GeometryProtractor";
+        size: number;
+    } | {
+        type: "GeometrySetSquare";
+        size: number;
     })[] | undefined;
 }, {
     type: "ExerciseDocument";
@@ -12328,6 +12412,15 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         style?: "diamond" | "classic" | undefined;
         includeOperators?: boolean | undefined;
         includeDecimal?: boolean | undefined;
+    } | {
+        type: "GeometryRuler";
+        size?: number | undefined;
+    } | {
+        type: "GeometryProtractor";
+        size?: number | undefined;
+    } | {
+        type: "GeometrySetSquare";
+        size?: number | undefined;
     })[] | undefined;
 }>;
 
@@ -12617,6 +12710,33 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ruler">;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ruler";
+        size?: number | undefined;
+    }, {
+        type: "ruler";
+        size?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"protractor">;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: "protractor";
+        size?: number | undefined;
+    }, {
+        type: "protractor";
+        size?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"set-square">;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: "set-square";
+        size?: number | undefined;
+    }, {
+        type: "set-square";
+        size?: number | undefined;
     }>]>>;
     validation: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<["simple", "expression", "mixed"]>;
@@ -12720,6 +12840,15 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    } | {
+        type: "ruler";
+        size?: number | undefined;
+    } | {
+        type: "protractor";
+        size?: number | undefined;
+    } | {
+        type: "set-square";
+        size?: number | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -12804,6 +12933,15 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    } | {
+        type: "ruler";
+        size?: number | undefined;
+    } | {
+        type: "protractor";
+        size?: number | undefined;
+    } | {
+        type: "set-square";
+        size?: number | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -12853,11 +12991,17 @@ export declare interface ExerciseRendererProps {
     onChange?: (values: Record<string, UserAnswerValue>) => void;
     showSubmitButton?: boolean;
     className?: string;
+    /** Master on/off for interaction sounds (default true). */
+    soundEnabled?: boolean;
+    /** Maps sound events → URL or callback. Omitted events stay silent. */
+    sounds?: SoundConfig;
 }
 
 export declare interface ExerciseRendererRef {
     submit: () => ValidationResult;
     getValues: () => Record<string, UserAnswerValue>;
+    /** Fill status of the answerable inputs — caller decides when to block submit. */
+    getCompletion: () => InputCompletion;
     reset: () => void;
     focusFirstInput: () => void;
 }
@@ -13004,6 +13148,16 @@ export declare const FreeTextInlineSchema: z.ZodObject<{
     type: "FreeText";
 }>;
 
+/**
+ * List every widget the exercise expects an answer for (simple answers,
+ * expression variables, or both in mixed mode). Empty when the exercise has
+ * no validation (display-only / hint exercises).
+ *
+ * @param exercise - The exercise JSON
+ * @returns Array of answerable widget IDs
+ */
+export declare function getAnswerableInputs(exercise: ExerciseJSON): string[];
+
 export declare function getFractionKey(widgetId: string, part: FractionPart): string;
 
 /**
@@ -13531,6 +13685,22 @@ export declare const InlineNodeSchema: z.ZodUnion<[z.ZodObject<{
     snap?: number | undefined;
 }>]>]>;
 
+/** Snapshot of how many answerable inputs are currently filled. */
+export declare interface InputCompletion {
+    /** Number of widgets the exercise expects an answer for (0 = display-only). */
+    total: number;
+    /** How many of those currently have a usable value. */
+    filled: number;
+    /** Widget IDs still empty. */
+    missing: string[];
+    /** Widget IDs that have a value. */
+    filledIds: string[];
+    /** true when there is at least one input AND none are missing. */
+    isComplete: boolean;
+    /** true when at least one input has a value. */
+    isAnyFilled: boolean;
+}
+
 /**
  * Type guard for BoldText
  */
@@ -13660,6 +13830,15 @@ export declare function isPairMatcherBlock(value: unknown): value is PairMatcher
 
 export declare function isPairMatcherWidget(widget: WidgetJSON): widget is PairMatcherWidgetJSON;
 
+export declare function isProtractorTool(value: unknown): value is ProtractorTool;
+
+/**
+ * Type guard for ProtractorWidgetJSON
+ */
+export declare function isProtractorWidget(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'protractor';
+}>;
+
 /**
  * Type guard for QuestionText
  */
@@ -13674,6 +13853,24 @@ export declare function isRadioOptionsJSON(widget: WidgetJSON): widget is Extrac
     type: 'radio-options';
 }>;
 
+export declare function isRulerTool(value: unknown): value is RulerTool;
+
+/**
+ * Type guard for RulerWidgetJSON
+ */
+export declare function isRulerWidget(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'ruler';
+}>;
+
+export declare function isSetSquareTool(value: unknown): value is SetSquareTool;
+
+/**
+ * Type guard for SetSquareWidgetJSON
+ */
+export declare function isSetSquareWidget(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'set-square';
+}>;
+
 export declare function isSimpleValidation(value: unknown): value is SimpleValidation;
 
 export declare function isSpace(value: unknown): value is SpaceInline;
@@ -13829,6 +14026,12 @@ export declare const JSON_TYPES: {
     readonly FRACTION: "fraction";
     /** Visual fraction widget */
     readonly VISUAL_FRACTION: "visual-fraction";
+    /** Ruler geometry tool widget */
+    readonly RULER: "ruler";
+    /** Protractor geometry tool widget */
+    readonly PROTRACTOR: "protractor";
+    /** Set square geometry tool widget */
+    readonly SET_SQUARE: "set-square";
 };
 
 /**
@@ -18811,6 +19014,32 @@ export declare function parseSafe(tokens: IToken[]): {
     cst?: undefined;
 };
 
+export declare type ProtractorTool = z.infer<typeof ProtractorToolSchema>;
+
+export declare const ProtractorToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"GeometryProtractor">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryProtractor";
+    size: number;
+}, {
+    type: "GeometryProtractor";
+    size?: number | undefined;
+}>;
+
+export declare type ProtractorWidgetJSON = z.infer<typeof ProtractorWidgetSchema>;
+
+export declare const ProtractorWidgetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"protractor">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "protractor";
+    size?: number | undefined;
+}, {
+    type: "protractor";
+    size?: number | undefined;
+}>;
+
 export declare type QuestionText = z.infer<typeof QuestionTextSchema>;
 
 export declare const QuestionTextSchema: z.ZodObject<{
@@ -18905,6 +19134,58 @@ export declare interface RenderOptions {
     className?: string;
 }
 
+export declare type RulerTool = z.infer<typeof RulerToolSchema>;
+
+export declare const RulerToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"GeometryRuler">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryRuler";
+    size: number;
+}, {
+    type: "GeometryRuler";
+    size?: number | undefined;
+}>;
+
+export declare type RulerWidgetJSON = z.infer<typeof RulerWidgetSchema>;
+
+export declare const RulerWidgetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ruler">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "ruler";
+    size?: number | undefined;
+}, {
+    type: "ruler";
+    size?: number | undefined;
+}>;
+
+export declare type SetSquareTool = z.infer<typeof SetSquareToolSchema>;
+
+export declare const SetSquareToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"GeometrySetSquare">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometrySetSquare";
+    size: number;
+}, {
+    type: "GeometrySetSquare";
+    size?: number | undefined;
+}>;
+
+export declare type SetSquareWidgetJSON = z.infer<typeof SetSquareWidgetSchema>;
+
+export declare const SetSquareWidgetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"set-square">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "set-square";
+    size?: number | undefined;
+}, {
+    type: "set-square";
+    size?: number | undefined;
+}>;
+
 export declare type SimpleValidation = z.infer<typeof SimpleValidationSchema>;
 
 /**
@@ -18928,6 +19209,31 @@ export declare const SimpleValidationSchema: z.ZodObject<{
     type: "SimpleValidation";
 }>;
 
+/**
+ * Maps a sound event to either:
+ *  - a `string` URL (renderer plays it via the native Audio API), or
+ *  - a `() => void` callback (consumer owns playback — preloading, mobile
+ *    unlock, volume, etc.).
+ * Omitted events are silent.
+ */
+export declare type SoundConfig = Partial<Record<SoundEvent, string | (() => void)>>;
+
+/** All sound events the renderer can emit. */
+export declare type SoundEvent = 'drag-start' | 'drag-drop' | 'drag-cancel' | 'radio-select' | 'pair-select' | 'pair-link' | 'pair-unlink' | 'keypad-press' | 'matcher-select' | 'fraction-shade' | 'clock-hour-tick' | 'clock-minute-tick' | 'counter-step' | 'input-select' | 'answer-correct' | 'answer-wrong';
+
+export declare const SoundProvider: default_2.FC<SoundProviderProps>;
+
+export declare interface SoundProviderProps {
+    children: default_2.ReactNode;
+    /** Master on/off switch. When false, `play()` is a no-op. */
+    enabled?: boolean;
+    /**
+     * Per-event overrides (URL or callback), merged over the bundled defaults.
+     * Omit to use the built-in sounds for every event.
+     */
+    sounds?: SoundConfig;
+}
+
 /**
  * Source position information for error reporting
  */
@@ -20975,6 +21281,33 @@ export declare const ToolNodeSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObjec
     style?: "diamond" | "classic" | undefined;
     includeOperators?: boolean | undefined;
     includeDecimal?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"GeometryRuler">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryRuler";
+    size: number;
+}, {
+    type: "GeometryRuler";
+    size?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"GeometryProtractor">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryProtractor";
+    size: number;
+}, {
+    type: "GeometryProtractor";
+    size?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"GeometrySetSquare">;
+    size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometrySetSquare";
+    size: number;
+}, {
+    type: "GeometrySetSquare";
+    size?: number | undefined;
 }>]>;
 
 /**
@@ -20998,6 +21331,12 @@ export declare class TransformError extends EngineError {
  */
 declare type UserAnswerValue = string | string[][] | number[];
 
+/**
+ * Returns `play(event)`. Safe to call outside a SoundProvider — it returns a
+ * stable no-op, so widgets never need to know whether sound is wired up.
+ */
+export declare function useSound(): (event: SoundEvent) => void;
+
 /**
  * Validate user inputs against an exercise
  *
@@ -21119,6 +21458,15 @@ export declare function validateExerciseJSON(data: unknown): {
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    } | {
+        type: "ruler";
+        size?: number | undefined;
+    } | {
+        type: "protractor";
+        size?: number | undefined;
+    } | {
+        type: "set-square";
+        size?: number | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -21221,6 +21569,15 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    } | {
+        type: "ruler";
+        size?: number | undefined;
+    } | {
+        type: "protractor";
+        size?: number | undefined;
+    } | {
+        type: "set-square";
+        size?: number | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -21305,6 +21662,15 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
         orientation?: "horizontal" | "vertical" | undefined;
         label?: string | undefined;
         size?: number | undefined;
+    } | {
+        type: "ruler";
+        size?: number | undefined;
+    } | {
+        type: "protractor";
+        size?: number | undefined;
+    } | {
+        type: "set-square";
+        size?: number | undefined;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -21439,6 +21805,15 @@ export declare function validateWidgetJSON(data: unknown): {
     orientation?: "horizontal" | "vertical" | undefined;
     label?: string | undefined;
     size?: number | undefined;
+} | {
+    type: "ruler";
+    size?: number | undefined;
+} | {
+    type: "protractor";
+    size?: number | undefined;
+} | {
+    type: "set-square";
+    size?: number | undefined;
 };
 
 /**
@@ -21514,6 +21889,15 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     orientation?: "horizontal" | "vertical" | undefined;
     label?: string | undefined;
     size?: number | undefined;
+} | {
+    type: "ruler";
+    size?: number | undefined;
+} | {
+    type: "protractor";
+    size?: number | undefined;
+} | {
+    type: "set-square";
+    size?: number | undefined;
 }, {
     length: number;
     type: "inline-input";
@@ -21581,6 +21965,15 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
     orientation?: "horizontal" | "vertical" | undefined;
     label?: string | undefined;
     size?: number | undefined;
+} | {
+    type: "ruler";
+    size?: number | undefined;
+} | {
+    type: "protractor";
+    size?: number | undefined;
+} | {
+    type: "set-square";
+    size?: number | undefined;
 }>;
 
 /**
@@ -24608,6 +25001,33 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
     orientation?: "horizontal" | "vertical" | undefined;
     label?: string | undefined;
     size?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ruler">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "ruler";
+    size?: number | undefined;
+}, {
+    type: "ruler";
+    size?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"protractor">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "protractor";
+    size?: number | undefined;
+}, {
+    type: "protractor";
+    size?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"set-square">;
+    size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "set-square";
+    size?: number | undefined;
+}, {
+    type: "set-square";
+    size?: number | undefined;
 }>]>;
 
 export declare type WidgetRef = z.infer<typeof WidgetRefSchema>;