@khanacademy/perseus 77.2.0 → 77.2.2

package/dist/widget-ai-utils/number-line/number-line-ai-utils.d.ts

@@ -1,14 +1,66 @@
 import type numberLine from "../../widgets/number-line/number-line";
 import type React from "react";
+/**
+ * JSON describing a number-line widget. Intended for consumption by AI tools.
+ * A number-line widget displays a horizontal number line with a draggable
+ * point. The learner positions the point to answer a question, optionally
+ * selecting an inequality relationship (e.g. ≤, ≥) when the widget is in
+ * inequality mode.
+ */
 export type NumberLinePromptJSON = {
     type: "number-line";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * The numeric values of the left and right endpoints of the number
+         * line, e.g. `[-5, 5]`. These bounds also constrain where the learner
+         * can place the point.
+         */
         range: ReadonlyArray<number>;
+        /**
+         * The number of sub-intervals between adjacent tick marks into which
+         * the point can snap. Higher values allow finer-grained placement.
+         * For example, a value of `4` means the point snaps to quarter-tick
+         * increments.
+         */
         snapDivisions: number;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The numeric axis value where the learner has placed the point,
+         * e.g. `3.5` on a `[-5, 5]` number line. Clamped to `options.range`
+         * and snapped to the nearest tick increment.
+         */
         numLinePosition: number;
+        /**
+         * The number of tick-mark divisions currently shown on the number
+         * line. When the widget's `isTickCtrl` option is enabled, the learner
+         * can adjust this value; otherwise it is set by the content author.
+         */
         numDivisions: number;
+        /**
+         * The number line widget can represent a set of real numbers that is
+         * greater than, greater than or equal to, less than, or less than or
+         * equal to some number. Visually, the portion of the number line
+         * included in this set is shaded. The `rel` property describes the
+         * inequality relation the learner has selected.
+         *
+         * Possible values:
+         * - `"eq"` – equals (standard point, no inequality shading)
+         * - `"lt"` – less than
+         * - `"gt"` – greater than
+         * - `"le"` – less than or equal to
+         * - `"ge"` – greater than or equal to
+         *
+         * Only meaningful when the widget is configured for inequality mode;
+         * otherwise always `"eq"`.
+         */
         rel: string;
     };
 };

package/dist/widget-ai-utils/numeric-input/prompt-utils.d.ts

@@ -1,9 +1,26 @@
 import type numericInput from "../../widgets/numeric-input/numeric-input.class";
 import type React from "react";
+/**
+ * JSON describing a numeric-input widget. Intended for consumption by AI tools.
+ * A numeric-input widget displays a single text field where the learner types
+ * a numeric answer (integer, decimal, fraction, etc.).
+ */
 export type NumericInputPromptJSON = {
     type: "numeric-input";
+    /**
+     * Accessible label for the input field, set by the content creator.
+     * Shown to learners using screen readers to describe what value should
+     * be entered.
+     */
     label: string;
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The text currently entered in the input field by the learner.
+         */
         value: string;
     };
 };

package/dist/widget-ai-utils/orderer/orderer-ai-utils.d.ts

@@ -1,11 +1,34 @@
 import type orderer from "../../widgets/orderer/orderer";
 import type React from "react";
+/**
+ * JSON describing an orderer widget. Intended for consumption by AI tools.
+ * An orderer presents a set of cards that the learner must arrange into the
+ * correct sequence. Cards can be dragged and dropped to reorder them. The
+ * same card may appear multiple times in the correct answer but is displayed
+ * only once in the card bank.
+ */
 export type OrdererPromptJSON = {
     type: "orderer";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * All of the cards available to the learner. Each string is the
+         * rendered content of one card (may include TeX or Markdown).
+         */
         options: ReadonlyArray<string>;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The cards in their current order as arranged by the learner. Each
+         * string is the content of a card. An empty array means the learner
+         * has not yet placed any cards.
+         */
         values: ReadonlyArray<string>;
     };
 };

