@mathscan/math-exercise-engine 1.0.14 → 1.0.16

package/dist/index.mjs

@@ -23,6 +23,8 @@ const AST_TYPES = {
   INLINE_INPUT: "InlineInput",
   /** Inline fraction widget (numerator/denominator with optional inputs) */
   FRACTION: "Fraction",
+  /** Inline image element */
+  IMAGE: "Image",
   // ═══════════════════════════════════════════════════════════════════════════
   // Blocks
   // ═══════════════════════════════════════════════════════════════════════════
@@ -50,6 +52,8 @@ const AST_TYPES = {
   MATCHER_ROW: "MatcherRow",
   /** Item within a matcher row */
   MATCHER_ITEM: "MatcherItem",
+  /** Visual fraction inline widget */
+  VISUAL_FRACTION: "VisualFraction",
   // ═══════════════════════════════════════════════════════════════════════════
   // Tools
   // ═══════════════════════════════════════════════════════════════════════════
@@ -88,6 +92,8 @@ const JSON_TYPES = {
   COLOR_TEXT: "color-text",
   /** Bold text */
   BOLD_TEXT: "bold-text",
+  /** Inline image */
+  IMAGE: "image",
   /** Reference to a widget */
   WIDGET_REF: "widget-ref",
   /** Line break element */
@@ -128,7 +134,9 @@ const JSON_TYPES = {
   /** Numeric keypad widget */
   NUMERIC_KEYPAD: "numeric-keypad",
   /** Inline fraction widget */
-  FRACTION: "fraction"
+  FRACTION: "fraction",
+  /** Visual fraction widget */
+  VISUAL_FRACTION: "visual-fraction"
 };
 const DRAG_OPTIONS_WIDGET_ID = "_drag_options";
 const VALIDATION_MODES = {
@@ -262,6 +270,10 @@ const HIGHLIGHT = createToken({
   name: "HIGHLIGHT",
   pattern: /HIGHLIGHT(?!_TEXT)/
 });
+const VISUAL_FRACTION = createToken({
+  name: "VISUAL_FRACTION",
+  pattern: /VISUAL_FRACTION/
+});
 const FRACTION = createToken({
   name: "FRACTION",
   pattern: /FRACTION/
@@ -278,6 +290,10 @@ const ANSWERS = createToken({
   name: "ANSWERS",
   pattern: /ANSWERS/
 });
+const IMAGE = createToken({
+  name: "IMAGE",
+  pattern: /IMAGE/
+});
 const NumberLiteral = createToken({
   name: "NumberLiteral",
   pattern: /-?\d+(\.\d+)?/
@@ -387,10 +403,12 @@ const allTokens = [
   CELL,
   COUNTER,
   HIGHLIGHT,
+  VISUAL_FRACTION,
   FRACTION,
   MATCHER,
   ITEM,
   ANSWERS,
+  IMAGE,
   // Literals
   NumberLiteral,
   StringLiteral,
@@ -849,6 +867,10 @@ class MathExerciseParser extends CstParser {
         { ALT: () => this.SUBRULE(this.boldText) },
         // FRACTION (inline fraction widget)
         { ALT: () => this.SUBRULE(this.fraction) },
+        // IMAGE (inline image element)
+        { ALT: () => this.SUBRULE(this.image) },
+        // VISUAL_FRACTION — always allowed; display-only when answer=[] or absence of answer parameter, interactive when answer=[...] with values.
+        { ALT: () => this.SUBRULE(this.visualFraction) },
         // W_S_I (inline input widget) — excluded in display-only contexts (e.g. MATCHER ITEM)
         { GATE: () => !displayOnly, ALT: () => this.SUBRULE(this.inlineInput) }
       ]);
@@ -880,6 +902,47 @@ class MathExerciseParser extends CstParser {
       this.SUBRULE(this.parameterList);
       this.CONSUME(RBracket);
     });
+    this.image = this.RULE("image", () => {
+      this.CONSUME(IMAGE);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+    });
+    this.visualFraction = this.RULE("visualFraction", () => {
+      this.CONSUME(VISUAL_FRACTION);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+    });
+    this.numberArray = this.RULE("numberArray", () => {
+      this.CONSUME(LBracket);
+      this.MANY(() => {
+        this.CONSUME(Space);
+      });
+      this.OPTION(() => {
+        this.CONSUME(NumberLiteral, { LABEL: "items" });
+        this.MANY2(() => {
+          this.MANY3(() => {
+            this.CONSUME2(Space);
+          });
+          this.CONSUME(Comma);
+          this.MANY4(() => {
+            this.CONSUME3(Space);
+          });
+          this.CONSUME2(NumberLiteral, { LABEL: "items" });
+        });
+        this.OPTION2(() => {
+          this.MANY5(() => {
+            this.CONSUME4(Space);
+          });
+          this.CONSUME2(Comma);
+        });
+      });
+      this.MANY6(() => {
+        this.CONSUME5(Space);
+      });
+      this.CONSUME(RBracket);
+    });
     this.inlineInput = this.RULE("inlineInput", () => {
       this.OR([
         { ALT: () => this.CONSUME(W_S_I, { LABEL: "stringInput" }) },
@@ -967,7 +1030,9 @@ class MathExerciseParser extends CstParser {
         // Tuple value: (start, end)
         { ALT: () => this.SUBRULE(this.tuple, { LABEL: "value" }) },
         // Curly-brace string list: {"a", "b", "c"}
-        { ALT: () => this.SUBRULE(this.curlyStringList, { LABEL: "value" }) }
+        { ALT: () => this.SUBRULE(this.curlyStringList, { LABEL: "value" }) },
+        // Square-bracket number array: [1, 2, 3]  — used by VISUAL_FRACTION filled/answer
+        { ALT: () => this.SUBRULE(this.numberArray, { LABEL: "value" }) }
       ]);
     });
     this.tuple = this.RULE("tuple", () => {
@@ -1023,6 +1088,25 @@ class MathExerciseParser extends CstParser {
   }
 }
 const parser = new MathExerciseParser();
+function parseOrThrow(schema, data, label) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    if (!issue) throw new Error(`${label}: validation failed`);
+    const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+    throw new Error(`${label}: ${path} ${issue.message}`);
+  }
+  return result.data;
+}
+const VISUAL_FRACTION_SHAPES = ["bar", "circle", "triangle", "grid"];
+const VISUAL_FRACTION_SHAPE = {
+  BAR: "bar",
+  CIRCLE: "circle",
+  TRIANGLE: "triangle",
+  GRID: "grid"
+};
+const VISUAL_FRACTION_DEFAULT_SIZE = 1.35;
+const VISUAL_FRACTION_MAX_DIVISIONS = 100;
 const FreeTextInlineSchema = z.object({
   type: z.literal(AST_TYPES.FREE_TEXT),
   value: z.string()
@@ -1052,6 +1136,7 @@ const InlineInputWidgetSchema = z.discriminatedUnion("inputType", [
     name: z.string(),
     inputType: z.literal(INPUT_TYPES.STRING),
     length: z.number().int().positive(),
+    placeholder: z.string().max(32).optional(),
     answer: z.union([z.string(), z.number()]).optional()
   }),
   z.object({
@@ -1059,6 +1144,7 @@ const InlineInputWidgetSchema = z.discriminatedUnion("inputType", [
     name: z.string(),
     inputType: z.literal(INPUT_TYPES.NUMERIC),
     digits: z.number().int().positive(),
+    placeholder: z.string().max(32).optional(),
     answer: z.union([z.string(), z.number()]).optional()
   })
 ]);
@@ -1070,6 +1156,71 @@ const FractionInlineSchema = z.object({
   answer: z.string().optional(),
   simplified: z.boolean().default(true)
 });
+const IMAGE_SRC_SCHEME_RE$1 = /^(https?:\/\/|data:image\/)/i;
+const ImageInlineSchema = z.object({
+  type: z.literal(AST_TYPES.IMAGE),
+  name: z.string().min(1),
+  src: z.string().url().refine((s) => IMAGE_SRC_SCHEME_RE$1.test(s), {
+    message: "src must use http(s) or data:image scheme"
+  }),
+  alt: z.string(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional()
+});
+const VisualFractionInlineSchema = z.object({
+  type: z.literal(AST_TYPES.VISUAL_FRACTION),
+  name: z.string(),
+  shape: z.enum(VISUAL_FRACTION_SHAPES).default("bar"),
+  divisions: z.number().int().positive().max(VISUAL_FRACTION_MAX_DIVISIONS, {
+    message: `divisions cannot exceed ${VISUAL_FRACTION_MAX_DIVISIONS}`
+  }),
+  filled: z.array(z.number().int().nonnegative()).default([]),
+  answer: z.array(z.number().int().nonnegative()).default([]),
+  orientation: z.enum(["horizontal", "vertical"]).optional(),
+  label: z.string().optional(),
+  /** Unified author size.
+   * - bar / grid:         overrides `--visual-fraction-part-size` (cell size).
+   * - circle / triangle:  maps to `--visual-fraction-size` with the renderer scale factor.
+   * Omit to use CSS defaults. */
+  size: z.number().positive().optional()
+}).superRefine(validateVisualFractionCapacity);
+function validateVisualFractionCapacity(data, ctx) {
+  const filledTotal = data.filled.reduce((sum, count) => sum + count, 0);
+  const answerTotal = data.answer.reduce((sum, count) => sum + count, 0);
+  if (filledTotal > data.divisions) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `filled total (${filledTotal}) cannot exceed divisions (${data.divisions})`,
+      path: ["filled"]
+    });
+  }
+  if (filledTotal + answerTotal > data.divisions) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `filled + answer total (${filledTotal + answerTotal}) cannot exceed divisions (${data.divisions})`,
+      path: ["answer"]
+    });
+  }
+  const shape = data.shape;
+  if (shape === "triangle" && !isPerfectSquare(data.divisions)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `triangle divisions (${data.divisions}) must be a perfect square to render equal triangle parts`,
+      path: ["divisions"]
+    });
+  }
+  if (shape === "grid" && !isPerfectSquare(data.divisions)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `grid divisions (${data.divisions}) must be a perfect square to render equal rows and columns`,
+      path: ["divisions"]
+    });
+  }
+}
+function isPerfectSquare(value) {
+  const root = Math.sqrt(value);
+  return Number.isInteger(root);
+}
 const InlineNodeSchema = z.union([
   FreeTextInlineSchema,
   SpaceInlineSchema,
@@ -1077,7 +1228,9 @@ const InlineNodeSchema = z.union([
   ColorTextInlineSchema,
   BoldTextInlineSchema,
   InlineInputWidgetSchema,
-  FractionInlineSchema
+  FractionInlineSchema,
+  ImageInlineSchema,
+  VisualFractionInlineSchema
 ]);
 function createFreeText(value) {
   return FreeTextInlineSchema.parse({
@@ -1112,22 +1265,33 @@ function createBoldText(value, highlight) {
     highlight
   });
 }
-function createStringInput(name, length, answer) {
-  return InlineInputWidgetSchema.parse({
+function createStringInput(name, length, answer, placeholder) {
+  return parseOrThrow(InlineInputWidgetSchema, {
     type: AST_TYPES.INLINE_INPUT,
     name,
     inputType: INPUT_TYPES.STRING,
     length,
+    placeholder,
     answer
-  });
+  }, "STRING_INPUT");
 }
-function createNumericInput(name, digits, answer) {
-  return InlineInputWidgetSchema.parse({
+function createNumericInput(name, digits, answer, placeholder) {
+  return parseOrThrow(InlineInputWidgetSchema, {
     type: AST_TYPES.INLINE_INPUT,
     name,
     inputType: INPUT_TYPES.NUMERIC,
     digits,
+    placeholder,
     answer
+  }, "NUMERIC_INPUT");
+}
+function createImage(name, src, alt, options = {}) {
+  return ImageInlineSchema.parse({
+    type: AST_TYPES.IMAGE,
+    name,
+    src,
+    alt,
+    ...options
   });
 }
 function createFraction(name, options = {}) {
@@ -1137,6 +1301,14 @@ function createFraction(name, options = {}) {
     ...options
   });
 }
+function createVisualFraction(name, divisions, options = {}) {
+  return VisualFractionInlineSchema.parse({
+    type: AST_TYPES.VISUAL_FRACTION,
+    name,
+    divisions,
+    ...options
+  });
+}
 function isFreeText(value) {
   return FreeTextInlineSchema.safeParse(value).success;
 }
@@ -1149,9 +1321,15 @@ function isInlineInput(value) {
 function isFraction(value) {
   return FractionInlineSchema.safeParse(value).success;
 }
+function isImage(value) {
+  return ImageInlineSchema.safeParse(value).success;
+}
 function isInlineNode(value) {
   return InlineNodeSchema.safeParse(value).success;
 }
+function isVisualFractionInline(value) {
+  return VisualFractionInlineSchema.safeParse(value).success;
+}
 const TextBlockSchema = z.object({
   type: z.literal(AST_TYPES.TEXT_BLOCK),
   value: z.string()
@@ -1347,13 +1525,19 @@ const DisplayFractionInlineSchema = FractionInlineSchema.refine(
   (f) => f.numerator !== void 0 && f.denominator !== void 0,
   { message: "FRACTION inside MATCHER ITEM must be in display mode (both numerator and denominator required)" }
 );
+const DisplayVisualFractionInlineSchema = VisualFractionInlineSchema.refine(
+  (vf) => vf.answer.length === 0,
+  { message: "VISUAL_FRACTION inside MATCHER ITEM must be display-only (answer must be empty: answer=[])" }
+);
 const DisplayInlineNodeSchema = z.union([
   FreeTextInlineSchema,
   SpaceInlineSchema,
   HighlightedTextInlineSchema,
   ColorTextInlineSchema,
   BoldTextInlineSchema,
-  DisplayFractionInlineSchema
+  DisplayFractionInlineSchema,
+  ImageInlineSchema,
+  DisplayVisualFractionInlineSchema
 ]);
 const MatcherItemSchema = z.object({
   type: z.literal(AST_TYPES.MATCHER_ITEM),
@@ -1449,7 +1633,8 @@ const DragOptionsToolSchema = z.object({
 const NumericKeypadToolSchema = z.object({
   type: z.literal(AST_TYPES.NUMERIC_KEYPAD),
   includeOperators: z.boolean().optional(),
-  includeDecimal: z.boolean().optional()
+  includeDecimal: z.boolean().optional(),
+  style: z.enum(["diamond", "classic"]).optional()
 });
 const ToolNodeSchema = z.discriminatedUnion("type", [
   DragOptionsToolSchema,
@@ -1461,11 +1646,12 @@ function createDragOptions(options) {
     options
   });
 }
-function createNumericKeypad(includeOperators, includeDecimal) {
+function createNumericKeypad(includeOperators, includeDecimal, style) {
   return NumericKeypadToolSchema.parse({
     type: AST_TYPES.NUMERIC_KEYPAD,
     includeOperators,
-    includeDecimal
+    includeDecimal,
+    style
   });
 }
 function isDragOptions(value) {
@@ -1529,6 +1715,51 @@ const ExerciseDocumentSchema = z.object({
   lines: z.array(ContentBlockSchema),
   tools: z.array(ToolNodeSchema).optional(),
   validation: ValidationNodeSchema.optional()
+}).superRefine((doc, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  const record = (name, path) => {
+    if (seen.has(name)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate name "${name}" — widget/image names must be unique across the document`,
+        path
+      });
+    } else {
+      seen.add(name);
+    }
+  };
+  const visitInlines = (inlines, basePath) => {
+    inlines.forEach((inline, i) => {
+      if (inline.type === AST_TYPES.INLINE_INPUT || inline.type === AST_TYPES.FRACTION || inline.type === AST_TYPES.IMAGE) {
+        record(inline.name, [...basePath, i, "name"]);
+      }
+    });
+  };
+  doc.lines.forEach((block, bi) => {
+    if (block.type === AST_TYPES.LINE_BLOCK) {
+      visitInlines(block.inlines, ["lines", bi, "inlines"]);
+    } else if (block.type === AST_TYPES.TABLE_BLOCK) {
+      block.rows.forEach((row, ri) => {
+        row.cells.forEach((cell, ci) => {
+          visitInlines(cell.inlines, ["lines", bi, "rows", ri, "cells", ci, "inlines"]);
+        });
+      });
+    } else if (block.type === AST_TYPES.NUMBER_LINE_BLOCK) {
+      block.positions.forEach((pos, pi) => {
+        visitInlines(pos.inlines, ["lines", bi, "positions", pi, "inlines"]);
+      });
+    } else if (block.type === AST_TYPES.MATCHER_BLOCK) {
+      const m = block;
+      record(m.name, ["lines", bi, "name"]);
+      m.rows.forEach((row, ri) => {
+        row.items.forEach((item, ii) => {
+          visitInlines(item.inlines, ["lines", bi, "rows", ri, "items", ii, "inlines"]);
+        });
+      });
+    } else if (block.type === AST_TYPES.RADIO_OPTIONS) {
+      record(block.name, ["lines", bi, "name"]);
+    }
+  });
 });
 function createExerciseDocument(question, lines, validation, tools) {
   return ExerciseDocumentSchema.parse({
@@ -1771,6 +2002,12 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     if (ctx.fraction) {
       return this.visit(ctx.fraction);
     }
+    if (ctx.image) {
+      return this.visit(ctx.image);
+    }
+    if (ctx.visualFraction) {
+      return this.visit(ctx.visualFraction);
+    }
     if (ctx.inlineInput) {
       return this.visit(ctx.inlineInput);
     }
@@ -1813,16 +2050,41 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     const simplified = params.simplified !== void 0 ? params.simplified : void 0;
     return createFraction(name, { numerator, denominator, answer, simplified });
   }
+  image(ctx) {
+    const params = this.visit(ctx.parameterList);
+    const name = params.name;
+    const src = params.src;
+    const alt = params.alt;
+    const width = params.width;
+    const height = params.height;
+    return createImage(name, src, alt, { width, height });
+  }
+  visualFraction(ctx) {
+    const params = this.visit(ctx.parameterList);
+    const name = params.name;
+    const divisions = params.divisions;
+    const shape = params.shape;
+    const filled = params.filled ?? [];
+    const answer = params.answer ?? [];
+    const orientation = params.orientation;
+    const label = params.label !== void 0 ? params.label : void 0;
+    const size = params.size !== void 0 ? params.size : void 0;
+    return createVisualFraction(name, divisions, { shape, filled, answer, orientation, label, size });
+  }
+  numberArray(ctx) {
+    return ctx.items ? ctx.items.map((t) => parseFloat(t.image)) : [];
+  }
   inlineInput(ctx) {
     const params = this.visit(ctx.parameterList);
     const name = params.name;
     const answer = params.answer;
+    const placeholder = params.placeholder;
     if (ctx.stringInput) {
       const length = params.length;
-      return createStringInput(name, length, answer);
+      return createStringInput(name, length, answer, placeholder);
     }
     const digits = params.digits;
-    return createNumericInput(name, digits, answer);
+    return createNumericInput(name, digits, answer, placeholder);
   }
   // ═══════════════════════════════════════════════════════════════════════════
   // Tools
@@ -1844,7 +2106,8 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     const params = ctx.parameterList ? this.visit(ctx.parameterList) : {};
     const includeOperators = params.includeOperators === true || params.includeOperators === "true";
     const includeDecimal = params.includeDecimal === true || params.includeDecimal === "true";
-    return createNumericKeypad(includeOperators || void 0, includeDecimal || void 0);
+    const style = params.style;
+    return createNumericKeypad(includeOperators || void 0, includeDecimal || void 0, style);
   }
   // ═══════════════════════════════════════════════════════════════════════════
   // Validation
@@ -1971,6 +2234,18 @@ const BoldTextSchema = z.object({
   value: z.string(),
   highlight: z.tuple([z.number(), z.number()]).optional()
 });
+const IMAGE_SRC_SCHEME_RE = /^(https?:\/\/|data:image\/)/i;
+const ImageItemSchema = z.object({
+  id: z.string(),
+  type: z.literal(JSON_TYPES.IMAGE),
+  name: z.string().min(1),
+  src: z.string().url().refine((s) => IMAGE_SRC_SCHEME_RE.test(s), {
+    message: "src must use http(s) or data:image scheme"
+  }),
+  alt: z.string(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional()
+});
 const SpaceItemSchema = z.object({
   id: z.string(),
   type: z.literal(JSON_TYPES.SPACE)
@@ -1993,6 +2268,7 @@ const LayoutItemSchema = z.lazy(
     HighlightedTextSchema,
     ColorTextSchema,
     BoldTextSchema,
+    ImageItemSchema,
     SpaceItemSchema,
     LinebreakSchema,
     GroupItemSchema,
@@ -2074,12 +2350,14 @@ const MatcherRowItemSchema = z.object({
 const StringInputJSONSchema = z.object({
   type: z.literal(JSON_TYPES.INLINE_INPUT),
   inputType: z.literal(INPUT_TYPES.STRING),
-  length: z.number().int().positive()
+  length: z.number().int().positive(),
+  placeholder: z.string().max(32).optional()
 });
 const NumericInputJSONSchema = z.object({
   type: z.literal(JSON_TYPES.INLINE_INPUT),
   inputType: z.literal(INPUT_TYPES.NUMERIC),
-  digits: z.number().int().positive()
+  digits: z.number().int().positive(),
+  placeholder: z.string().max(32).optional()
 });
 const InlineInputJSONSchema = z.discriminatedUnion("inputType", [
   StringInputJSONSchema,
@@ -2096,7 +2374,8 @@ const RadioOptionsJSONSchema = z.object({
 const NumericKeypadJSONSchema = z.object({
   type: z.literal(JSON_TYPES.NUMERIC_KEYPAD),
   includeOperators: z.boolean().optional(),
-  includeDecimal: z.boolean().optional()
+  includeDecimal: z.boolean().optional(),
+  style: z.enum(["diamond", "classic"]).optional()
 });
 const FractionJSONSchema = z.object({
   type: z.literal(JSON_TYPES.FRACTION),
@@ -2112,24 +2391,44 @@ const MatcherWidgetJSONSchema = z.object({
   /** Number of answer groups — equals answers.length, stored here to avoid prop-drilling. */
   groupCount: z.number().int().min(1)
 });
+const VisualFractionJSONSchema = z.object({
+  type: z.literal(JSON_TYPES.VISUAL_FRACTION),
+  shape: z.enum(["bar", "circle", "triangle", "grid"]).default("bar"),
+  divisions: z.number().int().positive().max(VISUAL_FRACTION_MAX_DIVISIONS, {
+    message: `divisions cannot exceed ${VISUAL_FRACTION_MAX_DIVISIONS}`
+  }),
+  filled: z.array(z.number().int().nonnegative()),
+  answer: z.array(z.number().int().nonnegative()),
+  orientation: z.enum(["horizontal", "vertical"]).optional(),
+  /** Optional label text rendered near the shape — replaces the old showLabel boolean */
+  label: z.string().optional(),
+  /** Overall shape size in unified author units.
+   * - bar / grid:         overrides `--visual-fraction-part-size` CSS custom property (cell size in rem).
+   * - circle / triangle:  overrides `--visual-fraction-size` through the renderer scale factor.
+   */
+  size: z.number().positive().optional()
+}).superRefine(validateVisualFractionCapacity);
 const WidgetJSONSchema = z.union([
   InlineInputJSONSchema,
   DragOptionsJSONSchema,
   RadioOptionsJSONSchema,
   NumericKeypadJSONSchema,
   FractionJSONSchema,
-  MatcherWidgetJSONSchema
+  MatcherWidgetJSONSchema,
+  VisualFractionJSONSchema
 ]);
 const ValidationJSONSchema = z.object({
   mode: z.enum([VALIDATION_MODES.SIMPLE, VALIDATION_MODES.EXPRESSION]),
   // Simple answers: string|number per widget id.
   // Matcher answers: string[][] keyed by matcher name. Outer/inner min(1)
   // mirrors MatcherBlockSchema invariants in src/ast/matcher.ts.
+  // VisualFraction answers: number[] — one count per color group.
   answers: z.record(
     z.union([
       z.string(),
       z.number(),
-      z.array(z.array(z.string().min(1)).min(1)).min(1)
+      z.array(z.array(z.string().min(1)).min(1)).min(1),
+      z.array(z.number().int().nonnegative())
     ])
   ).optional(),
   expression: z.string().optional(),
@@ -2179,6 +2478,9 @@ function isColorText(item) {
 function isBoldText(item) {
   return item.type === JSON_TYPES.BOLD_TEXT;
 }
+function isImageItem(item) {
+  return item.type === JSON_TYPES.IMAGE;
+}
 function isSpaceItem(item) {
   return item.type === JSON_TYPES.SPACE;
 }
@@ -2277,13 +2579,15 @@ function toJSON(ast) {
         widgets[inline.name] = {
           type: JSON_TYPES.INLINE_INPUT,
           inputType: INPUT_TYPES.STRING,
-          length: inline.length
+          length: inline.length,
+          placeholder: inline.placeholder
         };
       } else {
         widgets[inline.name] = {
           type: JSON_TYPES.INLINE_INPUT,
           inputType: INPUT_TYPES.NUMERIC,
-          digits: inline.digits
+          digits: inline.digits,
+          placeholder: inline.placeholder
         };
       }
       if (inline.answer !== void 0) {
@@ -2301,6 +2605,22 @@ function toJSON(ast) {
         answers[inline.name] = inline.answer;
       }
     }
+    if (inline.type === AST_TYPES.VISUAL_FRACTION) {
+      const answerArr = inline.answer ?? [];
+      widgets[inline.name] = {
+        type: JSON_TYPES.VISUAL_FRACTION,
+        shape: inline.shape,
+        divisions: inline.divisions,
+        filled: inline.filled ?? [],
+        answer: answerArr,
+        ...inline.orientation !== void 0 && { orientation: inline.orientation },
+        ...inline.label !== void 0 && { label: inline.label },
+        ...inline.size !== void 0 && { size: inline.size }
+      };
+      if (answerArr.length > 0) {
+        answers[inline.name] = answerArr;
+      }
+    }
   }
   for (const block of ast.lines) {
     if (block.type === AST_TYPES.RADIO_OPTIONS) {
@@ -2327,7 +2647,8 @@ function toJSON(ast) {
         widgets["_numeric_keypad"] = {
           type: JSON_TYPES.NUMERIC_KEYPAD,
           includeOperators: tool.includeOperators,
-          includeDecimal: tool.includeDecimal
+          includeDecimal: tool.includeDecimal,
+          style: tool.style
         };
       }
     }
@@ -2531,6 +2852,22 @@ function transformInline(inline, idGenerator) {
         type: JSON_TYPES.WIDGET_REF,
         widgetId: inline.name
       };
+    case AST_TYPES.IMAGE:
+      return {
+        id: idGenerator.generate(JSON_TYPES.IMAGE),
+        type: JSON_TYPES.IMAGE,
+        name: inline.name,
+        src: inline.src,
+        alt: inline.alt,
+        ...inline.width !== void 0 && { width: inline.width },
+        ...inline.height !== void 0 && { height: inline.height }
+      };
+    case AST_TYPES.VISUAL_FRACTION:
+      return {
+        id: idGenerator.generate(JSON_TYPES.WIDGET_REF),
+        type: JSON_TYPES.WIDGET_REF,
+        widgetId: inline.name
+      };
     default:
       throw new Error(`Unknown inline type: ${inline.type}`);
   }
@@ -8073,6 +8410,11 @@ function areMatcherEqual(expected, result) {
   const normalize2 = (groups) => lodashExports.sortBy(groups.map((g) => lodashExports.sortBy(g)), (g) => g.join("|"));
   return lodashExports.isEqual(normalize2(expected), normalize2(result));
 }
+function areVisualFractionCountsEqual(expected, result) {
+  if (!Array.isArray(result)) return false;
+  if (expected.length !== result.length) return false;
+  return lodashExports.isEqual(lodashExports.sortBy(expected), lodashExports.sortBy(result));
+}
 const math$1 = create(all);
 function collectNumberLines(items) {
   const result = [];
@@ -8121,6 +8463,15 @@ function validateSimple(exercise, userInputs) {
       else allCorrect = false;
       continue;
     }
+    if (widget?.type === JSON_TYPES.VISUAL_FRACTION) {
+      const userValue2 = userInputs[widgetId];
+      const isCorrect2 = areVisualFractionCountsEqual(expected, userValue2);
+      details[widgetId] = { widgetId, userValue: userValue2, isCorrect: isCorrect2 };
+      totalCount++;
+      if (isCorrect2) correctCount++;
+      else allCorrect = false;
+      continue;
+    }
     totalCount++;
     const userValue = userInputs[widgetId];
     const isFractionLenient = widget?.type === JSON_TYPES.FRACTION && widget.simplified === false;
@@ -8627,10 +8978,10 @@ function getOwnerDocument(target) {
   }
   return document;
 }
-const useIsomorphicLayoutEffect = canUseDOM ? useLayoutEffect : useEffect;
+const useIsomorphicLayoutEffect$1 = canUseDOM ? useLayoutEffect : useEffect;
 function useEvent(handler) {
   const handlerRef = useRef(handler);
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     handlerRef.current = handler;
   });
   return useCallback(function() {
@@ -8658,7 +9009,7 @@ function useLatestValue(value, dependencies) {
     dependencies = [value];
   }
   const valueRef = useRef(value);
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     if (valueRef.current !== value) {
       valueRef.current = value;
     }
@@ -10526,9 +10877,9 @@ function useResizeObserver(_ref) {
         return void 0;
       }
       const {
-        ResizeObserver
+        ResizeObserver: ResizeObserver2
       } = window;
-      return new ResizeObserver(handleResize);
+      return new ResizeObserver2(handleResize);
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [disabled]
@@ -10582,7 +10933,7 @@ function useRect(element, measure, fallbackRect) {
   const resizeObserver = useResizeObserver({
     callback: measureRect
   });
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     measureRect();
     if (element) {
       resizeObserver == null ? void 0 : resizeObserver.observe(element);
@@ -10756,7 +11107,7 @@ function useRects(elements, measure) {
   const resizeObserver = useResizeObserver({
     callback: measureRects
   });
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     resizeObserver == null ? void 0 : resizeObserver.disconnect();
     measureRects();
     elements.forEach((element) => resizeObserver == null ? void 0 : resizeObserver.observe(element));
@@ -11118,7 +11469,7 @@ function useLayoutShiftScrollCompensation(_ref) {
     x: config,
     y: config
   } : config;
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     const disabled = !x && !y;
     if (disabled || !activeNode) {
       initialized.current = false;
@@ -11479,7 +11830,7 @@ const DndContext = /* @__PURE__ */ memo(function DndContext2(_ref) {
   }, [draggableNodes, instantiateSensor]);
   const activators = useCombineActivators(sensors, bindActivatorToSensorInstantiator);
   useSensorSetup(sensors);
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     if (activeNodeRect && status === Status.Initializing) {
       setStatus(Status.Initialized);
     }
@@ -11563,7 +11914,7 @@ const DndContext = /* @__PURE__ */ memo(function DndContext2(_ref) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [overId]
   );
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     sensorContext.current = {
       activatorEvent,
       active,
@@ -11690,7 +12041,7 @@ function useDraggable(_ref) {
   const [activatorNode, setActivatorNodeRef] = useNodeRef();
   const listeners = useSyntheticListeners(activators, id);
   const dataRef = useLatestValue(data);
-  useIsomorphicLayoutEffect(
+  useIsomorphicLayoutEffect$1(
     () => {
       draggableNodes.set(id, {
         id,
@@ -11863,7 +12214,7 @@ function AnimationManager(_ref) {
   if (!children && !clonedChildren && previousChildren) {
     setClonedChildren(previousChildren);
   }
-  useIsomorphicLayoutEffect(() => {
+  useIsomorphicLayoutEffect$1(() => {
     if (!element) {
       return;
     }
@@ -12545,6 +12896,7 @@ const InlineInput = ({
   inputType,
   length,
   digits,
+  placeholder,
   onChange,
   onFocus
 }) => {
@@ -12590,19 +12942,88 @@ const InlineInput = ({
             onChange: (e) => handleChange(e.target.value, false),
             onFocus: () => onFocus?.(widgetId),
             maxLength: expectedLength,
-            style: { width: dynamicWidth }
+            style: { width: dynamicWidth },
+            placeholder
           }
         )
       )
     }
   );
 };
+const PillBackground = ({
+  width = "100%",
+  minHeight = "72px",
+  fill = "#FFE7B4",
+  children,
+  className = "",
+  style,
+  ...rest
+}) => {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `pill-bg-wrapper ${className}`.trim(),
+      style: {
+        position: "relative",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width,
+        minHeight,
+        ...style
+      },
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsx(
+          "svg",
+          {
+            viewBox: "0 0 510 108",
+            preserveAspectRatio: "none",
+            xmlns: "http://www.w3.org/2000/svg",
+            "aria-hidden": "true",
+            style: {
+              position: "absolute",
+              inset: 0,
+              width: "100%",
+              height: "100%",
+              display: "block"
+            },
+            children: /* @__PURE__ */ jsx(
+              "path",
+              {
+                d: "M439.707 0C457.071 0 472.52 8.196 482.398 20.9297C498.608 26.3308 510 39.1028 510 54C510 68.8966 498.608 81.667 482.399 87.0684C472.521 99.803 457.072 108 439.707 108H70.8975C53.653 108 38.2956 99.9172 28.4092 87.333C11.7719 82.0918 0.00025108 69.1432 0 54C0 38.8562 11.7721 25.906 28.4102 20.665C38.2966 8.08186 53.6537 0 70.8975 0H439.707Z",
+                fill
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              position: "relative",
+              zIndex: 1,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              width: "100%",
+              height: "100%",
+              padding: "0 2rem",
+              boxSizing: "border-box"
+            },
+            children
+          }
+        )
+      ]
+    }
+  );
+};
 const DragOptions = ({
   options,
   onOptionClick
 }) => {
   const { usedOptionIds } = useExerciseDnd();
-  return /* @__PURE__ */ jsx("div", { className: "drag-options", children: options.map((option, idx) => {
+  return /* @__PURE__ */ jsx(PillBackground, { children: /* @__PURE__ */ jsx("div", { className: "drag-options", children: options.map((option, idx) => {
     const optionId = `drag-option-${idx}`;
     const optionValue = String(option);
     const isUsed = usedOptionIds.has(optionId);
@@ -12629,7 +13050,7 @@ const DragOptions = ({
         }
       )
     ) }, optionId);
-  }) });
+  }) }) });
 };
 const NumericKeypad = ({
   value,
@@ -12725,28 +13146,6 @@ const FractionInput = ({
     /* @__PURE__ */ jsx("span", { className: "fraction-denominator", children: renderSlot(denKey, denominator, denValue, "denominator") })
   ] });
 };
-const RadioOptions = ({
-  name,
-  options,
-  value,
-  validationStatus = null,
-  onChange
-}) => {
-  return /* @__PURE__ */ jsx("div", { className: "radio-options", children: options.map((option, idx) => {
-    const isSelected = value === option;
-    const statusClass = isSelected && validationStatus ? ` widget--${validationStatus}` : "";
-    return /* @__PURE__ */ jsx(
-      "button",
-      {
-        className: `radio-option${isSelected ? " selected" : ""}${statusClass}`,
-        onClick: () => onChange(name, option),
-        type: "button",
-        children: option
-      },
-      `${name}-radio-${idx}`
-    );
-  }) });
-};
 function isLightColor(hex) {
   const clean = hex.replace("#", "");
   const full = clean.length === 3 ? clean.split("").map((c) => c + c).join("") : clean;
@@ -12761,7 +13160,8 @@ function isLightColor(hex) {
   return 1.05 / (L + 0.05) < 4.5;
 }
 function getTextColorForBackground(color) {
-  if (color.startsWith("hsl(")) return "#1a1a1a";
+  const hslLightness = parseHslLightness(color);
+  if (hslLightness !== null) return hslLightness >= 60 ? "#1a1a1a" : "#ffffff";
   return isLightColor(color) ? "#1a1a1a" : "#ffffff";
 }
 function generateHslPalette(n) {
@@ -12770,7 +13170,7 @@ function generateHslPalette(n) {
     return `hsl(${hue}, 60%, 72%)`;
   });
 }
-function resolveMatcherPalette(userColors, groupCount) {
+function resolveGroupPalette(userColors, groupCount) {
   if (groupCount <= 0) return [];
   if (!userColors || userColors.length === 0) {
     return generateHslPalette(groupCount);
@@ -12782,6 +13182,478 @@ function resolveMatcherPalette(userColors, groupCount) {
   const extras = generateHslPalette(needed);
   return [...userColors, ...extras];
 }
+function resolveDistinctGroupPalette(groupCount, options = {}) {
+  if (groupCount <= 0) return [];
+  const used = new Set((options.excludeColors ?? []).map(normalizeColorToken));
+  const palette = [];
+  for (const color of options.seedColors ?? []) {
+    const token = normalizeColorToken(color);
+    if (used.has(token)) continue;
+    palette.push(color);
+    used.add(token);
+    if (palette.length === groupCount) return palette;
+  }
+  const addCandidates = (candidates) => {
+    for (const color of candidates) {
+      const token = normalizeColorToken(color);
+      if (used.has(token)) continue;
+      palette.push(color);
+      used.add(token);
+      if (palette.length === groupCount) return;
+    }
+  };
+  addCandidates(generateHslPalette(groupCount));
+  let candidateCount = groupCount + 1;
+  while (palette.length < groupCount) {
+    addCandidates(generateHslPalette(candidateCount++));
+  }
+  return palette;
+}
+function getGroupClassName(groupIndex) {
+  return `widget-group-${groupIndex + 1}`;
+}
+function normalizeColorToken(color) {
+  return color.replace(/\s+/g, "").toLowerCase();
+}
+function parseHslLightness(color) {
+  const match = color.match(/^hsl\(\s*[\d.]+\s*,\s*[\d.]+%\s*,\s*([\d.]+)%\s*\)$/i);
+  return match ? Number(match[1]) : null;
+}
+function sumCounts(counts) {
+  return counts.reduce((sum, count) => sum + count, 0);
+}
+function countsToPartGroups(counts) {
+  return counts.flatMap(
+    (count, groupIndex) => Array.from({ length: count }, () => groupIndex)
+  );
+}
+function normalizeCounts(value, expected) {
+  if (!Array.isArray(value)) return expected.map(() => 0);
+  return expected.map((max, i) => Math.max(0, Math.min(max, value[i] ?? 0)));
+}
+function serializeCounts(value) {
+  return Array.isArray(value) ? value.join("|") : null;
+}
+function countsToAssignments(counts, divisions, filledCount) {
+  const assignments = Array.from({ length: divisions }, () => null);
+  let index = filledCount;
+  counts.forEach((count, groupIndex) => {
+    for (let i = 0; i < count && index < divisions; i++) {
+      assignments[index] = groupIndex;
+      index++;
+    }
+  });
+  return assignments;
+}
+function getNextAssignments(assignments, partIndex, groupCount) {
+  if (groupCount === 0) return [...assignments];
+  const current = assignments[partIndex] ?? null;
+  const next = current === null ? 0 : current + 1 >= groupCount ? null : current + 1;
+  const updated = [...assignments];
+  updated[partIndex] = next;
+  return updated;
+}
+function assignmentsToCounts(assignments, groupCount) {
+  const counts = Array.from({ length: groupCount }, () => 0);
+  for (const groupIndex of assignments) {
+    if (groupIndex !== null && groupIndex >= 0 && groupIndex < groupCount) {
+      counts[groupIndex] = (counts[groupIndex] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+function useVisualFractionState({
+  widgetId,
+  divisions,
+  filledCount,
+  answer,
+  value,
+  onChange
+}) {
+  const [partAssignments, setPartAssignments] = useState(
+    () => countsToAssignments(normalizeCounts(value, answer), divisions, filledCount)
+  );
+  const lastInternalValueRef = useRef(null);
+  const valueKey = serializeCounts(value);
+  useEffect(() => {
+    if (valueKey !== null && valueKey === lastInternalValueRef.current) return;
+    lastInternalValueRef.current = null;
+    setPartAssignments(
+      countsToAssignments(normalizeCounts(value, answer), divisions, filledCount)
+    );
+  }, [answer, divisions, filledCount, valueKey]);
+  const handlePartClick = (partIndex) => {
+    if (partIndex < filledCount) return;
+    const updated = getNextAssignments(partAssignments, partIndex, answer.length);
+    const nextCounts = assignmentsToCounts(updated, answer.length);
+    lastInternalValueRef.current = serializeCounts(nextCounts);
+    setPartAssignments(updated);
+    onChange(widgetId, nextCounts);
+  };
+  return { partAssignments, handlePartClick };
+}
+const VISUAL_FRACTION_DISPLAY_COLOR = "#AE9CFF";
+const VISUAL_FRACTION_BORDER_COLOR = "#705DC0";
+const VISUAL_FRACTION_SVG_SIZE_SCALE = 8;
+function getCircleSectorProps(index, divisions) {
+  if (divisions <= 1) return { kind: "circle" };
+  const angle = 360 / divisions;
+  const startAngle = -90 + index * angle;
+  const endAngle = startAngle + angle;
+  const start = polarToCartesian(50, 50, 48, endAngle);
+  const end = polarToCartesian(50, 50, 48, startAngle);
+  const largeArcFlag = angle > 180 ? 1 : 0;
+  return {
+    kind: "path",
+    d: [
+      "M",
+      50,
+      50,
+      "L",
+      start.x,
+      start.y,
+      "A",
+      48,
+      48,
+      0,
+      largeArcFlag,
+      0,
+      end.x,
+      end.y,
+      "Z"
+    ].join(" ")
+  };
+}
+function polarToCartesian(cx, cy, r, angleInDegrees) {
+  const rad = angleInDegrees * Math.PI / 180;
+  return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) };
+}
+function getEqualTrianglePartPath(index, divisions) {
+  const side = Math.sqrt(divisions);
+  if (!Number.isInteger(side)) {
+    throw new Error(`getEqualTrianglePartPath: divisions (${divisions}) must be a perfect square.`);
+  }
+  const smallSide = 96 / side;
+  const smallHeight = smallSide * Math.sqrt(3) / 2;
+  const totalHeight = side * smallHeight;
+  const offsetY = (100 - totalHeight) / 2;
+  let cursor = 0;
+  for (let row = 0; row < side; row++) {
+    const y = offsetY + row * smallHeight;
+    const rowLeft = 50 - (row + 1) * smallSide / 2;
+    for (let col = 0; col <= row; col++) {
+      if (cursor === index) {
+        const x = rowLeft + col * smallSide;
+        return ["M", x + smallSide / 2, y, "L", x + smallSide, y + smallHeight, "L", x, y + smallHeight, "Z"].join(" ");
+      }
+      cursor++;
+    }
+    for (let col = 0; col < row; col++) {
+      if (cursor === index) {
+        const x = rowLeft + col * smallSide;
+        return ["M", x + smallSide, y + smallHeight, "L", x + smallSide / 2, y, "L", x + smallSide * 1.5, y, "Z"].join(" ");
+      }
+      cursor++;
+    }
+  }
+  return "";
+}
+function getGridColumnCount(divisions) {
+  return Math.ceil(Math.sqrt(divisions));
+}
+function getInteractiveProps(part, onPartClick) {
+  if (!part.isInteractiveSlot) return {};
+  return {
+    onClick: () => onPartClick(part.index),
+    role: "button",
+    "aria-pressed": part.isSelected,
+    "aria-label": getPartAriaLabel(part),
+    tabIndex: 0,
+    onKeyDown: (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        onPartClick(part.index);
+      }
+    }
+  };
+}
+function getPartAriaLabel(part) {
+  return part.groupIndex === null ? `Part ${part.index + 1}, empty` : `Part ${part.index + 1}, group ${part.groupIndex + 1}`;
+}
+const BarShape = ({
+  parts,
+  divisions,
+  orientation,
+  onPartClick
+}) => {
+  const renderedParts = orientation === "vertical" ? [...parts].reverse() : parts;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: `visual-fraction-widget__parts${orientation === "vertical" ? " visual-fraction-widget__parts--vertical" : " visual-fraction-widget__parts--horizontal"}`,
+      style: { "--visual-fraction-divisions": divisions },
+      children: renderedParts.map((part) => /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: part.className,
+          style: part.style,
+          ...getInteractiveProps(part, onPartClick)
+        },
+        part.index
+      ))
+    }
+  );
+};
+BarShape.displayName = "BarShape";
+const GridShape = ({
+  parts,
+  divisions,
+  onPartClick
+}) => /* @__PURE__ */ jsx(
+  "div",
+  {
+    className: "visual-fraction-widget__parts visual-fraction-widget__parts--horizontal",
+    style: {
+      "--visual-fraction-divisions": divisions,
+      "--visual-fraction-grid-cols": getGridColumnCount(divisions)
+    },
+    children: parts.map((part) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: part.className,
+        style: part.style,
+        ...getInteractiveProps(part, onPartClick)
+      },
+      part.index
+    ))
+  }
+);
+GridShape.displayName = "GridShape";
+const CircleShape = ({
+  parts,
+  divisions,
+  onPartClick
+}) => /* @__PURE__ */ jsx(
+  "svg",
+  {
+    className: "visual-fraction-widget__shape visual-fraction-widget__circle",
+    viewBox: "0 0 100 100",
+    children: parts.map((part) => {
+      const sectorProps = getCircleSectorProps(part.index, divisions);
+      const className = `${part.className} visual-fraction-widget__sector`;
+      const interactiveProps = getInteractiveProps(part, onPartClick);
+      return sectorProps.kind === "circle" ? /* @__PURE__ */ jsx(
+        "circle",
+        {
+          className,
+          style: part.style,
+          cx: "50",
+          cy: "50",
+          r: "48",
+          ...interactiveProps
+        },
+        part.index
+      ) : /* @__PURE__ */ jsx(
+        "path",
+        {
+          className,
+          style: part.style,
+          d: sectorProps.d,
+          ...interactiveProps
+        },
+        part.index
+      );
+    })
+  }
+);
+CircleShape.displayName = "CircleShape";
+const TriangleShape = ({
+  parts,
+  divisions,
+  onPartClick
+}) => /* @__PURE__ */ jsx(
+  "svg",
+  {
+    className: "visual-fraction-widget__shape visual-fraction-widget__triangle",
+    viewBox: "0 0 100 100",
+    children: parts.map((part) => /* @__PURE__ */ jsx(
+      "path",
+      {
+        className: `${part.className} visual-fraction-widget__sector`,
+        style: part.style,
+        d: getEqualTrianglePartPath(part.index, divisions),
+        ...getInteractiveProps(part, onPartClick)
+      },
+      part.index
+    ))
+  }
+);
+TriangleShape.displayName = "TriangleShape";
+const ShapeBar = ({ parts, divisions, orientation, onPartClick }) => /* @__PURE__ */ jsx(BarShape, { parts, divisions, orientation, onPartClick });
+const ShapeCircle = ({ parts, divisions, onPartClick }) => /* @__PURE__ */ jsx(CircleShape, { parts, divisions, onPartClick });
+const ShapeTriangle = ({ parts, divisions, onPartClick }) => /* @__PURE__ */ jsx(TriangleShape, { parts, divisions, onPartClick });
+const ShapeGrid = ({ parts, divisions, onPartClick }) => /* @__PURE__ */ jsx(GridShape, { parts, divisions, onPartClick });
+const SHAPE_COMPONENTS = {
+  [VISUAL_FRACTION_SHAPE.BAR]: ShapeBar,
+  [VISUAL_FRACTION_SHAPE.CIRCLE]: ShapeCircle,
+  [VISUAL_FRACTION_SHAPE.TRIANGLE]: ShapeTriangle,
+  [VISUAL_FRACTION_SHAPE.GRID]: ShapeGrid
+};
+const VisualFraction = ({
+  widgetId,
+  widget,
+  value,
+  validationStatus = null,
+  onChange
+}) => {
+  const { shape, divisions, filled, answer, orientation, label } = widget;
+  const filledCount = sumCounts(filled);
+  const filledPartGroups = useMemo(() => countsToPartGroups(filled), [filled]);
+  const filledPalette = useMemo(() => {
+    if (filled.length === 0) return [];
+    return resolveDistinctGroupPalette(filled.length, {
+      seedColors: [VISUAL_FRACTION_DISPLAY_COLOR],
+      excludeColors: [VISUAL_FRACTION_BORDER_COLOR]
+    });
+  }, [filled]);
+  const answerPalette = useMemo(() => {
+    if (answer.length === 0) return [];
+    return resolveDistinctGroupPalette(answer.length, {
+      excludeColors: [VISUAL_FRACTION_BORDER_COLOR, ...filledPalette]
+    });
+  }, [answer, filledPalette]);
+  const { partAssignments, handlePartClick } = useVisualFractionState({
+    widgetId,
+    divisions,
+    filledCount,
+    answer,
+    value,
+    onChange
+  });
+  const parts = useMemo(
+    () => Array.from({ length: divisions }, (_, i) => {
+      let partClass = "visual-fraction-widget__part visual-fraction-widget__part--empty";
+      let groupIdx = null;
+      if (i < filledCount) {
+        groupIdx = filledPartGroups[i] ?? 0;
+        partClass = "visual-fraction-widget__part visual-fraction-widget__part--filled";
+      } else if (partAssignments[i] != null) {
+        groupIdx = partAssignments[i];
+        partClass = "visual-fraction-widget__part visual-fraction-widget__part--answer";
+      }
+      if (groupIdx !== null) {
+        partClass += ` visual-fraction-widget__part--group-${groupIdx + 1} ${getGroupClassName(groupIdx)}`;
+      }
+      const colorKind = i < filledCount ? "filled" : "answer";
+      const palette = colorKind === "filled" ? filledPalette : answerPalette;
+      const fallbackColor = palette[groupIdx ?? 0];
+      const style = groupIdx !== null ? {
+        "--visual-fraction-part-color": `var(--visual-fraction-${colorKind}-group-${groupIdx + 1}-color, ${fallbackColor})`,
+        "--visual-fraction-part-text-color": `var(--visual-fraction-${colorKind}-group-${groupIdx + 1}-text-color, ${getTextColorForBackground(fallbackColor)})`
+      } : void 0;
+      return {
+        index: i,
+        className: partClass,
+        style,
+        // A slot is interactive when there are answer groups AND it falls in the non-filled range.
+        // answer.length counts groups (not total slots); the state hook handles per-slot cycling.
+        isInteractiveSlot: answer.length > 0 && i >= filledCount,
+        isSelected: groupIdx !== null,
+        groupIndex: groupIdx
+      };
+    }),
+    [divisions, filledCount, filledPartGroups, partAssignments, answer, filledPalette, answerPalette]
+  );
+  const statusClass = validationStatus ? ` visual-fraction-widget--${validationStatus} widget--${validationStatus}` : "";
+  const rootStyle = useMemo(() => getSizeStyle(widget.size, shape), [widget.size, shape]);
+  const ShapeComponent = SHAPE_COMPONENTS[shape];
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `visual-fraction-widget visual-fraction-widget--${shape}${statusClass}`,
+      style: rootStyle,
+      role: "group",
+      "aria-label": `${divisions} part ${shape} fraction`,
+      children: [
+        /* @__PURE__ */ jsx(
+          ShapeComponent,
+          {
+            parts,
+            divisions,
+            orientation: orientation ?? "horizontal",
+            onPartClick: handlePartClick
+          }
+        ),
+        label && /* @__PURE__ */ jsx("span", { className: "visual-fraction-widget__label", children: label })
+      ]
+    }
+  );
+};
+VisualFraction.displayName = "VisualFraction";
+function getSizeStyle(size, shape) {
+  if (size === void 0) return void 0;
+  if (shape === "circle" || shape === "triangle") {
+    return {
+      "--visual-fraction-size": `${size * VISUAL_FRACTION_SVG_SIZE_SCALE}rem`
+    };
+  }
+  return {
+    "--visual-fraction-part-size": `${size}rem`
+  };
+}
+const RadioOptions = ({
+  name,
+  options,
+  value,
+  validationStatus = null,
+  onChange
+}) => {
+  return /* @__PURE__ */ jsx("div", { className: "radio-options", children: options.map((option, idx) => {
+    const isSelected = value === option;
+    const statusClass = isSelected && validationStatus ? ` widget--${validationStatus}` : "";
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        className: `radio-option${isSelected ? " selected" : ""}${statusClass}`,
+        onClick: () => onChange(name, option),
+        type: "button",
+        children: option
+      },
+      `${name}-radio-${idx}`
+    );
+  }) });
+};
+const Btn = ({
+  label,
+  extraClass = "keypad-btn-digit",
+  onClick
+}) => /* @__PURE__ */ jsx("button", { className: `keypad-btn ${extraClass}`, onClick, children: /* @__PURE__ */ jsx("span", { children: label }) });
+const DiamondKeypad = ({ value, onChange }) => {
+  const append = (ch) => onChange(value + ch);
+  const backspace = () => onChange(value.slice(0, -1));
+  return /* @__PURE__ */ jsxs("div", { className: "diamond-keypad", children: [
+    /* @__PURE__ */ jsxs("div", { className: "diamond-keypad-row", children: [
+      /* @__PURE__ */ jsx(Btn, { label: "1", onClick: () => append("1") }),
+      /* @__PURE__ */ jsx(Btn, { label: "2", onClick: () => append("2") }),
+      /* @__PURE__ */ jsx(Btn, { label: "3", onClick: () => append("3") })
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "diamond-keypad-row", children: [
+      /* @__PURE__ */ jsx(Btn, { label: "4", onClick: () => append("4") }),
+      /* @__PURE__ */ jsx(Btn, { label: "5", onClick: () => append("5") }),
+      /* @__PURE__ */ jsx(Btn, { label: "6", onClick: () => append("6") }),
+      /* @__PURE__ */ jsx(Btn, { label: "7", onClick: () => append("7") })
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "diamond-keypad-row", children: [
+      /* @__PURE__ */ jsx(Btn, { label: "8", onClick: () => append("8") }),
+      /* @__PURE__ */ jsx(Btn, { label: "9", onClick: () => append("9") }),
+      /* @__PURE__ */ jsx(Btn, { label: "0", onClick: () => append("0") })
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "diamond-keypad-row", children: [
+      /* @__PURE__ */ jsx(Btn, { label: ".", extraClass: "keypad-btn-decimal", onClick: () => append(".") }),
+      /* @__PURE__ */ jsx(Btn, { label: "⌫", extraClass: "keypad-btn-backspace", onClick: backspace })
+    ] })
+  ] });
+};
 function collectItemIds(rows) {
   return rows.flatMap((row) => row.items.map((item) => item.itemId));
 }
@@ -12823,7 +13695,7 @@ const MatcherWidget = ({
   const { rows, colors: userColors, groupCount } = widget;
   const widgetsMap = widgets ?? EMPTY_WIDGETS;
   const palette = useMemo(
-    () => resolveMatcherPalette(userColors, groupCount),
+    () => resolveGroupPalette(userColors, groupCount),
     [userColors, groupCount]
   );
   const textColors = useMemo(
@@ -12839,13 +13711,21 @@ const MatcherWidget = ({
       setAssignments((prev) => {
         const current = prev[itemId] ?? null;
         const next = current === null ? 0 : current + 1 >= groupCount ? null : current + 1;
-        const updated = { ...prev, [itemId]: next };
-        onChange(widgetId, buildGroups(updated));
-        return updated;
+        return { ...prev, [itemId]: next };
       });
     },
-    [groupCount, onChange, widgetId]
+    [groupCount]
   );
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const isMounted = useRef(false);
+  useEffect(() => {
+    if (!isMounted.current) {
+      isMounted.current = true;
+      return;
+    }
+    onChangeRef.current(widgetId, buildGroups(assignments));
+  }, [assignments, widgetId]);
   const maxCols = useMemo(
     () => rows.length === 0 ? 1 : Math.max(...rows.map((r) => r.items.length)),
     [rows]
@@ -12866,9 +13746,9 @@ const MatcherWidget = ({
           {
             type: "button",
             className: `matcher-card${isSelected ? " matcher-card--selected" : ""}`,
-            style: color ? {
-              "--matcher-card-color": color,
-              "--matcher-card-text-color": textColors[colorIdx]
+            style: colorIdx !== null && color ? {
+              "--matcher-card-color": `var(--matcher-group-${colorIdx + 1}-color, ${color})`,
+              "--matcher-card-text-color": `var(--matcher-group-${colorIdx + 1}-text-color, ${textColors[colorIdx]})`
             } : void 0,
             onClick: () => handleCardClick(item.itemId),
             "aria-pressed": isSelected,
@@ -12910,6 +13790,9 @@ function isFractionWidget(widget) {
 function isMatcherWidget(widget) {
   return widget.type === "matcher";
 }
+function isVisualFractionWidget(widget) {
+  return widget.type === "visual-fraction";
+}
 const WidgetRenderer = ({
   widget,
   widgetId,
@@ -12935,6 +13818,7 @@ const WidgetRenderer = ({
         inputType: widget.inputType,
         length: widget.inputType === "string" ? widget.length : void 0,
         digits: widget.inputType === "numeric" ? widget.digits : void 0,
+        placeholder: widget.placeholder,
         onChange,
         onFocus: onInputFocus
       }
@@ -12963,14 +13847,24 @@ const WidgetRenderer = ({
     );
   }
   if (isNumericKeypadWidget(widget)) {
+    const keypadOnChange = onKeypadChange || (() => {
+    });
+    if (widget.style === "classic") {
+      return /* @__PURE__ */ jsx(
+        NumericKeypad,
+        {
+          value: strValue,
+          includeOperators: widget.includeOperators,
+          includeDecimal: widget.includeDecimal,
+          onChange: keypadOnChange
+        }
+      );
+    }
     return /* @__PURE__ */ jsx(
-      NumericKeypad,
+      DiamondKeypad,
       {
         value: strValue,
-        includeOperators: widget.includeOperators,
-        includeDecimal: widget.includeDecimal,
-        onChange: onKeypadChange || (() => {
-        })
+        onChange: keypadOnChange
       }
     );
   }
@@ -13002,6 +13896,18 @@ const WidgetRenderer = ({
       }
     );
   }
+  if (isVisualFractionWidget(widget)) {
+    return /* @__PURE__ */ jsx(
+      VisualFraction,
+      {
+        widgetId,
+        widget,
+        value: Array.isArray(value) && value.every((v) => typeof v === "number") ? value : void 0,
+        validationStatus,
+        onChange: (id, nextValue) => onChange(id, nextValue)
+      }
+    );
+  }
   return null;
 };
 const EPSILON = 10 ** -INTERNAL_PRECISION;
@@ -13504,6 +14410,102 @@ const CounterControls = ({
   ] }),
   counter.name && /* @__PURE__ */ jsx("span", { className: "number-line-counter-label", children: counter.name })
 ] });
+const CONTENT_ROW_EXTRA_SPACE = 8;
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useMeasuredPositionContentHeight(positionIds) {
+  const [heightPx, setHeightPx] = useState(null);
+  const elementsRef = useRef(/* @__PURE__ */ new Map());
+  const refCallbacksRef = useRef(/* @__PURE__ */ new Map());
+  const observerRef = useRef(null);
+  const measureFrameRef = useRef(null);
+  const idsKey = positionIds.join("|");
+  const runMeasure = useCallback(() => {
+    let maxHeight = 0;
+    for (const element of elementsRef.current.values()) {
+      const rectHeight = element.getBoundingClientRect().height;
+      const measuredHeight = Math.max(rectHeight, element.offsetHeight);
+      maxHeight = Math.max(maxHeight, measuredHeight);
+    }
+    const nextHeight = maxHeight > 0 ? Math.ceil(maxHeight + CONTENT_ROW_EXTRA_SPACE) : null;
+    setHeightPx((current) => current === nextHeight ? current : nextHeight);
+  }, []);
+  const measure = useCallback(() => {
+    if (typeof window === "undefined" || typeof window.requestAnimationFrame !== "function") {
+      runMeasure();
+      return;
+    }
+    if (measureFrameRef.current !== null) return;
+    measureFrameRef.current = window.requestAnimationFrame(() => {
+      measureFrameRef.current = null;
+      runMeasure();
+    });
+  }, [runMeasure]);
+  useEffect(
+    () => () => {
+      if (measureFrameRef.current !== null && typeof window !== "undefined") {
+        window.cancelAnimationFrame(measureFrameRef.current);
+        measureFrameRef.current = null;
+      }
+    },
+    []
+  );
+  const getPositionContentRef = useCallback(
+    (id) => {
+      const cachedRef = refCallbacksRef.current.get(id);
+      if (cachedRef) return cachedRef;
+      const refCallback = (node) => {
+        const current = elementsRef.current.get(id);
+        if (current && observerRef.current) {
+          observerRef.current.unobserve(current);
+        }
+        if (node) {
+          elementsRef.current.set(id, node);
+          observerRef.current?.observe(node);
+        } else {
+          elementsRef.current.delete(id);
+        }
+        measure();
+      };
+      refCallbacksRef.current.set(id, refCallback);
+      return refCallback;
+    },
+    [measure]
+  );
+  useEffect(() => {
+    const liveIds = new Set(positionIds);
+    for (const id of elementsRef.current.keys()) {
+      if (!liveIds.has(id)) {
+        elementsRef.current.delete(id);
+      }
+    }
+    for (const id of refCallbacksRef.current.keys()) {
+      if (!liveIds.has(id)) {
+        refCallbacksRef.current.delete(id);
+      }
+    }
+    measure();
+  }, [idsKey, measure]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof ResizeObserver === "undefined") {
+      measure();
+      return void 0;
+    }
+    const observer = new ResizeObserver(measure);
+    observerRef.current = observer;
+    for (const element of elementsRef.current.values()) {
+      observer.observe(element);
+    }
+    measure();
+    return () => {
+      observer.disconnect();
+      observerRef.current = null;
+    };
+  }, [idsKey, measure]);
+  return {
+    positionContentHeight: heightPx === null ? void 0 : `${heightPx}px`,
+    getPositionContentRef
+  };
+}
 const NumberLineRenderer = ({
   item,
   widgets,
@@ -13558,17 +14560,26 @@ const NumberLineRenderer = ({
     () => positions.filter((pos) => !isDragMode || getPositionWidgetId(pos.content) === null),
     [isDragMode, positions]
   );
+  const visiblePositionIds = useMemo(
+    () => visiblePositions.map((pos) => pos.id),
+    [visiblePositions]
+  );
+  const { positionContentHeight, getPositionContentRef } = useMeasuredPositionContentHeight(visiblePositionIds);
   return /* @__PURE__ */ jsxs(
     "div",
     {
       className: `number-line${isDragMode ? " number-line--drag-mode" : ""}${lineStyle === "line" ? " number-line--style-line" : ""}`,
-      style: { [CSS_VAR_SIDE_PAD]: `${SIDE_PAD}%` },
+      style: {
+        [CSS_VAR_SIDE_PAD]: `${SIDE_PAD}%`,
+        ...positionContentHeight && { "--nl-position-content-height": positionContentHeight }
+      },
       role: "group",
       "aria-label": `Number line from ${min} to ${max}`,
       children: [
         visiblePositions.length > 0 && /* @__PURE__ */ jsx("div", { className: "number-line-content-row", children: visiblePositions.map((pos) => /* @__PURE__ */ jsx(
           "div",
           {
+            ref: getPositionContentRef(pos.id),
             className: "number-line-position-content",
             style: { left: `${toPercent(pos.value, min, max)}%` },
             children: pos.content.map((subItem) => /* @__PURE__ */ jsx(
@@ -13754,12 +14765,24 @@ const LayoutRenderer = ({
       }
       return /* @__PURE__ */ jsx("strong", { className: "bold-text text-item", dir: dirAttr, children: item.value });
     }
+    case JSON_TYPES.IMAGE:
+      return /* @__PURE__ */ jsx(
+        "img",
+        {
+          className: "image-item text-item",
+          src: item.src,
+          alt: item.alt,
+          ...item.width !== void 0 && { width: item.width },
+          ...item.height !== void 0 && { height: item.height },
+          loading: "lazy"
+        }
+      );
     case JSON_TYPES.WIDGET_REF: {
       const widget = widgets[item.widgetId];
       if (!widget) return null;
       const isCorrect = validationDetails?.[item.widgetId];
       const validationStatus = isCorrect === true ? "correct" : isCorrect === false ? "incorrect" : null;
-      const widgetKey = widget.type === JSON_TYPES.MATCHER ? `${item.widgetId}-${resetKey}` : item.widgetId;
+      const widgetKey = widget.type === JSON_TYPES.MATCHER || widget.type === JSON_TYPES.VISUAL_FRACTION ? `${item.widgetId}-${resetKey}` : item.widgetId;
       return /* @__PURE__ */ jsx(
         WidgetRenderer,
         {
@@ -14129,6 +15152,8 @@ export {
   GroupItemSchema,
   HighlightedTextInlineSchema,
   HighlightedTextSchema,
+  ImageInlineSchema,
+  ImageItemSchema,
   InlineInputJSONSchema,
   InlineInputWidgetSchema,
   InlineNodeSchema,
@@ -14162,9 +15187,14 @@ export {
   TextItemSchema,
   ToolNodeSchema,
   TransformError,
+  VISUAL_FRACTION_DEFAULT_SIZE,
+  VISUAL_FRACTION_MAX_DIVISIONS,
+  VISUAL_FRACTION_SHAPE,
+  VISUAL_FRACTION_SHAPES,
   ValidationError,
   ValidationJSONSchema,
   ValidationNodeSchema,
+  VisualFractionInlineSchema,
   WidgetJSONSchema,
   WidgetRefSchema,
   WidgetRenderer,
@@ -14178,6 +15208,7 @@ export {
   createFraction,
   createFreeText,
   createHighlightedText,
+  createImage,
   createLineBlock,
   createMatcherBlock,
   createMatcherItem,
@@ -14188,6 +15219,7 @@ export {
   createSpace,
   createStringInput,
   createTextBlock,
+  createVisualFraction,
   evaluate,
   extractVariables as extractExpressionVariables,
   findValidCombination,
@@ -14205,6 +15237,8 @@ export {
   isFreeText,
   isGroupItem,
   isHighlightedText,
+  isImage,
+  isImageItem,
   isInlineInput,
   isInlineInputJSON,
   isInlineNode,
@@ -14229,6 +15263,7 @@ export {
   isToolNode,
   isValidExpression,
   isValidationNode,
+  isVisualFractionInline,
   isWidgetRef,
   parse,
   parseFractionKey,
@@ -14245,6 +15280,7 @@ export {
   validateExpression,
   validateInputFormats,
   validateSimple,
+  validateVisualFractionCapacity,
   validateWidgetJSON,
   validateWidgetJSONSafe
 };