@mathscan/math-exercise-engine 1.1.8 → 1.1.10

package/dist/index.mjs

@@ -56,10 +56,14 @@ const AST_TYPES = {
   NUMBER_LINE_BLOCK: "NumberLineBlock",
   /** A position marker on the number line */
   NUMBER_LINE_POSITION: "NumberLinePosition",
+  /** A draggable cursor on the number line */
+  NUMBER_LINE_CURSOR: "NumberLineCursor",
   /** A dynamic subdivision counter embedded in a number line */
   NUMBER_LINE_COUNTER: "NumberLineCounter",
   /** A highlighted range on the number line axis */
   NUMBER_LINE_HIGHLIGHT: "NumberLineHighlight",
+  /** An arrow annotation spanning a number line interval */
+  NUMBER_LINE_ARROW: "NumberLineArrow",
   /** Matcher layout block */
   MATCHER_BLOCK: "MatcherBlock",
   /** Row within a matcher */
@@ -152,6 +156,10 @@ const JSON_TYPES = {
   NUMBER_LINE_COUNTER: "number-line-counter",
   /** Highlighted range within a number line */
   NUMBER_LINE_HIGHLIGHT: "number-line-highlight",
+  /** Draggable cursor within a number line */
+  NUMBER_LINE_CURSOR: "number-line-cursor",
+  /** Arrow annotation within a number line */
+  NUMBER_LINE_ARROW: "number-line-arrow",
   /** Matcher layout block */
   MATCHER: "matcher",
   /** Row within a matcher */
@@ -318,6 +326,14 @@ const POSITION = createToken({
   name: "POSITION",
   pattern: /POSITION/
 });
+const CURSOR = createToken({
+  name: "CURSOR",
+  pattern: /CURSOR/
+});
+const ARROW = createToken({
+  name: "ARROW",
+  pattern: /ARROW/
+});
 const TABLE = createToken({
   name: "TABLE",
   pattern: /TABLE/
@@ -515,6 +531,8 @@ const allTokens = [
   NUMERIC_INPUT,
   NUMBER_LINE,
   POSITION,
+  CURSOR,
+  ARROW,
   TABLE,
   ROW,
   TOP_ROW,
@@ -789,7 +807,9 @@ class MathExerciseParser extends CstParser {
         this.OR6([
           { ALT: () => this.SUBRULE(this.position) },
           { ALT: () => this.SUBRULE(this.counter) },
-          { ALT: () => this.SUBRULE(this.highlight) }
+          { ALT: () => this.SUBRULE(this.highlight) },
+          { ALT: () => this.SUBRULE(this.cursor) },
+          { ALT: () => this.SUBRULE(this.arrow) }
         ]);
       });
       this.CONSUME(RBrace);
@@ -838,6 +858,38 @@ class MathExerciseParser extends CstParser {
         this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
       });
     });
+    this.cursor = this.RULE("cursor", () => {
+      this.CONSUME(CURSOR);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+      this.MANY2(() => {
+        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
+      });
+    });
+    this.arrow = this.RULE("arrow", () => {
+      this.CONSUME(ARROW);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+      this.MANY2(() => {
+        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
+      });
+      this.CONSUME(LBrace);
+      this.MANY3(() => {
+        this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
+      });
+      this.MANY4(() => {
+        this.OR4([
+          { ALT: () => this.SUBRULE(this.inlineElement) },
+          { ALT: () => this.CONSUME4(Newline) }
+        ]);
+      });
+      this.CONSUME(RBrace);
+      this.MANY5(() => {
+        this.OR5([{ ALT: () => this.CONSUME5(Space) }, { ALT: () => this.CONSUME5(Newline) }]);
+      });
+    });
     this.matcher = this.RULE("matcher", () => {
       this.MANY(() => {
         this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
@@ -1865,6 +1917,44 @@ function createNumberLineHighlight(from, to, color, label) {
     ...label !== void 0 && { label }
   });
 }
+const NumberLineCursorSchema = z.object({
+  type: z.literal(AST_TYPES.NUMBER_LINE_CURSOR),
+  value: z.number().finite({ message: "CURSOR: value must be a finite number" }).default(0),
+  answer: z.number({ required_error: "CURSOR: answer is required" }).finite({ message: "CURSOR: answer must be a finite number" }),
+  color: z.string().regex(/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/, {
+    message: 'CURSOR: color must be a hex value (e.g. "#3B82F6" or "#F00")'
+  }).optional(),
+  fillRange: z.boolean().default(false),
+  label: z.string().optional()
+});
+function createNumberLineCursor(answer, value, color, fillRange, label) {
+  return NumberLineCursorSchema.parse({
+    type: AST_TYPES.NUMBER_LINE_CURSOR,
+    answer,
+    ...value !== void 0 && { value },
+    ...color !== void 0 && { color },
+    ...fillRange !== void 0 && { fillRange },
+    ...label !== void 0 && { label }
+  });
+}
+const NumberLineArrowSchema = z.object({
+  type: z.literal(AST_TYPES.NUMBER_LINE_ARROW),
+  from: z.number().finite({ message: "ARROW: from must be a finite number" }),
+  to: z.number().finite({ message: "ARROW: to must be a finite number" }),
+  color: z.string().optional(),
+  inlines: z.array(InlineNodeSchema)
+}).refine((d) => d.from < d.to, {
+  message: "ARROW: from must be less than to"
+});
+function createNumberLineArrow(from, to, inlines, color) {
+  return NumberLineArrowSchema.parse({
+    type: AST_TYPES.NUMBER_LINE_ARROW,
+    from,
+    to,
+    ...color !== void 0 && { color },
+    inlines
+  });
+}
 const NumberLineBlockSchema = z.object({
   type: z.literal(AST_TYPES.NUMBER_LINE_BLOCK),
   min: z.number().finite({ message: "NUMBER_LINE: min must be a finite number" }),
@@ -1883,6 +1973,8 @@ const NumberLineBlockSchema = z.object({
   }).optional(),
   counter: NumberLineCounterSchema.optional(),
   highlights: z.array(NumberLineHighlightSchema).optional(),
+  cursors: z.array(NumberLineCursorSchema).optional(),
+  arrows: z.array(NumberLineArrowSchema).optional(),
   dragMode: z.enum(NUMBER_LINE_DRAG_MODES, {
     errorMap: () => ({
       message: `NUMBER_LINE: dragMode must be one of ${NUMBER_LINE_DRAG_MODES.join(", ")}`
@@ -1916,6 +2008,14 @@ const NumberLineBlockSchema = z.object({
       });
     }
   }
+  for (const arrow of data.arrows ?? []) {
+    if (arrow.from < data.min || arrow.to > data.max) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `NUMBER_LINE: ARROW range [${arrow.from}, ${arrow.to}] must be within [${data.min}, ${data.max}]`
+      });
+    }
+  }
   if (data.counter?.default !== void 0) {
     if (data.counter.default < data.counter.min || data.counter.default > data.counter.max) {
       ctx.addIssue({
@@ -1924,8 +2024,22 @@ const NumberLineBlockSchema = z.object({
       });
     }
   }
+  for (const c of data.cursors ?? []) {
+    if (c.value < data.min || c.value > data.max) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `NUMBER_LINE: CURSOR value (${c.value}) must be within [${data.min}, ${data.max}]`
+      });
+    }
+    if (c.answer < data.min || c.answer > data.max) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `NUMBER_LINE: CURSOR answer (${c.answer}) must be within [${data.min}, ${data.max}]`
+      });
+    }
+  }
 });