package/dist/widget-ai-utils/prompt-types.d.ts

@@ -21,12 +21,26 @@ import type { SorterPromptJSON } from "./sorter/sorter-ai-utils";
 import type { UnsupportedWidgetPromptJSON } from "./unsupported-widget";
 export type UnsupportedWidget = "cs-program" | "iframe" | "interaction" | "interactive-graph-unsupported" | "measurer" | "phet-simulation" | "plotter" | "python-program" | "video";
 export type WidgetPromptJSON = CategorizerPromptJSON | DefinitionPromptJSON | DropdownPromptJSON | ExplanationPromptJSON | ExpressionPromptJSON | GradedGroupPromptJSON | GradedGroupSetPromptJSON | GrapherPromptJSON | GroupPromptJSON | ImagePromptJSON | InputNumberPromptJSON | LabelImagePromptJSON | MatcherPromptJSON | MatrixPromptJSON | MockWidgetPromptJSON | NumberLinePromptJSON | NumericInputPromptJSON | OrdererPromptJSON | RadioPromptJSON | SorterPromptJSON | UnsupportedWidgetPromptJSON;
-export type RendererPromptJSON = {
+/**
+ * JSON describing a Perseus renderer. Intended for consumption by AI tools.
+ * A "renderer" is essentially a Markdown document with embedded interactive
+ * widgets.
+ */
+export interface RendererPromptJSON {
+    /**
+     * Markdown content of the document. Widgets are represented by
+     * placeholders containing a Unicode snowman symbol, e.g.
+     * `[[☃ radio 1]]`. May contain TeX delimited by dollar signs, e.g.
+     * `$\dfrac{1}{2}$`. Literal dollar signs are escaped by backslashes.
+     */
     content: string;
+    /**
+     * Information about the configuration and UI state of each widget.
+     */
     widgets: {
         [widgetId: string]: WidgetPromptJSON;
     };
-};
+}
 export interface GetPromptJSONInterface {
     getPromptJSON(): RendererPromptJSON;
 }

package/dist/widget-ai-utils/radio/radio-ai-utils.d.ts

@@ -1,16 +1,54 @@
 import type radio from "../../widgets/radio";
 import type { PerseusRadioUserInput, RecursiveReadonly } from "@khanacademy/perseus-core";
 import type React from "react";
+/**
+ * A single answer choice in a radio widget.
+ */
 type BasicOption = {
+    /**
+     * The label displayed for this choice.
+     */
     value: string;
+    /**
+     * An opaque string that uniquely identifies this choice within the radio
+     * widget. The format is subject to change.
+     */
     id: string;
+    /**
+     * Rationale for why this answer is correct or incorrect. Shown to the
+     * learner when they select an incorrect answer. Only present when the
+     * content creator supplied one.
+     */
     rationale?: string;
 };
+/**
+ * JSON describing a radio (multiple-choice) widget. Intended for consumption
+ * by AI tools. A radio widget presents a list of answer choices and asks the
+ * learner to select one (or, when multiple-select is enabled, one or more).
+ */
 export type RadioPromptJSON = {
     type: "radio";
+    /**
+     * Whether the widget includes a "None of the above" option. When true,
+     * the last entry in `options` represents that special choice.
+     */
     hasNoneOfTheAbove: boolean;
+    /**
+     * The answer choices presented to the learner, in the order they appear
+     * on screen. The first choice is labeled "A", the second is "B", and so
+     * on.
+     */
     options: BasicOption[];
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The IDs of the choices the learner has selected. Each entry
+         * corresponds to a choice's `id` field in `options`. Order is
+         * insignificant — scoring uses set membership, not position.
+         */
         selectedOptions: ReadonlyArray<string>;
     };
 };

package/dist/widget-ai-utils/sorter/sorter-ai-utils.d.ts

@@ -1,8 +1,27 @@
 import type { PerseusSorterUserInput } from "@khanacademy/perseus-core";
