DEMO (not for merging): experimenting with Item Scaling

.changeset/olive-pianos-knock.md

@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus-core": minor
+"@khanacademy/perseus-editor": minor
+---
+
+again

.changeset/soft-olives-push.md

@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus-core": minor
+"@khanacademy/perseus-editor": minor
+---
+
+DEMO adding selectable regions

.changeset/wet-files-repair.md

@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus-core": minor
+"@khanacademy/perseus-editor": minor
+---
+
+string substitutions

packages/perseus-core/src/index.ts

@@ -7,6 +7,9 @@ export type {
     Relationship,
     Alignment,
     RecursiveReadonly,
+    SelectableRegion,
+    VariableSubstitution,
+    TextSubstitution,
 } from "./types";
 export type {
     KeypadKey,
@@ -284,6 +287,12 @@ export {
     getPerseusAIData,
 } from "./utils/extract-perseus-ai-data";
 
+export {extractSelectableRegions} from "./utils/selectable-content";
+export {
+    createItemVariation,
+    applyTextSubstitutions,
+} from "./utils/item-variation";
+
 import {registerCoreWidgets} from "./widgets/core-widget-registry";
 
 registerCoreWidgets();

packages/perseus-core/src/types.ts

@@ -63,3 +63,50 @@ export type Alignment =
 export type RecursiveReadonly<T> = {
     readonly [K in keyof T]: RecursiveReadonly<T[K]>;
 };
+
+// ============================================================================
+// Variable Selection Types (for Scale Item feature)
+// ============================================================================
+
+/**
+ * Represents a region of content that can be selected as a variable.
+ * The token is opaque to consumers - only Perseus understands its format.
+ */
+export type SelectableRegion = {
+    /** Opaque identifier for this selectable region */
+    token: string;
+    /** The text content that can be selected */
+    text: string;
+    /** Human-readable label (e.g., "Question", "Choice A", "Hint 1") */
+    label: string;
+    /** Category for grouping in UI */
+    category: "question" | "widget" | "hint" | "answer";
+    /** Widget type if from a widget (for display purposes only) */
+    widgetType?: string;
+};
+
+/**
+ * A substitution to apply when creating an item variation.
+ * This replaces the entire region's content.
+ */
+export type VariableSubstitution = {
+    /** The opaque token from SelectableRegion */
+    token: string;
+    /** The new value to substitute */
+    newValue: string;
+};
+
+/**
+ * A text substitution with character offsets for substring replacement.
+ * This allows replacing specific text within a region rather than the entire region.
+ */
+export type TextSubstitution = {
+    /** The opaque token from SelectableRegion identifying which region */
+    token: string;
+    /** Character offset where the replacement starts (0-based) */
+    startIndex: number;
+    /** Character offset where the replacement ends (exclusive) */
+    endIndex: number;
+    /** The new text to insert */
+    newValue: string;
+};