@mathscan/math-exercise-engine 1.2.8 → 1.2.9

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { CheckGeometryAnswerResult } from '@mathscan/geometry-engine/validation';
 import { CstNode } from 'chevrotain';
 import { default as default_2 } from 'react';
 import { ForwardRefExoticComponent } from 'react';
@@ -57,6 +58,8 @@ export declare const AST_TYPES: {
     readonly NUMBER_LINE_BLOCK: "NumberLineBlock";
     /** Symmetry exercise on a square grid */
     readonly GRID_SYMMETRY_BLOCK: "GridSymmetryBlock";
+    /** Geometry widget definition carried as raw JSON for the external engine */
+    readonly GEOMETRY_BLOCK: "GeometryBlock";
     /** A position marker on the number line */
     readonly NUMBER_LINE_POSITION: "NumberLinePosition";
     /** A draggable cursor on the number line */
@@ -6268,6 +6271,10 @@ export declare function compileWithAST(dsl: string): {
             interactiveArea: "left" | "right" | "top" | "bottom";
             cellSize: number;
             cells: [number, number][];
+        } | {
+            type: "GeometryBlock";
+            name?: string | undefined;
+            json?: unknown;
         } | {
             type: "TableBlock";
             rows: {
@@ -7083,6 +7090,9 @@ export declare function compileWithAST(dsl: string): {
         } | {
             type: "set-square";
             size?: number | undefined;
+        } | {
+            type: "geometry";
+            json?: unknown;
         }>;
         validation?: {
             mode: "simple" | "expression" | "mixed";
@@ -16365,6 +16375,18 @@ export declare const ContentBlockSchema: z.ZodUnion<[z.ZodObject<{
             snap?: number | undefined;
         })[] | undefined;
     }[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"GeometryBlock">;
+    json: z.ZodUnknown;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryBlock";
+    name?: string | undefined;
+    json?: unknown;
+}, {
+    type: "GeometryBlock";
+    name?: string | undefined;
+    json?: unknown;
 }>]>;
 
 /**
@@ -16452,6 +16474,10 @@ export declare function createFraction(name: string, options?: {
  */
 export declare function createFreeText(value: string): FreeTextInline;
 
+export declare function createGeometryBlock(json: unknown, options?: {
+    name?: unknown;
+}): GeometryBlock;
+
 export declare function createGridSymmetryBlock(rows: number, cols: number, axis: GridSymmetryAxis, interactiveArea: GridSymmetryInteractiveArea, cells: GridCell[], cellSize?: number): GridSymmetryBlock;
 
 /**
@@ -26120,6 +26146,18 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
                 snap?: number | undefined;
             })[] | undefined;
         }[] | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"GeometryBlock">;
+        json: z.ZodUnknown;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
+    }, {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
     }>]>, "many">;
     tools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"DragOptions">;
@@ -26492,6 +26530,10 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         interactiveArea: "left" | "right" | "top" | "bottom";
         cellSize: number;
         cells: [number, number][];
+    } | {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
     } | {
         type: "TableBlock";
         rows: {
@@ -27505,6 +27547,10 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         interactiveArea: "left" | "right" | "top" | "bottom";
         cells: [number, number][];
         cellSize?: number | undefined;
+    } | {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
     } | {
         type: "TableBlock";
         rows: {
@@ -28518,6 +28564,10 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         interactiveArea: "left" | "right" | "top" | "bottom";
         cellSize: number;
         cells: [number, number][];
+    } | {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
     } | {
         type: "TableBlock";
         rows: {
@@ -29531,6 +29581,10 @@ export declare const ExerciseDocumentSchema: z.ZodEffects<z.ZodObject<{
         interactiveArea: "left" | "right" | "top" | "bottom";
         cells: [number, number][];
         cellSize?: number | undefined;
+    } | {
+        type: "GeometryBlock";
+        name?: string | undefined;
+        json?: unknown;
     } | {
         type: "TableBlock";
         rows: {
@@ -30632,6 +30686,15 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
     }, {
         value: number;
         type: "chart-picto";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"geometry">;
+        json: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        type: "geometry";
+        json?: unknown;
+    }, {
+        type: "geometry";
+        json?: unknown;
     }>]>>;
     validation: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<["simple", "expression", "mixed"]>;
@@ -30760,6 +30823,9 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
     } | {
         type: "set-square";
         size?: number | undefined;
+    } | {
+        type: "geometry";
+        json?: unknown;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -30869,6 +30935,9 @@ export declare const ExerciseJSONSchema: z.ZodObject<{
     } | {
         type: "set-square";
         size?: number | undefined;
+    } | {
+        type: "geometry";
+        json?: unknown;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -31109,6 +31178,48 @@ export declare const FreeTextInlineSchema: z.ZodObject<{
     type: "FreeText";
 }>;
 
+export declare type GeometryBlock = z.infer<typeof GeometryBlockSchema>;
+
+/**
+ * Geometry widget definition carried as raw JSON for the external
+ * @mathscan/geometry-engine package. Domain validation is intentionally not
+ * duplicated here — this layer only guarantees the DSL payload is valid JSON.
+ *
+ * `name` comes from the DSL parameters, not the JSON: it is a host-side
+ * setting (the widget id) the engine never sees.
+ */
+export declare const GeometryBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"GeometryBlock">;
+    json: z.ZodUnknown;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "GeometryBlock";
+    name?: string | undefined;
+    json?: unknown;
+}, {
+    type: "GeometryBlock";
+    name?: string | undefined;
+    json?: unknown;
+}>;
+
+export declare type GeometryJSON = z.infer<typeof GeometryJSONSchema>;
+
+/**
+ * Geometry widget. The payload is a raw JSON blob owned by the external
+ * `@mathscan/geometry-engine` package — this layer does not validate its
+ * shape (no domain validation, no answer checking, yet).
+ */
+export declare const GeometryJSONSchema: z.ZodObject<{
+    type: z.ZodLiteral<"geometry">;
+    json: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "geometry";
+    json?: unknown;
+}, {
+    type: "geometry";
+    json?: unknown;
+}>;
+
 /**
  * List every widget the exercise expects an answer for (simple answers,
  * expression variables, or both in mixed mode). Empty when the exercise has
@@ -31893,6 +32004,15 @@ export declare function isFractionKey(key: string): boolean;
 
 export declare function isFreeText(value: unknown): value is FreeTextInline;
 
+export declare function isGeometryBlock(value: unknown): value is GeometryBlock;
+
+/**
+ * Type guard for GeometryJSON
+ */
+export declare function isGeometryJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
+    type: 'geometry';
+}>;
+
 export declare function isGridSymmetryBlock(value: unknown): value is GridSymmetryBlock;
 
 export declare function isGridSymmetryJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