+/**
+ * JSON describing a sorter widget. Intended for consumption by AI tools.
+ * A sorter presents a list of cards that the learner must arrange into the
+ * correct order by dragging them. The cards are initially displayed in a
+ * randomized order.
+ */
 export type SorterPromptJSON = {
     type: "sorter";
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The content strings of the sortable cards in the learner's current
+         * order.
+         */
         values: ReadonlyArray<string>;
+        /**
+         * Whether the learner has moved any cards from their initial
+         * randomized order. The widget is considered empty (invalid) until
+         * this is true.
+         */
         changed: boolean;
     };
 };

package/dist/widget-ai-utils/unsupported-widget.d.ts

@@ -1,11 +1,12 @@
 import type { UnsupportedWidget } from "./prompt-types";
+/**
+ * A placeholder in prompt JSON for a widget that doesn't support AI tooling.
+ */
 export type UnsupportedWidgetPromptJSON = {
     type: UnsupportedWidget;
+    /** Always empty; not used. */
     message?: string;
+    /** Always false. */
     isSupported: boolean;
 };
-export declare const getUnsupportedPromptJSON: (widgetType: UnsupportedWidget, message?: string) => {
-    type: UnsupportedWidget;
-    isSupported: boolean;
-    message: string;
-};
+export declare const getUnsupportedPromptJSON: (widgetType: UnsupportedWidget, message?: string) => UnsupportedWidgetPromptJSON;

package/dist/widgets/dropdown/dropdown.d.ts