-function createNumberLineBlock(min, max, positions, step, minorTicks, style, labelVisibility, counter, highlights, dragMode) {
+function createNumberLineBlock(min, max, positions, step, minorTicks, style, labelVisibility, counter, highlights, cursors, arrows, dragMode) {
   return NumberLineBlockSchema.parse({
     type: AST_TYPES.NUMBER_LINE_BLOCK,
     min,
@@ -1936,6 +2050,8 @@ function createNumberLineBlock(min, max, positions, step, minorTicks, style, lab
     labelVisibility,
     counter,
     highlights,
+    cursors,
+    arrows,
     dragMode,
     positions
   });
@@ -2589,7 +2705,9 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     }
     const counter = rawCounters ? this.visit(rawCounters) : void 0;
     const highlights = ctx.highlight ? ctx.highlight.map((h) => this.visit(h)) : [];
-    return createNumberLineBlock(min, max, positions, step, minorTicks, style, labelVisibility, counter, highlights, dragMode);
+    const cursors = ctx.cursor ? ctx.cursor.map((c) => this.visit(c)) : [];
+    const arrows = ctx.arrow ? ctx.arrow.map((a) => this.visit(a)) : [];
+    return createNumberLineBlock(min, max, positions, step, minorTicks, style, labelVisibility, counter, highlights, cursors.length > 0 ? cursors : void 0, arrows.length > 0 ? arrows : void 0, dragMode);
   }
   position(ctx) {
     const params = this.visit(ctx.parameterList);
@@ -2623,6 +2741,29 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     const label = params.label;
     return createNumberLineHighlight(from, to, color, label);
   }
+  cursor(ctx) {
+    const params = this.visit(ctx.parameterList);
+    if (params.answer === void 0) {
+      throw new Error("CURSOR requires parameter: answer");
+    }
+    const answer = Number(params.answer);
+    const value = params.value !== void 0 ? Number(params.value) : void 0;
+    const color = params.color;
+    const fillRange = params.fillRange !== void 0 ? params.fillRange === true || params.fillRange === "true" : void 0;
+    const label = params.label;
+    return createNumberLineCursor(answer, value, color, fillRange, label);
+  }
+  arrow(ctx) {
+    const params = this.visit(ctx.parameterList);
+    if (params.from === void 0 || params.to === void 0) {
+      throw new Error("ARROW requires parameters: from and to");
+    }
+    const from = Number(params.from);
+    const to = Number(params.to);
+    const color = params.color;
+    const inlines = ctx.inlineElement ? ctx.inlineElement.map((elem) => this.visit(elem)) : [];
+    return createNumberLineArrow(from, to, inlines, color);
+  }
   // ═══════════════════════════════════════════════════════════════════════════
   // Matcher Block
   // ═══════════════════════════════════════════════════════════════════════════
@@ -3277,6 +3418,23 @@ const NumberLineHighlightItemSchema = z.object({
   color: z.enum(NUMBER_LINE_HIGHLIGHT_COLORS).optional(),
   label: z.string().optional()
 });
+const NumberLineCursorItemSchema = z.object({
+  id: z.string(),
+  type: z.literal(JSON_TYPES.NUMBER_LINE_CURSOR),
+  value: z.number().finite(),
+  answer: z.number().finite(),
+  color: z.string().regex(/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/).optional(),
+  fillRange: z.boolean(),
+  label: z.string().optional()
+});
+const NumberLineArrowItemSchema = z.object({
+  id: z.string(),
+  type: z.literal(JSON_TYPES.NUMBER_LINE_ARROW),
+  from: z.number().finite(),
+  to: z.number().finite(),
+  color: z.string().optional(),
+  content: z.array(LayoutItemSchema)
+});
 const NumberLineItemSchema = z.object({
   id: z.string(),
   type: z.literal(JSON_TYPES.NUMBER_LINE),
@@ -3288,6 +3446,8 @@ const NumberLineItemSchema = z.object({
   labelVisibility: z.enum(NUMBER_LINE_LABELS).optional(),
   counter: NumberLineCounterItemSchema.optional(),
   highlights: z.array(NumberLineHighlightItemSchema).optional(),
+  cursors: z.array(NumberLineCursorItemSchema).optional(),
+  arrows: z.array(NumberLineArrowItemSchema).optional(),
   dragMode: z.enum(NUMBER_LINE_DRAG_MODES).optional(),
   positions: z.array(NumberLinePositionItemSchema)
 });
@@ -3635,6 +3795,9 @@ function toJSON(ast) {
       if (nlItem.counter?.answer !== void 0) {
         answers[nlItem.counter.id] = nlItem.counter.answer;
       }
+      for (const cursor of nlItem.cursors ?? []) {
+        answers[cursor.id] = cursor.answer;
+      }
     } else if (block.type === AST_TYPES.MATCHER_BLOCK) {
       const matcherBlock = block;
       layout.push({
@@ -3825,9 +3988,13 @@ function collectAllInlines(blocks) {
         }
       }
     } else if (block.type === AST_TYPES.NUMBER_LINE_BLOCK) {
-      for (const position of block.positions) {
+      const numberLine = block;
+      for (const position of numberLine.positions) {
         result.push(...position.inlines);
       }
+      for (const arrow of numberLine.arrows ?? []) {
+        result.push(...arrow.inlines);
+      }
     } else if (block.type === AST_TYPES.MATCHER_BLOCK) {
       for (const row of block.rows) {
         for (const item of row.items) {
@@ -3877,6 +4044,29 @@ function transformNumberLine(numberLine, idGenerator, inlineDragIds) {
       ...h.label !== void 0 && { label: h.label }
     }));
   }
+  let cursors;
+  if (numberLine.cursors !== void 0 && numberLine.cursors.length > 0) {
+    cursors = numberLine.cursors.map((c) => ({
+      id: idGenerator.generate(JSON_TYPES.NUMBER_LINE_CURSOR),
+      type: JSON_TYPES.NUMBER_LINE_CURSOR,
+      value: c.value,
+      answer: c.answer,
+      fillRange: c.fillRange,
+      ...c.color !== void 0 && { color: c.color },
+      ...c.label !== void 0 && { label: c.label }
+    }));
+  }
+  let arrows;
+  if (numberLine.arrows !== void 0 && numberLine.arrows.length > 0) {
+    arrows = numberLine.arrows.map((a) => ({
+      id: idGenerator.generate(JSON_TYPES.NUMBER_LINE_ARROW),
+      type: JSON_TYPES.NUMBER_LINE_ARROW,
+      from: a.from,
+      to: a.to,
+      ...a.color !== void 0 && { color: a.color },
+      content: a.inlines.map((inline) => transformInline(inline, idGenerator, inlineDragIds))
+    }));
+  }
   const item = {
     id: idGenerator.generate(JSON_TYPES.NUMBER_LINE),
     type: JSON_TYPES.NUMBER_LINE,
@@ -3888,6 +4078,8 @@ function transformNumberLine(numberLine, idGenerator, inlineDragIds) {
     ...numberLine.labelVisibility !== void 0 && { labelVisibility: numberLine.labelVisibility },
     ...counterItem !== void 0 && { counter: counterItem },
     ...highlights !== void 0 && { highlights },
+    ...cursors !== void 0 && { cursors },
+    ...arrows !== void 0 && { arrows },
     ...numberLine.dragMode !== void 0 && { dragMode: numberLine.dragMode },
     positions
   };
@@ -4019,7 +4211,7 @@ function transformLine(line, idGenerator, inlineDragIds) {
 }
 function transformInline(inline, idGenerator, inlineDragIds) {
   switch (inline.type) {
-    case AST_TYPES.FREE_TEXT:
+    case AST_TYPES.FREE_TEXT: {
       const trimmed = inline.value.trim();
       const operators = ["+", "-", "×", "÷", "=", "<", ">", "?"];
       if (operators.includes(trimmed) && inline.value.trim() === inline.value) {
@@ -4034,6 +4226,7 @@ function transformInline(inline, idGenerator, inlineDragIds) {
         type: JSON_TYPES.TEXT,
         value: inline.value
       };
+    }
     case AST_TYPES.SPACE:
       return {
         id: idGenerator.generate(JSON_TYPES.SPACE),
@@ -8296,7 +8489,7 @@ lodash.exports;
         var tag = baseGetTag(value);
         return tag == errorTag || tag == domExcTag || typeof value.message == "string" && typeof value.name == "string" && !isPlainObject(value);
       }
-      function isFinite(value) {
+      function isFinite2(value) {
         return typeof value == "number" && nativeIsFinite(value);
       }
       function isFunction(value) {
@@ -9397,7 +9590,7 @@ lodash.exports;
       lodash2.isEqual = isEqual;
       lodash2.isEqualWith = isEqualWith;
       lodash2.isError = isError;
-      lodash2.isFinite = isFinite;
+      lodash2.isFinite = isFinite2;
       lodash2.isFunction = isFunction;
       lodash2.isInteger = isInteger;
       lodash2.isLength = isLength;
@@ -13951,6 +14144,8 @@ const DEFAULT_SOUNDS = {
   "clock-hour-tick": buttonClick,
   "clock-minute-tick": buttonClick,
   "counter-step": buttonClick,
+  "cursor-step": buttonClick,
+  "cursor-release": dragDrop,
   "input-select": inputSelect,
   "answer-correct": answerCorrect,
   "answer-wrong": answerWrong
@@ -15048,19 +15243,21 @@ const DragOptions = ({
   options,
   onOptionClick
 }) => {
-  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);
-    return /* @__PURE__ */ jsx(
-      SingleDragOption,
-      {
-        optionId,
-        value: optionValue,
-        onOptionClick
-      },
-      optionId
-    );
-  }) }) });
+  const [shuffledOptions] = useState(
+    () => lodashExports.shuffle(options.map((option, idx) => ({
+      optionId: `drag-option-${idx}`,
+      value: String(option)
+    })))
+  );
+  return /* @__PURE__ */ jsx(PillBackground, { children: /* @__PURE__ */ jsx("div", { className: "drag-options", children: shuffledOptions.map(({ optionId, value }) => /* @__PURE__ */ jsx(
+    SingleDragOption,
+    {
+      optionId,
+      value,
+      onOptionClick
+    },
+    optionId
+  )) }) });
 };
 const InlineDragOption = ({
   widgetId,
@@ -15644,7 +15841,8 @@ const RadioOptions = ({
   onChange
 }) => {
   const playSound = useSound();
-  return /* @__PURE__ */ jsx("div", { className: "radio-options", children: options.map((option, idx) => {
+  const [shuffledOptions] = useState(() => lodashExports.shuffle(options));
+  return /* @__PURE__ */ jsx("div", { className: "radio-options", children: shuffledOptions.map((option, idx) => {
     const isSelected = value === option;
     const statusClass = isSelected && validationStatus ? ` widget--${validationStatus}` : "";
     return /* @__PURE__ */ jsx(
@@ -16509,6 +16707,182 @@ const HighlightBands = ({ highlights, min, max }) => {
     );
   }) });
 };
+const DraggableCursor = ({
+  cursor,
+  min,
+  max,
+  snapTicks,
+  audibleTicks,
+  axisRowRef,
+  onChange,
+  currentValue,
+  validationStatus
+}) => {
+  const [isDragging, setIsDragging] = useState(false);
+  const isDraggingRef = useRef(false);
+  const currentValueRef = useRef(currentValue);
+  currentValueRef.current = currentValue;
+  const dragStartValueRef = useRef(currentValue);
+  const lastSoundValueRef = useRef(currentValue);
+  const { jiggling, onAnimationEnd } = useJiggle(isDragging);
+  const playSound = useSound();
+  const colorVar = !validationStatus && cursor.color ? { "--nl-cursor-color": cursor.color } : void 0;
+  const initialPct = toPercent(cursor.value, min, max);
+  const ballPct = toPercent(currentValue, min, max);
+  const fillLeft = Math.min(initialPct, ballPct);
+  const fillWidth = Math.abs(ballPct - initialPct);
+  const snap = useCallback((clientX) => {
+    const el = axisRowRef.current;
+    if (!el) return currentValueRef.current;
+    const rect = el.getBoundingClientRect();
+    const raw = pixelToValue(clientX, rect.left, rect.width, min, max);
+    return snapTicks.length > 0 ? snapToNearest(raw, snapTicks) : cleanFloat(raw);
+  }, [axisRowRef, min, max, snapTicks]);
+  const handlePointerDown = useCallback((e) => {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    e.stopPropagation();
+    isDraggingRef.current = true;
+    dragStartValueRef.current = currentValue;
+    lastSoundValueRef.current = currentValue;
+    setIsDragging(true);
+  }, [currentValue]);
+  const updateCursorValue = useCallback((clientX) => {
+    const next = snap(clientX);
+    if (!almostEqual(next, lastSoundValueRef.current)) {
+      const soundTicks = audibleTicks ?? snapTicks;
+      if (soundTicks.some((tick) => almostEqual(tick, next))) playSound("cursor-step");
+      lastSoundValueRef.current = next;
+    }
+    onChange(cursor.id, String(next));
+    return next;
+  }, [snap, audibleTicks, snapTicks, playSound, onChange, cursor.id]);
+  const handlePointerMove = useCallback((e) => {
+    if (!isDraggingRef.current) return;
+    e.stopPropagation();
+    updateCursorValue(e.clientX);
+  }, [updateCursorValue]);
+  const handlePointerUp = useCallback((e) => {
+    if (!isDraggingRef.current) return;
+    isDraggingRef.current = false;
+    setIsDragging(false);
+    e.currentTarget.releasePointerCapture(e.pointerId);
+    e.stopPropagation();
+    const next = updateCursorValue(e.clientX);
+    if (!almostEqual(next, dragStartValueRef.current)) {
+      playSound("cursor-release");
+    }
+  }, [updateCursorValue, playSound]);
+  const handleKeyDown = useCallback((e) => {
+    if (!snapTicks.length) return;
+    const sorted = [...snapTicks].sort((a, b) => a - b);
+    const idx = sorted.findIndex((t) => t >= currentValue - 1e-9);
+    const first = sorted[0] ?? currentValue;
+    const last = sorted[sorted.length - 1] ?? currentValue;
+    if (e.key === "ArrowRight" || e.key === "ArrowUp") {
+      e.preventDefault();
+      const next = sorted[idx + 1] ?? last;
+      const soundTicks = audibleTicks ?? snapTicks;
+      if (!almostEqual(next, currentValue) && soundTicks.some((tick) => almostEqual(tick, next))) {
+        playSound("cursor-step");
+      }
+      onChange(cursor.id, String(next));
+    } else if (e.key === "ArrowLeft" || e.key === "ArrowDown") {
+      e.preventDefault();
+      const next = sorted[idx - 1] ?? first;
+      const soundTicks = audibleTicks ?? snapTicks;
+      if (!almostEqual(next, currentValue) && soundTicks.some((tick) => almostEqual(tick, next))) {
+        playSound("cursor-step");
+      }
+      onChange(cursor.id, String(next));
+    }
+  }, [snapTicks, audibleTicks, currentValue, playSound, onChange, cursor.id]);
+  const ballClass = [
+    "number-line-cursor-ball",
+    isDragging ? "number-line-cursor-ball--dragging" : "",
+    jiggling && !isDragging ? "number-line-cursor-ball--jiggle" : "",
+    validationStatus ? `number-line-cursor-ball--${validationStatus}` : ""
+  ].filter(Boolean).join(" ");
+  const fillClass = [
+    "number-line-cursor-fill",
+    validationStatus ? `number-line-cursor-fill--${validationStatus}` : ""
+  ].filter(Boolean).join(" ");
+  const labelClass = [
+    "number-line-cursor-label",
+    validationStatus ? `number-line-cursor-label--${validationStatus}` : ""
+  ].filter(Boolean).join(" ");
+  const sliderAriaLabel = cursor.label ? `${cursor.label}: cursor position ${currentValue}` : `cursor position ${currentValue}`;
+  return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+    cursor.fillRange && fillWidth > 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: fillClass,
+        "aria-hidden": "true",
+        style: { left: `${fillLeft}%`, width: `${fillWidth}%`, ...colorVar }
+      }
+    ),
+    cursor.label && /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: labelClass,
+        "aria-hidden": "true",
+        style: { left: `${ballPct}%`, ...colorVar },
+        children: cursor.label
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: ballClass,
+        style: { left: `${ballPct}%`, ...colorVar },
+        onPointerDown: handlePointerDown,
+        onPointerMove: handlePointerMove,
+        onPointerUp: handlePointerUp,
+        onKeyDown: handleKeyDown,
+        onAnimationEnd,
+        role: "slider",
+        "aria-valuemin": min,
+        "aria-valuemax": max,
+        "aria-valuenow": currentValue,
+        "aria-label": sliderAriaLabel,
+        tabIndex: 0
+      }
+    )
+  ] });
+};
+const CursorBalls = ({
+  cursors,
+  min,
+  max,
+  snapTicks,
+  audibleTicks,
+  axisRowRef,
+  onChange,
+  values,
+  cursorValidationStatuses
+}) => {
+  if (!cursors?.length) return null;
+  return /* @__PURE__ */ jsx(Fragment, { children: cursors.map((cursor) => {
+    const raw = values[cursor.id];
+    const parsed = Number(raw);
+    const currentValue = raw !== void 0 && raw !== "" && isFinite(parsed) ? parsed : cursor.value;
+    const validationStatus = cursorValidationStatuses?.[cursor.id] ?? null;
+    return /* @__PURE__ */ jsx(
+      DraggableCursor,
+      {
+        cursor,
+        min,
+        max,
+        snapTicks,
+        audibleTicks,
+        axisRowRef,
+        onChange,
+        currentValue,
+        validationStatus
+      },
+      cursor.id
+    );
+  }) });
+};
 const PlacedChip = ({ widgetId, label, leftPercent, isLanding, onRemove }) => {
   const { attributes, listeners, setNodeRef, isDragging } = useDraggable({
     id: widgetId,
@@ -16572,6 +16946,8 @@ const FreeDragAxis = ({
   values,
   onChange,
   highlights,
+  cursors,
+  cursorValidationStatuses,
   snapKey
 }) => {
   const axisRef = useRef(null);
@@ -16744,6 +17120,20 @@ const FreeDragAxis = ({
         showArrowLeft && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-left", "aria-hidden": "true" }),
         showArrowRight && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-right", "aria-hidden": "true" }),
         /* @__PURE__ */ jsx(HighlightBands, { highlights, min, max }),
+        /* @__PURE__ */ jsx(
+          CursorBalls,
+          {
+            cursors,
+            min,
+            max,
+            snapTicks,
+            audibleTicks: majorTicks,
+            axisRowRef: axisRef,
+            onChange,
+            values,
+            cursorValidationStatuses
+          }
+        ),
         minorValues.map((v) => /* @__PURE__ */ jsx(
           "div",
           {
@@ -16812,40 +17202,65 @@ const AxisTicks = ({
   showArrowLeft,
   showArrowRight,
   highlights,
-  positions
-}) => /* @__PURE__ */ jsxs("div", { className: "number-line-axis-row", role: "presentation", children: [
-  /* @__PURE__ */ jsx("div", { className: "number-line-track", "aria-hidden": "true" }),
-  showArrowLeft && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-left", "aria-hidden": "true" }),
-  showArrowRight && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-right", "aria-hidden": "true" }),
-  /* @__PURE__ */ jsx(HighlightBands, { highlights, min, max }),
-  minorValues.map((v) => /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: "number-line-minor-tick",
-      "aria-hidden": "true",
-      style: { left: `${toPercent(v, min, max)}%` }
-    },
-    `minor-${v}`
-  )),
-  majorTicks.map((tick) => /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: "number-line-major-tick",
-      "aria-hidden": "true",
-      style: { left: `${toPercent(tick, min, max)}%` }
-    },
-    `major-${tick}`
-  )),
-  positions.map((pos) => /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: "number-line-position-dot",
-      "aria-hidden": "true",
-      style: { left: `${toPercent(pos.value, min, max)}%` }
-    },
-    `dot-${pos.id}`
-  ))
-] });
+  positions,
+  cursors,
+  onChange,
+  values,
+  cursorValidationStatuses
+}) => {
+  const axisRowRef = useRef(null);
+  const snapTicks = useMemo(
+    () => [...majorTicks, ...minorValues],
+    [majorTicks, minorValues]
+  );
+  return /* @__PURE__ */ jsxs("div", { ref: axisRowRef, className: "number-line-axis-row", role: "presentation", children: [
+    /* @__PURE__ */ jsx("div", { className: "number-line-track", "aria-hidden": "true" }),
+    showArrowLeft && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-left", "aria-hidden": "true" }),
+    showArrowRight && /* @__PURE__ */ jsx("div", { className: "number-line-arrow number-line-arrow-right", "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx(HighlightBands, { highlights, min, max }),
+    /* @__PURE__ */ jsx(
+      CursorBalls,
+      {
+        cursors,
+        min,
+        max,
+        snapTicks,
+        audibleTicks: majorTicks,
+        axisRowRef,
+        onChange,
+        values,
+        cursorValidationStatuses
+      }
+    ),
+    minorValues.map((v) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "number-line-minor-tick",
+        "aria-hidden": "true",
+        style: { left: `${toPercent(v, min, max)}%` }
+      },
+      `minor-${v}`
+    )),
+    majorTicks.map((tick) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "number-line-major-tick",
+        "aria-hidden": "true",
+        style: { left: `${toPercent(tick, min, max)}%` }
+      },
+      `major-${tick}`
+    )),
+    positions.map((pos) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "number-line-position-dot",
+        "aria-hidden": "true",
+        style: { left: `${toPercent(pos.value, min, max)}%` }
+      },
+      `dot-${pos.id}`
+    ))
+  ] });
+};
 const isLabelVisible = (tick, min, max, labelVisibility) => {
   switch (labelVisibility) {
     case "none":
@@ -16939,6 +17354,209 @@ const CounterControls = ({
     counter.name && /* @__PURE__ */ jsx("span", { className: "number-line-counter-label", children: counter.name })
   ] });
 };
+const ARROW_ARC_LEVEL_HEIGHT = 80;
+const ARROW_ARC_VIEWBOX_HEIGHT = 64;
+const ARROW_ARC_VIEWBOX_WIDTH = 100;
+const ARROW_ARC_BASE_Y = 56;
+const ARROW_ARC_MIN_LIFT = 28;
+const ARROW_ARC_MAX_LIFT = 58;
+const ARROW_ARC_LIFT_RATIO = 1.15;
+const ARROW_ARC_LABEL_OFFSET = 24;
+const ARROW_ARC_HEAD_LENGTH = 8;
+const ARROW_ARC_HEAD_HALF_WIDTH = 3.2;
+function getArrowArcLift(widthPct) {
+  return Math.min(ARROW_ARC_MAX_LIFT, Math.max(ARROW_ARC_MIN_LIFT, widthPct * ARROW_ARC_LIFT_RATIO));
+}
+function fmt(n) {
+  return Number(n.toFixed(2));
+}
+function getArrowArcSvgWidth(renderedWidthPx) {
+  return renderedWidthPx > 0 ? renderedWidthPx : ARROW_ARC_VIEWBOX_WIDTH;
+}
+function getArrowArcLabelTop(widthPct) {
+  const svgTop = ARROW_ARC_LEVEL_HEIGHT - ARROW_ARC_VIEWBOX_HEIGHT;
+  const arcTop = svgTop + ARROW_ARC_BASE_Y - getArrowArcLift(widthPct);
+  return Math.max(0, arcTop - ARROW_ARC_LABEL_OFFSET);
+}
+function getArrowArcPaths(widthPct, svgWidthPx = ARROW_ARC_VIEWBOX_WIDTH) {
+  const endX = getArrowArcSvgWidth(svgWidthPx);
+  const controlInset = Math.min(svgWidthPx * 0.18, 48);
+  const lift = getArrowArcLift(widthPct);
+  const controlY = fmt(ARROW_ARC_BASE_Y - lift);
+  const tangentAngle = Math.atan2(ARROW_ARC_BASE_Y - controlY, endX - (endX - controlInset));
+  const tx = Math.cos(tangentAngle);
+  const ty = Math.sin(tangentAngle);
+  const shaftEndX = fmt(endX - tx * ARROW_ARC_HEAD_LENGTH);
+  const shaftEndY = fmt(ARROW_ARC_BASE_Y - ty * ARROW_ARC_HEAD_LENGTH);
+  const endControlX = fmt(shaftEndX - tx * controlInset);
+  const endControlY = fmt(shaftEndY - ty * controlInset);
+  const arcPath = `M 0 ${ARROW_ARC_BASE_Y} C ${fmt(controlInset)} ${controlY} ${endControlX} ${endControlY} ${shaftEndX} ${shaftEndY}`;
+  const nx = -ty;
+  const ny = tx;
+  const baseX = endX - tx * ARROW_ARC_HEAD_LENGTH;
+  const baseY = ARROW_ARC_BASE_Y - ty * ARROW_ARC_HEAD_LENGTH;
+  const headPath = `M ${fmt(endX)} ${ARROW_ARC_BASE_Y} L ${fmt(baseX + nx * ARROW_ARC_HEAD_HALF_WIDTH)} ${fmt(baseY + ny * ARROW_ARC_HEAD_HALF_WIDTH)} L ${fmt(baseX - nx * ARROW_ARC_HEAD_HALF_WIDTH)} ${fmt(baseY - ny * ARROW_ARC_HEAD_HALF_WIDTH)} Z`;
+  return { arcPath, headPath };
+}
+function getArrowArcLayouts(arrows, min, max) {
+  if (!arrows?.length) return [];
+  const sorted = arrows.map((arrow, index) => {
+    const fromPct = toPercent(arrow.from, min, max);
+    const toPct = toPercent(arrow.to, min, max);
+    return {
+      arrow,
+      index,
+      leftPct: fromPct,
+      rightPct: toPct,
+      widthPct: toPct - fromPct,
+      level: 0
+    };
+  }).filter((layout) => layout.widthPct > 0).sort((a, b) => a.leftPct - b.leftPct || a.rightPct - b.rightPct || a.index - b.index);
+  const levelRightEdges = [];
+  for (const layout of sorted) {
+    const reusableLevel = levelRightEdges.findIndex((rightPct) => layout.leftPct >= rightPct);
+    const level = reusableLevel === -1 ? levelRightEdges.length : reusableLevel;
+    layout.level = level;
+    levelRightEdges[level] = layout.rightPct;
+  }
+  return sorted.sort((a, b) => a.index - b.index);
+}
+function getArrowArcsRowHeight(layouts) {
+  if (layouts.length === 0) return 0;
+  const levelCount = Math.max(...layouts.map((layout) => layout.level)) + 1;
+  return levelCount * ARROW_ARC_LEVEL_HEIGHT;
+}
+function useElementWidth() {
+  const ref = useRef(null);
+  const [width, setWidth] = useState(0);
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    const updateWidth = () => {
+      const nextWidth = element.getBoundingClientRect().width;
+      setWidth((previousWidth) => previousWidth === nextWidth ? previousWidth : nextWidth);
+    };
+    updateWidth();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(updateWidth);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  return [ref, width];
+}
+const ArrowArc = ({
+  layout: { arrow, leftPct, widthPct, level },
+  widgets,
+  values,
+  droppedInputs,
+  validationDetails,
+  onChange,
+  onInputFocus
+}) => {
+  const [arcRef, renderedWidthPx] = useElementWidth();
+  const hasLabel = arrow.content.length > 0;
+  const svgWidthPx = getArrowArcSvgWidth(renderedWidthPx);
+  const { arcPath, headPath } = useMemo(
+    () => getArrowArcPaths(widthPct, svgWidthPx),
+    [widthPct, svgWidthPx]
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: arcRef,
+      className: "number-line-arrow-arc",
+      "data-level": level,
+      style: {
+        left: `${leftPct}%`,
+        width: `${widthPct}%`,
+        bottom: `${level * ARROW_ARC_LEVEL_HEIGHT}px`,
+        // DSL color overrides the CSS default — only set when the author
+        // explicitly wrote e.g. ARROW[from=0,to=5,color="#2B6DEA"]
+        ...arrow.color !== void 0 && { "--nl-arrow-arc-color": arrow.color }
+      },
+      children: [
+        /* @__PURE__ */ jsxs(
+          "svg",
+          {
+            className: "number-line-arrow-arc-svg",
+            viewBox: `0 0 ${svgWidthPx} ${ARROW_ARC_VIEWBOX_HEIGHT}`,
+            preserveAspectRatio: "none",
+            "aria-hidden": "true",
+            focusable: "false",
+            children: [
+              /* @__PURE__ */ jsx(
+                "path",
+                {
+                  className: "number-line-arrow-arc-path",
+                  d: arcPath
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                "path",
+                {
+                  className: "number-line-arrow-arc-head",
+                  d: headPath
+                }
+              )
+            ]
+          }
+        ),
+        hasLabel && /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "number-line-arrow-arc-label",
+            style: { top: `${getArrowArcLabelTop(widthPct)}px` },
+            children: arrow.content.map((subItem) => /* @__PURE__ */ jsx(
+              LayoutRenderer,
+              {
+                item: subItem,
+                widgets,
+                values,
+                droppedInputs,
+                validationDetails,
+                onChange,
+                onInputFocus
+              },
+              subItem.id
+            ))
+          }
+        )
+      ]
+    }
+  );
+};
+const ArrowArcsRow = ({
+  layouts,
+  rowHeight,
+  widgets,
+  values,
+  droppedInputs,
+  validationDetails,
+  onChange,
+  onInputFocus
+}) => {
+  if (layouts.length === 0) return null;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "number-line-arrow-arcs-row",
+      style: { height: `${rowHeight}px` },
+      children: layouts.map((layout) => /* @__PURE__ */ jsx(
+        ArrowArc,
+        {
+          layout,
+          widgets,
+          values,
+          droppedInputs,
+          validationDetails,
+          onChange,
+          onInputFocus
+        },
+        layout.arrow.id
+      ))
+    }
+  );
+};
 const CONTENT_ROW_EXTRA_SPACE = 8;
 const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 function useMeasuredPositionContentHeight(positionIds) {
@@ -17052,8 +17670,10 @@ const NumberLineRenderer = ({
     style: lineStyle = "arrow-right",
     labelVisibility,
     highlights,
+    arrows,
     counter,
-    positions
+    positions,
+    cursors
   } = item;
   const [counterCount, setCounterCount] = useState(
     counter !== void 0 ? counter.default ?? counter.min : 0
@@ -17069,6 +17689,15 @@ const NumberLineRenderer = ({
       onChangeRef.current(counter.id, String(counterCount));
     }
   }, [counterCount, counter?.id]);
+  const cursorKeys = useMemo(
+    () => (cursors ?? []).map((c) => `${c.id}:${c.value}`).join(","),
+    [cursors]
+  );
+  useEffect(() => {
+    for (const cursor of cursors ?? []) {
+      onChangeRef.current(cursor.id, String(cursor.value));
+    }
+  }, [cursorKeys]);
   const effectiveStep = useMemo(() => {
     if (counter !== void 0 && counterCount > 0) {
       return cleanFloat((max - min) / counterCount);
@@ -17102,6 +17731,15 @@ const NumberLineRenderer = ({
     [visiblePositions]
   );
   const { positionContentHeight, getPositionContentRef } = useMeasuredPositionContentHeight(visiblePositionIds);
+  const arrowArcLayouts = useMemo(
+    () => getArrowArcLayouts(arrows, min, max),
+    [arrows, min, max]
+  );
+  const arrowArcsRowHeight = useMemo(
+    () => getArrowArcsRowHeight(arrowArcLayouts),
+    [arrowArcLayouts]
+  );
+  const hasOverlayRow = arrowArcsRowHeight > 0 || visiblePositions.length > 0;
   const nlValidationStatus = useMemo(() => {
     if (!validationDetails || counter === void 0) return null;
     if (counter.answer === void 0) return null;
@@ -17109,6 +17747,17 @@ const NumberLineRenderer = ({
     if (counterValidation === void 0) return null;
     return counterValidation.isCorrect ? "correct" : "incorrect";
   }, [validationDetails, counter]);
+  const cursorValidationStatuses = useMemo(() => {
+    if (!validationDetails || !cursors?.length) return void 0;
+    const statuses = {};
+    for (const cursor of cursors) {
+      const detail = validationDetails[cursor.id];
+      if (detail !== void 0) {
+        statuses[cursor.id] = detail.isCorrect ? "correct" : "incorrect";
+      }
+    }
+    return statuses;
+  }, [validationDetails, cursors]);
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -17120,28 +17769,50 @@ const NumberLineRenderer = ({
       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(
+        hasOverlayRow && /* @__PURE__ */ jsxs(
           "div",
           {
-            ref: getPositionContentRef(pos.id),
-            className: "number-line-position-content",
-            style: { left: `${toPercent(pos.value, min, max)}%` },
-            children: pos.content.map((subItem) => /* @__PURE__ */ jsx(
-              LayoutRenderer,
-              {
-                item: subItem,
-                widgets,
-                values,
-                droppedInputs,
-                validationDetails,
-                onChange,
-                onInputFocus
-              },
-              subItem.id
-            ))
-          },
-          pos.id
-        )) }),
+            className: "number-line-overlays-row",
+            style: { "--nl-arrow-arcs-row-height": `${arrowArcsRowHeight}px` },
+            children: [
+              /* @__PURE__ */ jsx(
+                ArrowArcsRow,
+                {
+                  layouts: arrowArcLayouts,
+                  rowHeight: arrowArcsRowHeight,
+                  widgets,
+                  values,
+                  droppedInputs,
+                  validationDetails,
+                  onChange,
+                  onInputFocus
+                }
+              ),
+              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(
+                    LayoutRenderer,
+                    {
+                      item: subItem,
+                      widgets,
+                      values,
+                      droppedInputs,
+                      validationDetails,
+                      onChange,
+                      onInputFocus
+                    },
+                    subItem.id
+                  ))
+                },
+                pos.id
+              )) })
+            ]
+          }
+        ),
         isAxisDragMode ? /* @__PURE__ */ jsx(
           FreeDragAxis,
           {
@@ -17156,6 +17827,8 @@ const NumberLineRenderer = ({
             values,
             onChange,
             highlights,
+            cursors,
+            cursorValidationStatuses,
             snapKey: counterCount
           }
         ) : /* @__PURE__ */ jsx(
@@ -17168,7 +17841,11 @@ const NumberLineRenderer = ({
             showArrowLeft,
             showArrowRight,
             highlights,
-            positions
+            positions,
+            cursors,
+            onChange,
+            values,
+            cursorValidationStatuses
           }
         ),
         /* @__PURE__ */ jsx(
@@ -18148,7 +18825,9 @@ export {
   MatcherRowSchema,
   MatcherWidgetJSONSchema,
   MixedValidationSchema,
+  NumberLineArrowItemSchema,
   NumberLineCounterItemSchema,
+  NumberLineCursorItemSchema,
   NumberLineHighlightItemSchema,
   NumberLineItemSchema,
   NumberLinePositionItemSchema,