@@ -32193,6 +32313,8 @@ export declare const JSON_TYPES: {
     readonly PROTRACTOR: "protractor";
     /** Set square geometry tool widget */
     readonly SET_SQUARE: "set-square";
+    /** Geometry widget definition carried as raw JSON for the external engine */
+    readonly GEOMETRY: "geometry";
 };
 
 /**
@@ -39409,6 +39531,18 @@ export declare const RulerWidgetSchema: z.ZodObject<{
     size?: number | undefined;
 }>;
 
+/** Explicit scoring units contributed by a validator. */
+export declare interface ScoreContribution {
+    correct: boolean;
+    earned: number;
+    possible: number;
+}
+
+/** A result from one of this package's validators: `scoreContribution` is always present. */
+export declare type ScoredValidationResult = ValidationResult & {
+    scoreContribution: ScoreContribution;
+};
+
 export declare type SetSquareTool = z.infer<typeof SetSquareToolSchema>;
 
 export declare const SetSquareToolSchema: z.ZodObject<{
@@ -41747,7 +41881,7 @@ export declare function useSound(): (event: SoundEvent) => void;
  * }
  * ```
  */
-export declare function validate(exercise: ExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ValidationResult;
+export declare function validate(exercise: ExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ScoredValidationResult;
 
 /**
  * Validate that an expression will return a boolean
@@ -41873,6 +42007,9 @@ export declare function validateExerciseJSON(data: unknown): {
     } | {
         type: "set-square";
         size?: number | undefined;
+    } | {
+        type: "geometry";
+        json?: unknown;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -42000,6 +42137,9 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
     } | {
         type: "set-square";
         size?: number | undefined;
+    } | {
+        type: "geometry";
+        json?: unknown;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -42109,6 +42249,9 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
     } | {
         type: "set-square";
         size?: number | undefined;
+    } | {
+        type: "geometry";
+        json?: unknown;
     }>;
     validation?: {
         mode: "simple" | "expression" | "mixed";
@@ -42132,7 +42275,7 @@ export declare function validateExerciseJSONSafe(data: unknown): z.SafeParseRetu
  * @param userInputs - User's answers keyed by widget ID (variable names)
  * @returns Validation result
  */
-export declare function validateExpression(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number>): ValidationResult;
+export declare function validateExpression(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number>): ScoredValidationResult;
 
 /**
  * Check if user inputs are valid (proper format, etc.)
@@ -42151,7 +42294,7 @@ export declare function validateInputFormats(exercise: ExerciseJSON, userInputs:
  * @param userInputs - User's answers keyed by widget ID
  * @returns Validation result
  */
-export declare function validateMixed(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ValidationResult;
+export declare function validateMixed(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ScoredValidationResult;
 
 /**
  * Validate using simple mode (predetermined answers)
@@ -42160,7 +42303,7 @@ export declare function validateMixed(exercise: ValidatedExerciseJSON, userInput
  * @param userInputs - User's answers keyed by widget ID
  * @returns Validation result
  */
-export declare function validateSimple(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ValidationResult;
+export declare function validateSimple(exercise: ValidatedExerciseJSON, userInputs: Record<string, string | number | string[][] | number[] | GridCell[]>): ScoredValidationResult;
 
 export declare function validateVisualFractionCapacity(data: {
     divisions: number;
@@ -42268,6 +42411,9 @@ export declare function validateWidgetJSON(data: unknown): {
 } | {
     type: "set-square";
     size?: number | undefined;
+} | {
+    type: "geometry";
+    json?: unknown;
 };
 
 /**
@@ -42368,6 +42514,9 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
 } | {
     type: "set-square";
     size?: number | undefined;
+} | {
+    type: "geometry";
+    json?: unknown;
 }, {
     length: number;
     type: "inline-input";
@@ -42460,6 +42609,9 @@ export declare function validateWidgetJSONSafe(data: unknown): z.SafeParseReturn
 } | {
     type: "set-square";
     size?: number | undefined;
+} | {
+    type: "geometry";
+    json?: unknown;
 }>;
 
 /**
@@ -42530,6 +42682,12 @@ export declare interface ValidationResult {
     details: Record<string, WidgetValidation>;
     /** Numeric score (0-1) for partial grading */
     score?: number;
+    /**
+     * Raw scoring units, used when combining independent validators. Always set
+     * by this package's validators; optional so host code that builds its own
+     * results keeps compiling.
+     */
+    scoreContribution?: ScoreContribution;
     /** The expression that was evaluated (expression mode only) */
     expression?: string;
     /** The scope used for evaluation (expression mode only, debugging) */
@@ -45581,6 +45739,15 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
 }, {
     value: number;
     type: "chart-picto";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"geometry">;
+    json: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "geometry";
+    json?: unknown;
+}, {
+    type: "geometry";
+    json?: unknown;
 }>]>;
 
 export declare type WidgetRef = z.infer<typeof WidgetRefSchema>;
@@ -45650,6 +45817,14 @@ export declare interface WidgetValidation {
      * Equal to the overall expression boolean; the per-widget granularity comes from `simpleCorrect`.
      */
     expressionCorrect?: boolean;
+    /**
+     * GEOMETRY widgets: the geometry engine's own verdict, passed through
+     * untouched. The renderer hands it back to `StudentGeometryExercise` as
+     * `validationFeedback`; the engine decides what the canvas shows and, through
+     * the fingerprints inside it, whether the result still describes the figure on
+     * screen. Nothing in this package reads its contents.
+     */
+    geometryFeedback?: CheckGeometryAnswerResult;
     /** Optional error message (for debugging) */
     error?: string;
 }