@@ -68,7 +68,7 @@ declare const _default: {
         keypadElement?: any;
         onFocus: (blurPath: import("../..").FocusPath) => void;
         onBlur: (blurPath: import("../..").FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: PerseusDropdownUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/expression/expression.d.ts

@@ -58,7 +58,7 @@ export declare const Expression: React.ForwardRefExoticComponent<PerseusExpressi
     keypadElement?: any;
     onFocus: (blurPath: FocusPath) => void;
     onBlur: (blurPath: FocusPath) => void;
-    findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+    findWidgets: import("../../types").FindWidgetsFunction;
     reviewMode: boolean;
     showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
     handleUserInput: (newUserInput: string, cb?: () => void, silent?: boolean) => void;
@@ -137,7 +137,7 @@ declare const _default: {
         keypadElement?: any;
         onFocus: (blurPath: FocusPath) => void;
         onBlur: (blurPath: FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: string, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/image/components/explore-image-modal-content.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
 import type { CommonImageProps, ZoomProps, GifProps } from "./image-info-area";
 type Props = CommonImageProps & ZoomProps & GifProps;
-export default function ExploreImageModalContent({ backgroundImage, scale: contentScale, caption, alt, longDescription, linterContext, apiOptions, box, labels, range, zoomSize, isGifPlaying, setIsGifPlaying, }: Props): React.JSX.Element | null;
+export default function ExploreImageModalContent({ backgroundImage, scale: contentScale, caption, alt, longDescription, linterContext, apiOptions, box, labels, range, zoomSize, }: Props): React.JSX.Element | null;
 export {};

package/dist/widgets/interactive-graphs/interactive-graph.d.ts

@@ -210,7 +210,7 @@ declare class InteractiveGraph extends React.Component<Props, State> {
         keypadElement?: any;
         onFocus: (blurPath: import("../..").FocusPath) => void;
         onBlur: (blurPath: import("../..").FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<import("../../types").Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: PerseusGraphType, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/label-image/label-image.d.ts

@@ -167,7 +167,7 @@ declare const _default: {
         keypadElement?: any;
         onFocus: (blurPath: import("../..").FocusPath) => void;
         onBlur: (blurPath: import("../..").FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: ShowSolutions;
         handleUserInput: (newUserInput: PerseusLabelImageUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/mock-widgets/mock-widget.d.ts

@@ -91,7 +91,7 @@ declare class MockWidgetComponent extends React.Component<Props> implements Widg
         keypadElement?: any;
         onFocus: (blurPath: import("../..").FocusPath) => void;
         onBlur: (blurPath: import("../..").FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: PerseusMockWidgetUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/numeric-input/numeric-input.class.d.ts

@@ -98,7 +98,7 @@ export declare class NumericInput extends React.Component<NumericInputProps> imp
         keypadElement?: any;
         onFocus: (blurPath: import("../..").FocusPath) => void;
         onBlur: (blurPath: import("../..").FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: PerseusNumericInputUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/numeric-input/numeric-input.d.ts

@@ -61,7 +61,7 @@ export declare const NumericInputComponent: React.ForwardRefExoticComponent<impo
     keypadElement?: any;
     onFocus: (blurPath: import("../..").FocusPath) => void;
     onBlur: (blurPath: import("../..").FocusPath) => void;
-    findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<import("../../types").Widget>;
+    findWidgets: import("../../types").FindWidgetsFunction;
     reviewMode: boolean;
     showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
     handleUserInput: (newUserInput: import("@khanacademy/perseus-core").PerseusNumericInputUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widgets/table/table.d.ts

@@ -99,7 +99,7 @@ declare class Table extends React.Component<Props> implements Widget {
         keypadElement?: any;
         onFocus: (blurPath: FocusPath) => void;
         onBlur: (blurPath: FocusPath) => void;
-        findWidgets: (criterion: import("../../types").FilterCriterion) => ReadonlyArray<Widget>;
+        findWidgets: import("../../types").FindWidgetsFunction;
         reviewMode: boolean;
         showSolutions?: import("@khanacademy/perseus-core").ShowSolutions;
         handleUserInput: (newUserInput: PerseusTableUserInput, cb?: () => void, silent?: boolean) => void;

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core Perseus API (includes renderers and widgets)",
   "author": "Khan Academy",
   "license": "MIT",
-  "version": "77.2.0",
+  "version": "77.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,16 +38,17 @@
   ],
   "dependencies": {
     "@use-gesture/react": "^10.2.27",
+    "gifuct-js": "^2.1.2",
     "mafs": "0.19.0",
     "tiny-invariant": "1.3.1",
     "uuid": "^10.0.0",
     "@khanacademy/kas": "2.2.1",
-    "@khanacademy/keypad-context": "3.2.42",
-    "@khanacademy/kmath": "2.4.0",
-    "@khanacademy/math-input": "26.4.13",
-    "@khanacademy/perseus-core": "24.1.0",
-    "@khanacademy/perseus-linter": "4.9.2",
-    "@khanacademy/perseus-score": "8.6.0",
+    "@khanacademy/keypad-context": "3.2.43",
+    "@khanacademy/kmath": "2.4.1",
+    "@khanacademy/math-input": "26.4.14",
+    "@khanacademy/perseus-core": "24.1.1",
+    "@khanacademy/perseus-linter": "4.9.4",
+    "@khanacademy/perseus-score": "8.6.1",
     "@khanacademy/perseus-utils": "2.1.5",
     "@khanacademy/pure-markdown": "2.2.7",
     "@khanacademy/simple-markdown": "2.2.2"
@@ -61,8 +62,8 @@
     "@khanacademy/wonder-blocks-data": "15.0.1",
     "@khanacademy/wonder-blocks-dropdown": "10.8.3",
     "@khanacademy/wonder-blocks-form": "7.5.6",
-    "@khanacademy/wonder-blocks-icon-button": "11.1.6",
     "@khanacademy/wonder-blocks-icon": "5.3.9",
+    "@khanacademy/wonder-blocks-icon-button": "11.1.6",
     "@khanacademy/wonder-blocks-labeled-field": "4.0.16",
     "@khanacademy/wonder-blocks-layout": "3.1.46",
     "@khanacademy/wonder-blocks-link": "10.1.7",